a-share-mcp如何变成AI工具:FastMCP、stdio传输与系统提示词设计全解析

原创2026-11-07 15:56:081,831 阅读

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 界面,通常会看到绿灯亮起,配置已经成功。

a-share-mcp在CherryStudio中调用MCP工具查询A股大盘

四、系统提示词设计:教 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生成沪深300指数一周走势与技术面观察分析报告

五、总结:三个层次,一条链路

回顾 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 提供客观数据分析,仅供参考,不构成投资建议。

登录后查看全文
a-share-mcp-is-just-i-need