MCP Server 可用性评分不及格：协议合规不等于 Agent 能用

对 36 个热门 MCP 静态评分显示约三分之一得 D/F。主因是参数无 description。本文总结失败模式、mcpgrade 用法，以及自建/选型检查清单。

Teng Li 用开源工具 mcpgrade 扫了 36 个常见 MCP Server：协议可以完全合规，Agent 仍然选错工具、瞎填参数，或把模糊目录里的「看起来像」工具乱调用。约三分之一落到 D/F——问题不在 JSON-RPC，而在描述、命名、schema 是否写给人模型看。

核心结论：可用性 ≠ 合规

MCP 规范管传输与 schema 形状，不管「模型能不能用」。静态扫描高频失败项是 D004：参数没有 description。

典型现象：

从 Zod/OpenAPI 生成 schema，类型有了，.describe() 没人写
模型只看到 url: string，不知道是页面 URL、Webhook，还是文档链接
工具一多、命名近似（extract vs scrape），选错率明显上升

作者用小模型做 live eval：文档写得好的服务器工具选择可到 100%；文档烂的（如评测中的 firecrawl 快照）会掉到约 84%，且错误落在静态规则已标出的命名冲突上。更危险的是 该拒绝时不拒绝：模糊大目录上，模型对越界任务仍「找到一个差不多的工具」去调——生产里等于乱动手。

一句话：MCP 传输层过了 lint，只说明「能连上」；Agent 能不能选对、填对，看 descriptions 和命名。

分数背后的几类坑

坑	表现	优先修法
无参数描述	descriptions 分直接崩	每个参数写格式 + 一例值
目录过大且糊	token 税高、拒识差	拆 server 或砍低价值工具
近义工具名	选错工具	`verb_object`、禁止双胞胎名
只追更新频率	活跃商业 server 也可能 0 描述	把「可写性」当发布门槛
归档参考实现反而高分	曾经手写过完整文档	说明：维护≠可用性

榜单是时点快照；context7 曾在修复参数描述后从 C 拉到满分静态分——可见缺口一旦可见，修起来很快。完整表见作者站点 leaderboard。

坏 schema vs 好 schema（复制即用）

不及格（模型只能猜）：

{
  "name": "fetch",
  "description": "Fetch data",
  "inputSchema": {
    "type": "object",
    "properties": {
      "url": { "type": "string" },
      "mode": { "type": "string" }
    }
  }
}

及格线（模型能一次填对）：

{
  "name": "fetch_page_markdown",
  "description": "Fetch a public HTTPS page and return markdown. Use for docs only, not for authenticated APIs.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "url": {
        "type": "string",
        "description": "Full HTTPS URL, e.g. https://example.com/docs"
      },
      "mode": {
        "type": "string",
        "enum": ["markdown", "html"],
        "description": "Output format; default markdown"
      }
    },
    "required": ["url"]
  }
}

差别不在类型，而在动词+对象命名、何时用、示例值、enum 代替散文。

用 mcpgrade 给自己的 Server 打分

无需 API Key 的静态扫描：

npx mcpgrade --stdio "npx -y your-mcp-server"
npx mcpgrade --stdio "node ./my-server.js"
npx mcpgrade https://my-server.example/mcp
npx mcpgrade &lt;target> --fail-on error   # CI 门禁
npx mcpgrade &lt;target> --eval            # 需自备模型 Key

如何读报告：

输出项	含义	行动
Overall grade	静态可用性汇总	D/F 先修 D004
D004 计数	缺 description 的参数个数	逐个补 `.describe()`
descriptions 子分	参数文档质量	加示例与格式说明
`--eval` 结果	小模型 live 选工具	验证改名后是否提升

CI 建议：合并前 --fail-on error，把「无 description」当成构建失败，而不是「以后再写文档」。npx 首次拉包慢时，CI 里 pin 版本或预装 mcpgrade。

接 MCP 做产品能力时，先保证工具可被选中，再谈花活；能力地图见 Claude Code / Cursor 接 MCP 能做什么。安全上，可用性差会放大乱调工具的风险，可与 MCP ANSI 转义注入一起做评审。

「好」长什么样（可直接当 PR 模板）

每个工具描述回答三问：做什么 / 何时用 / 返回什么
每个参数有描述，含格式与示例值
固定取值用 enum，别写在散文里
显式声明 required（哪怕为空）
统一命名，避开通用动词堆叠
错误信息点名缺哪个参数，方便模型一轮自纠

大目录也能拿 A（例如精心写过的多工具 server），但默认不会「自动变好」——每加一个工具就多一份写作债。PR review checklist 可加一条：mcpgrade --fail-on error 绿。

选型与自建决策

选型：别只看 GitHub star 与「官方」字样；跑一遍 mcpgrade，看 descriptions 是否为 0。
自建：生成器链路强制 .describe() / OpenAPI description 透传。
平台：团队统一 MCP 分发时，把评分报告挂进评审，参考 Cursor Team Marketplace 分发 MCP。
Fork 第三方 F 分 server：只改 description 往往就能升一档；upstream PR 一并提。

国内开发者：npx mcpgrade 走 npm，与 MCP server 本体一样可能受网络影响；CI 建议缓存 node_modules 或内网 Verdaccio。选型时别迷信「某某大厂的 MCP 一定好用」——评测里活跃商业 server 照样 0 描述。

从 F 拉到 B 的最小修复包（通常半天内）

Rename：fetch → fetch_public_https_page，消灭泛动词
Tool description：补「何时用 / 何时不用」各一句
参数：每个 string 加 description + 示例 URL 或 ID
enum：把 mode、format 等封闭集合写进 schema
required：显式列出，别让模型猜可选参数
再跑 npx mcpgrade --fail-on error，确认 D004 归零

若 live eval 仍选错工具，多半是近义工具未合并——把 scrape_url 和 extract_url 合成一个，用 enum 区分输出格式，比两个模糊工具强。

Agent 侧临时兜底（server 一时修不了）

手段	代价
系统提示写死「只准调用 xxx_tool」	brittle，换 server 要改提示
MCP 配置里 disable 部分 tools（若客户端支持）	推荐，减目录噪音
Wrapper server 转发并补 description	维护成本中等
Fork 上游补文档再 `npx` 本地路径	适合长期私用

兜底是过渡，不是替代 mcpgrade——F 分 server 在工具变多后几乎必然误调。

组织内发布 MCP 时的门禁建议

若你在维护 Team Marketplace 或内部 MCP 目录，可把静态分写进准入规则：

新 server 合并：mcpgrade --fail-on error 必须通过
Major 版本：重新跑 eval，对比工具选择准确率
文档站：README 放最新 grade 截图，别只贴「Official」徽章
安全并联：可用性 B 以上再接入生产 Agent；同时过 AESI / 权限 checklist

这样 Agent 侧少踩「连上了但乱调」的坑，也避免 star 数误导采购。Marketplace 分发细节可参考 Cursor Team MCP 配置一文里的集中配置段落。

维护者常问：「参数已经用 TypeScript 类型写清楚了，为什么还要 description？」——模型读的是 JSON Schema，不是 TS 类型文件；string 无法区分「ISO 日期」与「任意 slug」。把 .describe() 当成 API 文档的必填字段，和写 OpenAPI 一样省不了。

常见问题

静态分高就一定生产安全吗？

不一定。静态分代理「模型是否看得懂」；权限、注入、密钥泄露要另做。高分只说明「更不容易选错工具」。Security 评审仍要做最小权限、AESI 消毒、Secrets 隔离。

第三方 Server 得了 F 还能用吗？

能，但要降期望：少暴露工具、在系统提示里写清何时调用，或 fork 补 description 再私用。生产环境尽量 whitelist 工具子集，别把整本 40+ 工具的目录全塞给 Agent。

和 MCP lint 类工具重复吗？

作者对比过合规向 lint 与可用性向 grade：轴不同。合规过了仍可能 Agent 不可用——正是这篇要打的点。理想流水线：lint（协议）→ mcpgrade（可用性）→ 安全扫描（注入/权限） 三道门。

MCP Server 可用性评分不及格：协议合规不等于 Agent 能用

核心结论：可用性 ≠ 合规

分数背后的几类坑

坏 schema vs 好 schema（复制即用）

用 mcpgrade 给自己的 Server 打分

「好」长什么样（可直接当 PR 模板）

选型与自建决策

从 F 拉到 B 的最小修复包（通常半天内）

Agent 侧临时兜底（server 一时修不了）

组织内发布 MCP 时的门禁建议

常见问题

静态分高就一定生产安全吗？

第三方 Server 得了 F 还能用吗？

和 MCP lint 类工具重复吗？

参考资料