MCP Failure Lab

Model Context Protocol サーバー向けのカオスエンジニアリング／レジリエンス検証ツールキットです。

ドキュメント · プロジェクトページ

クイックスタート

リポジトリをクローンしたり、パッケージをグローバルにインストールしたりせずに、実際の決定的遅延シナリオを実行できます:

npx mcp-failure-lab demo

出力例:

MCP Failure Lab — Demo
Running a real 500ms delay scenario...

Scenario: Deterministic delay demo
Outcome: success
Duration: ~500 ms
Assertions: passed

実行ごとに正確な所要時間は多少前後する場合があります。API キーや外部 MCP サーバーは不要です。

利用可能なコマンドを表示:

npx mcp-failure-lab --help

組み込みの MCP サーバーを stdio 経由で起動:

npx mcp-failure-lab serve

Related MCP server: mcp-chaos-rig

目的

MCP Failure Lab は、サーバー作者が遅延、ハングするツール、キャンセル、トランスポート切断を決定的な方法で再現できるようにします。

タイムアウト処理、キャンセル時のクリーンアップ、トランスポート切断からの復旧、アサーション、CI の結果をテストするための、制御された障害動作を提供します。

現在のスコープ

MCP Failure Lab は、コマンドラインから独自の組み込み MCP サーバーに対して決定的な JSON シナリオを実行します。

現在利用可能な機能:

• ping、delay、hang、disconnect ツール

• stdio 経由の MCP 通信

• コードファーストおよび JSON のシナリオ定義

• 結果と最大所要時間のアサーション

• MCP 結果のアサーション

• 後条件検証のための逐次オブザーバー呼び出し

• コンソールおよび JSON レポート

• 機械可読なコマンドエラー

• CI 向けの終了コード

• ユニット、統合、エンドツーエンドのテスト

未実装の機能:

• 外部 MCP クライアントのオーケストレーション

• ターゲットクライアントアダプター

• Streamable HTTP

• JUnit レポート

• 不正なメッセージ、重複レスポンス、セッション喪失のフォールト

MCP Failure Lab は、現時点では汎用プロキシでも、外部 MCP クライアントのテストオーケストレーターでもありません。

仕組み

MCP Failure Lab は、組み込みの MCP クライアントとサーバーを通じて決定的なシナリオを実行します。シナリオは ping、delay、hang、disconnect のいずれかを呼び出し、観測された結果と所要時間を記録し、宣言された期待値を評価します。

オプションのオブザーバー呼び出しは、同じ MCP クライアント接続上で逐次実行され、別のツールパスを通じて後条件を検証します。

図、責務、実装の境界については、アーキテクチャドキュメント を参照してください。

ドキュメント

完全なガイドとリファレンスは mcplab.dev/docs で入手できます。

• はじめに

• シナリオ

• フォールトツール

• CLI リファレンス

• レポート

• アーキテクチャ

• 例

• トラブルシューティング

要件

• Node.js 22.19.0 以降

• npm

プロトコル互換性

MCP Failure Lab は、デフォルトで MCP 2026-07-28 をターゲットにしています。CLI サーバーは SDK v2 の era 対応 stdio エントリポイントを使用し、組み込みのシナリオクライアントは 2026-07-28 に固定されているため、最新の動作が明示的に実行されます。

サーバーは互換性のため 2025-11-25 の初期化フローも受け入れます。このレガシーパスは引き続き統合テストでカバーされていますが、新規開発は 2026-07-28 をターゲットにしています。既存の ping、delay、hang、disconnect フォールトツールは、両方の era で同じユーザー向け動作を備えています。サーバー主導のリクエストに依存するプロトコル機能は era によって異なり、これらのフォールトツールの対象外です。

インストール

npx でパッケージを直接実行:

npx mcp-failure-lab demo

グローバルインストールは不要です。

コマンドをグローバルにインストールする場合:

npm install -g mcp-failure-lab

CLI

# Run the built-in demonstration
npx mcp-failure-lab demo

# Display command help
npx mcp-failure-lab --help

# Display the installed version
npx mcp-failure-lab --version

# Start the MCP server over stdio
npx mcp-failure-lab serve

serve プロセスは MCP クライアントを待機します。Ctrl+C で正常にシャットダウンできます。

シナリオを実行する

シナリオファイルは JSON を使用します:

{
  "name": "bounded delay succeeds",
  "call": {
    "tool": "delay",
    "args": {
      "delayMs": 250
    }
  },
  "timeoutMs": 1000,
  "expect": {
    "outcome": "success",
    "maxDurationMs": 500
  }
}

リポジトリのチェックアウトから、同梱のシナリオを実行:

npm run dev -- run examples/scenarios/delay-success.json

機械可読な出力を生成:

npm run dev -- run examples/scenarios/delay-success.json --report json

コマンドは次の終了コードで終了します:

結果アサーション、オブザーバー呼び出し、レポート形式、タイムアウト動作については、シナリオ および レポート のドキュメントを参照してください。

フォールトツール

引数と動作については、フォールトツールリファレンス を参照してください。

サーバーを検査する

公開パッケージに対して MCP Inspector を起動:

npx @modelcontextprotocol/inspector npx mcp-failure-lab serve

stdio で接続し、利用可能なツールを一覧表示して、ping、delay、hang、disconnect を呼び出します。

Inspector の URL に含まれる一時的な認証トークンを共有したりコミットしたりしないでください。

外部統合の検証

MCP Failure Lab は、独立した Python MCP クライアントを使用した Future AGI シミュレーションによって独立に検証されました。この実験では、実際の hang ツールを stdio 経由で呼び出し、シミュレートされたエージェント応答を評価する前にクライアント側のタイムアウトを適用しました。

これは外部検証の例であり、公式の Future AGI 統合や推奨を意味するものではありません。

結果と再現手順については、Future AGI の例 を参照してください。

開発

リポジトリをクローンして依存関係をインストール:

git clone https://github.com/anilloutombam/mcp-failure-lab.git
cd mcp-failure-lab
npm install

開発用 CLI を実行:

npm run dev -- --help

プルリクエストを開く前に、以下を実行:

npm run format:check
npm run typecheck
npm test
npm run build

貢献のワークフローについては CONTRIBUTING.md を参照してください。

ロードマップ

計画中の作業は GitHub Issues で管理されています。

ロードマップ項目は、利用可能として明示的に文書化されていない限り、現在の実装の一部ではありません。

ライセンス

MIT