MCP エージェント宿題

MCP_HOMEWORK_SKILL.md の課題用に構築された TypeScript 製 MCP (Model Context Protocol) システムです。Agent Skill (SKILL.md) を読み込み、3 つの必須トランスポートすべてを通じて 3 つの MCP サーバーに接続し、それらのツールを検出・集約して、Gemini が適切なサーバー上の適切なツールを選択・呼び出しできるようにする Agent Host です。

アーキテクチャ

                          Agent Host (src/host)
                     skill-loader + connection-manager
                       + tool-bridge + gemini-client
                                 |
              +------------------+------------------+
              |                  |                   |
              v                  v                   v
        stdio server       local HTTP server    public HTTP server
     (src/servers/stdio-  (src/servers/http-   (same http-server.ts,
        server.ts)          server.ts, no auth)   API-key protected)
              |                  |                   |
              +------------------+-------------------+
                                 |
              shared tool logic (src/servers/shared/tools.ts)
       3 tools (calculator, text_stats, unit_convert) + 1 resource + 1 prompt

• src/servers/shared/tools.ts — 3 つのツール、1 つのリソース、1 つのプロンプトの単一実装。すべてのサーバーに同一に登録されるため、同じロジックがどこでも再利用されます (ビジネスロジックの重複なし)。

• src/servers/stdio-server.ts — stdio 上の MCP (子プロセスとして起動)。

• src/servers/http-server.ts — Streamable HTTP 上の MCP。「ローカル」サーバーと「パブリック」サーバーの両方でまったく同じファイル/コードが実行されます。違いは設定のみです (PORT、PUBLIC_MCP_API_KEY)。

• src/host/connection-manager.ts — MCP ホスト: 設定されたすべてのサーバーに接続し、ツール/リソース/プロンプトを検出し、衝突を避けるためにツール名を <namespace>__<tool> として名前空間化し、ツール呼び出しを所有サーバーにディスパッチします。

• src/host/tool-bridge.ts — 検出された MCP ツールを Gemini の関数宣言に変換します。

• src/host/gemini-client.ts — Gemini のツール呼び出しループ (メッセージ送信 → 関数呼び出しの読み取り → コネクションマネージャー経由でディスパッチ → 関数レスポンスを送信 → 最終テキストが返るまで繰り返し)。

• src/host/skill-loader.ts — SKILL.md を読み込み、モデルのシステム指示として注入し、スキルがツールの使用方法を積極的に形成できるようにします。

• src/host/agent-host.ts — config/servers.json から上記を結び付けます。

• src/host/cli.ts — CLI エントリポイント (対話モードまたは --demo)。

Related MCP server: mcp-tools-server

セットアップ

npm install

シークレットは api.env にあります (すでに gitignore 済み):

API_KEY=your-gemini-api-key
# Optional, only needed once you deploy the public server:
# PUBLIC_MCP_URL=https://your-app.onrender.com/mcp
# PUBLIC_MCP_API_KEY=some-strong-random-key

各コンポーネントの実行

stdio サーバー (20 点)

npm run server:stdio            # run directly
npm run inspector:stdio         # open MCP Inspector against it

Inspector は 3 つのツール (calculator、text_stats、unit_convert)、1 つのリソース (docs://unit-conversions)、1 つのプロンプト (explain-tool-result) を検出し、それらすべてを実行/読み取りできます。

ローカル HTTP サーバー

npm run server:http             # listens on http://127.0.0.1:8787/mcp, no auth
npm run inspector:http          # then connect Inspector to that URL

パブリック HTTP サーバー (15 点)

同じ http-server.ts は、PUBLIC_MCP_API_KEY が設定されると「パブリック」サーバーになります。以降、すべてのリクエストには一致する x-api-key ヘッダーが必要となり、キーがない場合や無効な場合は 401 Unauthorized が返ります。

$env:PORT=8788; $env:PUBLIC_MCP_API_KEY="a-strong-secret"; npm run server:http

公開デプロイ (同梱の render.yaml を使用した Render.com):

1. git init && git add -A && git commit -m "MCP homework" を実行し、自分が所有する GitHub リポジトリにプッシュします。

2. Render で: New + → Blueprint → リポジトリを選択 (render.yaml を自動的に読み取ります)。または、Web Service を手動で作成します:

   • ビルドコマンド: npm install && npm run build

   • 開始コマンド: npm run start:http

   • ヘルスチェックパス: /health

3. Render ダッシュボードで、PUBLIC_MCP_API_KEY 環境変数に強力なシークレットを設定します (決してコミットしないでください)。

4. デプロイ後、取得した URL とキーを api.env に設定します: PUBLIC_MCP_URL=https://<your-service>.onrender.com/mcp と PUBLIC_MCP_API_KEY=<same secret>。

5. Inspector で検証します:

   • キーなし → 拒否: curl -X POST https://<url>/mcp -H "Content-Type: application/json" -d "{...}" は 401 を返します。

   • キーあり → 動作: npx @modelcontextprotocol/inspector --cli <url> --method tools/list に --header "x-api-key: <secret>" を渡します。

Agent Host

npm run agent          # interactive CLI
npm run agent:demo      # runs a scripted set of demo queries

起動時にホストは次のことを行います:

1. SKILL.md をシステム指示として読み込みます。

2. config/servers.json を読み取り、stdio サーバー (自動的に起動)、ローカル HTTP サーバー (すでに実行されている必要があります)、パブリック HTTP サーバー (PUBLIC_MCP_URL/PUBLIC_MCP_API_KEY が設定されていない場合は自動的にスキップ — ライブデプロイがなくてもデモが動作するようにオプションです) に接続します。

3. すべてのツールを検出して名前空間化し、Gemini に渡し、Gemini が行う各ツール呼び出しを正しい MCP サーバーにディスパッチします。

設定

サーバー登録は config/servers.json によるデータ駆動型です。ホストコードを編集する代わりに、そこでサーバーを追加/削除します。url 内の ${VAR} は接続時に process.env から解決されます。apiKeyEnv は、その値が x-api-key として送信される環境変数を指定します。

Agent Skill

SKILL.md は、エージェントに対して、算術/変換/テキスト統計を推測するよりもツールを呼び出すことを優先し、論理的なリクエストごとに 1 つの名前空間化されたツールを選択し、サポートされている変換について不明な場合は docs://unit-conversions リソースを参照し、結果を平易な言葉で説明するよう指示します。これは毎回の実行で Gemini のシステム指示にそのまま読み込まれるため (src/host/skill-loader.ts を参照)、そのルールはツールの選択と応答スタイルに直接影響します — デモ出力で確認できます (例: エージェントは算術を自分で計算せず、常にツールを呼び出します)。

セキュリティに関する注意事項

• シークレットはコミットされません。api.env は gitignore されており、パブリックサーバーは環境から PUBLIC_MCP_API_KEY のみを読み取ります。

• パブリック HTTP サーバーは、一致する x-api-key ヘッダーのないリクエストを拒否し (401)、有効なキーが提供されるとリクエストを受け入れます。