a-share-mcp如何变成AI工具:FastMCP、stdio传输与系统提示词设计全解析
a-share-mcp如何变成AI工具:FastMCP、stdio传输与系统提示词设计全解析
a-share-mcp 是一个专为 A 股市场打造的 MCP 服务器,它把股票行情、财务报表、指数成分、宏观经济等 41 个数据查询能力,通过 FastMCP 框架变成 AI 可以直接调用的工具。本文带你拆解它的三大核心机制:FastMCP 工具注册、stdio 传输启动方式,以及一段值得借鉴的系统提示词设计——看完你就明白一个普通 Python 项目是如何"长出手脚",接入 Claude Desktop、CherryStudio 等 AI 客户端的。
一、项目全景:一个 A 股数据 MCP 服务器长什么样
先认识一下这位主角。a-share-mcp 基于免费的 Baostock 数据源,覆盖了:
- 📈 股票市场数据:历史 K 线、股票基础信息、分红配送、复权因子
- 📊 财务报表数据:盈利、营运、成长、资产负债、现金流、杜邦分析等 9 类报表
- 🏛️ 指数与行业:上证 50、沪深 300、中证 500 成分股,行业分类
- 🌐 宏观经济:存款/贷款利率、存款准备金率、货币供应量
- 📅 日期工具:最新交易日、交易日历、智能分析周期
- 📝 分析报告:一键生成基本面/技术面股票分析报告
整体架构非常清晰,分层如下:
| 层级 | 目录 | 职责 |
|---|---|---|
| 入口层 | mcp_server.py | FastMCP 初始化、注册工具、启动服务 |
| 工具层 | src/tools/ | 面向 AI 的工具定义(参数 + 文档字符串) |
| 用例层 | src/use_cases/ | 参数校验 + 数据编排 |
| 数据层 | src/baostock_data_source.py | 对接 Baostock 接口 |
| 格式化层 | src/formatting/markdown_formatter.py | 把 DataFrame 转成 Markdown/JSON/CSV |
这种分层让"AI 能调用的工具"和"底层取数逻辑"彻底解耦,想换数据源只需实现 src/data_source_interface.py 中的 FinancialDataSource 抽象接口即可,工具层一行都不用改。
二、FastMCP:用装饰器把 Python 函数变成 AI 工具
打开入口文件 mcp_server.py,整个服务器的骨架其实只有 10 来行:
from mcp.server.fastmcp import FastMCP
app = FastMCP(
server_name="a_share_data_provider",
description=f"""今天是{current_date}。提供中国A股市场数据分析工具。……"""
)
register_stock_market_tools(app, active_data_source)
register_financial_report_tools(app, active_data_source)
# ……其余 6 个模块的注册函数
这里有两个关键设计:
1. FastMCP 是轻量级的"工具箱"
FastMCP 是官方 SDK(mcp 包)提供的 Python 高层封装。你只需要创建一个 FastMCP 实例,然后用 @app.tool() 装饰器标记任意 Python 函数,它就自动变成一个可被 AI 调用的 MCP 工具。函数的参数类型会变成工具的 schema,docstring 文档字符串会变成 AI 看到的"使用说明"——所以这个项目里每个工具的文档都写得格外详细(见 src/tools/stock_market.py)。
2. 模块化注册,41 个工具井然有序
工具按业务域拆成 8 个文件,各自暴露一个 register_xxx_tools(app, data_source) 函数,由主入口统一挂载(mcp_server.py)。新增一个"北向资金工具"?只需新建文件、写一个注册函数,主入口加一行调用,互不干扰。
再看单个工具的真实形态(src/tools/stock_market.py):
@app.tool()
def get_historical_k_data(
code: str, start_date: str, end_date: str,
frequency: str = "d", adjust_flag: str = "3",
limit: int = 250, format: str = "markdown",
) -> str:
"""
Fetches historical K-line (OHLCV) data for a Chinese A-share stock.
Args:
code: The stock code in Baostock format (e.g., 'sh.600000', 'sz.000001').
...
"""
return run_tool_with_handling(...)
注意几个对 AI 友好度影响极大的细节:
- ✅ 参数全部带默认值和枚举说明:
frequency的d/w/m/5/15/30/60取值写在 docstring 里,AI 不会传错 - ✅ 输出格式可控:支持
markdown/json/csv三种返回,由 src/formatting/markdown_formatter.py 统一格式化,并自动截断到 250 行保护上下文长度 - ✅ 永不抛异常:所有工具都套上 src/services/tool_runner.py 的
run_tool_with_handling,把"查无数据""登录失败""参数非法"等异常统一翻译成Error: ...字符串返回给 AI,让它能自己判断并换一种问法,而不是让整个会话崩溃
这正是"给 AI 用的工具"和"给人用的 API"的本质区别:返回值必须让 AI 读得懂、猜得着下一步。
三、stdio 传输:AI 客户端如何"拉起"这个 MCP 服务器
注册完工具,最后两行代码完成了从"代码"到"服务"的跨越(mcp_server.py):
if __name__ == "__main__":
app.run(transport='stdio')
transport='stdio' 是 MCP 三种传输方式中最经典的一种:标准输入/输出。它意味着:
- AI 客户端(Host)以子进程方式执行
python mcp_server.py - 双方的全部通信走进程的 stdin/stdout,用 JSON-RPC 报文交换
- 服务器不需要监听端口、不需要公网、不需要鉴权——天生适合本地部署
这就是为什么它"零运维成本":没有 URL 可配、没有防火墙要开,客户端一启动进程就完成握手。
最快配置方法:在 JSON 中接入任意 IDE / 桌面客户端
以 Cursor、VSCode 插件为例,在 MCP 配置里添加(README.md 中的官方示例):
{
"mcpServers": {
"a-share-mcp": {
"command": "uv",
"args": [
"--directory",
"C:\\Users\\YourName\\Projects\\a_share_mcp",
"run",
"python",
"mcp_server.py"
]
}
}
}
推荐用 uv 作为 command 的原因很实用:uv --directory <项目路径> run python mcp_server.py 一条命令就同时解决了三件事——指定工作目录、使用项目虚拟环境、运行入口脚本。依赖由 pyproject.toml 声明(mcp[cli]、baostock、pandas 等),首次启动时自动装齐。
CherryStudio 用户:按位填参即可
在 CherryStudio 的 MCP 设置中,类型选 标准输入/输出 (stdio),命令填 uv,参数逐行填入 5 个值:--directory → 项目绝对路径 → run → python → mcp_server.py。
💡 小技巧(来自 README.md 作者实测):如果开关点击后毫无反应,随便点一下左侧目录再回到 MCP 界面,通常会看到绿灯亮起,配置已经成功。
四、系统提示词设计:教 AI"正确地用数据"
这是全项目最容易被忽略、却最有价值的一段——mcp_server.py 里 FastMCP 的 description 参数:
current_date = datetime.now().strftime("%Y-%m-%d")
app = FastMCP(
server_name="a_share_data_provider",
description=f"""今天是{current_date}。提供中国A股市场数据分析工具。此服务提供客观数据分析,用户需自行做出投资决策。……
⚠️ 重要说明:
1. 最新交易日不一定是今天,需要从 get_latest_trading_date() 获取
2. 请始终使用 get_latest_trading_date() 工具获取实际当前最近的交易日,不要依赖训练数据中的日期认知
3. 当分析"最近"或"近期"市场情况时,必须首先调用 get_market_analysis_timeframe() 工具确定实际的分析时间范围
4. 任何涉及日期的分析必须基于工具返回的实际数据,不得使用过时或假设的日期
""",
)
这段系统提示词浓缩了 4 个高手级技巧:
🔢 注入"现在"——对抗大模型的日期幻觉
LLM 的训练数据有截止日期,它根本不知道"今天"是几号。datetime.now() 在每次服务器启动时动态拼进描述里(注意 f"""..."""),AI 从第一眼就知道当前日期。
🔗 把工具调用"编排"进提示词
第 1、3 条是典型的 ReAct 编排:告诉 AI "分析'最近'行情前,必须先调 get_market_analysis_timeframe();判断日期,必须先调 get_latest_trading_date()"。这两个工具分别实现在 src/tools/date_utils.py,前者会按"最近/季度/半年/年度"智能计算时间区间(src/use_cases/date_utils.py),后者从交易日历反查真实最新交易日(周末、节假日自动回退)。没有这几句提示词,AI 很可能直接拿"今天"去查 K 线,然后一脸困惑地发现没有数据。
📅 用"最新交易日"替代"今天"——金融场景的正确姿势
A 股有交易日概念:周六问"今天大盘怎么样",正确答案是周五的数据。这个语义被同时写进了系统提示词和日期工具层,双保险。
⚖️ 免责声明前置
"不构成投资建议,仅供参考"直接写进服务器级描述,AI 生成的每份分析都会自然带上这个免责立场——合规意识不靠事后审查,而靠提示词前置约束。
效果实证:AI 自主串联了 3 个工具
来看 README.md 里的真实对话。用户只说了一句"分析最近的A股大盘",AI 自主规划并依次调用了 get_latest_trading_date → get_hs300_stocks → get_historical_k_data 三个工具,然后输出包含最新交易日点位、一周走势、压力位/支撑位、MACD 观察的完整分析——这正是系统提示词 + 工具描述共同作用的结果:
五、总结:三个层次,一条链路
回顾 a-share-mcp 变成"AI 工具"的完整链路,其实只有三层:
| 层次 | 技术要点 | 对应文件 |
|---|---|---|
| ① 工具层 | FastMCP + @app.tool(),docstring 即说明书 |
src/tools/ |
| ② 传输层 | app.run(transport='stdio'),客户端拉起子进程 |
mcp_server.py |
| ③ 提示层 | 动态日期注入 + 工具编排指令 + 合规声明 | mcp_server.py |
对想给自家项目接入 AI 的同学,这份项目提供了可直接抄的完整范式:用 FastMCP 定义工具 → 用 stdio 传输本地部署 → 用系统提示词纠正 AI 的"常识偏差"。配合 Python 3.10+ 环境,uv venv && uv sync 两分钟即可在 CherryStudio 或 Cursor 里问出任何 A 股问题。
⚠️ 数据更新提醒:Baostock 在交易日 17:30 后才入库当日 K 线数据,盘中查询当天的行情是拿不到的(详见 README.md)。
免责声明:a-share-mcp 提供客观数据分析,仅供参考,不构成投资建议。

