mcp-runtime-check Skill 技能

mcp-runtime-check（别名 mcp-fuzz）是 MCP 服务器运行时行为测试工具。它真正启动 MCP 服务器并用工具自声明的 JSON Schema 推导输入，验证服务器在有效输入、缺失必填字段、类型错误等情况下是否按描述行事——而非崩溃或挂起。

技能简介

mcp-doctor 通过读取 MCP 服务器源码检查工具文档是否完整。mcp-runtime-check 做的是相反的事：它实际启动服务器并调用工具，检验服务器的行为是否与 Schema 声明一致。静态分析看不到服务器是否会在缺少必填字段时崩溃、是否会在类型错误时挂起——只有真正运行代码才能知道。

核心能力

• 真实运行时测试：启动 MCP 服务器，通过 stdio 协议调用每个工具的真实实现
• Schema 推导测试用例：从工具的 inputSchema 自动推导三种测试输入：
  • valid：每个属性一个合理值，应成功
  • missing required：逐个移除必填字段，应返回结构化 MCP 错误而非崩溃
  • wrong type：逐个将属性替换为错误类型，应返回结构化错误而非崩溃
• 只读工具自动识别：默认只测试标注了 readOnlyHint: true 的工具，自动跳过有副作用的工具
• 崩溃恢复机制：每次坏工具调用后完整重连，不因一次崩溃中断整个报告
• 超时控制：默认 15 秒超时，防止服务器挂起阻塞测试
• JSON 输出 / CI 集成：--json 输出机器可读结果，--fail-under 90 非零退出码
• 真实场景验证：已在 modelcontextprotocol 官方服务器、arxiv-mcp-server 等项目验证

安装配置

安装

pip install mcp-runtime-check

PyPI 分发名为 mcp-runtime-check，但安装后的 CLI 命令是 mcp-fuzz（原名）。

快速测试一个服务器

mcp-fuzz -- python server.py mcp-fuzz -- npx -y some-mcp-server mcp-fuzz --json -- python server.py

-- 后面的是启动 MCP 服务器的命令。

配置安全模式（默认）

默认只测试 readOnlyHint: true 的工具，不会有副作用：

mcp-fuzz -- python server.py

包含有副作用工具（谨慎使用）

mcp-fuzz --include-destructive -- python server.py

仅在确定服务器安全时使用（本地沙箱、测试/预发环境），绝不用于连接生产数据、真实邮箱或支付系统。

CI 集成示例

mcp-fuzz --fail-under 90 -- python server.py 崩溃 resilience 低于 90% 时返回非零退出码。

使用步骤

1. 安装 mcp-runtime-check：pip install mcp-runtime-check

2. 找到要测试的 MCP 服务器命令（如 python server.py 或 npx -y @some/mcp-server）

3. 运行测试：

   mcp-fuzz --

4. 查看崩溃 resilience 分数：报告每个工具在 missing-required 和 wrong-type 测试中的表现

5. 查看"可能是假阳性"的标记：valid 输入报错不一定是 bug，可能是 Schema 推导的占位符值不够真实

6. 调整阈值：

   mcp-fuzz --fail-under 95 -- python server.py

适用场景

• MCP 服务器开发：发布前验证工具的鲁棒性，确保边界情况有正确错误处理
• MCP 服务器质量评估：对比不同 MCP 服务器实现的质量差异
• 回归测试：在 MCP 服务器更新后运行，确认没有引入新的崩溃问题
• CI 流程集成：作为 MCP Server 项目的 CI 步骤，确保每次提交不降低鲁棒性
• Schema 质量审计：发现服务器 Schema 声明与实际行为的不一致

适用人群

• MCP 服务器开发者：实现 Model Context Protocol 服务器的工程师
• AI 平台质量工程师：负责评估和保障 MCP 生态质量的工程师
• AI Agent 开发者：使用 MCP 服务器并关注其稳定性的开发者
• DevOps / CI 工程师：需要在 CI 中集成 MCP 服务器测试的工程师

工作原理

mcp-runtime-check 通过 stdio 协议启动目标 MCP 服务器，发送 initialize 和 tools/list 请求获取工具列表和每个工具的 inputSchema。然后对每个工具生成三类测试用例（valid / missing required / wrong type），通过 tools/call 发送调用并记录响应。任何崩溃（进程退出、非结构化错误）或超时都会触发重连。报告的"崩溃 resilience"百分比仅涵盖 missing-required 和 wrong-type 两类测试中返回了结构化错误的比例。valid 调用失败时单独标记为"可能是假阳性"，需要人工复核而非直接判定为 bug。

官方链接

• PyPI：https://pypi.org/project/mcp-runtime-check/
• GitHub：https://github.com/vishalhabib99/mcp-doctor（mcp-doctor 同仓库）
• 官方参考服务器测试结果：modelcontextprotocol/servers、blazickjp/arxiv-mcp-server 等