目的
github-webhook-mcp の Worker を MCP 仕様 2026-07-28（ステートレスコア）へ移行する。
互換レーンを持たない 単レーン一括切替とし、破断の吸収はコードではなく minor リリース + README 注意書きで行う。
前提
依存の現在地
経路の実測（重要 — 当初の前提を訂正する）
mcp-server/server.json は "transport": { "type": "stdio" } のみを宣言し、npm / npx パッケージだけを配布している。リモートトランスポートの宣言は無い。 したがって全利用者が npx ブリッジ経由で Worker に到達する。
ブリッジは二面を持ち、両面は独立している:
| 面 |
実装 |
版 |
| Claude Desktop に対してサーバー |
SDK v1 stdio (new Server) |
2025-11-25 まで |
| Worker に対してクライアント |
mcp-server/server/index.js:606 および local-mcp/src/index.ts:674 の手書き fetch |
2024-11-05 を宣言 |
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 経路と並走させ、クライアントが移りセッションが枯れるまで待つ」手順を推奨しているが、採用しない。
理由:
- 保守されないフォールバック経路は放置され死にコード化する。
rules/model/subtractive-structural-beauty.md が禁じる「念のため残す」に該当する
- 畳む条件が観測可能（旧レーンへの到達がゼロになる）であっても、観測できることと観測しに行くことは別。運用上、外す判断は忘れられる
- 破断の吸収は、コードではなく版とドキュメントという別チャネルで行う（決定 2）
先例（Cloudflare の推奨手順）は採用理由にならない。上記が本体。
決定 2 — 破断の扱い: minor リリース + README 注意書き
何が壊れるか
Worker がステートレス化した時点で、旧ブリッジ（initialize + mcp-session-id 前提）は動作しなくなる。
| 段 |
旧ブリッジの動作 |
新 Worker での結果 |
| 1 |
POST /mcp に method: "initialize" |
メソッドが存在しない → エラー |
| 2 |
レスポンスヘッダから mcp-session-id を取得 |
ヘッダが返らない → _sessionId = "" |
| 3 |
tools/call に session ヘッダを付与 |
_meta にプロトコル版が無い → UnsupportedProtocolVersionError |
落ち方は静か。ブリッジは JSON-RPC エラーをツール出力テキストとして返すため、クラッシュせず「エラー文字列を返すツール」になる。
非対称の所在
版を固定している外部利用者は再起動しても復旧しない。この層の切り捨てを受け入れるというのが本決定。
吸収チャネル
制約
- 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 に削除義務を課さない。
関連
参照
目的
github-webhook-mcp の Worker を MCP 仕様 2026-07-28（ステートレスコア）へ移行する。
互換レーンを持たない 単レーン一括切替とし、破断の吸収はコードではなく minor リリース + README 注意書きで行う。
前提
依存の現在地
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@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 に到達する。ブリッジは二面を持ち、両面は独立している:
new Server)mcp-server/server/index.js:606およびlocal-mcp/src/index.ts:674の手書き fetch2024-11-05を宣言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）これは Desktop ↔ ブリッジ間の移行条件であり、本 issue（Worker ↔ ブリッジ間）の条件ではない。
決定 1 — 互換レーンを実装しない
Cloudflare は「ステートレス経路を既存
McpAgent経路と並走させ、クライアントが移りセッションが枯れるまで待つ」手順を推奨しているが、採用しない。理由:
rules/model/subtractive-structural-beauty.mdが禁じる「念のため残す」に該当する先例（Cloudflare の推奨手順）は採用理由にならない。上記が本体。
決定 2 — 破断の扱い: minor リリース + README 注意書き
何が壊れるか
Worker がステートレス化した時点で、旧ブリッジ（
initialize+mcp-session-id前提）は動作しなくなる。POST /mcpにmethod: "initialize"mcp-session-idを取得_sessionId = ""tools/callに session ヘッダを付与_metaにプロトコル版が無い →UnsupportedProtocolVersionError落ち方は静か。ブリッジは JSON-RPC エラーをツール出力テキストとして返すため、クラッシュせず「エラー文字列を返すツール」になる。
非対称の所在
@latest指定でも起動済みプロセスは古い版を保持する）版を固定している外部利用者は再起動しても復旧しない。この層の切り捨てを受け入れるというのが本決定。
吸収チャネル
rules/operations/release-version-rule.mdの「構造変更 かつ user/system observable → minor」に該当（旧ブリッジが実際に壊れる = 観測可能）。v0.x のため破壊的変更を minor に載せることは規定内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 が追加した再起動導線と同じ場所）制約
本 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 に削除義務を課さない。
関連
agents0.19.0 引き上げ（本移行の前段、完了）参照