mcp-resource-subscriber: Instructions file for Codex

AGENTS.md

プロジェクトの目的

本リポジトリは、MCP resources/subscribe の互換性検証スパイクとして開始した。CLI AI エージェント（Codex, Gemini, Claude Code, Crush 等）が MCP resource subscription を正しく処理できるかを、再現可能な形でテストするためのものである。この検証フェーズは既に完了しており、現在は以下の 2 つの実運用向けコンポーネントを提供する:

1. CLI probe（mcp-resource-subscriber、src/client/cli.ts）— CLI エージェントのワークフローや外部ツール（例: squirrel-notifier）が、MCP resource を subscribe して notifications/resources/updated を待ち、結果を構造化された stdout/JSON として報告させるために呼び出す、公開済みのサブプロセス。protocol revision は 2026-07-28 に pin しており、legacy へフォールバックしない（#162）。mcp-gateway 向け認証（--login / --logout、キャッシュ済みトークンの自動更新）も担い、これらの呼び出し元がトークンを手動で用意する必要をなくす。call サブコマンド（--tool / --args）は、subscribe とは別に任意の MCP tool を単発 tools/call 呼び出しして即終了するモードで、同じ認証経路を再利用する（#111）。
2. リファレンス MCP Streamable HTTP サーバー（src/server/）— stateless（legacy: "reject"）。1 つの resource（test://review/status）を公開し、subscriptions/listen の stream 開通を起点に更新をシミュレートして、その stream へ notifications/resources/updated を配信する。probe クライアントのローカル / Docker テスト用に維持されており、本番トラフィック向けではない。

必須コマンド

pnpm install --frozen-lockfile # 依存関係のインストール
pnpm run build                 # tsc コンパイル → dist/
pnpm test                      # vitest run（in-process サーバーに対するテスト、Docker 不要）
pnpm run test:coverage         # vitest run --coverage
pnpm run typecheck             # tsc --noEmit（出力ファイルなし）
pnpm run check                 # biome check .（lint + フォーマットチェック）
pnpm run format                # biome format --write .
pnpm run dev                   # tsx でサーバーをローカル実行（ビルド不要）
pnpm run start                 # コンパイル済み dist/ からサーバーを実行（本番エントリ）
pnpm run probe:subscribe -- --url http://127.0.0.1:8089/mcp  # 稼働中サーバーに対して probe クライアントを実行
docker compose up --build      # ポート 8089 でリファレンスサーバーを起動

Node 要件: >=26.4.0（package.json の engines と CI で強制）。 パッケージマネージャ: [email protected]（packageManager で固定。pnpm-lock.yaml が唯一の lockfile）。

アーキテクチャ

src/
  server/
    index.ts         — エントリポイント: 環境設定を読み込み、Express HTTP サーバーを起動
    config.ts        — TestConfig 型 + configFromEnv()（全環境変数をここでパース）
    httpServer.ts    — createMcpHttpApp(): createMcpHandler（legacy: "reject"）+ toNodeHandler を Express にマウントし、{ app, close } を返す。resource の状態と更新シミュレーションは McpServer がリクエストごとに作り直されるためここ（アプリスコープ）に置く。InMemoryServerEventBus をラップした自前 bus を渡し、listen stream の開閉を観測して更新タイマーを張る
    mcpServer.ts     — createProbeServer(): MCP ハンドラを登録（list/read + tool）。2026-07-28 に resources/subscribe RPC は無く、通知配信は handler.notify.resourceUpdated() が担う
    resourceState.ts — ReviewStatusStore（in-memory、version 1→2）、renderReviewStatus()、定数
    logger.ts        — createConsoleLogger(config): logLevel が 'silent' でない限り全行を出力する LogSink を返す（レベル階層フィルタなし）
  client/
    probeClient.ts   — runSubscribeProbe(): 全フローを実行し型付き結果を返す SDK クライアント（subscriptions/listen → ack 検証 → 通知待機 → 再 read → stream close）
    protocolNegotiation.ts — protocol revision を 2026-07-28 に pin する Client オプションと connectPinned()。negotiation 失敗を ProtocolNegotiationError に正規化する（ネットワーク起因は素通し）
    callClient.ts    — runToolCall(): call サブコマンド用、単発 tools/call を実行し型付き結果を返す SDK クライアント
    callJsonOutput.ts — call サブコマンドの --json 出力スキーマ（CallJsonOutput）
    cli.ts           — 公開 bin エントリ; --url, --uri, --auth-token, --login, --logout, --skip-resource-list-check, --timeout-ms に加え `call` サブコマンド（--tool, --args）をサポート
    auth/
      tokenStore.ts  — node:sqlite トークンキャッシュ（gateway origin 単位で 1 行、OS state dir、0600）; withExclusiveLock() は任意の timeoutMs を受け取り、BEGIN IMMEDIATE の同期的な待機がそれを超えないよう busy_timeout を一時的に下げる（LockTimeoutError を送出）
      oauthClient.ts — RFC 8414 discovery / RFC 7591 DCR / RFC 8628 device flow / refresh grant（fetch + sleep を注入可能）
      gatewayAuth.ts — loginToGateway() と resolveCachedToken()（rotation 永続化を伴う自動 refresh）

scripts/
  subscribe-client.ts  — CLI 引数で runSubscribeProbe() を呼び出し、結果を表示する薄いラッパー

test/
  mcp-resource-subscribe.test.ts  — vitest 統合テスト（ポート 0 で in-process サーバーを起動）
  cli.test.ts                     — CLI サブプロセステスト: --json モード、不正な引数、exit code
  e2e.test.ts                     — 外部 copilot-review-mcp サーバーに対する E2E テスト（環境変数が必要）
  tokenStore.test.ts              — 一時 SQLite ファイルに対するトークンキャッシュ CRUD; withExclusiveLock() のロック挙動
  oauthClient.test.ts             — in-process モック認可サーバーに対する device flow / refresh
  gatewayAuth.test.ts             — login + キャッシュ済みトークン解決（refresh, rotation, re-login エラー, AUTH_TIMEOUT）
  cliAuth.test.ts                 — CLI サブプロセス認証統合（--login, --logout, キャッシュ優先順位, AUTH_LOGIN_REQUIRED, AUTH_TIMEOUT）
  call.test.ts                    — call サブコマンドの CLI サブプロセステスト（引数パース、成功、tool エラー、認証エラー、通信エラー、exit code 0/1/2/3）
  helpers/mockAuthServer.ts       — mcp-gateway の OAuth surface を模した express モック