MCP Grand Prix

LLM駆動型の3DレーシングゲームのMVPです。LLMエージェントが共有サーキット上でFormula 1カーを走らせ、ハイブリッドレースループ（戦略立案、物理シミュレーション、短いリアクティブな意思決定ウィンドウ）を経て進みます。その間、ブラウザの観戦クライアントがレースをライブで見守ります。

このプロジェクトは、ゲームの状態と戦略ツールをLLMエージェントに公開するMCPサーバーであり、加えてThree.jsの観戦ダッシュボードと、少数のスクリプト/LLMエージェント群から構成されます。

アーキテクチャ

┌────────────┐   MCP (SSE)   ┌───────────────┐   tool calls   ┌──────────────┐
│  LLM agents│ ────────────▶ │  src/mcp      │ ◀───────────── │  RaceEngine  │
│ (LLM or    │               │  server.ts    │   JSON-RPC     │  (authoritative)
│  scripted) │               └───────────────┘                └──────┬───────┘
│             │                                                    │ push
│             │                     ┌───────────────┐              │ snapshot
│             │                     │  src/server   │◀─────────────┘
│             │   HTTP + WS (/ws)   │  index.ts     │
└────────────┘ ◀────────────────── │  spectator    │
        Browser spectator        └───────────────┘
        (Three.js, www/client.js)

• src/game/raceEngine.ts — サーバー権威型のゲームコア。すべてのゲーム状態を保持し、決定的かつ冪等なツールメソッド（startRace、submitPhaseStrategy、reactToEvent、step）を公開します。同じメソッドはMCP経由で実際のLLMにも提供され、プロセス内のスクリプトエージェントにも提供されるため、呼び出し元に関わらず挙動は同一です。

• src/mcp/server.ts — エンジンのツールをエージェントに公開するMCP（JSON-RPC/SSE）サーバー。

• src/game/raceRunner.ts — ハイブリッドレースループ（戦略 → シミュレーション → リアクティブウィンドウ）をティックごとに駆動します。

• src/server/ — HTTP + WebSocketサーバーと観客向けフィード。

• www/ — ブラウザ上の観戦クライアント（Three.js）。

Related MCP server: fastf1-mcp

レースループ

1. 戦略フェーズ — 各ラップで、全エージェントが StrategyPacket（タイヤコンパウンド、ドライブモード、燃料、任意のピットラップ）を提出します。

2. シミュレーションフェーズ — エンジンはティックごとに物理演算を進めます。

3. リアクティブウィンドウ — トリガーイベント（接戦、セーフティカー、天候、タイヤの摩耗）がラップ途中の短いウィンドウを開き、関係するエージェントが（push / save / pit_now / attack / defend）で応答します。

クイックスタート

npm install
npm run build   # prebuild copies three.js into www/lib
npm start       # serves the spectator app + MCP server

観戦ダッシュボードを http://localhost:3000 で開き、レースを開始します：

curl -X POST http://localhost:3000/race

ブラウザはWebSocket（/ws）で同じホスト/ポートに接続し、ライブ更新を受け取ります。

CLIからスクリプトレースを実行する

npm run agents        # launches 4 scripted agents in a full race (demo)

設定（環境変数）

PORT はサーバーレスプラットフォームとの互換性のために使用されます（例：Vercel が PORT を設定します）。

スクリプト

テスト

• ユニットテスト（npm test）は、実エンジンコアに対して、レースエンジンの公開コントラクト — ライフサイクル、戦略提出、リアクティブ応答、フルレース完了 — をカバーします。

• エンドツーエンド（npm run test:e2e）はサーバーを起動してレースを開始し、ブラウザがマシンとライブ順位表を描画すること、レースが進行して勝者とともに完了すること、そしてリアクティブウィンドウのUIが表示されることを検証します。

MCPツール

サーバーは4つのMCPツールを公開します（src/mcp/server.ts を参照）：

実際のLLMエージェントはMCPクライアント（SSE）として接続し、これらのツールを呼び出します。スクリプトエージェントはエンジンのメソッドをプロセス内で呼び出します。startRace と毎ティックの step はレースランナー内部のものであり、MCPツールとしては公開されません。