# 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)