news/docs/mcp_tools.md

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

示例:

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

示例:

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

示例:

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

示例:

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

示例:

search_sentiment_trend("AI算力", sentiment="all")

返回:头部为统计行(共 N 条 | 🟢利好 x | 🔴利空 y | ⚪中性 z),下方为 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 自动管理进程):

uv run python -m scripts.run_mcp_server

SSE 调试模式:

uv run python -m scripts.run_mcp_server --sse 8765
# 浏览器访问 http://<host>:8765/sse

Cherry Studio 配置(设置 → MCP 服务器 → 添加):

{
  "mcpServers": {
    "a-share-research": {
      "command": "uv",
      "args": ["run", "python", "-m", "scripts.run_mcp_server"],
      "cwd": "/home/pi/news"
    }
  }
}

Claude Code 配置(项目根目录 .mcp.json,已随仓库提交):

{
  "mcpServers": {
    "a-share-research": {
      "command": "uv",
      "args": ["run", "python", "-m", "scripts.run_mcp_server"],
      "cwd": "/home/pi/news"
    }
  }
}

---

六、测试

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)