MCP Grand Prix

An MVP of an LLM-driven 3D racing game. LLM agents steer Formula 1 cars over a shared circuit through a hybrid race loop — strategic planning, physics simulation, and short reactive decision windows — while a browser spectator client watches the race live.

The project is an MCP server exposing game-state and strategy tools to LLM agents, plus a Three.js spectator dashboard and a small fleet of scripted/LLM agents.

Architecture

┌────────────┐   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 — the server-authoritative game core. Owns all game state and exposes deterministic, idempotent tool methods (startRace, submitPhaseStrategy, reactToEvent, step). The same methods are served to real LLMs over MCP and to in-process scripted agents, so behaviour is identical regardless of who is calling.

• src/mcp/server.ts — the MCP (JSON-RPC/SSE) server exposing the engine's tools to agents.

• src/game/raceRunner.ts — drives the hybrid race loop (strategy → simulation → reactive windows) tick by tick.

• src/server/ — the HTTP + WebSocket server and spectator feed.

• www/ — the browser spectator client (Three.js).

Related MCP server: fastf1-mcp

Race loop

1. Strategy Phase — every lap, all agents submit a StrategyPacket (tire compound, drive mode, fuel save, optional pit lap).

2. Simulation Phase — the engine advances physics each tick.

3. Reactive Windows — trigger events (close battles, safety cars, weather, tire wear) open short mid-lap windows where involved agents respond (push / save / pit_now / attack / defend).

Quick start

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

Open the spectator dashboard at http://localhost:3000 and start a race:

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

The browser connects to the same host/port over WebSocket (/ws) for live updates.

Run a scripted race from the CLI

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

Configuration (environment variables)

PORT is used so the app is compatible with serverless platforms (e.g. Vercel sets PORT).

Scripts

Testing

• Unit tests (npm test) cover the race engine's public contract — lifecycle, strategy submission, reactive responses, and full-race completion — against the real engine core.

• End-to-end (npm run test:e2e) boots the server, starts a race, and asserts the browser renders cars and a live leaderboard, that the race progresses and finishes with a winner, and that reactive-window UI appears.

MCP tools

The server exposes four MCP tools (see src/mcp/server.ts):

Real LLM agents connect as MCP clients (SSE) to call these tools; scripted agents call the engine's methods in-process. startRace and the per-tick step are internal to the race runner rather than exposed as MCP tools.