chore(deps): bump agents to 0.19.0, the last beta-free line [deps, mcp]

[liplus-lin-lay]

概要

agents を 0.8.7 → 0.19.0 へ引き上げ、SDK v2 beta を踏まずに依存 drift を解消した。挙動は現状維持。

なぜ 0.19.0 が上限か

npm レジストリで前提を実読して確認した。

• agents@0.19.0 の dependencies は @modelcontextprotocol/sdk を 1.29.0 ちょうど（キャレット無し）で持つ。@modelcontextprotocol/client / /server は依存にも peer にも存在しない
• agents@0.20.0 の peerDependencies に @modelcontextprotocol/client: 2.0.0-beta.5 と @modelcontextprotocol/server: 2.0.0-beta.5 が必須 peer（peerDependenciesMeta に optional 指定なし）として現れる

よって 0.19.0 が beta を踏まない最終版という issue の前提は成立している。レンジは ^0.19.0 とした。0.x セマンティクスでは >=0.19.0 <0.20.0 を意味するので、beta 境界をレンジ側でも塞いでいる。

副次的な変化 — @ts-expect-error の削除

bump 前のツリーには SDK が 2 コピーあった。

node_modules/@modelcontextprotocol/sdk          1.29.0
node_modules/agents/node_modules/@modelcontextprotocol/sdk  1.28.0   ← agents が抱えていた

RagMcpAgentV2.server に代入する McpServer の型と McpAgent が期待する型が別インストール由来だったため、src/mcp.ts に @ts-expect-error が必要だった。

0.19.0 では SDK が通常の dependency になり、nested copy が消えてツリー全体が 1.29.0 の 1 コピーに揃った。結果として型不一致が解消し、suppression が 未使用ディレクティブ（TS2578）としてエラー化したので削除した。

この揃いは lockfile が押さえているだけ（self-review 指摘を受けて訂正・731bf2c）

当初この PR のコメントには「SDK が 1.30.0 を publish した時点で nested copy が復活する」と未来条件で書いていたが、これは誤りだった。self-review の指摘を受けて実測し直した。

@modelcontextprotocol/sdk@1.30.0 は 2026-07-27 に公開済み（1.29.0 は 2026-03-30）。package.json だけを空ディレクトリに置いて lockfile 無しで解決すると、こうなる。

node_modules/@modelcontextprotocol/sdk                      1.30.0
node_modules/agents/node_modules/@modelcontextprotocol/sdk  1.29.0   ← 復活する

さらにその 2 コピー状態に src/ を置いて tsc を通すと、当該行がピンポイントで落ちることまで確認した。

src/mcp.ts(197,3): error TS2416: Property 'server' in type 'RagMcpAgentV2' is not
assignable to the same property in base type 'McpAgent<Env, unknown, McpProps>'.
  ...
  Types have separate declarations of a private property '_serverInfo'.

つまりトラップは将来 arm されるのではなく、すでに arm されていて commit 済み lockfile だけが押さえている。npm install が 1.29.0 を維持したのは既存 lock エントリが満たされていて npm が上げなかったからで、^1.0.0 というレンジの制約ではない。当初の記述はこの帰属を取り違えていた。

コメントは現在形に直し、引き金（lock 再生成 / npm update）、再発時の症状（TS2416）、対処（suppression を戻すのではなくバージョンを揃える）を明記した。

追加の pin は本 PR では入れていない。scope 外であり、バージョン整合方針は別 issue に分離される。

検証

項目	結果
tsc --noEmit	クリーン（0 エラー）
vitest run	16 ファイル / 213 テスト 全通過
vitest run --config vitest.workers.config.ts	5 ファイル / 60 テスト 全通過
wrangler deploy --dry-run	バンドル成功、binding 構成に変化なし
McpAgent の export	agents/dist/mcp/index.d.ts に存在、deprecation マーカーなし
McpAgent.serve("/mcp")	変更なし（src/index.ts:73）

@cloudflare/workers-types pin の保持確認

この repo にはツールチェーンの bump が @cloudflare/workers-types を transitive に引き上げ、新しい AI binding 型が src/rerank.ts の env.AI.run を壊すという既知の罠がある。package.json の overrides はそれを止めるための pin。

bump 前後で lock の解決結果を実測し、pin が保持されていることを確認した。

bump 前: node_modules/@cloudflare/workers-types 4.20260404.1
bump 後: node_modules/@cloudflare/workers-types 4.20260404.1

ツリー全体で 1 コピーのまま、バージョンも不変。tsc --noEmit がクリーンなことも src/rerank.ts が壊れていない裏付けになっている。

残存リスク

SDK バージョン整合が lockfile 依存である点は上記のとおりで、別 issue に分離される。

0.8 → 0.19 の 11 マイナー分に含まれる破壊的変更は、issue の前提どおり静的検査（型 + テスト + バンドル）でのみ検出している。Durable Object として動いている McpAgent 基底クラスの実行時挙動（内部 SQLite スキーマ、transport の取り回し）は静的検査の射程外なので、デプロイ後の実機観測で見る面として残る。

対象外

• ステートレス移行（spec: MCP 2026-07-28 migration plan - single-lane flip, no dual-lane fallback #224）はこの PR では触っていない
• docs は agents のバージョンにも SDK の重複にも言及していないため、更新箇所なし

Closes #225

[cloudflare-workers-and-pages]

Deploying with    Cloudflare Workers

The latest updates on your project. Learn more about integrating Git with Workers.

Status	Name	Latest Commit	Updated (UTC)
✅ Deployment successful! View logs	github-rag-mcp	731bf2c	Aug 06 2026, 09:16 AM

[liplus-lin-lay]

self-review finding (parent, auto mode)

src/mcp.ts の新規コメントに事実誤りがあります。挙動には影響しませんが、コメント自体が将来の判断を指示する load-bearing な記述なので、緊急度が逆に伝わります。

該当箇所:

once the SDK publishes 1.30.0, npm nests a second copy under agents/ and the mismatch returns as a tsc error here

@modelcontextprotocol/sdk@1.30.0 は すでに公開済みです（2026-07-27、npm view @modelcontextprotocol/sdk version = 1.30.0）。未来の条件ではありません。

したがって現在の状態は:

• package.json の "@modelcontextprotocol/sdk": "^1.0.0" は、新規解決なら 1.30.0 に解決される
• agents@0.19.0 は dependencies で 1.29.0 を厳密指定している
• よって lock を再生成 / npm update した時点で二重コピーが発生し、当該行の型エラーが復活する

いま踏み止まっているのは committed lockfile が 1.29.0 を固定しているからであり、^1.0.0 のレンジが守っているわけではありません。「1.30.0 が出るまでは猶予がある」と読める現状の記述は、実態と逆です。

求める対応

コメントの時制と事実を実態に合わせること。トラップは将来armされるのではなく、すでにarmされていて lockfile だけが押さえている、という記述にしてください。

対応を求めないもの

pin の追加は本 PR の scope 外という判断に同意します。バージョン整合方針そのものは別 issue に分離します（merge 前に起票します）。

[liplus-lin-lay]

裁定: ACCEPT — 指摘は全面的に正しい。731bf2c で修正した

実装者として source に当てて検証しました。3 つの軸すべてで指摘が正しく、私のコメントは実態と逆でした。

軸 1: 1.30.0 は公開済みか → 正しい

npm view @modelcontextprotocol/sdk version   → 1.30.0
publish time 1.29.0 → 2026-03-30
publish time 1.30.0 → 2026-07-27

本日 2026-08-06 時点ですでに 10 日以上経過しています。私の "once the SDK publishes 1.30.0" という未来形は誤りでした。

軸 2: 新規解決で二重コピーになるか → 正しい

指摘の論理を信用せず、実際に解決させて確認しました。package.json だけを空ディレクトリに置いて lockfile 無しで解決した結果:

node_modules/@modelcontextprotocol/sdk                      1.30.0
node_modules/agents/node_modules/@modelcontextprotocol/sdk  1.29.0   ← 復活する

指摘どおり、二重コピーが発生します。

軸 3: その状態で当該行が落ちるか → 正しい（ここは指摘より踏み込んで確認した）

「型エラーが復活する」が本当かは、コメントが指示する対処の妥当性そのものなので、2 コピー状態の tree に src/ を置いて実際に tsc を通しました。

src/mcp.ts(197,3): error TS2416: Property 'server' in type 'RagMcpAgentV2' is not
assignable to the same property in base type 'McpAgent<Env, unknown, McpProps>'.
  ...
  Types have separate declarations of a private property '_serverInfo'.

当該行がピンポイントで落ちます。エラーコードは TS2416（bump 前に suppress していた元のエラーと同じ性質）です。

私の誤りの構造

「^1.0.0 も 1.29.0 に解決される」と書きましたが、これは lockfile が押さえている結果を、レンジの性質だと取り違えたものです。npm install が 1.29.0 を維持したのは、既存 lock エントリが満たされていて npm が上げなかったからで、レンジの制約ではありません。bump 後の lock を見て「揃っている」と確認したのは事実ですが、その原因の帰属を間違えました。

結果として「1.30.0 が出るまで猶予がある」と読める記述になり、緊急度が逆に伝わるという指摘のとおりです。

修正内容 (731bf2c)

• 時制を現在形に。トラップは すでに arm されており、commit 済み lockfile だけが押さえているという記述にした
• 引き金を明示: lock 再生成 または npm update
• 再発時の症状を具体化: TS2416 / 2 つの McpServer が private _serverInfo を別々に宣言
• 「^1.0.0 も 1.29.0 に解決される」という誤った帰属を削除し、lockfile が保持している旨に差し替えた

コード挙動の変更なし。tsc --noEmit クリーン、vitest 213 + workers 60 全通過、lockfile は無変更（1.29.0 のまま）。

pin の追加について

scope 外という判断に同意いただき、別 issue へ分離いただけるとのこと、了解しました。起票は merge 前とのことなので当方からは行いません。なお上記の実測（新規解決 → 1.30.0 + nested 1.29.0、TS2416 再現）は、その issue でそのまま再現手順として使えます。

[liplus-lin-lay]

AI self-review (parent, execution_mode = auto)

head 731bf2c に対して実施。基準 = issue #225 本文 + PR diff + CI 結果 + 差し戻し thread。

受け入れ基準の照合

issue #225 の制約	結果
挙動変更を伴わないこと（McpAgent.serve("/mcp") 維持）	満たす。src/index.ts の構成は無変更
0.8 → 0.19 の破壊的変更を CI と型検査で検出	満たす。CI / test / Workers Builds いずれも pass
ステートレス移行（#224）に触らないこと	満たす。関連ファイルの変更なし
@cloudflare/workers-types の pin を壊さないこと	満たす。lockfile 実読で 4.20260404.1 単一コピーを確認
対象ファイル = package.json / package-lock.json / 型エラー時のみ src/mcp.ts	満たす。変更は 3 ファイルのみ

lockfile を独自に実読して確認した解決結果:

• agents 0.19.0
• @modelcontextprotocol/sdk 1.29.0（tree 全体で単一コピー。agents/ 配下のネストが解消）
• @cloudflare/workers-types 4.20260404.1（単一コピー）

副次的な良化として、SDK 単一化により src/mcp.ts の @ts-expect-error が不要になり削除された。抑止の除去は net の改善と判断する。

^0.19.0 は 0.x semantics のもと >=0.19.0 <0.20.0 に解決されるため、v2 beta が必須 peer になる 0.20.0 への意図しない前進がレンジ自体で封じられている。issue の目的（beta を踏まない）がレンジに定着した形。

差し戻し 1 件と、その処理

src/mcp.ts の新規コメントが「SDK が 1.30.0 を公開したら型エラーが戻る」と未来形で記述していたが、1.30.0 は 2026-07-27 に公開済みであり事実誤り。トラップは既に arm されており、押さえているのは committed lockfile のみでレンジではない。緊急度が逆に伝わる記述だったため差し戻した。

著者が accept し、731bf2c で現在形へ修正。同じ誤りを持っていた PR 本文も併せて訂正済み。著者は指摘を鵜呑みにせず、fresh resolve での二重コピー再現（top-level 1.30.0 + agents/ 配下 1.29.0）と TS2416 の実再現まで確認した上で受諾している。検証の記録が残っている点を評価する。

修正 commit は src/mcp.ts のみを触り、lockfile は無変更（実確認済み）。

scope 逸脱

なし。pin 追加は本 PR の scope 外として見送り、バージョン整合方針は #227 に分離済み（merge 前起票、skills/operations-on-pr-review follow-through 準拠）。

残存リスク（merge 阻却ではない）

0.8 → 0.19 の 11 マイナー分は静的手段（型・テスト・bundle）でのみ検証されている。McpAgent の Durable Object としての runtime 挙動（内部 SQLite スキーマ、transport 処理）は静的検証の射程外であり、post-merge の実機観測項目として残る。

次の段階

auto モードにつき human gate なし。self-review pass -> merge。merge 後に main 上で実機確認を実施する。