spec: MCP 2026-07-28 migration plan - single-lane flip, no dual-lane fallback #249

目的

github-webhook-mcp の Worker を MCP 仕様 2026-07-28（ステートレスコア）へ移行する。
互換レーンを持たない 単レーン一括切替とし、破断の吸収はコードではなく minor リリース + README 注意書きで行う。

前提

依存の現在地

• Worker = agents@0.19.0 + @modelcontextprotocol/sdk@1.29.0（exact pin、chore(deps): bump agents to 0.19.0 in worker, the last beta-free line #250 / chore(deps): bump worker agents to 0.19.0, the last line before the MCP SDK v2 beta peers #251 で引き上げ済み、LATEST_PROTOCOL_VERSION = 2025-11-25）。WebhookMcpAgent.serve("/mcp") による Streamable HTTP
• 新仕様の SDK は別パッケージへ分割。@modelcontextprotocol/server@2.0.0 / @modelcontextprotocol/client@2.0.0（2026-07-28 公開、beta 初版）
• agents@0.20.0 以降が v2 beta を非 optional な必須 peerとして要求し、dist/mcp/index.js が静的 import する。0.19.0 が beta を踏まない最終版
• agents@0.20.1 で McpAgent は deprecated / feature-frozen。移行先は createMcpHandler

経路の実測（重要 — 当初の前提を訂正する）

mcp-server/server.json は "transport": { "type": "stdio" } のみを宣言し、npm / npx パッケージだけを配布している。リモートトランスポートの宣言は無い。 したがって全利用者が npx ブリッジ経由で Worker に到達する。

ブリッジは二面を持ち、両面は独立している:

Worker のプロトコル版は、本 repo の 2 成果物のあいだの私的な契約である。 Claude 側の対応状況は Worker 側移行の条件ではない。

Claude Desktop 側の実測（別軸の記録）

• インストール実体 Claude_1.25927.0.0（リリース 2026-08-04、仕様公開の 7 日後）
• バンドル内 LATEST_PROTOCOL_VERSION = "2025-11-25"
• バンドル内に "2026-07-28" の文字列は存在しない（grep ヒット 0）
• 同版の変更履歴に MCP プロトコル関連の項目なし（ただし版引き上げは利用者非可視のため、履歴の不在は単独では弱い根拠。バイナリ側の直接観測が主）

これは Desktop ↔ ブリッジ間の移行条件であり、本 issue（Worker ↔ ブリッジ間）の条件ではない。

決定 1 — 互換レーンを実装しない

Cloudflare は「ステートレス経路を既存 McpAgent 経路と並走させ、クライアントが移りセッションが枯れるまで待つ」手順を推奨しているが、採用しない。

理由:

1. 保守されないフォールバック経路は放置され死にコード化する。rules/model/subtractive-structural-beauty.md が禁じる「念のため残す」に該当する
2. 畳む条件が観測可能（旧レーンへの到達がゼロになる）であっても、観測できることと観測しに行くことは別。運用上、外す判断は忘れられる
3. 破断の吸収は、コードではなく版とドキュメントという別チャネルで行う（決定 2）

先例（Cloudflare の推奨手順）は採用理由にならない。上記が本体。

決定 2 — 破断の扱い: minor リリース + README 注意書き

何が壊れるか

Worker がステートレス化した時点で、旧ブリッジ（initialize + mcp-session-id 前提）は動作しなくなる。

落ち方は静か。ブリッジは JSON-RPC エラーをツール出力テキストとして返すため、クラッシュせず「エラー文字列を返すツール」になる。

非対称の所在

• Worker = 全員共有の 1 デプロイ。一斉に飛ぶ
• ブリッジ = 利用者ごと。各自の Claude Desktop 再起動で追随する（docs: release does not reach a running client until the local npx process restarts #247 / docs: document the client-restart stage of the release delivery chain (README / Home / mcp-server README / requirements specs) #248 で実測・文書化済: @latest 指定でも起動済みプロセスは古い版を保持する）

版を固定している外部利用者は再起動しても復旧しない。この層の切り捨てを受け入れるというのが本決定。

吸収チャネル

• minor リリース。rules/operations/release-version-rule.md の「構造変更 かつ user/system observable → minor」に該当（旧ブリッジが実際に壊れる = 観測可能）。v0.x のため破壊的変更を minor に載せることは規定内
• README 注意書き。README.md および mcp-server/README.md に、この版から Worker が新仕様のみを提供すること、旧ブリッジは動作しないこと、Claude Desktop の再起動でブリッジを更新する必要があることを明記する（docs: document the client-restart stage of the release delivery chain (README / Home / mcp-server README / requirements specs) #248 が追加した再起動導線と同じ場所）

制約

• Worker とブリッジのクライアント面は同一リリースで出す。 片方だけ先に出すと破断窓が伸びる
• SDK v2 が beta である間の本番投入可否は、着手時点で再判断する
• 着手トリガーは Claude 側の出荷ではない。SDK v2 の枯れ具合と Master のタイミングで決める
• Desktop ↔ ブリッジ間の移行は本 issue の範囲外。別 issue として分離する

本 repo 固有の作業

rag-mcp と違い、本 repo は手書きハンドシェイクを 2 箇所持つ。

• mcp-server/server/index.js（npm 公開ブリッジ）
• local-mcp/src/index.ts（ローカル開発用ブリッジ）

新仕様では毎リクエストが自己完結するため、これらのセッション管理は移行ではなく 削除になる。getSessionIdWithToken 系がまるごと不要。

仕様側の期限との関係

deprecated レジストリ 6 件のうち本 repo に該当するのは Dynamic Client Registration のみ（worker/src/oauth.ts:160 に RFC 7591 を手書き実装、worker/src/oauth.ts:147 で registration_endpoint を広告）。最短撤去 = 2027-07-28 以降の最初のリビジョン、移行先 = Client ID Metadata Documents。OAuth 周辺を触る本移行に相乗りさせる。

該当しないもの: Roots / Sampling / Logging / includeContext（未使用）、HTTP+SSE トランスポート（serve() 既定が transport: "streamable-http" のため未露出）。

「最短撤去」は撤去が可能になる時点であり、実際の撤去は Core Maintainer 判断でそれ以降にずれうる。仕様からの撤去は SDK に削除義務を課さない。

関連

• chore(deps): bump agents to 0.19.0 in worker, the last beta-free line #250 / chore(deps): bump worker agents to 0.19.0, the last line before the MCP SDK v2 beta peers #251 — agents 0.19.0 引き上げ（本移行の前段、完了）
• memo(worker): the workers-types pin now sits below the range partyserver declares #252 — workers-types pin が partyserver の宣言レンジを下回っている件
• docs: release does not reach a running client until the local npx process restarts #247 / docs: document the client-restart stage of the release delivery chain (README / Home / mcp-server README / requirements specs) #248 — 配送鎖に利用側再起動の段があることの実測記録（本 issue の決定 2 の根拠）
• spec: MCP 2026-07-28 migration plan - single-lane flip, no dual-lane fallback github-rag-mcp#224 — 同一決定の姉妹 issue

参照

• https://modelcontextprotocol.io/specification/2026-07-28/changelog
• https://modelcontextprotocol.io/community/feature-lifecycle
• https://modelcontextprotocol.io/specification/2026-07-28/deprecated
• https://claude.com/blog/bringing-mcp-2026-07-28-to-claude