a-share-mcp错误处理设计:如何把数据源异常变成AI友好的人类可读消息
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 的核心设计目标是:每个异常最终都变成一句说清楚"发生了什么 + 该怎么修"的文本。下面看它如何用四层协作做到这一点。
异常的四层流转路径:从 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: … |
三个设计亮点:
- 单一出口:全部 41 个工具共用同一套错误语义,AI 学习一次就能应对所有工具
- 日志与回复分离:每个分支都会按
context(如get_historical_k_data:sh.600000)记录日志,开发者可追溯完整堆栈;而用户/AI 只看到精简文案 - 兜底不吞错:未知异常也会带原文返回,而不是静默失败
两个容易忽略的细节
细节 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 收到错误消息后会怎样?
得益于上面的设计,典型失败场景的处理过程是:
- AI 调用
get_historical_k_data时传了frequency="day" - 收到
Error: Invalid input parameter. Invalid frequency 'day'. Valid options are: ['d', 'w', 'm', '5', '15', '30', '60'] - AI 自行改用
frequency="d"重试,用户侧无感 - 若数据源不可用,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 能读懂、能行动的消息。

