为 MCP 写集成测试：mock stdio、断言 tool schema，防止升级后静默坏掉

MCP Server 最烦人的故障不是「进程起不来」——那种很吵你会立刻发现。真正危险的是静默损坏升级 SDK 或依赖后tool 改名、必填字段消失、枚举变松客户端要到运行时才炸而且不一定好猜。动态加载成为常见能力之后见同日快报你装的 Server 可能更多升级更频繁——契约测试就该成为标配。本文给最小集成测试骨架拉起或 mock stdio、断言 schema、抽样调用并可推进 AtomGit。目标CI 无 GUI 可跑。tool 名集合与必填字段有硬断言。故意破坏 schema 时测试变红。夹具无真实密钥。测试流水线启动子进程跑 Serverstdio或使用内存/mock 传输。握手按 MCP 生命周期做 initialize细节以当前规范/SDK 为准。列表list_tools或等价拿到名称与 schema。调用happy path 预期错误形状各至少一条。契约测试优先于「打开 Cursor 点一点」的端到端——后者慢、脆、难进 CI。该断言什么断言为何失败意味tool 名集合防改名/删除调用方直接崩必填参数防破坏性变更参数对不上类型/枚举防悄悄放宽或收紧脏数据或误拒错误形状防乱码回包难排障把 schema 当公开 API破坏性变更必须红灯而不是靠用户群提问发现。实现五步1. 夹具 Server最小 Server两个 tools 即可例如echo与add回包固定便于测。生产 Server 也可在测试里用「只读 list」模式。2. 客户端与传输两条路选一或都做真 stdiospawn 进程连标准输入输出——更接近真实。mock 传输单测里注入固定 JSON-RPC 帧——更快、更稳。团队初期可先 mock 锁 schema再加一条 stdio 冒烟。3. 快照将list_tools规范化 JSON 存为快照审阅后入库。CI 对比快照防止无意漂移。快照变更必须走 PR 说明。4. 用例名称集合相等。某 tool 的inputSchema.required包含预期字段。调用 happy path 返回约定结构。缺必填时错误可解析不要只判断「有报错」。5. CI依赖升级Dependabot/Renovate 或手工必须跑该套件。红了就挡住合并。示例断言伪代码语言可换意思是硬相等tools{t[name]:tfortinlist_tools()}assertset(tools){echo,add}reqtools[add][inputSchema].get(required,[])assertset(req){a,b}resultcall_tool(add,{a:1,b:2})assertresult[content][0][text]3# 依真实回包结构调整schema 字段路径以你使用的 SDK 序列化为准断言要对着真实回包写不要抄过期博客。mock stdio 注意点行缓冲/粘包按 SDK 推荐方式读帧勿假设每次readline一条完整消息。超时子进程挂死要有 timeout避免 CI 卡死。环境测试用临时目录与假密钥禁止读开发者真实.env。清理finally里杀子进程。与 Cursor / 动态加载的关系即使客户端动态加载工具Server 端 schema 仍是契约。客户端少加载只能省前缀不能发现 Server 改坏了名字。测试站在 Server 仓或「工具适配层」仓两端都受益。验收清单CI 无 GUI 跑通tool 名与必填字段硬断言故意改 schema 时变红密钥不出现在夹具README 写明如何跑测试示例已去密钥可推 AtomGit推进 AtomGit 的目录建议mcp-server-min/ src/ tests/test_tools_contract.py snapshots/tools.json README.md .env.example秋季活动里「带契约测试的 MCP 示例」比「又能聊天的 Demo」更耐看。快照审阅清单合并变更snapshots/tools.json时审阅者应问是否有工具被删或改名调用方是否同步必填字段是否减少可能导致静默用默认值或增加可能导致旧客户端失败描述是否暴涨前缀税是否出现疑似密钥的默认值快照不是「让测试通过的金文件」是API 评审附件。mock 与真 stdio 的分工手段优点缺点mock 传输快、稳、易测错误形状可能漏掉进程/缓冲问题真 stdio更接近生产慢、易抖、要清理进程推荐契约断言以 mock 或进程内为主CI 夜跑或预发加一条 stdio 冒烟。破坏性实验请在分支做改 tool 名 → 期望红。删除 required 中的字段 → 期望红。把返回从结构化改成随意字符串 → 期望红。若实验不红说明断言太弱先修测试再修功能。版本钉扎策略在清单文件中钉 MCP SDK 与运行时版本。升级用单独 PR先跑契约测试再更新快照若有意变更最后改 Changelog。禁止「顺便升级」混在业务 PR——静默损坏最爱混战。客户端侧的补充测试可选若你维护 Cursor 用的包装配置可增加启用分组后期望出现的工具名子集测试读配置 对 Server list 做交集断言。这把「动态加载习惯」也固化进 CI。文档模板段落可复制到 README## 测试 - 契约pytest tests/test_tools_contract.py - 更新快照……命令 - 故意改名应失败……说明没有这段的「开源 MCP 示例」活动场上容易被当成不可维护 Demo。最小测试文件结构说明test_tools_contract.py建议分区test_tool_names集合相等。test_required_fields关键 tool 的 required。test_call_echo_okhappy path。test_call_missing_param错误可解析。不要一上来写五十个用例先锁契约再按故障补行为测试。持续集成伪配置示意# 示意字段以你所用 CI 为准test:script:-pip install-r requirements-dev.txt-pytest tests/test_tools_contract.py-qAtomGit Actions / 其他 CI 同理关键是每 PR 必跑不是本地偶发。与资源resources相关的测试若 Server 暴露 resources同样 list/read 断言 URI 前缀与「不可逃逸到仓库外路径」。只测 tools 不够资源 URI 也是攻击面与误配面。保持只读与路径沙箱声明在测试里用故意错误的 URI 期望被拒绝。发布前检查单维护者SDK 版本钉扎契约测试绿快照已审CHANGELOG 记录工具变更示例配置去密钥README 测试段落仍准确维护者比作者更需要这张单——升级依赖的人往往不是当初写 Demo 的人。把测试当作活动故事秋季活动介绍里可写「本示例的 CI 会在工具改名时失败。」这比「支持 AI」六个字更像工程。读者克隆后看到红灯可复现是信任的来源。从坏掉中学习生产一旦出现静默损坏先补契约断言再现再修 Server最后才谈客户端兼容层。顺序反了会修成「兼容所有历史错误」的泥球。手写一版「伪客户端」思路若官方测试工具尚未接入可用最小客户端启动 Server 子进程发送 initialize 与 initialized 通知按规范发送 tools/list解析 JSON断言发送 tools/call关闭。伪代码级别即可起步重要的是进 CI。等 SDK 测试辅助成熟再替换内部实现契约断言可保留。错误注入表注入期望未知 tool 名明确错误非空响应缺必填明确错误类型错误字符串当数字明确错误或按文档拒绝超大参数超时或尺寸拒绝不崩溃留尸错误注入保证「坏输入」时可观测避免客户端挂死。多 Server 仓库的单体测试策略单体仓含多个 MCP Server 时每个 Server 独立测试目录与快照CI 矩阵按目录跑。禁止一个巨型测试文件断言所有 Server——失败定位会地狱化。文档中的「破坏性变更」声明当有意改 tool 名或必填项Changelog 用醒目标记给调用方迁移期并同步更新快照与示例。测试保证你自己先痛而不是用户先痛。系列咬合上接手写最小 MCP、resources/prompts、动态加载习惯下接鉴权与密钥托管实战。契约测试是中间的保险丝。收官与秋季活动里带保险丝的示例比会闪光的 Demo 更像可维护开源。进阶schema 兼容性策略对外部已有调用方的 Server采用加字段可选字段可增必填增属破坏性。改名破坏性需新 tool 弃用期或主版本。删 tool破坏性需公告。放宽类型可能藏脏数据谨慎并补测试。把策略写进docs/compatibility.md契约测试负责执行红线。动态加载再流行也救不了你擅自改名的调用方。FAQQ只做快照对比够不够A不够。快照防漂移行为用例防「结构对但逻辑坏」。Q要不要测 Cursor 本身A一般测 Server 契约即可客户端升级另说。Qmock 会不会假绿A会若 mock 回包过时。定期用真 stdio 冒烟对拍。Q测试失败但功能「看起来能用」A以契约为准先红灯再决定是放宽断言还是修 Server——禁用「先合并再说」。保险丝的意义是让合并变吵吵比静默好。把这句话写进维护者指南升级依赖的人会感谢你。附录最小断言清单打印级tools 名称集合是否与快照一致关键 tool 的 required 是否仍包含约定字段happy path 调用是否返回约定结构缺参错误是否可解析资源 URI若有是否拒绝路径逃逸CI 是否在无 GUI 环境绿故意改名是否变红夹具是否无密钥八条全勾升级才敢点合并。动态加载省前缀契约测试省事故一个管成本一个管信任。将本清单与示例仓 README 对齐后AtomGit 秋季展示就有了可验收故事不是「我们接了 MCP」而是「MCP 改坏会被红灯抓住」。这才是开源工具链该有的成年人味道。实践节奏与责任人指定 Server 「契约责任人」不一定是作者谁合并依赖升级谁先看契约测试。责任人轮值也可但要在 README 写明当前联系方式或团队频道。升级 PR 模板强制勾选「契约测试已本地绿 / CI 绿 / 快照变更已说明」。没有勾选就请评审直接请求修改。对示例仓而言责任人可以是文档里的维护者小节。秋季活动过后若无人维护至少 CI 仍会在破坏时尖叫——这比华丽却失修的 README 更负责任。记住mock stdio、断言 schema、防止静默坏掉这三件事做实了MCP 才从「能 Demo」变成「能养」。养得起的开源才值得别人 star 与二次开发。与排障、动态加载的三角关系动态加载管「默认少注入」契约测试管「升级不静默」排障剧本当「坏了怎么问」。三角缺一只会装、不会测、坏了只会骂模型。把三角写进团队 AI 工程页MCP 生态再吵你的仓库仍有自己的节奏。今晚先让故意改名变红那盏红灯就是信任的开始。收尾提醒测试是保险丝不是装饰。缺断言的 MCP 示例仓升级一次就可能静默坏掉有断言的仓坏掉时至少会吵。把吵声留给 CI把安静留给生产变更窗口——这就是本文想逼近的工程秩序。边界声明MCP 规范与 SDK API 持续演进以官方规范与你钉扎的版本为准。本文不覆盖攻击性 fuzz、越权利用或破解鉴权。draft 未发布。今晚可执行给现有最小 MCP 加list_tools名称断言。加一条必填字段断言。故意改名看 CI 是否红。写 README「如何跑测试」并推 AtomGit。静默损坏的对面是嘈杂但诚实的红灯。把 schema 测红比在 IDE 里猜一天便宜。