🛡️ MCPResilience

公式SDK v2上に構築された、仕様準拠で堅牢なMCPサーバー

クライアントが話すプロトコルに合わせてMCPを話します。MCPResilienceは、最初のリクエストでレガシーとモダンのプロトコル時代を自動検出し、その違いを乗り越えます。

🔌 クライアントモード

MCPResilienceは、接続するクライアントが話すプロトコル時代を自動検出します。設定は不要です。

1. ⚡ モダンなステートレスクライアント — 最初のリクエストに_metaエンベロープ（io.modelcontextprotocol/protocolVersion + clientInfo）が含まれるクライアントは、ハンドシェイクを完全にスキップします。tools/callを最初のメッセージにできます。

2. 🤝 レガシーハンドシェイククライアント — そのエンベロープがないクライアントは、従来のinitializeフローにルーティングされ、initializeが完了する前に送信されたものには-32600 Invalid request parametersが適用されます。

両時代の完全な内訳については、プロトコルサポートを参照してください。

Related MCP server: mcp-uni

🧠 これは何か

MCPResilienceが存在する理由は、手作りのMCPサーバーを公式SDKに置き換えることがドロップイン変更ではないからです。ワイヤーフォーマットが変化し、素朴な移行を壊すことがあります。このプロジェクトは、2つの段階でそれに取り組みます。

1. SDK移行 — 手作りのMCPサーバーコアを公式MCP SDK v2に置き換え、2026-07-28仕様をターゲットにして、ステートレスコアと型安全なPydanticシリアライゼーションを獲得します。

2. 互換性の強化 — 移行が、レガシーハンドシェイクをまだ使用しているクライアントのサポートを静かに落としたり、上流のスキーマギャップでデータを失ったり、実験的なTasks拡張を途中で壊したりしないようにします。

両方の段階は、途中で表面化した1つの上流SDKバグを含めて、以下で正直に文書化されています。

📊 主な結果

すべてのPhase 5互換性テストとPhase 6ベンチマークは、公式MCP SDK v2上でエンドツーエンドで合格しています。両方のプロトコル時代と実験的なTasks拡張を完全にサポートし、さらに1つの上流SDKバグを特定してパッチを適用しました（既知のSDKの癖を参照）。

Tasks拡張：SDK移行で変わった点

🏗️ 仕組み

Incoming connection
        │
        ▼
  First request received
        │
        ▼
  Does it carry the _meta envelope?
  (protocolVersion + clientInfo)
        │
   ┌────┴────┐
  Yes         No
   │           │
   ▼           ▼
Modern Era   Legacy Era
(stateless)  (handshake required)
   │           │
   ▼           ▼
tools/call   initialize → any request
runs          (initialize enforced,
immediately    notifications/initialized
               not blocked)
   │           │
   └─────┬─────┘
         ▼
  Era locked for the
  life of the connection

📡 プロトコルサポート

ステートレス時代（2026-07-28）

モダンな仕様では、従来のinitialize → notifications/initializedハンドシェイクは廃止されています。サーバーはserve_dual_era_loopを実行します。

• 最初のリクエストにio.modelcontextprotocol/protocolVersionとio.modelcontextprotocol/clientInfoを含む_metaエンベロープが含まれている場合、サーバーはモダンなステートレス時代にロックされます。

• クライアントはtools/callを最初のリクエストとして送信できます — initialize呼び出しは不要です。

レガシー時代

最初のリクエストにモダンな_metaエンベロープがない場合、サーバーはレガシー時代にロックされます。

• initializeの前に送信されたリクエスト（例：tools/call）は、-32600 Invalid request parametersで拒否されます。

• initializeが応答された後、サーバーは後続のリクエストを処理する前にnotifications/initializedを待ちません。

バージョン不一致の処理

_metaエンベロープでサポートされていないプロトコルバージョンを指定するモダンなリクエストは、-32022 Unsupported protocol versionでクリーンに拒否されます — 接続自体は切断されずに保持されます。

🧩 Tasks拡張の詳細

実験的なTasks拡張は、移行の中で最もワイヤーフォーマットの変更を受けました（主な結果の比較表を参照）。特に注目すべき2つの動作があります。

• tasks/getは現在メタデータのみです。 タスクコンテンツはtools/callレスポンスストリーム経由でのみ配信されます。tasks/getのポーリングは、statusMessageやcreatedAtなどのステータスフィールドのみを返し、ペイロード自体は決して返しません。

• キャンセルは設計上冪等です。 すでにcompletedまたはcancelledのタスクを再キャンセルすると、エラーではなく成功したCancelTaskResultが返されます。レガシーサーバーが繰り返しキャンセルで-32602を返すのとは異なります。

既知のSDKの癖

SDK Issue #2156 — executionフィールドがtools/listから削除される。 現在のv2026_07_28.ToolのPydanticスキーマは、実験的なexecutionフィールドを定義していないため、serialize_server_resultはtools/listレスポンスからそれを静かに削除します。

回避策： mcp_types.methods.serialize_server_resultへのターゲットを絞ったモンキーパッチが、検証済みの出力をインターセプトし、元のハンドラーデータからexecutionディクショナリを復元します。これは暫定措置です — 上流のスキーマがフィールドをネイティブに提供したら削除してください。

🔧 技術ノート（簡単ではなかった部分）

1. 時代検出は最初のリクエストで一度だけ行われます。 接続途中のアップグレードパスはありません — _metaエンベロープなしで開かれたクライアントは、後でモダンな形のリクエストを送信し始めても、その接続の存続期間中はレガシー時代に留まります。

2. タスクハンドルは移動しただけでなく、その契約も変わりました。 taskHandleをトップレベルのresultからresult._metaに移動することで、トップレベルのresultオブジェクトは即時コンテンツ出力とisErrorフラグ専用に予約できるようになりました — レガシーな形よりもクリーンな分離です。

3. モンキーパッチは意図的に狭い範囲に限定されています。 SDKのスキーマ全体をフォークしたりラップしたりするのではなく、serialize_server_resultのみをインターセプトして1つの欠落フィールドを復元します — 上流が修正を提供した瞬間にパッチを簡単に削除できるようにしています。

🛠️ 技術スタック

• プロトコル： Model Context Protocol上のJSON-RPC 2.0、仕様2026-07-28

• SDK： 公式MCP SDK v2 — Pydanticベースのスキーマ検証とシリアライゼーション

• サーバーコア： Python、ステートレスファーストのリクエスト処理（serve_dual_era_loop）

• テスト： Phase 5互換性スイート + Phase 6ベンチマーク実行

🚀 はじめに

git clone https://github.com/HoorShumail/MCPResilience.git
cd MCPResilience
pip install -r requirements.txt

上記のコマンドは、実際のパッケージレイアウトとエントリポイントに合わせて調整してください。

互換性スイートとベンチマークを実行するには：

pytest

⚠️ 正直な制限事項

• Tasks拡張は上流ではまだ実験的です。 コアMCP仕様で最終化されていないため、そのワイヤーフォーマットは将来のSDKリリースで再び変わる可能性があります — このサーバーはSDKの現在の実験的実装を追跡しており、安定したターゲットではありません。

• executionフィールドの修正はモンキーパッチであり、恒久的な解決策ではありません。 基盤となるスキーマを修正するのではなく、実行時にserialize_server_resultをパッチします — SDK Issue #2156が上流の修正を提供したら削除する必要があります。

• 時代検出は最初のリクエストのみです。 接続開始時にレガシー時代にロックされたクライアントは、後でモダンなリクエストに見えても、接続途中でステートレス時代に「アップグレード」するパスはありません。

🙏 謝辞

• 公式MCP SDK v2 — Model Context Protocolメンテナー

• Model Context Protocol仕様（2026-07-28）

🧑💻 著者

Hoor Shumail AI | 機械学習 | エージェンティックAI | マルチエージェントシステム | キャリアインテリジェンス

• GitHub: https://github.com/HoorShumail

• LinkedIn: https://www.linkedin.com/in/hoor-shumail-a3a076326/

📜 ライセンス

このプロジェクトは、教育、研究、ポートフォリオの目的で開発されています。

これは公式のModel Context Protocol SDKに基づいています — それらのコンポーネントを管理する条件については、そのSDK自体のライセンスとModel Context Protocol仕様を参照してください。