MCP Failure Lab

MCP Failure Lab

意図的に障害を発生させるMCPサーバーと、制限付きのリファレンスクライアントハーネスです。 v0.1.0、MITライセンス。公式MCP TypeScript SDK 2.3.1 を基盤としており、プロトコル実装を置き換えるものではありません。

試す

Dockerが必要です。イメージはNode 24とバージョンを固定したnpm依存関係を使用します。

docker build -t mcp-failure-lab:local .
docker run --rm --network none --read-only --cap-drop ALL --security-opt no-new-privileges mcp-failure-lab:local npm test
docker run --rm --network none --read-only --cap-drop ALL --security-opt no-new-privileges mcp-failure-lab:local node runner.mjs

最後のコマンドは、決定論的な7回の実行結果と、OpenAIメッセージ形式のトレースをJSONで出力します。 言語モデルは使用しません。所要時間は実測した経過ミリ秒であり、ベンチマークではありません。 テストコマンドはリグレッションがあるとゼロ以外の終了コードを返します。デモコマンドは判定結果ではなく、観測内容を出力します。

ローカルで開発する場合は、npm ci --ignore-scripts を実行してから、npm test を実行します。

公開イメージから実行する場合（公式MCP Registry：io.github.cloudlabworks/mcp-failure-lab）：

docker run -i --rm -e LAB_SCENARIO=tool-error ghcr.io/cloudlabworks/mcp-failure-lab:0.1.2

リリースの検証

v0.1.2以降、各リリースには publish-mcp ワークフローを通じてSigstoreで署名されたビルド来歴が付属します。GitHub CLIを使用する場合：

gh attestation verify oci://ghcr.io/cloudlabworks/mcp-failure-lab:0.1.2 --repo cloudlabworks/mcp-failure-lab
gh attestation verify mcp-failure-lab-0.1.2.tar.gz --repo cloudlabworks/mcp-failure-lab

2つ目のコマンドは、GitHub Releaseのソースtarballを検証します。オフラインで検証するには、--bundle mcp-failure-lab-0.1.2.tar.gz.intoto.jsonl（同じリリースに添付された来歴ファイル）を追加します。

障害

LAB_SCENARIO	注入される動作	リファレンスクライアントの想定
healthy	通常のツール応答	1回成功
tool-error	isError=trueの有効な結果	設定された試行回数の上限で停止
transient-error	最初のLAB_FAILURES回の呼び出しが失敗	試行回数の上限内であれば復旧
delay	ツール応答の前にLAB_DELAY_MS待機	期限内に成功、またはタイムアウト
malformed	有効なJSON-RPCエンベロープだが、テキストブロックの値が無効	ツール結果を拒否
disconnect	ツール応答中に終了	接続のクローズを報告し、成功とはしない

影響を受けるのは、告知される lab_probe ツールのみです。初期化と検出には公式SDKを使用します。 トランスポートラッパーが破損させるのは 結果の形式 であり、JSONフレーミングではありません。フレームの切り詰め、不正なID、HTTP障害、認証障害は実装されていません。

設定はプロセス起動時に読み込まれます。シナリオはプロセスごとにリセットされます。 LAB_DELAY_MS：整数0～10000（デフォルト1000）。 LAB_FAILURES：整数0～10（デフォルト2）。 値は10進数字のみで指定してください。変数が未設定または空の場合はデフォルトが使用され、それ以外（0x10、1e3、 7）の場合、サーバーは終了コード2で停止します。 リファレンスクライアントが再試行するのは明示的なツールエラーのみで、最大5回です。プロトコルエラー、タイムアウト、切断の場合は直ちに停止します。 ハーネスのツール呼び出し期限は10～10000 msです。SDKの接続および検出の期限は別に設定されています。 生成されるフィクスチャで繰り返し呼び出しが確認できるよう、再試行には意図的にバックオフを設けていません。これは本番環境に推奨される再試行ポリシーではありません。

独自のMCPクライアントを接続する

標準入力／標準出力を接続して、このコマンドを実行する テスト用 MCP接続を設定します。

docker run --rm -i --network none --read-only --cap-drop ALL --security-opt no-new-privileges -e LAB_SCENARIO=transient-error -e LAB_FAILURES=2 mcp-failure-lab:local

{"message":"probe"} を指定して lab_probe を呼び出します。 実際の下流サービス、認証情報、ファイル書き込みツール、待ち受け中のネットワークポートはありません。 付属のリファレンスクライアント以外のクライアント連携は 未検証 です。

Agent Trace Clinicに障害を入力する

このリポジトリで、Clinicを隣にチェックアウトした状態で実行します。

mkdir -p artifacts
docker run --rm --network none --read-only mcp-failure-lab:local node runner.mjs > artifacts/run.json
node --input-type=module -e 'import fs from "node:fs"; const r=JSON.parse(fs.readFileSync("artifacts/run.json","utf8")); console.log(JSON.stringify(r.results.find(x=>x.scenario==="tool-error").trace));' > artifacts/tool-error.json
node ../agent-trace-clinic/cli.mjs artifacts/tool-error.json --html > artifacts/clinic-report.html

Clinicは、このフィクスチャでtool_loop、retry_storm、unhandled_tool_errorを特定するはずです。 これらはヒューリスティックによる手がかりです。意図的に制限された再試行でも検出される場合があります。トークン数は捏造していません。

upstream との関係

MCP conformance は、プロトコルテストにおける上流の権威です。 このプロジェクトは、リカバリー実験のための小規模な障害領域を提供しますが、適合認証を主張するものではありません。 公式フレームワークでは現在、HTTP ベースのクライアント／サーバーシナリオランナーが文書化されています。この初回リリースは stdio のみを対象としています。 上流シナリオアダプターと Streamable HTTP ターゲットは次の予定であり、今回のリリースには含まれていません。

確認したソース：2026-10-14

• SDK v2 documentation
• SDK source and examples
• Conformance framework

メンテナンス契約

トランスポートは 1 つ、ツールは 1 つ、障害モードは 6 つ、リファレンスクライアントは 1 つです。SDK をアップグレードする際はバージョンを固定し、すべての障害テストを再実行してください。 オーナー：Cloud Lab Works / Waku。Gherkin のレビューは割り当てられておらず、完了していません。 一般公開の前に、ソース／依存関係のレビュー、独立したテスト実施、公開承認が必要です。 クラウドで実行する前に、ジョブ予算の上限設定、ティアダウン、実行時間の測定が必要です。このリリースにクラウドアカウントは不要です。 テレメトリやリモートレポート機能はありません。生成されたレポートは無視対象の artifacts/ に保存されます。

Agent Reliability Lab

公開デモを開くか、実験ガイドをご覧ください。4 つの制御された変更前／変更後の事例では、公式 MCP リファレンスクライアントを、決定論的な Clinic の検査に接続します。公開サンプルは、ライブのクラウド実行ではなく、記録されたローカルの証拠です。クラウドアダプターと運用手順書も含まれています。

引用

このプロジェクトを使用する場合は、付属のプレプリントを引用してください。 MCP Failure Lab: Reproducible Tool-Failure Fixtures and Cross-Platform Traces for Testing Agent Reliability。DOI：10.5281/zenodo.23720942。 要旨と PDF については、論文ページをご覧ください。

@techreport{alvord2026mcp,
  author = {Alvord, Alex},
  title = {{MCP Failure Lab: Reproducible Tool-Failure Fixtures and Cross-Platform Traces for Testing Agent Reliability}},
  institution = {CloudLab Works},
  publisher = {Zenodo},
  year = {2026},
  month = oct,
  type = {Preprint},
  doi = {10.5281/zenodo.23720942},
  url = {https://doi.org/10.5281/zenodo.23720942}
}