MCP Doctor
Check and improve the contract quality of any MCP server — for humans, agents, and platforms.
问题
大多数MCP服务器在构建时只考虑一个受众（通常是阅读README的人类开发人员）。但一个成功的MCP服务器需要同时满足三个受众：
- 分销平台 （Registry、Smithery、PulseMCP、Glama）需要结构化元数据
- 人类用户 需要明确的目的、信任信号和低安装摩擦
- AI代理 需要明确的工具描述、声明的副作用和令牌高效的响应
MCP医生检查“合同质量”的所有六个维度，并为您提供可操作的建议。
快速开始
pip install mcp-doctor
mcp-doctor check /path/to/your-mcp-server它检查什么
| 维度 | 问题 |
|---|---|
| 任务清晰度 | 服务器的用途是否立即明确？ |
| 信任与安全 | 是否声明了副作用、许可和安全界限？ |
| 界面质量 | 工具的名称、描述和类型是否恰当？ |
| 代币效率 | 工具响应是否符合代理的上下文预算？ |
| 安装摩擦力 | 一个人从发现到首次使用的速度有多快？ |
| 跨平台就绪 | Registry、Smithery、PulseMCP、Glama的元数据是否完整？ |
用法
命令行界面
# Terminal output (default, rule-based)
mcp-doctor check /path/to/server
# JSON output (for CI/CD)
mcp-doctor check /path/to/server --format json
# Markdown output (for README badges or reports)
mcp-doctor check /path/to/server --format markdown
# AI-enhanced evaluation (requires OPENAI_API_KEY)
mcp-doctor check /path/to/server --mode ai
# AI mode with a specific model
mcp-doctor check /path/to/server --mode ai --model gpt-4o作为MCP服务器
MCP Doctor也是一个MCP服务器，因此AI代理可以使用它来检查其他服务器：
{
"mcpServers": {
"mcp-doctor": {
"command": "python",
"args": ["-m", "mcp_doctor.mcp_server"]
}
}
}工具：
check_server(path, format, mode, model)--运行所有6个检查。使用mode="ai"法学硕士强化复习。list_dimensions()--列出MCP医生评估的内容
对于AI代理：快速安装
一个衬垫 （将此粘贴到您的AI代理）：
安装mcp医生(pip install mcp-doctor)并使用命令将其添加到MCP配置中python -m mcp_doctor.mcp_server。然后使用check_server用于检查任何MCP服务器质量的工具。
一步一步地：
- 安装：
pip install mcp-doctor - 添加到MCP配置中：
{
"mcpServers": {
"mcp-doctor": {
"command": "python",
"args": ["-m", "mcp_doctor.mcp_server"]
}
}
}- 使用
check_server带有指向任何MCP服务器仓库的路径的工具 - 如果MCP不可用，请返回CLI：
mcp-doctor check /path/to/server --format json
代理工作流程： 检查服务器->查看分数->确定最低维度->遵循建议
评分
每个维度的得分为0-100，分为A/B/C/D：
- A. （90+）：典范
- B （75-89）：良好，差距较小
- C （55-74）：充分、显著的差距
- D （\<55）：需要大幅改进
理论基础
MCP Doctor基于 合同质量框架 --一个成功的MCP产品的承诺（它的作用、成本、风险）应该同样可以被平台、人类和代理解析的原则。
该框架借鉴了：
- Anthropic的“为代理编写有效工具”（工具描述工程、命名空间、令牌效率）
- MCP注册表官方要求（server.json模式、命名空间验证）
- Smithery、PulseMCP、Glama排名信号的跨平台分析
评估模式
| 模式 | 标志 | 确定性 | 网络 | API密钥 |
|---|---|---|---|---|
| 基于规则 （默认） | --mode rule | 是 | 否 | 否 |
| AI增强 | --mode ai | 否 | 是（LLM API） | OPENAI_API_KEY |
基于规则的模式 完全离线且具有确定性。无需网络调用，无需LLM，无需API密钥。
AI模式 将元数据摘要（服务器名称、工具定义、自述预览、基于规则的分数）发送到与OpenAI兼容的API进行定性审查。没有发送源代码。报告包括型号名称和版本，以确保可重复性。
AI模式支持任何与OpenAI兼容的提供商：
OPENAI_API_KEY-API键（AI模式需要）OPENAI_BASE_URL--自定义端点（适用于Ollama、vLLM、LM Studio、Azure等）MCP_DOCTOR_MODEL--型号名称（默认值：gpt-4o-mini)
安装AI支持： pip install mcp-doctor[ai]
信任和权限
MCP医生 只读。它从不修改、删除或创建文件。
| 它访问什么 | 为什么 |
|---|---|
server.json | 解析MCP元数据 |
README.md | 检查文件质量 |
LICENSE | 验证许可证是否存在 |
*.py, *.json 在 src/ | 检测工具定义 |
所有MCP工具都具有 readOnlyHint: true 和 destructiveHint: false 注释。
反馈
发现bug了吗？有什么建议吗？我们很乐意收到您的来信：
- GitHub 问题: https://github.com/Jiansen/mcp-doctor/issues
- 快速报告 （如果你有
ghCLI）：
gh issue create --repo Jiansen/mcp-doctor --title "Bug: ..." --body "..."如果您是代理，请包含以下JSON输出 check_server 在你的报告中提供背景信息。
贡献
git clone https://github.com/Jiansen/mcp-doctor.git
cd mcp-doctor
pip install -e ".[dev,ai]"
ruff check src/ tests/
pytest tests/ -v______________________________________________________________________
如果MCP Doctor帮助您改进了服务器，请考虑在GitHub上给它一颗星——它可以帮助其他人发现该工具。
许可证
麻省理工学院