我评估了36个热门MCP服务器的代理可用性，三分之一得了D或F

# 我给 36 个流行的 MCP 服务器做了 lint 扫描。三分之一正在让你的 Agent 翻车 · Teng Li 来源: https://tengli.dev/posts/mcp-servers-failing-agents.html 2026-07-21 Agent | MCP | 工程 你的 MCP 服务器可以 100% 符合规范，但依然无法被 Agent 使用。 模型上下文协议规范告诉你如何*传输*工具：JSON-RPC 框架、能力协商、Schema 形状。但它丝毫未提模型是否真的能*用*你提供的东西——是否能从你的工具目录里挑出正确的工具、填对参数、是否每次请求都花 8k token 来解析你的 Schema。 我的日常工作就是为生产环境的人工智能 Agent 集成第一方和第三方的 MCP 连接器，我反复看到同样的失败：服务器通过了所有合规检查，但模型却调用了错误的工具、编造参数，或者干脆无视工具。问题从来不在协议层。问题出在没人 lint 的部分：描述、命名、Schema 设计。 所以我写了 `mcpgrade`（https://github.com/TengByte/mcpgrade）——一个给 MCP 服务器用的 Lighthouse 风格评分卡。一条命令，无需 API 密钥，几秒出报告： ```bash npx mcpgrade --stdio "npx -y your-mcp-server" ``` 然后我对着 36 个流行服务器跑了一遍。结果不太乐观。 ## 结果 完整可排序表格：[https://tengli.dev/mcp-leaderboard.html](https://tengli.dev/mcp-leaderboard.html)。 简版（静态分析，时间点快照；标记 *（已归档）* 的服务器是无人维护的参考实现，但因为仍被广泛安装和复制，所以包含在内）： **最优等（A）：** brave-search*（已归档）*、exa、google-maps*（已归档）*、slack*（已归档）*、perplexity-ask、@shopify/dev-mcp、@apify/actors-mcp-server、airbnb、figma-developer-mcp、tavily、gitlab*（已归档）*、elastic、shrimp-task-manager 等——36 个中的 15 个。 **最差等（D/F），36 个中的 11 个——而且不是个人项目：** MongoDB 的官方服务器（66 分，66 个错误）、Notion 的官方服务器（62 分）、Airtable（69 分，66 个错误）、todoist-mcp-server（67 分，**110 个错误**）、GitHub 的归档参考服务器（67 分，44 个错误），以及 firecrawl-mcp 排在最后（57 分，**134 个错误**）。 还有两个服务器（Stripe、Supabase）因无法用假凭证扫描而被排除，未参与评分。 ## 发现 1：生态系统中存在普遍的无文档参数问题 几乎所有 D/F 服务器都在**描述评分上得了零分**，而 Schema、命名和 token 评分却没问题。一条规则占了主导：`D004——参数没有描述`。 - firecrawl：134 个错误中有 132 个是未文档化的参数。`url`、`formats`、`jsonOptions`——模型只得到一个名字和类型，除此之外什么也没有。 - todoist：110 个。 - MongoDB 和 Airtable：各 66 个。 根因在几乎所有服务器的源代码中都能看到：**Schema 是从 zod 或 OpenAPI 定义生成的，但没人加上 `.describe()`**。类型系统知道 `url: string`。模型却需要知道*哪个* URL、什么格式、有什么约束。你的 Schema 生成器正安静地剥离着你的工具所拥有的、最重要的那个信号。 如果你从这篇文章中只带走一件事：打开你的服务器，数一数没有 `description` 的参数，然后修复它们。这是你在 Agent 可靠性上能花的最具杠杆效应的一小时。 ## 发现 2：这是文档纪律问题，不是目录大小问题——但规模让纪律更难遵守 我对数据的初步分析暗示“小目录赢”：大多数 95+ 得分者工具较少，而 24–26 个工具的服务器集中在 D/F 档。然后 shrimp-task-manager 以 **A/96 的分数、15 个工具** 杀了出来——精心文档化、命名紧凑、每个描述都截然不同。所以诚实的版本是：**文档化良好的大目录是可能的，只是很罕见。** 你每添加一个工具，就多了一个要写的描述、一个可能冲突的名字、一个要收紧的 Schema。纪律不会自动扩展。（规模无论如何都会使你付出代价：每次请求都要序列化整个目录。） ## 发现 3：合规性与可用性是两个不同的维度 更新最频繁的服务器并不一定是最可用的。*已归档的* Slack 参考服务器——没有人维护的代码——得到了 A/97 分，因为当初有人手动为每个工具和每个参数写了文档。与此同时，几个积极开发的商业服务器输送的参数却完全没有描述。 Agent 的可用性更多是*写作*问题，而不是工程问题。合规检查工具无法衡量这一点。而这正是 mcpgrade 填补的空白。（一个令人鼓舞的反例：在写这篇文章期间，context7 发布了一个新版本，修复了所有缺失的参数描述——从 C 档跳到了完美的静态分数。当差距可见时，生态系统的反应速度可以很快。） ## 发现 4：我用真实模型对比了静态分数。令人担忧的数字是“拒绝率” 静态 lint 只是一个代理指标，所以我构建了 `--eval`：它合成现实的一步式任务（每个任务都为每个必需参数嵌入具体值），向模型展示整个目录，然后测量模型是否选对了工具并填入了有效参数。校准细节和方法：docs/eval-calibration.md（https://github.com/TengByte/mcpgrade/blob/main/docs/eval-calibration.md）。 成本：在一个小模型上，每个服务器只需几分钱。有两个结果值得你注意： **静态发现能预测真实混淆。** 在文档良好的服务器上，工具选择准确率是 100%。在 firecrawl 上下降到 84%——而且失误恰恰落在静态规则标记出的命名冲突上：`extract` ↔ `scrape`、`agent_status` ↔ `check_crawl_status`、`feedback` ↔ `search_feedback`。 **大而模糊的目录会破坏拒绝率。** 对于故意超出范围的任务，模型在小而文档良好的目录上 100% 正确拒绝——但在 firecrawl 的 26 个模糊工具上只做到了 **50% 的拒绝率**。有一半的时间它“找到”了一个看似合适的工具并调用了它。在生产环境中，这就是 Agent 本应*什么都不做*时却做了*某些事*——可以说这是最危险的失败模式。 ## “好”的标准是什么 从高分服务器来看，一份检查清单： - 每个工具描述回答三个问题：它做什么、何时使用、它返回什么。 - 每个参数都有描述，包含格式和一个示例值。 - 固定值集合放在 `enum` 里，而不是写在散文中。 - `required` 明确声明——即使它为空。 - 使用统一的命名惯例：动词_宾语风格，没有泛泛的动词，没有近似的孪生名字。 - 错误信息指明缺失/无效的参数，以便模型能在一次交互中自我纠正。 ## 在你的服务器上试试 ```bash npx mcpgrade --stdio "node ./my-server.js" # 本地 stdio npx mcpgrade https://my-server.example/mcp # 可流式 HTTP npx mcpgrade --fail-on error # CI 门控 npx mcpgrade --eval # 实时模型测试（自带密钥；任何兼容 OpenAI 的端点都可以） ``` 24 条规则，每条都有具体的修复方法和理由，欢迎在 issues 里讨论——规则集本质上是带有设计倾向的，我宁愿公开争论。（它与 mcp-lint 及其他 MCP 质量工具的区别——附有并排输出比较：docs/comparison.md（https://github.com/TengByte/mcpgrade/blob/main/docs/comparison.md）。） 如果你维护以上某个服务器并修复了分数，可以开一个 `rescan` issue——我很乐意重新运行并更新表格。给自己服务器提 PR 比跟我的规则集争论更有用。 --- *我在一家大型科技公司负责生产环境 AI Agent 的集成；mcpgrade 是一个个人项目，反映了我集成数十个 MCP 连接器留下的伤痕。与上述任何排名中的服务器均无关联。* --- ← 所有文章（https://tengli.dev/writing.html）