MCP Doctor

MCP Doctor

检查并提升任意 MCP 服务的契约质量，满足人类、Agent 和平台的需求。

问题

大多数 MCP 服务只面向一种受众构建（通常是阅读 README 的人类开发者）。但成功的 MCP 服务需要同时满足三类受众的需求：

• 分发平台（Registry、Smithery、PulseMCP、Glama）需要结构化元数据
• 人类用户需要清晰的用途、可信信号和低安装门槛
• AI Agent需要明确无歧义的工具描述、声明副作用，以及节省 Token 的响应

MCP Doctor 会检查“契约质量”的全部六个维度，并提供可执行的改进建议。

快速开始

pip install mcp-doctor
mcp-doctor check /path/to/your-mcp-server

检查内容

维度	问题
任务清晰度	是否能立即理解服务的用途？
信任与安全	是否声明了副作用、权限和安全边界？
接口质量	工具的命名、描述和类型是否恰当？
Token 效率	工具响应是否能控制在 Agent 的上下文预算内？
安装门槛	用户从发现到首次使用需要多长时间？
跨平台就绪度	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 Agent 可以用它检查其他服务：

{
  "mcpServers": {
    "mcp-doctor": {
      "command": "python",
      "args": ["-m", "mcp_doctor.mcp_server"]
    }
  }
}

工具：

• check_server(path, format, mode, model) — 运行全部 6 项检查。使用 mode="ai" 启用大模型增强审查。
• list_dimensions() — 列出 MCP Doctor 的评估项目

面向 AI Agent：快速安装

单行安装命令（将其粘贴给你的 AI Agent）：

安装 mcp-doctor（pip install mcp-doctor），并使用命令 python -m mcp_doctor.mcp_server 将其添加到 MCP 配置中。然后使用 check_server 工具检查任意 MCP 服务的质量。

分步操作：

1. 安装：pip install mcp-doctor
2. 添加到 MCP 配置：

   {
     "mcpServers": {
       "mcp-doctor": {
         "command": "python",
         "args": ["-m", "mcp_doctor.mcp_server"]
       }
     }
   }
   

3. 使用 check_server 工具，并指定任意 MCP 服务仓库的路径
4. 如果无法使用 MCP，则改用命令行：mcp-doctor check /path/to/server --format json

**Agent 工作流：**检查服务 -> 审查评分 -> 找出得分最低的维度 -> 按照建议改进

评分

每个维度的评分为 0-100，并按 A/B/C/D 等级划分：

• A（90+）：表现出色
• B（75-89）：良好，存在少量不足
• C（55-74）：尚可，存在明显不足
• D（<55）：需要大幅改进

理论基础

MCP Doctor 基于契约质量框架：成功的 MCP 产品所作出的承诺（它能做什么、需要付出什么代价、会带来哪些风险），应当能够被平台、人类和 Agent 同等清晰地解析。

该框架参考了：

• Anthropic 的《为 Agent 编写有效工具》（工具描述工程、命名空间、Token 效率）
• 官方 MCP Registry 要求（server.json 架构、命名空间验证）
• 对 Smithery、PulseMCP、Glama 排名信号的跨平台分析

评估模式

模式	标志	确定性	网络	API 密钥
基于规则（默认）	--mode rule	是	否	否
AI 增强	--mode ai	否	是（大模型 API）	OPENAI_API_KEY

基于规则的模式完全离线且结果确定。不会发起网络调用，不使用大模型，也不需要 API 密钥。

AI 模式会将元数据摘要（服务名称、工具定义、README 预览、基于规则的评分）发送至兼容 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 Doctor 仅供读取。它绝不会修改、删除或创建文件。

访问内容	用途
server.json	解析 MCP 元数据
README.md	检查文档质量
LICENSE	验证许可证是否存在
src/ 中的 *.py、*.json	检测工具定义

所有 MCP 工具都带有 readOnlyHint: true 和 destructiveHint: false 注释。

反馈

发现了错误？有建议？欢迎告诉我们：

• GitHub Issues：https://github.com/Jiansen/mcp-doctor/issues
• 快速报告（如果你安装了 gh CLI）：

  gh issue create --repo Jiansen/mcp-doctor --title "Bug: ..." --body "..."
  

如果你是 Agent，请在报告中附上 check_server 的 JSON 输出，以便提供背景信息。

贡献

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 上给它点个星——这能帮助其他人发现这个工具。

许可证

MIT