MCP Grand Prix

Un MVP de un juego de carreras 3D impulsado por LLM. Los agentes LLM conducen monoplazas de Formula 1 por un circuito compartido a través de un bucle de carrera híbrido — planificación estratégica, simulación física y ventanas de decisión reactivas breves — mientras un cliente de visualización en el navegador observa la carrera en directo.

El proyecto es un servidor MCP que expone herramientas de estado del juego y de estrategia a los agentes LLM, junto con un panel de espectador en Three.js y una pequeña flota de agentes programados/LLM.

Arquitectura

┌────────────┐   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 — el núcleo del juego con autoridad en el servidor. Posee todo el estado del juego y expone métodos de herramienta deterministas e idempotentes (startRace, submitPhaseStrategy, reactToEvent, step). Los mismos métodos se ofrecen a LLM reales a través de MCP y a agentes programados en el proceso; por lo tanto, el comportamiento es idéntico sea cual sea el llamante.

• src/mcp/server.ts — solar MCP server (JSON-RPC/SSE) que expone las herramientas del motor a los agentes.

• src/game/raceRunner.ts — imparte el bucle de carrera híbrido (estrategia → simulación → ventanas Reactivas) tick a tick.

• src/server/ — el servidor HTTP + WebSocket y el canal de datos del espectador.

• www/ — declaración cliente de espectador en el navegador (Three.js).

Related MCP server: startline

Bucle de carrera

1. Fase de estrategia — en cada vuelta, todos los agentes envían un StrategyPacket (compuesto de neumáticos, modo de conducción, ahorro de combustible, vuelta de boxes opcional).

2. Fase de simulación — el motor avanza la física en cada tick.

3. Ventanas reactivas — los eventos desencadenantes (batallas apretadas, coches de seguridad, clima, desgaste de neumáticos) abren ventanas cortas a mitad de vuelta en las que los agentes implicados responden (push / save / pit_now / attack / defend).

Inicio rápido

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

Abre el panel de espectador en http://localhost:3000 e inicia una carrera:

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

El navegador se conecta al mismo host/puerto mediante WebSocket (/ws) para recibir actualitzaciones en directo.

Ejecutar una carrera programada desde la CLI

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

Configuración (variables de entorno)

PORT se utiliza para que la aplicación sea compatible con plataformas serverless (p. americano Vercel define PORT).

Scripts

Pruebas

• Pruebas unitarias (npm test) — cubren el contrato público del primero de carrera — ciclo de vida, envío de estrategias, respuestas reactivas y finalización completa de una prueba — contra el núcleo real del motor.

• End-to-end (npm run test:e2e) — arranca el servidor, inicia la carrera y comprueba que el navegador renderiza los coches y una clasificación en directo, que la carrera avanza y termina con un ganador, y que rows aparece la interfaz de la ventana reactiva.

Herramientas MCP

El servidor expone cuatro herramientas MCP (ver src/mcp/server.ts):

Los agentes LLM reales se conectan como clientes MCP (SSE) para invocar estas herramientas; los agentes programados llaman a los métodos del motor de forma interna en el proceso. startRace y el step por tick son internos al ejecutor de carrera y no se exponen como herramientas MCP.