内容
# mcpgrade
> **MCP 服务器的 Lighthouse.** 您的服务器可以 100% 符合规范，但仍然会失败代理 — 描述模糊、令牌消耗过大的模式、易混淆的工具名称。mcpgrade 评估合规性检查无法评估的内容：LLM 是否实际上可以使用您的工具。
```bash
npx mcpgrade https://your-server.example.com/mcp # 可流式传输的 HTTP
npx mcpgrade --stdio "node ./my-server.js" # 本地 stdio 服务器
npx mcpgrade --snapshot tools.json # 保存的工具/列表输出
```
零配置。无需 API 密钥。秒级报告。
## 检查内容
| 类别 | 权重 | 示例 |
|---|---|---|
| **描述** | 30% | 缺失/过短的描述、未文档化的参数、占位文本、重复描述 |
| **模式设计** | 30% | 缺失类型、无 `required` 数组、`additionalProperties: true`、使用文本而不是枚举、深度嵌套 |
| **命名** | 15% | 易混淆的名称（`get_user` vs `get_users`）、通用动词（`process`）、混合约定 |
| **令牌成本** | 15% | 目录总预算、每个工具的预算 — 代理在*每次*请求时都会支付您的模式费用 |
| **一致性** | 10% | 目录范围内的统一；使用 `--probe` 进行实时检查，错误消息帮助模型自我纠正 |
每个发现都附有具体的修复方法。分数是密度归一化的：3 个损坏的工具中的 3 个是 F；30 个中的 3 个是凹痕。
## 示例
```
mcpgrade — 代理可用性报告
目标：examples/bad-server.json · 4 个工具
F 37/100
描述 ░░░░░░░░░░░░░░░░░░░░ 0
命名 ███████████░░░░░░░░░ 55
模式设计 ███░░░░░░░░░░░░░░░░░ 13
令牌成本 ████████████████████ 100
一致性 ████████████████████ 100
发现：6 个错误 · 10 个警告 · 2 个信息
描述
✖ D002 [get_user] "get_user" 的描述只有 12 个字符（"获取用户。）。
↳ 扩展到至少一个完整的句子：它做什么、何时使用它、它返回什么。
...
```
## CI
```bash
mcpgrade <target> --json # 机器可读
mcpgrade <target> --fail-on error # 错误时退出 1 — 门控您的 PR
mcpgrade <target> --disable S008,N001 # 调整规则
mcpgrade rules # 列出所有规则
```
## 为什么
我将第一方和第三方 MCP 连接器集成到生产 AI 代理中。大多数 MCP 服务器在代理中失败的相同十种方式 — 这些在规范合规性检查中都不会显示出来。 所以我编写了这个我希望服务器作者在交付前运行的校验工具。
## mcpgrade vs mcp-lint
不同的工具，不同的问题。 [mcp-lint](https://www.npmjs.com/package/mcp-lint) 检查您的工具模式是否在客户端（Claude、Cursor、OpenAI 严格模式等）正确解析 — 语法级兼容性。mcpgrade 衡量模型是否可以实际*使用*您的工具 — 描述质量、命名混淆、令牌经济和实时 LLM 工具选择准确性。服务器可以通过 mcp-lint 检查，但在此处仍可能获得 F 分，反之亦然。它们可以很好地组合使用：使用 lint 进行兼容性检查，使用 grade 进行可用性评估。完整的并排比较及具体输出： [docs/comparison.md](docs/comparison.md)。
## 路线图
- [x] v0.1 — 静态 lint 引擎，24 条规则，A–F 评分
- [x] v0.2 — `--eval`：LLM 驱动的实时测试 — 合成任务生成、盲工具选择、参数验证、拒绝准确性和混淆对。校准于真实服务器（[方法论](docs/eval-calibration.md)）；在 Haiku 上花费约 0.05–0.2 美元/服务器。 自带 `ANTHROPIC_API_KEY`，或通过 `--eval-base-url` 使用任意 OpenAI 兼容端点（DeepSeek、OpenRouter 等）； `--eval-mock` 离线运行。 尊重 `HTTPS_PROXY`。
- [ ] v0.3 — GitHub Action、动态徽章、热门 MCP 服务器公开排行榜
## 许可证
MIT
MCP 市场