a-share-mcp错误处理设计:如何把数据源异常变成AI友好的人类可读消息

原创2026-11-07 10:26:301,908 阅读

a-share-mcp错误处理设计:如何把数据源异常变成AI友好的人类可读消息

a-share-mcp 是一个专注 A 股市场的 MCP 服务器,内置 41 个工具,可查询 K 线、财报、宏观数据等。这篇文章讲它的错误处理设计:如何把 Baostock 数据源的异常,一层层转换成人类可读、AI 能理解的错误消息——让 AI 知道"为什么失败",从而自主纠正参数、优雅应对,而不是一脸懵地对着堆栈跟踪。

为什么 MCP 项目的错误处理更关键?

普通 API 报错,看日志的是工程师;而 MCP(Model Context Protocol)服务器的"读者"是 LLM 大模型。当工具调用失败时:

  • ❌ 抛出一串 Traceback:AI 可能无法判断原因,反复重试、消耗 Token,甚至误导用户
  • ✅ 返回结构化友好文案:AI 一眼看出"参数不合法,可选值是 d/w/m…",立刻修正后重试

所以 a-share-mcp 的核心设计目标是:每个异常最终都变成一句说清楚"发生了什么 + 该怎么修"的文本。下面看它如何用四层协作做到这一点。

a-share-mcp 错误处理与 A 股数据 MCP 对话场景

异常的四层流转路径:从 Baostock 到 AI

整体链路如下(自下而上):

Baostock API 返回 error_code / error_msg
        │
① src/baostock_data_source.py  把错误码翻译成 3 种类型化异常
        │
② src/services/validation.py   参数不合法时提前抛出"指路型" ValueError
        │
③ src/use_cases/  校验参数 → 取数 → 格式化,只做业务编排
        │
④ src/services/tool_runner.py  统一兜底,把异常变成 "Error: …" 友好文案

第一层:参数校验,提前抛出"指路型"错误

AI 调用工具时最常见的失败是传错参数(比如把 frequency 写成 "day")。a-share-mcp 在 src/services/validation.py 中定义了统一的白名单校验函数,一旦不合法立即抛出 ValueError,且消息里直接带上所有合法选项:

Invalid frequency 'day'. Valid options are: ['d', 'w', 'm', '5', '15', '30', '60']

注意这个细节:报错不是"参数错误"四个字,而是"错误值 + 正确答案"。AI 读到后下一轮就能自动改用 d 重试——错误消息本身就是修复指南。

第二层:数据源层把错误码翻译成类型化异常

Baostock 的 API 出错时返回 error_code 和 error_msg。在 src/baostock_data_source.py 中,这些数据被翻译成三种"类型化异常",它们的定义集中在 src/data_source_interface.py:

异常类 含义 典型触发
LoginError 数据源连接/登录失败 Baostock 登录返回非 0 状态码
NoDataFoundError 查询合法但没数据 error_code 为 10002 或消息含 "no record found"
DataSourceError 其他数据源故障 其余非 0 错误码、未预期的 API 异常

为什么要把"没有数据"单独拎出来? 因为"2024Q1 没有财报数据"不是系统坏了,而是客观事实——AI 拿到 NoDataFoundError 后应该回答用户"该公司该季度暂无披露",而不是宣称服务故障。错误分级让 AI 能给出正确语义的回复。

第三层:run_tool_with_handling 统一归一化

各工具(如 src/tools/stock_market.py)自己不写 try/except,而是把取数动作交给 src/services/tool_runner.py 中的 run_tool_with_handling 统一处理:

捕获的异常 返回给 AI 的文案
NoDataFoundError Error: No profit data found for sh.600000, 2024Q1…
LoginError Error: Could not connect to data source. …
DataSourceError Error: An error occurred while fetching data. …
ValueError Error: Invalid input parameter. …
其他 Exception Error: An unexpected error occurred: …

三个设计亮点:

  1. 单一出口:全部 41 个工具共用同一套错误语义,AI 学习一次就能应对所有工具
  2. 日志与回复分离:每个分支都会按 context(如 get_historical_k_data:sh.600000)记录日志,开发者可追溯完整堆栈;而用户/AI 只看到精简文案
  3. 兜底不吞错:未知异常也会带原文返回,而不是静默失败

a-share-mcp A 股数据 MCP 分析结果示例

两个容易忽略的细节

细节 1:登录输出必须"静音"(MCP stdio 陷阱)

MCP 服务器走 stdio 传输,标准输出通道专门用来传协议消息。而 Baostock 登录成功时会往 stdout 打印一行 login success!——这行字会污染协议流,轻则客户端解析异常,重则连接直接断开。

a-share-mcp 在 src/utils.py 的 baostock_login_context 上下文管理器中,登录/登出前后临时把 stdout 重定向到 os.devnull,保证通道干净;同时在这里判断登录结果,失败即抛 LoginError。这是 stdio 型 MCP 服务器很容易踩的坑。

细节 2:异常在"数据源层"产生,在"工具层"消化

数据源实现只负责如实报告(抛类型化异常),从不对话术负责;工具层只负责翻译话术。好处是:未来把 Baostock 换成其他数据源,只要新实现也抛同样的三类异常,上层所有工具的报错行为完全不变。

AI 收到错误消息后会怎样?

得益于上面的设计,典型失败场景的处理过程是:

  1. AI 调用 get_historical_k_data 时传了 frequency="day"
  2. 收到 Error: Invalid input parameter. Invalid frequency 'day'. Valid options are: ['d', 'w', 'm', '5', '15', '30', '60']
  3. AI 自行改用 frequency="d" 重试,用户侧无感
  4. 若数据源不可用,AI 会基于 Could not connect to data source 如实告知"数据源暂时无法连接",而不是编造数据

错误处理设计得好,AI 的"自愈率"就会高;反之,一次模糊的报错可能引发多轮无效重试。这也是 a-share-mcp 把错误消息当作产品功能来设计的原因。

错误处理关键文件清单

文件 职责
src/data_source_interface.py 定义 DataSourceError / LoginError / NoDataFoundError 异常体系
src/baostock_data_source.py 将 Baostock 错误码转换为类型化异常
src/utils.py baostock_login_context:登录态管理 + stdout 静音
src/services/validation.py 参数白名单校验,抛出带"正确选项"的 ValueError
src/services/tool_runner.py run_tool_with_handling:异常到友好文案的统一归一化
src/use_cases/stock_market.py 用例编排:先校验、后取数、再格式化
mcp_server.py 工具注册入口,依赖注入数据源

一句话总结:a-share-mcp 的错误处理 = 类型化异常(数据源层)+ 指路型校验(服务层)+ 统一友好文案(工具层),三层协作让每一个异常都变成 AI 能读懂、能行动的消息。

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