MCP Grand Prix

Ein MVP eines LLM-gesteuerten 3D-Rennspiels. LLM-Agenten steuern Formula-1-Rennwagen über eine gemeinsame Rennstrecke durch eine hybride Rennschleife – strategische Planung, Physiksimulation und kurze reaktive Entscheidungsfenster –, während ein Browser-Zuschauerclient das Rennen live verfolgt.

Das Projekt ist ein MCP-Server, der LLM-Agenten Werkzeuge für Spielzustand und Strategie bereitstellt, dazu ein Three.js-Zuschauer-Dashboard und eine kleine Flotte skriptgesteuerter/LLM-Agenten.

Architektur

┌────────────┐   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 – der server-autoritative Spielkern. Er verwaltet den gesamten Spielzustand und stellt deterministische, idempotente Tool-Methoden bereit (startRace, submitPhaseStrategy, reactToEvent, step). Dieselben Methoden werden echten LLMs über MCP und prozessinternen Skriptagenten bereitgestellt, sodass das Verhalten unabhängig davon identisch ist, wer sie aufruft.

• src/mcp/server.ts – der MCP-Server (JSON-RPC/SSE), der die Tools der Engine den Agenten bereitstellt.

• src/game/raceRunner.ts – treibt die hybride Rennschleife (Strategie → Simulation → reaktive Fenster) Tick für Tick voran.

• src/server/ – der HTTP- und WebSocket-Server sowie der Zuschauer-Feed.

• www/ – der Browser-Zuschauerclient (Three.js).

Related MCP server: startline

Rennschleife

1. Strategiephase – Jede Runde übermitteln alle Agenten ein StrategyPacket (Reifenmischung, Fahrmodus, Kraftstoffsparen, optionale Boxenstopp-Runde).

2. Simulationsphase – Die Engine rechnet die Physik in jedem Tick neu.

3. Reaktive Fenster – Trigger-Ereignisse (enge Duelle, Safety-Cars, Wetter, Reifenverschleiß) öffnen kurze Fenster innerhalb der Runde, in denen die betroffenen Agenten mit Aktionen wie (push / save / pit_now / attack / defend) reagieren.

Schnellstart

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

Öffne das Zuschauer-Dashboard unter http://localhost:3000 und starte ein Rennen:

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

Der Browser verbindet sich zum selben Host/Port über WebSocket (/ws) für Live-Updates.

Ein skriptgesteuertes Rennen über die CLI ausführen

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

Konfiguration (Umgebungsvarianten)

PORT wird verwendet, um die Kompatibilität mit Serverless-Plattformen zu gewährleisten (Vercel setzt z. B. PORT).

Skripte

Testen

• Unit-Tests (npm test) decken den öffentlichen Vertrag der Renn-Engine ab – Lebenszyklus, Strategieabgabe, reaktive Antworten und kompletten Rennabschluss – geprüft gegen den echten Engine-Kern.

• End-to-End-Tests (npm run test:e2e) starten den Server, initialisieren ein Rennen und prüfen, dass auf der Clientseite Fahrzeuge und eine Live-Rangliste gerendert werden, dass das Rennen fortschreitet und mit einem Sieger endet, und dass die reaktive Benutzeroberfläche in den Fenstern erscheint.

MCP-Tools

Der Server gibt vier MCP-Tools frei (siehe src/mcp/server.ts):

Echte LLM-Agenten verbinden sich als MCP-Clients (SSE), um diese Tools aufzurufen; skriptgesteuerte Agenten rufen die Engine-Methoden direkt in-process auf. startRace und step sind genau die internen Step-Methoden des Renn-Runners und werden nicht als MCP-Tools exponiert.