diff --git a/docs/architecture.md b/docs/architecture.md index c506519..5d3ccbc 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -404,6 +404,8 @@ from scheduler import ( | `search_stock_events` | query, stock_code, top_k | 按股票代码过滤 | | `search_sentiment_trend` | query, sentiment, top_k | 情绪趋势 + 统计 | +> 工具参数/返回格式/降级策略详见 [`docs/mcp_tools.md`](mcp_tools.md) + **启动方式**：stdio 模式(Cherry Studio/Claude Code 自动管理进程)或 SSE 模式(调试:`--sse 8765`) ### 3.9 `a_share_cli/` — 统一 CLI diff --git a/docs/mcp_tools.md b/docs/mcp_tools.md new file mode 100644 index 0000000..21cbbcb --- /dev/null +++ b/docs/mcp_tools.md @@ -0,0 +1,224 @@ +# MCP 工具说明 + +> A 股 Deep Research 平台通过 MCP(Model Context Protocol)向 Cherry Studio / Claude Code 等 AI 客户端提供**新闻与投资事件语义检索**能力。 +> +> 服务入口:`scripts/run_mcp_server.py`(stdio 默认 / SSE 调试)。 +> 实现位置:`mcp_server/tools.py`,共 **5 个工具**。 + +--- + +## 一、工具总览 + +| # | 工具 | 参数 | 用途 | +|---|------|------|------| +| 1 | `search_news` | `query`, `top_k` | 通用语义检索财经新闻知识库 | +| 2 | `search_company_news` | `query`, `company`, `top_k` | 按公司名称过滤检索 | +| 3 | `search_industry_news` | `query`, `industry`, `top_k` | 按行业名称过滤检索 | +| 4 | `search_stock_events` | `query`, `stock_code`, `top_k` | 按股票代码过滤投资事件 | +| 5 | `search_sentiment_trend` | `query`, `sentiment`, `top_k` | 情绪倾向过滤 + 分布统计 | + +--- + +## 二、工具详情 + +### 1. `search_news(query: str, top_k: int = 10) -> str` + +通用语义检索,无过滤条件,返回知识库中最相关的新闻。 + +| 参数 | 类型 | 必填 | 说明 | +|------|------|------|------| +| `query` | str | ✅ | 自然语言查询,如「宁德时代最新动态」「AI 行业政策」 | +| `top_k` | int | ❌ | 返回条数,默认 10 | + +**示例**: + +```text +search_news("国务院常务会议") +``` + +**返回**:Markdown 列表,每条含标题、来源、相似度、时间、公司/代码/行业、摘要、URL。 + +--- + +### 2. `search_company_news(query: str, company: str, top_k: int = 10) -> str` + +按**公司名称**精确过滤(`company_names` 字段,MatchAny)。若精确命中 0 条,自动降级为纯语义搜索(无过滤),保证有结果可用。 + +| 参数 | 类型 | 必填 | 说明 | +|------|------|------|------| +| `query` | str | ✅ | 自然语言查询 | +| `company` | str | ✅ | 公司名称,如「宁德时代」「贵州茅台」 | +| `top_k` | int | ❌ | 返回条数,默认 10 | + +**示例**: + +```text +search_company_news("业绩", company="贵州茅台") +``` + +**注意**:过滤字段来自 LLM 事件抽取的 `company_names`,公司简称/全称需与抽取结果一致;不匹配时自动降级为语义搜索。 + +--- + +### 3. `search_industry_news(query: str, industry: str, top_k: int = 10) -> str` + +按**行业名称**精确过滤(`industries` 字段,MatchAny)。0 命中时降级为纯语义搜索。 + +| 参数 | 类型 | 必填 | 说明 | +|------|------|------|------| +| `query` | str | ✅ | 自然语言查询 | +| `industry` | str | ✅ | 行业名,如「动力电池」「白酒」「半导体」 | +| `top_k` | int | ❌ | 返回条数,默认 10 | + +**示例**: + +```text +search_industry_news("政策", industry="半导体") +``` + +--- + +### 4. `search_stock_events(query: str, stock_code: str, top_k: int = 10) -> str` + +按**股票代码**过滤(`stock_codes` 字段,MatchAny)。代码自动标准化:去除 `.SH/.SZ` 后缀并统一大写(如 `300750.SZ` → `300750`)。0 命中时降级为纯语义搜索。 + +| 参数 | 类型 | 必填 | 说明 | +|------|------|------|------| +| `query` | str | ✅ | 自然语言查询 | +| `stock_code` | str | ✅ | 6 位 A 股代码,可带后缀,如「300750」「000001.SZ」 | +| `top_k` | int | ❌ | 返回条数,默认 10 | + +**示例**: + +```text +search_stock_events("重大事件", stock_code="300750") +``` + +--- + +### 5. `search_sentiment_trend(query: str, sentiment: str = "all", top_k: int = 20) -> str` + +按**情绪倾向**过滤,并返回情绪分布统计(`🟢利好 / 🔴利空 / ⚪中性` 计数)。 + +| 参数 | 类型 | 必填 | 说明 | +|------|------|------|------| +| `query` | str | ✅ | 自然语言查询 | +| `sentiment` | str | ❌ | `positive`(利好) / `negative`(利空) / `neutral`(中性) / `all`(全部,默认) | +| `top_k` | int | ❌ | 返回条数,默认 20 | + +**示例**: + +```text +search_sentiment_trend("AI算力", sentiment="all") +``` + +**返回**:头部为统计行(`共 N 条 | 🟢利好 x | 🔴利空 y | ⚪中性 z`),下方为 Markdown 结果列表。 + +--- + +## 三、返回格式 + +所有工具返回 **Markdown 文本**,单条结果结构如下: + +```markdown +### 1. 李强主持召开国务院常务会议 +- 来源: xwlb | 相似度: 0.759 | ⚪中性 +- 时间: 2026-08-31T00:00:00 +- 行业: 宏观政策 +- 摘要: 国务院常务会议部署灾后救援与地下管网建设… +- URL: https://… +``` + +字段说明: + +| 字段 | 说明 | +|------|------| +| 来源 | 主来源(多源新闻显示「来源A / 来源B [多源]」) | +| 相似度 | 余弦相似度,保留 4 位小数 | +| 时间 | `publish_time`,ISO8601(可为空) | +| 公司/代码/行业 | LLM 事件抽取结果(存在才显示) | +| 摘要 | LLM 生成的一句话事件摘要 | +| URL | 原文链接 | + +无结果时返回:`未找到与「{query}」相关的结果。` + +--- + +## 四、工作原理 + +``` +用户输入自然语言查询 + → DashScope 嵌入(query → 1024 维向量) + → Qdrant 余弦相似度检索(score_threshold ≥ 0.3) + → 按过滤条件筛选(公司/行业/代码/情绪,MatchAny) + → Markdown 格式化返回 +``` + +- **嵌入**:复用 M5 embedding 模块(`make_sync_provider`),读取 `.env` 的 `EMBEDDING_PROVIDER` +- **检索**:复用 M6 vectorstore(`VectorStore.query`),本地文件模式 Qdrant(`data/qdrant_storage`) +- **单例**:后端(embedder + vector_store)首次调用时初始化,后续所有工具共用 +- **降级策略**:公司/行业/代码过滤精确命中 0 条时,自动降级为无过滤语义搜索,避免空结果 + +--- + +## 五、调试与连接 + +**stdio 模式**(默认,Cherry Studio / Claude Code 自动管理进程): + +```bash +uv run python -m scripts.run_mcp_server +``` + +**SSE 调试模式**: + +```bash +uv run python -m scripts.run_mcp_server --sse 8765 +# 浏览器访问 http://:8765/sse +``` + +**Cherry Studio 配置**(设置 → MCP 服务器 → 添加): + +```json +{ + "mcpServers": { + "a-share-research": { + "command": "uv", + "args": ["run", "python", "-m", "scripts.run_mcp_server"], + "cwd": "/home/pi/news" + } + } +} +``` + +**Claude Code 配置**(项目根目录 `.mcp.json`,已随仓库提交): + +```json +{ + "mcpServers": { + "a-share-research": { + "command": "uv", + "args": ["run", "python", "-m", "scripts.run_mcp_server"], + "cwd": "/home/pi/news" + } + } +} +``` + +--- + +## 六、测试 + +```bash +uv run pytest tests/test_mcp.py -q +``` + +覆盖:工具注册完整性、Markdown 格式化、多源展示、情绪统计、过滤降级、代码标准化。 + +--- + +## 七、数据前提 + +工具检索的是 **Qdrant 知识库**(collection `a_share_news`),数据由定时 pipeline 填充: + +- M1 抓取 → M2 提取 → M3 去重 → M4 LLM 事件抽取 → M5 嵌入 → M6 入库 +- 无数据时工具返回「未找到」;数据时效取决于最近一次定时任务(07:00/12:00/18:00/22:00) diff --git a/docs/user-guide.md b/docs/user-guide.md index 68d9259..2b1c08e 100644 --- a/docs/user-guide.md +++ b/docs/user-guide.md @@ -571,6 +571,8 @@ Cherry Studio → 设置 → MCP 服务器 → 添加： | `search_stock_events` | query, stock_code, top_k | `search_stock_events("重大事件", stock_code="300750")` | | `search_sentiment_trend` | query, sentiment, top_k | `search_sentiment_trend("AI算力", sentiment="all")` | +> 📄 工具完整说明(参数/返回格式/降级策略/工作原理/调试):见 [`docs/mcp_tools.md`](mcp_tools.md) + ### 8.4 调试(SSE 模式) ```bash