ContextJet-ai/mcpvitals
GitHub: ContextJet-ai/mcpvitals
mcpvitals 是一款 MCP 服务器一键健康检查工具，通过健康评分、token 成本分析、工具混淆检测、安全卫生审计和协议迁移就绪度评估，帮助开发者和使用者在发布或信任服务器前全面了解其质量与风险。
Stars: 0 | Forks: 0
# mcpvitals
**您的 MCP 服务器的生命体征。只需一条命令即可获得健康评分，以及别人无法提供的检查项。**
[](https://github.com/ContextJet-ai/mcpvitals/actions/workflows/tests.yml)
[](https://pypi.org/project/mcpvitals/)
[](LICENSE)
[](https://www.contextjetai.com)
## 60秒快速上手
无需安装。将其指向任何 MCP 服务器（一个 stdio 命令或一个 http url）：
```
uvx mcpvitals check "npx -y @your/mcp-server"
```
```
mcp health: 40 (F)
x MV020 [run_sql] tool 'run_sql' appears to contain a hard-coded secret
-> never ship keys in tool metadata; use env vars
x MV022 [run_sql] description contains model-directed instructions (poisoning surface)
-> tool descriptions should describe, not instruct the model
! MV030 [run_sql] tool 'run_sql' costs ~410 tokens to expose
-> trim the description/schema; it inflates every request
! MV040 tools 'get_user' and 'fetch_user' are 0.91 similar; agents may pick the wrong one
-> differentiate names/descriptions or merge them
i MV050 protocol 2025-03-26 predates the 2026-07-28 stateless spec
```
## 检查内容
大多数 linter 仅停留在基础的一致性检查上。`mcpvitals` 不仅会运行这些检查，还会执行其他四种任何工具都没有的检查：
| 领域 | 捕获的问题 |
|---|---|
| **一致性** | 空的工具描述、重复的工具名称、格式错误的 schema |
| **可靠性** | 没有 `required` 列表的参数、无类型的参数、错误路径缺失 |
| **安全卫生** | 工具元数据中的机密信息、范围过广的工具（`run_sql`、`exec`）、描述中由模型指示的指令（工具投毒攻击面） |
| **Token 成本** | 每个工具在上下文窗口中消耗的 token 数量，以及连接服务器的总成本 |
| **工具混淆** | 智能体容易混淆的工具对，*在生产环境发生之前*根据名称/描述的重叠度进行预测 |
| **迁移就绪度** | 在 2026-07-28 无状态规范下会破坏哪些内容 |
每项检查都是评分确定的纯函数。运行 `mcpvitals check --json` 获取机器可读的输出。
## 将健康徽章添加到您的 README
`mcpvitals` 会生成一个可分享的徽章，以便一目了然地查看好成绩：
```
mcpvitals check "npx your-server" --badge badge.svg
```
或者使用 shields.io endpoint 输出以保持其实时更新。
## 在 CI 中使用
使用内置的 GitHub Action 在每次推送时对您的服务器进行门控检查：
```
- uses: ContextJet-ai/mcpvitals@v0
with:
target: "python -m your_server"
strict: "true" # fail the build on any error-level finding
```
## 跟踪和监控（不仅仅是单次检查）
固定服务器的工具，并在它们发生更改时收到警报。这可以捕获**“暗中替换”**，即您已批准的服务器在事后悄悄地篡改了工具的 schema 或描述：
```
mcpvitals watch "npx your-server" # pins tools to mcp.lock
mcpvitals watch "npx your-server" --check # re-run in CI; fails if a pinned tool changed
```
探查正在运行的服务器以获取实时健康状况（正常运行时间和延迟）：
```
mcpvitals monitor "https://your-server/mcp" --count 5
# probe 1/5: up 210ms ... uptime 100.0% avg 207ms
```
## 存在原因
MCP 生态系统的发展速度超过了其周边工具的发展速度。目前有数以千计的服务器，但却没有标准的方法来判断一个服务器是否优秀、安全或运行成本低廉。`mcpvitals` 为作者在发布前提供了一条命令的检查，并为其他所有人提供了一种在信任服务器之前进行审查的方法。
由 [ContextJet.ai](https://www.contextjetai.com) 构建。MIT 许可证。欢迎贡献，请参阅 [CONTRIBUTING.md](CONTRIBUTING.md)。标签：AI安全规范, DLL 劫持, MCP, Python, SOC Prime, 代码质量检查, 大语言模型, 开发工具, 无后门, 逆向工具