docs: 新增 MCP 工具说明文档 docs/mcp_tools.md

- 5 个工具参数/返回格式/降级策略/工作原理/调试连接/测试/数据前提
- user-guide §8.3 与 architecture §3.8 挂链接

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

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://<host>: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)

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