evals-mcp-server

---

概要

サーバー側で強制される採点器を使い、検証可能な評価レコードを作成します。実行可能な採点器を備えたレコードの下書きを作成し、フィールドごとに修正してから、正解例が合格し、否定例が不合格となり、独立したチェックも一致することを必須とするゲートを通じて提出します。JSONL、CSV、Inspect AI、または lm-evaluation-harness にエクスポートできます。

ツール

ツール	説明
evals_describe_schema	タスクタイプに必要なフィールドと任意のフィールド、および採点器のオプションを返します。下書きの作成前に呼び出してください。
evals_create_draft	独自の採点器を備えた評価レコードの下書きを作成します。解析済みレコード、レビュープロトコル、検証用サブエージェントのプロンプトを返します。
evals_get_record	下書きまたは提出済みレコードを ID で読み取ります。ID は提出後も変わりません。
evals_revise_draft	ドット区切りのパスを指定し、set／append／unset のパッチを下書きに適用します。自己整合性チェックが再実行されます。
evals_discard_draft	ID で下書きレコードを削除します。下書きのみが対象です。
evals_run_check	保存済みレコードとは独立して、採点器の仕様を候補回答に対して実行し、候補ごとの PASS／REJECT を取得します。
evals_submit_draft	提出可能性ゲートを通じて下書きを確定し、凍結します。
evals_list_records	ステータス、ドメイン、タスクタイプ、またはタグでレコードを参照・絞り込みます。レコードごとに簡潔な概要を返します。
evals_export_records	提出済みレコードを JSONL、CSV、Inspect AI、または lm-evaluation-harness にコンパイルし、成果物を exports/ に書き込みます。

リソース

リソース	説明
eval://record/{id}	idで指定した単一の下書きまたは提出済みレコードです。リソース対応クライアント向けに、evals_get_record が返すものと同じペイロードを返します。

すべてのレコードデータには、ツール経由でもアクセスできます。単一のレコードには evals_get_record、一覧の閲覧には evals_list_records を使用します。このリソースは、リソースに対応したクライアント向けの便利なミラーであり、アクセス経路ではありません。

機能リファレンス

evals_describe_schema _tool

• task_type に numeric、exact_answer、set_answer、mcq、regex_answer、json_answer、または free_response を指定します。
• 静的スキーマから、正解データの形式、採点器の種類、必須／任意フィールド、作成時の注意事項を返します。mcq では choices が必須で、free_response では llm_rubric が必須です。

---

evals_create_draft _tool

• 採点器と識別用ケースを含むレコードを受け取ります。また、任意で verification と captures（EvalsIDs）を指定できます。mcq では choices が必須で、free_response では llm_rubric が必須です。
• 採点器の実行後、レコードを draft として保存し、正規化されたレコード、レビュー用プロトコル、検証サブエージェント向けプロンプト、提出に必要な残りの項目を返します。正解データが採点器に合格しない下書きも保存されます。
• 型付きエラー：grader_unexecutable、task_type_constraint、mcq_choice_mismatch。

---

evals_get_record _tool

• id で指定した下書きまたは提出済みレコードを読み取ります。提出後も id は変わりません。
• 採点器全体、識別用ケース、検証エビデンスを返します。not_found が返された場合は、evals_list_records を参照してください。

---

evals_revise_draft _tool

• ドット区切りのパスを指定して、下書きに set、append、unset を適用します。task_type とサーバー管理フィールドは変更できません。また、配列は全体を置き換えるか追加する必要があり、インデックスを指定した編集はできません。
• 書き込み前にレコードと採点器を再検証し、レコードと changed エントリー（op、path、before、after）を返します。不明なパスがある場合は、パッチ全体が拒否されます。
• 型付きエラー：not_found、提出済みIDに対する record_frozen、invalid_patch_path、grader_unexecutable、task_type_constraint、mcq_choice_mismatch。

---

evals_discard_draft _tool

• draft_id で指定した下書きを削除し、discarded: true を返します。
• 提出済みレコードの場合は record_frozen が返され、存在しないIDまたはすでに破棄されたIDの場合は not_found が返されます。

---

evals_run_check _tool

• 保存済みレコードを使わずに、1つ以上の candidates に対して採点器を実行します。exact_match では gold を指定しますが、numeric や mcq などのターゲット埋め込み型では無視されます。
• PASS／REJECT、detail、各候補の解決済み参照 resolved を返します。ここでは llm_rubric を実行できません。
• 数値採点で受け付けるのは有限の実数値のみです。単位付き、複素数、非有限値、スカラー以外の候補は拒否されます。units は説明用のみです。
• 型付きエラー：grader_unexecutable、mcq_choice_mismatch。

---

evals_submit_draft _tool

• draft_id で指定した下書きを確定します。正解データがPASSし、1件以上の負例がREJECTEDとなり、非相関の検証結果が一致する必要があります。また、captures と EVALS_CAPTURE_DIR の整合性を確認し、重複する content_hash を拒否します。confirm または EVALS_REQUIRE_CONFIRMATION によって確認を求める場合があります。
• 成功すると、submitted_at と checksum を付与してレコードを凍結し、status: submitted を返します。拒否された場合、下書きはそのまま残ります。free_response のレコードは検証のみに依存し、server_verified: false が設定されます。
• 型付きエラー：not_found、record_frozen、verification_incomplete、grader_failed_on_gold、verification_disagrees_with_gold、missing_negative_case、negative_case_passed、duplicate、decorrelation_violation、capture_unresolved、submit_declined。

---

evals_list_records _ツール

• status（draft/submitted）、domain、task_type、または tag で絞り込みます。limit は正の整数で、デフォルトは 50 です。
• 要約（id、status、task_type、domain、tags、timestamps）を新しい順に返し、shown、cap、totalCount、truncated も含みます。

---

evals_export_records _ツール

• submitted レコードを、必要に応じて domain、task_type、または tag で絞り込み、jsonl（損失なし）、csv（要約のため損失あり）、inspect（Inspect AI）、または lm-eval（lm-evaluation-harness）形式でエクスポートします。
• exports/ 以下に書き込み、パス、レコード数、バイトサイズ、プレビューを返します。

---

eval://record/{id} _リソース

• evals_list_records またはドラフト／送信の応答から id を取得します。
• evals_get_record のペイロードを application/json として返します。一致するレコードがない場合は not_found を返します。

機能

@cyanheads/mcp-ts-core を基盤としており、stdio および Streamable HTTP トランスポート、切り替え可能な認証（none / jwt / oauth）、切り替え可能なストレージ（in-memory、filesystem、Supabase、Cloudflare KV/R2/D1）、オプションの OpenTelemetry トレーシングを備えた構造化ログを提供します。

評価の作成：

• draft → review → surgical-revise → submit のループでは、サーバーがレコードを保存するとともに、各レコード独自の採点器を実行し、要件を満たさないものを却下します
• 7 種類のタスク：numeric、exact_answer、set_answer、mcq、regex_answer、json_answer、free_response
• 各レコードとともにシリアライズされる採点器。決定的な種類（math.js を使う numeric、exact_match、set_match、regex、mcq、json_match）はサーバー側で実行され、llm_rubric は記録された独立検証に依存します
• 送信ゲート：正解が自身の採点器に合格し、1 件以上の負例が却下され、記録された無相関の検証結果が正解と一致する必要があります
• EVALS_DATA_DIR 以下のプレーンな JSON ファイル。ドラフト、送信済みレコード、エクスポートは別々に保存されます

エージェントに適した出力：

• evals_create_draft と evals_revise_draft は、解析済みレコード、フィールドごとのレビュープロトコル、すぐに貼り付けて使える検証サブエージェント用プロンプトを返します
• ドラフトと改訂の応答では、各正例および負例について、合格／却下の結果を報告します
• evals_list_records は、上限に達した場合に shown / cap / 合計件数を報告します
• 送信ゲートが失敗すると、型付きの reason と復旧のヒントが返されます

はじめに

以下を MCP クライアントの設定ファイルに追加してください。EVALS_DATA_DIR には書き込み可能なフォルダーを設定してください。サーバーはその中に drafts/、submitted/、exports/ を管理します。

{
  "mcpServers": {
    "evals-mcp-server": {
      "type": "stdio",
      "command": "bunx",
      "args": ["@cyanheads/evals-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info",
        "EVALS_DATA_DIR": "/absolute/path/to/evals-data"
      }
    }
  }
}

または npx を使う場合（Bun は不要）：

{
  "mcpServers": {
    "evals-mcp-server": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@cyanheads/evals-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info",
        "EVALS_DATA_DIR": "/absolute/path/to/evals-data"
      }
    }
  }
}

または Docker を使う場合：

{
  "mcpServers": {
    "evals-mcp-server": {
      "type": "stdio",
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "MCP_TRANSPORT_TYPE=stdio",
        "-v", "evals-data:/usr/src/app/evals-data",
        "ghcr.io/cyanheads/evals-mcp-server:latest"
      ]
    }
  }
}

Streamable HTTP を使う場合は、トランスポートを設定してサーバーを起動します：

MCP_TRANSPORT_TYPE=http MCP_HTTP_PORT=3010 EVALS_DATA_DIR=./evals-data bun run start:http
# Server listens at http://localhost:3010/mcp

前提条件

• Bun v1.4.0 以降（または Node.js v24 以降）。
• EVALS_DATA_DIR 用の書き込み可能なディレクトリー。外部 API キーは必要ありません。

インストール

1. リポジトリーをクローンします：

git clone https://github.com/cyanheads/evals-mcp-server.git

2. ディレクトリーに移動します：

cd evals-mcp-server

3. 依存関係をインストールします：

bun install

4. 環境を設定します：

cp .env.example .env
# edit .env and set EVALS_DATA_DIR

設定

すべてのサーバー設定は、起動時に src/config/server-config.ts の Zod スキーマで検証されます。

変数	説明	デフォルト
EVALS_DATA_DIR	レコード JSON のルートフォルダーです。ストアはその下に drafts/、submitted/、exports/ を管理します。	./evals-data
EVALS_REQUIRE_CONFIRMATION	true の場合、evals_submit_draft は確定前に複数ラウンドの入力を通じて人間の確認を求めます。	false
EVALS_DEFAULT_LICENSE	ドラフトにライセンスが指定されていない場合に適用されるデフォルトの metadata.license です（例：CC-BY-4.0）。	—
EVALS_CAPTURE_DIR	フレームワークが書き込むツール呼び出しキャプチャのディレクトリです。設定すると、captures の EvalsID は完全なダンプを参照します。	—
MCP_TRANSPORT_TYPE	トランスポートです。stdio または http を指定します。	stdio
MCP_HTTP_PORT	HTTP サーバーのポートです。	3010
MCP_SESSION_MODE	HTTP セッションモードです。auto、stateful、または stateless を指定します。送信の確認にはライブセッションが必要なため、stateless は拒否されます。	stateful
MCP_AUTH_MODE	認証モードです。none、jwt、または oauth を指定します。	none
MCP_LOG_LEVEL	ログレベルです（RFC 5424）。	info
OTEL_ENABLED	OpenTelemetry instrumentation を有効にします。	false

オプションの上書き設定の全一覧については、.env.example を参照してください。

送信確認は 10 分後に期限切れとなり、ドラフトが変更された場合は再度確認が必要です。複数のインスタンスを実行する場合は、共有ストレージ（STORAGE_PROVIDER_TYPE=filesystem と共有の STORAGE_FILESYSTEM_PATH、supabase、または cloudflare-d1。cloudflare-kv は不可）を使用し、各インスタンスで同じ MCP_REQUEST_STATE_KEY（32 バイト以上）を設定してください。

サーバーの実行

ローカル開発

• ビルドして実行：

  # One-time build
  bun run rebuild
  
  # Run the built server
  bun run start:stdio
  # or
  bun run start:http
  

• チェックとテストを実行：

  bun run devcheck   # Lint, format, typecheck, security
  bun run test       # Vitest test suite
  bun run lint:mcp   # Validate MCP definitions against spec
  

Docker

docker build -t evals-mcp-server .
docker run --rm -e MCP_TRANSPORT_TYPE=stdio -v evals-data:/usr/src/app/evals-data evals-mcp-server

Dockerfile のデフォルトは HTTP トランスポート、stateful セッションモード、および /var/log/evals-mcp-server へのログ出力です。レコードストレージは、ランタイムユーザーが所有するデフォルトディレクトリ /usr/src/app/evals-data にマウントしてください。OpenTelemetry のピア依存関係はデフォルトでインストールされます。省略するには、--build-arg OTEL_ENABLED=false を指定してビルドしてください。

プロジェクト構成

ディレクトリ	用途
src/index.ts	createApp() のエントリーポイントです。ツールとリソースを登録し、record-store サービスと exporter サービスを初期化します。
src/config	サーバー固有の環境変数を Zod で解析および検証します。
src/mcp-server/tools	ツールの定義（*.tool.ts）です。
src/mcp-server/resources	リソースの定義（*.resource.ts）です。
src/services/eval-record	レコードスキーマ、ドラフトビルダー、および送信ゲートです。
src/services/grader	決定論的な grader DSL の実行と、コミット可能性のチェックです。
src/services/record-store	ディスク上の JSON レコードの CRUD、draft から submitted への移動、およびエクスポートの書き込みを行います。
src/services/exporter	送信済みレコードを JSONL/CSV/Inspect/lm-eval にコンパイルします。
tests/	src/ に対応するユニットテストと統合テストです。

開発ガイド

開発ガイドラインとアーキテクチャ上のルールについては、CLAUDE.md/AGENTS.md を参照してください。要点は次のとおりです。

• ハンドラーは例外をスローし、フレームワークが捕捉します。ツールロジック内で try/catch を使わないでください。
• リクエスト単位のログには ctx.log を使用してください。レコードは ctx.state ではなく、record-store サービス経由でディスクに永続化します。
• 新しいツールとリソースは、src/index.ts の createApp() 配列に登録してください。
• サーバーを信頼できる情報源としてください。入力を検証し、grader を必須のゲートとして実行し、アサーションだけでレコードを受け入れないでください。

コントリビューション

Issue の報告を歓迎します。提出前にチェックとテストを実行してください。

bun run devcheck
bun run test

ライセンス

Apache-2.0 — 詳細は LICENSE を参照してください。