6.6 KiB
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)