15755/15977：一个开源工具给MCP服务器做全身体检

一个Agent靠不靠谱，取决于它调用的工具。但大多数MCP服务器，从来没被任何东西检查过。

工具没写描述，永远不会被选中。参数写成 str = None，反而拒绝了它自己声明的默认值。写入工具回一句"Successfully wrote"，实际上什么都没写。

mcp-doctor 就是为了抓这些坑而生的。它已经长成一个覆盖MCP服务器完整生命周期的开源工具：上线前、每个PR里、以及运行中的Agent内部。

1. 上线之前

装法很简单：pip install mcp-server-lint，然后 mcp-doctor path/to/your/server。

Lint会读取Python、TypeScript和Go源码，不运行代码，把质量和安全分开打分。这样做的用意很直接：一个文档写得漂亮的服务器，没法用一个混合分数把安全漏洞藏起来。

质量项覆盖的是那些真正会让Agent翻车的问题：工具缺描述、参数没文档、None默认值拒绝null、stdio上乱写stdout、两个工具的描述让人分不清区别。

安全项覆盖：工具投毒话术、动态exec、易受SSRF攻击的请求、不安全的反序列化、硬编码密钥，以及说谎的只读注解。

--fix 只应用不需要判断的修复：可空的None默认值、缺失的Args条目、裸except。在三个仓库上，针对同一个bug手写PR，它产出的类型改动完全一致。

--diff-against 用来对比两个版本，标出被删掉的工具、被删掉的参数、或者新增的必填参数——这些改动会悄悄弄坏一个已经学会旧结构的Agent。

2. 每个PR里

GitHub Action（uses: vishalhabib99/mcp-doctor@v1）会在每个PR下评论，在它改动的行上给出一键修复建议，还能让分数跌破阈值的PR直接失败。pre-commit钩子则在提交落地前跑同一套检查。

3. Agent内部：guard

静态检查看不出一次调用到底有没有成功。mcp-doctor guard 把任意stdio MCP服务器跑在实时检查后面，每条消息原样通过；当某个"成功"并不是成功时，它加上一条Agent能读到的警告。

它会标记这些情况：

• 写入报告成功，但对应的读取找不到它
• schema里没有的参数，被服务器悄悄丢掉
• 等待提前返回，却声称等满了全部时间
• 错误或拒绝被当成成功答案返回、空读取、破坏工具自身outputSchema的输出
• 疑似提示注入泄露：一次调用读到的密钥即将被另一次调用发出去，或者一个仓库的文本在会话读过外部内容后即将被写进另一个仓库

同一个坏掉的 write_file、同一个提示词，在Claude Code里：没有guard时，回答是"Yes, the file was saved."；有guard时，回答是"I can't confirm the file was saved."

对编码Agent，mcp-doctor-guard 的Claude Code插件把同样的思路用在Agent自己的工具上（shell、文件写入、网页抓取）。一次用Haiku在bypassPermissions下的实跑中，没有guard的Agent读了一个网页，然后埋了个 .git 钩子，把 .env 里的token发给了服务器。有guard时，两个动作都被拦下，Agent也没再尝试别的路径。

4. 在哪儿都能用

• 浏览器里：粘贴仓库、npm或PyPI名字。真正的mcp-doctor在页面里跑（Pyodide），不上传也不执行任何东西
• GitHub issue：开一个扫描请求，机器人回复报告
• Claude Code插件：说一句"check my MCP server"，Claude扫描、解释每条发现，并在你同意后修复它能修的
• fix-upstream：一个把发现变成带测试PR的Agent，由人review后发出

它凭什么可信

召回率是公开的：在5个框架的805个真实服务器上，它找到了15977个工具中的15755个，每一次漏报都列在 docs/coverage.md 里。

mcp-doctor自己身上有113个bug，都是拿它在真实服务器上跑出来的，全部已修（有构建日志）。外部仓库的维护者合并了48个修复，分布在46个仓库里，包括langflow和ha-mcp。第一个外部CI用户是jupyter-mcp-server，其维护者主动要求后，当天就加上了这个Action。

边界在哪

guard目前只覆盖stdio服务器，还不支持HTTP；只有当服务器有对应的读取工具时，它才能确认一次写入；它匹配的是被复制的文本，所以改写过措辞的泄露可能溜过去。它是模型被骗时的一张网，不是最小权限token的替代品。

拿它跑跑你的服务器，然后告诉它哪里判断错了：github.com/vishalhabib99/mcp-doctor