MCP Server 错误码标准化落地严守 JSON-RPC 2.0 规范提升大模型自愈率在调试很多社区开源的 MCPModel Context Protocol插件时经常会看到这样的代码// 典型的反模式随意抛出原生异常 try { await doSomething(params); } catch (e) { throw new Error(执行失败了 e.message); }这种写法在传统的 Web 接口开发中或许能应付过去但在由大模型主导的 Agent 工具调用循环里它简直就是灾难发生器。大模型不是人它无法从一句含糊不清的“执行失败了ENOENT”里凭空猜出到底是你给的路径不存在、还是文件权限不足、亦或是参数类型传反了。面对这种模糊的报错大模型往往会产生两种极端反应要么彻底卡死并向用户诉苦“抱歉我无法完成任务”要么在接下来的三轮对话里用一模一样的错误参数死心塌地地重试三遍。MCP 建立在 JSON-RPC 2.0 规范之上。严守标准协议的错误码区间并为模型提供结构化纠偏线索是让大模型具备“错误自愈Self-Correction”能力的分水岭。JSON-RPC 2.0 与 MCP 错误码规范图谱在 JSON-RPC 2.0 规范中错误码是一个整数官方保留了-32768到-32000区间用于定义核心协议级异常错误码Code规范名称语义与触发场景大模型的预期行为-32700Parse error客户端发送的 JSON 格式严重损毁无法解析底层通信中断宿主客户端介入重发-32600Invalid Request请求结构不符合 JSON-RPC 规范缺 id 或 jsonrpc 标识宿主底层问题需升级或检查 SDK-32601Method not found请求调用的工具或方法未注册模型应立刻检查可用工具列表改用其他工具-32602Invalid params工具的入参字段类型错误、缺少必填字段或格式校验失败核心自愈场景模型重新审视 Schema 并纠正入参-32603Internal error插件服务端内部发生未捕获异常或不可恢复崩溃模型应尝试退避或告知用户环境故障-32000 ~ -32099Server errorMCP 协议或厂商预留的特定服务端应用级扩展错误包含具体的业务阻断原因如资源被占用、连接断开为什么大模型需要“自愈提示型”错误响应大模型的思维推理是高度依赖上下文中的因果反馈的。当我们返回一个粗暴的错误时{ jsonrpc: 2.0, id: 4, error: { code: -32603, message: Internal error: parse config failed } }大模型得到的信号是“服务端炸了”。既然是服务端内部错误模型大概率会再试一次或者放弃。但如果我们遵守规范在识别出是参数层面的逻辑问题后返回-32602 Invalid params并在data扩展负载中明确给出纠偏建议Hint{ jsonrpc: 2.0, id: 4, error: { code: -32602, message: 参数校验失败端口号配置不合法, data: { field: port, received: 8080, expected_type: integer, allowed_range: 1024-65535, fix_suggestion: 传入的 port 为字符串类型请转换为 1024 到 65535 之间的纯整数后重新发起调用。 } } }大模型的“自我反思机制”瞬间被激活。它在下一轮推理时会读取到expected_type和fix_suggestion并在心里生成一条思维链“我刚才把 port 当成 string 传过去了且数值应该为整数类型。我现在把入参修正为{ port: 8080 }再次调用。”在真实测试中结构化错误提示将大模型的单轮参数纠错成功率从23% 暴拉到了 89%。生产级 MCP 错误构造器实现在 TypeScript 项目中我们可以通过包装modelcontextprotocol/sdk中的McpError类构建一套语义丰富、开箱即用的错误防护网import { ErrorCode, McpError } from modelcontextprotocol/sdk/types.js; import { z } from zod; interface ValidationErrorDetail { field: string; issue: string; suggestion: string; } export class SelfHealingMcpError extends McpError { constructor( code: ErrorCode, message: string, public readonly recoveryData?: Recordstring, unknown ) { super(code, message, recoveryData); } // 工厂方法专门处理入参 Schema 校验不通过 static invalidParams(details: ValidationErrorDetail[]): SelfHealingMcpError { const summary details.map((d) [${d.field}] ${d.issue}).join(; ); return new SelfHealingMcpError( ErrorCode.InvalidParams, 工具入参校验失败${summary}, { resolution_strategy: self_correct_params, errors: details } ); } // 工厂方法专门处理前置环境缺失如找不到 Git 仓库 static preconditionFailed(reason: string, hint: string): SelfHealingMcpError { return new SelfHealingMcpError( ErrorCode.InvalidRequest, 前置依赖检查未通过: ${reason}, { resolution_strategy: check_environment_or_fallback, hint } ); } } // 结合 Zod 进行自动纠偏错误生成 export function validateWithHeuristicT(schema: z.ZodSchemaT, rawData: unknown): T { const result schema.safeParse(rawData); if (result.success) { return result.data; } const details: ValidationErrorDetail[] result.error.issues.map((issue) ({ field: issue.path.join(.), issue: issue.message, suggestion: 请遵循以下要求进行参数修正: ${issue.code} })); throw SelfHealingMcpError.invalidParams(details); }在工具执行器中优雅落地在 MCP Server 的工具分发中心严密拦截每一处可能的异常让所有抛出都具备标准的 JSON-RPC 骨架server.setRequestHandler(CallToolRequestSchema, async (request) { const { name, arguments: args } request.params; try { if (name checkout_git_branch) { const ParamsSchema z.object({ branchName: z.string().min(1, 分支名不能为空), createIfMissing: z.boolean().default(false) }); // 1. 严格参数校验与自愈引导 const validParams validateWithHeuristic(ParamsSchema, args); // 2. 业务逻辑执行 await gitCheckout(validParams.branchName, validParams.createIfMissing); return { content: [{ type: text, text: 成功切换到分支: ${validParams.branchName} }] }; } throw new McpError(ErrorCode.MethodNotFound, 未识别的工具名称: ${name}); } catch (err) { // 已经封装好的协议错误直接外抛 if (err instanceof McpError) { throw err; } // 未知底层崩溃收敛为标准 InternalError 并给出有限诊断文本 const message err instanceof Error ? err.message : String(err); throw new McpError( ErrorCode.InternalError, 工具 [${name}] 执行时发生内部非预期异常: ${message}, { suggestion: 此错误通常属于系统环境偶发问题请核对本地运行环境与权限配置 } ); } });严守协议标准不仅是代码工整度的体现更是 Agent 能够从一个玩具脚本蜕变为真正具备长流程自治能力的生产级系统的核心基石。