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 — 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 では、もう1つの補完的なチェックとして、スキーマ、説明、メタデータがほかのユーザーによるインストールに適した状態かどうかを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

この複合スコアは、3つのサブスコア — プロトコル（ワイヤ形式が機能するか）、エッジケース（特殊な入力を処理できるか）、公開可能性（初めて使う人にもツールが理解できるか） — と、公開可能性の5つの評価軸による内訳を組み合わせます。

評価軸	チェック内容
description-five-axis	各ツールの説明における 目的、変更、影響、副作用、不変条件、例 の充実度を評価します。5軸中3.0未満のツールがあると、複合スコアの上限が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 サーバー5つはすべて、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"

各変更は分類されるため、ゲートが有意義に機能し、不要な警告も発生しません。

重大度	例
❌ 破壊的変更	ツールの削除 · 新しい必須引数 · プロパティの削除 · 型の変更 · enum の選択肢の縮小
⚠️ セキュリティ	ツール説明の変更（ラグプル／ツールポイズニング） · readOnlyHint の削除 · ツールが破壊的な操作を行うようになった
✅ 追加的変更	新しいツール · 新しい任意フィールド · enum の選択肢の拡大
ℹ️ 情報	サーバー名 · リソース／プロンプトの説明文

デフォルトでは gate は breaking,security で失敗します。--fail-on breaking（またはカンマ区切りの任意の組み合わせ）で調整できます。スナップショットは 決定論的 です。変更のないサーバーを再記録すると、バイト単位で同一のファイルが生成されるため、コミット済みのベースラインと差分をクリーンに保てます。稼働中のターゲットではなく、--against <file> を使って、記録済みの2つのファイルをオフラインで比較できます。また、--markdown <path> を使うと、PR に投稿できるコメントを生成できます。

重要な理由：2026-07-28 MCP 仕様 では破壊的変更が導入されています（initialize ハンドシェイクの削除、エラーコードと JSON Schema の変更、HTTP+SSE から Streamable HTTP への移行）。記録済みの .mcpvcr ベースラインを使えば、「クライアントを壊していないか？」を1行の 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 サーバーの GitHub Actions ワークフローに mcp-probe を 2 行で追加できます。

- 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。

マーケットプレイスの掲載ページ：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