mcp-eval-runner

MCP Eval Runner

npm mcp-eval-runner package

MCP サーバーとエージェントのワークフロー向けの標準化されたテストハーネスです。YAML フィクスチャとしてテストケース（ステップ → 期待されるツール呼び出し → 期待される出力）を定義し、MCP クライアントから回帰テストスイートを直接実行できます。Claude Code や Cursor を離れることなく、差分付きの合格／不合格結果を確認できます。

ツールのリファレンス | 設定 | フィクスチャ形式 | コントリビューション | トラブルシューティング | 設計原則

主な機能

• YAML フィクスチャ：テストケースはバージョン管理に含められる通常のファイルです。差分の確認やレビュー、共有が簡単にできます。
• 2 つの実行モード：ライブモードでは実際の MCP サーバーを起動し、stdio 経由でツールを呼び出します。シミュレーションモードでは、サーバーなしで expected_output に対するアサーションを実行します。
• 組み合わせ可能なアサーション：各ステップで output_contains、output_not_contains、output_equals、output_matches、schema_match、tool_called、latency_under を組み合わせられます。
• ステップ出力の受け渡し：{{steps.<step_id>.output}} を使って、前のステップの出力を後続の入力で参照できます。
• 回帰レポート：現在の実行結果を過去の任意の実行結果と比較し、変更点を表示します。
• 監視モード：ファイルが変更されると、影響を受けるフィクスチャを自動で再実行します。
• CI 対応：設定が変更されるたびに評価を実行する GitHub Action が含まれています。

要件

• Node.js v22.5.0 以降。
• npm。

はじめに

以下の設定を MCP クライアントに追加します。

{
  "mcpServers": {
    "eval-runner": {
      "command": "npx",
      "args": ["-y", "mcp-eval-runner@latest"]
    }
  }
}

デフォルトでは、評価フィクスチャは現在の作業ディレクトリにある ./evals/ から読み込まれます。別のパスを使うには、以下のようにします。

{
  "mcpServers": {
    "eval-runner": {
      "command": "npx",
      "args": ["-y", "mcp-eval-runner@latest", "--fixtures=~/my-project/evals"]
    }
  }
}

MCP クライアントの設定

Amp · Claude Code · Cline · Cursor · VS Code · Windsurf · Zed

最初のプロンプト

evals/smoke.yaml にファイルを作成します。server ブロックを含めて、ライブモード（推奨）を使います。

name: smoke
description: "Verify eval runner itself is working"
server:
  command: node
  args: ["dist/index.js"]
steps:
  - id: list_check
    description: "List available test cases"
    tool: list_cases
    input: {}
    expect:
      output_contains: "smoke"

次に、以下を MCP クライアントに入力します。

Run the eval suite.

クライアントにスモークテストの合格／不合格結果が表示されます。

フィクスチャ形式

フィクスチャは、フィクスチャディレクトリに配置する YAML（または JSON）ファイルです。各ファイルで 1 つのテストケースを定義します。

トップレベルのフィールド

フィールド	必須	説明
name	はい	テストケースの一意な名前
description	いいえ	人が読める説明
server	いいえ	サーバー設定。指定するとライブモードで実行し、省略するとシミュレーションモードで実行します
steps	はい	実行するステップの配列

server ブロック（ライブモード）

server:
  command: node # executable to spawn
  args: ["dist/index.js"] # arguments
  env: # optional environment variables
    MY_VAR: "value"

server が指定されている場合、eval runner はサーバーを子プロセスとして起動し、MCP stdio トランスポート経由で接続して、各ステップのツールをライブサーバーに対して呼び出します。

steps 配列

各ステップには、以下のフィールドがあります。

フィールド	必須	説明
id	はい	フィクスチャ内で一意の識別子（出力の受け渡しに使用）
tool	はい	呼び出す MCP ツール名
description	いいえ	人が読めるステップの説明
input	いいえ	ツールに渡す引数のキーと値のマップ（デフォルト：{}）
expected_output	いいえ	シミュレーションモードで出力として使うリテラル文字列
expect	いいえ	ステップの出力に対して評価するアサーション

実行モード

ライブモード — フィクスチャに server ブロックがある場合：

• サーバーが起動され、各ステップでは MCP stdio 経由で指定されたツールが呼び出されます。
• アサーションは実際のツール応答に対して実行されます。
• サーバーのエラーが発生すると、そのステップ（およびデフォルトではケース）は直ちに失敗します。

シミュレーションモード — server ブロックがない場合：

• サーバーは起動されません。
• 各ステップの出力には expected_output の値が使用されます（指定がない場合は空文字列）。
• アサーションはその静的な出力に対して実行されます。
• 作成作業や CI のドライランに便利ですが、expected_output が設定されていない場合、output_contains アサーションは常に失敗します。

アサーションの種類

すべてのアサーションは、ステップの expect ブロックに記述します。

expect:
  output_contains: "substring" # output includes this text
  output_not_contains: "error" # output must NOT include this text
  output_equals: "exact string" # output exactly matches
  output_matches: "regex pattern" # output matches a regular expression
  tool_called: "tool_name" # verifies which tool was called
  latency_under: 500 # latency in ms must be below this threshold
  schema_match: # output (parsed as JSON) matches JSON Schema
    type: object
    required: [id]
    properties:
      id:
        type: number

1 つの expect ブロック内の複数のアサーションはすべて評価され、いずれかのアサーションが失敗すると、そのステップは失敗します。

ステップ出力の受け渡し

前のステップの出力を後続のステップの input で参照するには、{{steps.<step_id>.output}} を使用します。

steps:
  - id: search_step
    tool: search
    input:
      query: "mcp eval runner"
    expected_output: "result: mcp-eval-runner v1.0"
    expect:
      output_contains: "mcp-eval-runner"

  - id: summarize_step
    tool: summarize
    input:
      text: "{{steps.search_step.output}}"
    expected_output: "Summary: mcp-eval-runner v1.0"
    expect:
      output_contains: "Summary"

出力の受け渡しは、ライブモードとシミュレーションモードの両方で機能します。

create_test_case に関する注意

create_test_case ツールで作成されたフィクスチャには、server ブロックが含まれません。常にシミュレーションモードで実行されます。ライブモードを使用するには、生成された YAML ファイルに server ブロックを手動で追加してください。

ツール

実行

• run_suite — フィクスチャディレクトリ内のすべてのフィクスチャを実行し、合格／不合格の概要を返します
• run_case — 名前を指定して、単一のフィクスチャを実行します
• list_cases — ステップ数と説明を含め、利用可能なフィクスチャを一覧表示します

作成

• create_test_case — 新しい YAML フィクスチャファイルを作成します（シミュレーションモード、server ブロックなし）
• scaffold_fixture — プレースホルダーのステップと、あらかじめ入力されたアサーションのコメントを含む、ひな形のフィクスチャを生成します

レポート

• regression_report — 現在のフィクスチャの状態を前回の実行結果と比較し、リグレッションと修正を提示します
• compare_results — 実行 ID を指定して、2 つの実行結果を比較します
• generate_html_report — 完了した実行の単一ファイル形式の HTML レポートを生成します

運用

• evaluate_deployment_gate — CI ゲートとして機能し、直近の合格率が設定可能なしきい値を下回ると失敗します
• discover_fixtures — 1 つ以上のディレクトリからフィクスチャファイルを検出します（FIXTURE_LIBRARY_DIRS を参照します）

設定

--fixtures / --fixtures-dir

YAML／JSON 形式の評価フィクスチャファイルを読み込むディレクトリです。

型：string デフォルト：./evals

--db / --db-path

実行履歴の保存に使用する SQLite データベースファイルのパスです。

型：string デフォルト：~/.mcp/evals.db

--timeout

単一のステップを失敗と判定するまでに待機する最大時間（ミリ秒）です。

型：number デフォルト：30000

--watch

フィクスチャディレクトリを監視し、ファイルが変更されたときに影響を受けるフィクスチャを自動的に再実行します。

型：boolean デフォルト：false

--format

評価結果の出力形式です。

型：string 選択肢：console、json、html デフォルト：console

--concurrency

並列実行するテストケースの数です。

型：number デフォルト：1

--http-port

stdio トランスポートの代わりに、このポートで HTTP サーバーを起動します。

型：number デフォルト：無効（stdio を使用）

JSON 設定の args プロパティでフラグを渡します。

{
  "mcpServers": {
    "eval-runner": {
      "command": "npx",
      "args": ["-y", "mcp-eval-runner@latest", "--watch", "--timeout=60000"]
    }
  }
}

設計原則

• モックなし：ライブモードの評価は実際のサーバーに対して実行されます。正確性は譲れません。
• フィクスチャはテキスト：バージョン管理下に YAML／JSON で保存し、独自形式やデータベースは使用しません。
• ドッグフードを優先：評価ランナー自体のスモークフィクスチャで、評価ランナー自身をテストします。

検証

新しいバージョンを公開する前に、MCP Inspector でサーバーを検証し、すべてのツールが正しく公開されていることと、プロトコルのハンドシェイクが成功することを確認してください。

対話型 UI（ブラウザーで開きます）：

npm run build && npm run inspect

CLI モード（スクリプト実行／CI に適しています）：

# List all tools
npx @modelcontextprotocol/inspector --cli node dist/index.js --method tools/list

# List resources and prompts
npx @modelcontextprotocol/inspector --cli node dist/index.js --method resources/list
npx @modelcontextprotocol/inspector --cli node dist/index.js --method prompts/list

# Call a tool (example — replace with a relevant read-only tool for this plugin)
npx @modelcontextprotocol/inspector --cli node dist/index.js \
  --method tools/call --tool-name list_cases

# Call a tool with arguments
npx @modelcontextprotocol/inspector --cli node dist/index.js \
  --method tools/call --tool-name run_case --tool-arg name=smoke

公開前に実行して、ツールの登録やランタイムの起動に関するリグレッションを検出してください。

コントリビューション

新しいアサーションの種類は src/assertions.ts に追加します。Assertion インターフェースを実装し、テストを追加してください。統合テストは、ユニットテストとして tests/ に、評価フィクスチャとして evals/ に配置されています。

npm install && npm test

MCP レジストリとマーケットプレイス

このプラグインは次の場所で利用できます。

• MCP レジストリ
• MCP Market

mcp-eval-runner を検索してください。