hatago-mcp-hub: Instructions file for Codex

AGENTS ガイドライン（開発支援用）

このドキュメントは、リポジトリで作業する AI エージェント／開発者向けの運用ガイドです。基本方針、モノレポ構成、テックスタック、開発コマンド、CLI/設定、MCP 準拠要点、設計哲学、リリース運用、ドキュメント方針などを最新の状態でまとめています。

— ドキュメントは日本語（です・ます調）で記載します。技術文書ではキャラクター口調は使用しません。

プロジェクト概要

Hatago MCP Hub は、複数の MCP（Model Context Protocol）サーバーを一元管理する軽量ハブです。Claude Code / Codex CLI / Cursor / Windsurf / VS Code など各種クライアントから、ローカル/NPX/リモートの MCP サーバーへ透過的に接続するための中継点を提供します。設計の核は「薄い実装（最低限の転送・管理に徹する）」です。

テックスタック

• ランタイム: Node.js 20+（Cloudflare Workers 対応: リモートサーバー接続機能中心）
• 言語: TypeScript（ESM, strict）
• Web フレームワーク: Hono（HTTP モード）
• MCP SDK: @modelcontextprotocol/sdk（Zod ベースの schema 必須）
• ビルド: tsdown
• テスト: Vitest
• Lint/Format: ESLint + Prettier（現行の実行スクリプトに準拠）
• パッケージマネージャー: pnpm

補足: 一部ドキュメントに Biome 言及がありますが、現状のルート実行コマンドは ESLint/Prettier を使用します（pnpm lint / pnpm format）。

モノレポ構成

• パッケージマネージャー: pnpm
• 主要ワークスペース（公開想定スコープ: @himorishige/*）
  • packages/core → @himorishige/hatago-core
  • packages/runtime → @himorishige/hatago-runtime
  • packages/transport → @himorishige/hatago-transport
  • packages/hub → @himorishige/hatago-hub
  • packages/server → @himorishige/hatago-server
  • packages/cli → @himorishige/hatago-cli
  • packages/mcp-hub → @himorishige/hatago-mcp-hub（現行の公開対象）
• その他
  • examples/: サンプル（Node / Workers）
  • docs/: アーキテクチャ、設定、運用ガイド
  • schemas/: JSON Schema とサンプル設定（schemas/config.schema.json）

参考ツリー（抜粋）:

packages/
  mcp-hub/      # メイン npm パッケージ（CLI `hatago` 提供）
  server/       # HTTP/StreamableHTTP サーバー実装
  hub/          # ハブ中核（ルーティング/レジストリ）
  core/         # 共通型/定数
  runtime/      # 実行時コンポーネント
  transport/    # STDIO/HTTP/SSE 等のトランスポート
schemas/
  config.schema.json  # 設定スキーマ
examples/
  node-example/
  workers-example/

前提ツール・環境

• Node.js 20 以上（engines に準拠）
• TypeScript（ESM）
• Lint/Format: ESLint + Prettier（ルートの eslint.config.js/prettier.config.js と pnpm スクリプトに準拠）

HTTP モードの追加オプション（計測/ログ）:

• HATAGO_METRICS=1 でインメモリ計測を有効化し /metrics を公開
• HATAGO_LOG=json（HATAGO_LOG_LEVEL に準拠）で JSON ログを有効化