mcp-probe

mcp-probe

一条命令诊断你的 MCP 服务。

测试你的服务公开的每个工具、资源和提示词，然后生成包含通过/失败评分卡的健康报告。

基于 Anthropic Model Context Protocol（MCP）规范构建。

**注意：**已发布到 npm，包名为 @incultnitollc/mcp-probe。CLI 二进制文件名为 mcp-probe。npm 上不带作用域的名称 mcp-doctor 属于另一个无关工具，因此本项目使用带作用域的名称发布。版本 <= 0.2.1 使用已弃用的作用域 @incultnitostudiosllc 发布——请改为安装 @incultnitollc/mcp-probe。

npx @incultnitollc/mcp-probe test "npx -y @modelcontextprotocol/server-everything"

30 秒内测试你的 MCP 服务

检查项	描述
工具调用	根据输入架构自动生成示例参数，并调用每个工具
资源读取	读取每个资源并验证是否返回内容
提示词渲染	使用示例参数获取每个提示词，并验证是否返回消息
架构验证	检查工具架构是否缺少描述、必填字段是否无效、类型是否格式错误
健康评分	将所有结果汇总为通过/失败评分卡

安装

npm install -g @incultnitollc/mcp-probe

也可以直接运行：

npx @incultnitollc/mcp-probe test "your-server-command"

用法

本地 stdio 服务

npx @incultnitollc/mcp-probe test "npx -y @modelcontextprotocol/server-everything"

远程服务（Streamable HTTP）

npx @incultnitollc/mcp-probe test https://your-server.example.com/mcp

远程服务（SSE）

npx @incultnitollc/mcp-probe test https://your-server.example.com/mcp --transport sse

经过身份验证的远程服务

npx @incultnitollc/mcp-probe test https://your-server.example.com/mcp \
  --header "Authorization: Bearer $TOKEN"

选项

标志	描述
--json	将结果输出为 JSON
--timeout <ms>	每项操作的超时时间（默认值为 30000）
--transport <kind>	强制使用 stdio、sse 或 http（根据目标自动检测）
--header <Name: value>	为远程传输添加标头。可重复使用。

退出代码

• 0 — 所有检查均通过
• 1 — 一项或多项检查失败（适用于 CI 门禁）

JSON 输出

使用 --json 获取用于自动化的结构化输出：

mcp-probe test --json "your-server" | jq '.score'

{
  "toolsCallable": 12,
  "toolsTotal": 13,
  "resourcesReadable": 7,
  "resourcesTotal": 7,
  "promptsGettable": 3,
  "promptsTotal": 4,
  "schemaErrors": 0,
  "schemaWarnings": 1
}

工具调用的工作原理

mcp-probe 根据每个工具的 inputSchema 自动生成参数：

• 仅为必填字段赋值（最安全的做法）
• 优先使用 default 值和 enum 的首选项（如有）
• 根据字段名称推断合理的默认值（url → https://example.com，email → [email protected]）
• 使用符合类型的默认值作为后备（string → "test"，number → 1，boolean → false）

这意味着必填输入复杂的工具可能会失败——而这能提供有用的信息。它会告诉你，你的工具还不够独立，无法进行自动化测试。

可发布性评分（v1.1.0+）

mcp-probe 提供第二项互补检查：可发布性综合评分，用于评估服务器的架构、描述和元数据是否已准备好供他人安装，评分范围为 0–100。可使用简写运行：

npx @incultnitollc/mcp-probe score "npx -y @your-scope/your-server" --package ./package.json

也可以使用 --publishability 将其纳入完整的 test 运行：

npx @incultnitollc/mcp-probe test "npx -y @your-scope/your-server" --publishability --package ./package.json

综合评分包含三个子项——协议（传输格式是否正常工作）、边缘情况（是否能处理特殊输入）和可发布性（陌生人能否理解你的工具）——以及对可发布性维度的五轴细分：

轴	检查内容
description-five-axis	每个工具描述在用途、变更、 副作用、不变量、示例方面的详尽程度。低于 3.0/5 轴的工具会触发综合评分上限 ≤60。
enum-shape	检查仅以文本描述的枚举（例如，在描述中写 "one of: open, closed"，却没有 JSON Schema enum）。
mutation-legibility	每个工具是否告知规划器它会修改数据，还是只读取数据？名称前缀、描述信号或注释均计入。
anti-purpose-clause	影响范围大的工具（删除、发送、转账）应包含“不要用于 X，请优先使用 Y”的提示，指向功能范围更窄的工具。
distribution-metadata	npm 包就绪度——描述长度、关键词数量、repository / license / homepage 字段。未使用 --package 时跳过。

实际服务器的评分情况

五个官方 Anthropic MCP 服务在 v1.1.0 下的评分均为 60/100——每个服务都触发了 description-five-axis 上限。这不是评分标准的问题；这是 Anthropic 发布时的水平，也是大多数服务的起点。完整评分表见 docs/publishability-scorecards/。

CI 门禁

- uses: incultnitollc/mcp-probe@v1
  with:
    command: 'node dist/index.js'
    publishability: 'true'
    package: './package.json'
    fail-under: '70'

发布前与安装时

mcp-probe 的可发布性评分属于发布前质量范畴，面向发布服务前的服务作者。若要了解安装时的安全性范畴——即连接第三方服务前的服务安装人员，请参阅 @stephenywilson/mcp-doctor。面向的受众不同，但工具互为补充。

契约测试——“MCP 版 VCR”（v1.2.0+）

test/score 会告诉你服务器当前是否健康。契约测试会告诉你自上次以来发生了什么变化——这样，破坏性架构编辑或被投毒的工具描述就不会悄无声息地发布。

记录服务器契约的快照（包括其工具、资源、提示词及其架构——不含流量，也不产生副作用），提交 .mcpvcr 文件，然后针对每个 PR 执行 diff 或 gate。

# 1. Record a baseline (lists only — never calls a tool)
mcp-probe record "node dist/index.js" --out .mcp/contract.mcpvcr
git add .mcp/contract.mcpvcr && git commit -m "record MCP contract baseline"

# 2. See what a change did to the contract
mcp-probe diff --baseline .mcp/contract.mcpvcr "node dist/index.js"

# 3. Gate CI — exit 1 on breaking or security changes
mcp-probe gate --baseline .mcp/contract.mcpvcr "node dist/index.js"

每项变更都会分类，让门禁发挥实际作用而非产生噪声：

严重程度	示例
❌ 破坏性	移除工具 · 新增必需参数 · 移除属性 · 类型变更 · 枚举范围缩小
⚠️ 安全	工具描述变更（暗中操纵 / 工具投毒） · 移除 readOnlyHint · 工具变为破坏性操作
✅ 增量	新增工具 · 新增可选字段 · 扩大枚举范围
ℹ️ 信息	服务器名称 · 资源/提示词描述文本

默认情况下，gate 会在出现 breaking,security 时失败——可使用 --fail-on breaking（或任意逗号分隔的集合）调整。快照具有确定性：对未更改的服务器重新录制会生成字节完全一致的文件，因此已提交的基线和差异始终整洁。使用 --against <file> 离线比较两个录制文件，无需连接实时目标；使用 --markdown <path> 生成可直接发布的 PR 评论。

为何重要：2026-07-28 MCP 规范包含破坏性变更（移除 initialize 握手、错误代码和 JSON-Schema 变更、HTTP+SSE → Streamable HTTP）。录制的 .mcpvcr 基线可将“我们是否破坏了客户端？”转化为一行 CI 检查。完整的 PR 工作流（含自动评论）请参阅 examples/contract-gate.yml。

使用场景

• MCP 服务开发 — 在测试套件中运行 mcp-probe，及时发现回归问题
• CI/CD 门禁 — 如果 MCP 服务未通过健康检查，则阻止部署
• 服务评估 — 在集成第三方 MCP 服务前快速评估
• 架构质量 — 在用户遇到问题前，找出缺失的描述和格式错误的架构

CI 集成

mcp-probe 在全部通过时以 0 退出，出现任何失败时以 1 退出，因此可以直接用于任何 CI 流水线：

# .github/workflows/mcp-health.yml
- name: Health-check MCP server
  run: npx @incultnitollc/mcp-probe test "$MCP_SERVER_CMD"

使用 --json 获取结构化输出，并用 jq 根据特定指标设置门禁（例如，若 schemaWarnings > 0，则使构建失败）。

GitHub Action

只需两行，即可将 mcp-probe 添加到 MCP 服务的 GitHub Actions 工作流中：

- uses: incultnitollc/mcp-probe@v1
  with:
    command: 'node dist/index.js'

根据可发布性综合评分为 PR 设置门禁：

- uses: incultnitollc/mcp-probe@v1
  with:
    command: 'node dist/index.js'
    publishability: 'true'
    package: './package.json'
    fail-under: '70'

输入

名称	必填	默认值	描述
command	是	—	用于启动 MCP 服务的命令（例如 node dist/index.js 或 npx -y @your-scope/your-server）。
fail-under	否	0	如果可发布性综合评分低于此值，则使任务失败（0–100）。需要设置 publishability: 'true'。
publishability	否	false	运行可发布性测试套件 — 5 项检查 + 0–100 综合评分。需要 mcp-probe >= 1.1.0（于 2026-05-23 发布）。
package	否	''	分发元数据检查所用 package.json 的路径。留空则跳过分发检查。
html-report	否	''	HTML 评分卡的写入路径。可在后续步骤中通过 actions/upload-artifact 上传。
mcp-probe-version	否	latest	npm 版本、dist-tag 或 latest。为保证构建可复现，请固定版本。
json-output	否	''	JSON 报告的写入路径，供后续解析。

输出

名称	描述
composite-score	可发布性综合评分（0–100）。仅在 publishability: 'true' 时设置。
band	等级区间：publishable / almost / rough / not-ready。仅在 publishability: 'true' 时设置。
tools-pass-rate	tools_callable / tools_listed 的小数值（例如 0.83）。
schema-warnings	所有工具的架构警告总数。

更多示例：examples/basic.yml · examples/publishability-gate.yml · examples/matrix.yml。

Marketplace 列表：github.com/marketplace/actions/mcp-probe-mcp-server-health-check。

与 MCP Inspector 对比

官方 MCP Inspector 是用于交互式探索的 GUI — 指向、点击，即可查看服务返回的内容。mcp-probe 是用于自动化、可重复诊断的 CLI — 自动调用每个工具/资源/提示词，输出通过/失败评分卡，并返回退出代码。探索时使用 Inspector；在 CI、发布前检查中，或需要分享其他服务的评分卡时，使用 mcp-probe。

生态系统

• MCP Registry — 跨来源 MCP 服务目录（汇集 6 个上游列表中的约 6,900 个条目），质量评分由 mcp-probe 提供。CLI：npm i -g @incultnitollc/mcpr。由 Incultnito LLC 构建。

开发

git clone https://github.com/incultnitollc/mcp-probe.git
cd mcp-probe
npm install
npm run dev -- test "npx -y @modelcontextprotocol/server-everything"
npm test

许可证

MIT - Incultnito LLC