fix(client): Node.js 26.5.1 未満を fail-fast し HTTP/2 starvation の再発を防ぐ

[scottlz0310-user]

背景

mcp-gateway#204 で、Node.js 26 の組み込み undici が HTTP/2 上で長寿命 SSE GET と body 付き POST を併用した際、POST を dispatch せずタイムアウトまで starvation させる問題が確認された。

上流では nodejs/undici#5538 が修正され、undici v8.8.0 以降に収録済み。Node.js では v26.5.1 が undici 8.9.0 を bundle した最初のリリースである。

このリポジトリの main は既に以下を Node.js 26.5.1 へ更新済み:

• package.json#engines.node: PR chore(deps): update node.js to >=26.5.1 #148
• GitHub Actions: PR ci(actions): update dependency node to v26.5.1 #150
• Docker image: PR chore(deps-docker): update node.js to v26.5.1 #151

一方、公開済み v0.5.0 は engines.node >=26.5.0 のため、未修正の Node.js v26.5.0 / undici 8.7.0 でも要件を満たす。また、engines は package manager の設定によっては警告に留まり、CLI の実行自体を止めない。

mcp-gateway が将来 HTTP/2 を既定有効へ戻した場合、未修正 runtime で subscriber を実行すると、従来どおり約 60 秒の timeout と副次的な 502 が再発し得る。

方針

1. 実際の subscribe / call 処理へ入る前に Node.js runtime を検証し、v26.5.1 未満ではネットワーク接続を開始せず明示的に失敗する。
2. package.json#engines.node >=26.5.1、CI、Docker の現在値を維持する。
3. Node.js 26.5.1 要件の理由と mcp-gateway の h2 互換性検証結果を CHANGELOG / README に記録する。
4. patch release を公開し、Squirrel Notifier ホストが修正版を取得できる状態にする。

クライアント側で allowH2: false を固定する回避策は追加しない。上流修正済みであり、runtime floor を一元化する方が将来の HTTP/2 利用を妨げず、保守対象も増やさないため。

受け入れ条件

• Node.js v26.5.1 未満で subscribe / call を実行すると、ネットワーク接続前に原因と最低必要バージョンを含むエラーで終了する
• unsupported runtime のテストを、実 runtime の切り替えに依存しない形（version 判定ロジックへの依存性注入）で追加する
• --help / --version は unsupported runtime でも診断目的で利用できる
• package.json#engines.node、CI、Docker が v26.5.1 以上で揃っている
• CHANGELOG / README に Node.js 26.5.1 が必要な理由（undici h2 starvation 修正）と関連 Issue を記載する
• patch version を publish し、npm package と GitHub Release の双方で engines.node >=26.5.1 を確認する
• 公開 package を Node.js v26.5.1 で実行し、MCP_GATEWAY_ENABLE_HTTP2=true の TLS gateway 経由で subscribe → notification → re-read → unsubscribe が成功する
• 検証結果を chore: undici の h2 修正が Node に行き渡ったら TLS リスナーの HTTP/2 既定を再検討する mcp-gateway#206 に共有する

関連

• bug: thread-owl の Streamable HTTP 購読が reverse proxy 経由で 502 / timeout になる mcp-gateway#204
• chore: undici の h2 修正が Node に行き渡ったら TLS リスナーの HTTP/2 既定を再検討する mcp-gateway#206
• HTTP/2: fetch POST hangs while an SSE stream is open nodejs/undici#5524
• fix(h2): allow stream-bodied requests to multiplex on a busy session nodejs/undici#5538
• deps: update undici to 8.9.0 nodejs/node#64712
• PR chore(deps): update node.js to >=26.5.1 #148 / ci(actions): update dependency node to v26.5.1 #150 / chore(deps-docker): update node.js to v26.5.1 #151

[scottlz0310-user]

クローズ理由

この Issue は、依存更新の適用範囲を十分に確認せず「mcp-resource-subscriber 側に追加実装が必要」と判断して起票したものだった。改めて現在の repository と実行環境を確認した結果、Issue で提案した runtime fail-fast と専用 patch release は、現時点の問題解決に必要ないため not planned とする。

既に完了している対応

• PR chore(deps): update node.js to >=26.5.1 #148: package.json#engines.node を >=26.5.1 に更新
• PR ci(actions): update dependency node to v26.5.1 #150: CI と publish workflow の Node.js を 26.5.1 に更新
• PR chore(deps-docker): update node.js to v26.5.1 #151: Docker base image を Node.js 26.5.1 に更新

3 PR はすべて main にマージ済みであり、repository が管理する Node.js version surface は既に 26.5.1 へ揃っている。

実行環境の確認

mcp-resource-subscriber の CLI は Node.js runtime を内包せず、起動元ホストの Node.js を使う。Squirrel Notifier が実際に subscriber を起動する現在のホストは Node.js v26.5.1 / undici 8.9.0 である。

この実 runtime を使用し、MCP_GATEWAY_ENABLE_HTTP2=true の TLS gateway 経由で次のフローが成功している。

initialize -> standalone GET/SSE -> subscribe -> notification -> re-read -> unsubscribe

• subscriber exit code: 0
• notification 受信: 成功
• SSE GET と後続 POST: 同一 h2 接続上で並行処理
• 旧事象の timeout / Content-Length ... but only wrote 0 bytes / 502: 発生なし

なぜ追加実装しないか

公開済み v0.5.0 の engines.node が >=26.5.0 であること自体は事実だが、現在の対象ホストは修正版 Node.js 26.5.1 を既に使用しており、subscriber のコード変更なしで根本不具合は解消している。

この状態で runtime fail-fast、追加 error contract、専用 release を導入すると、現在発生していない問題に対して新しい保守対象を増やすことになる。必要最小限の対応方針に反するため実施しない。

HTTP/2 の既定再有効化に関するクライアント環境全体の判断は scottlz0310/mcp-gateway#206 で継続する。将来、未修正 Node.js を使う実環境で再現が確認された場合は、その実測と対象範囲を根拠に新しい Issue として切り出す。