MCP Grand Prix

Это MVP гоночной 3D-игры на основе LLM. LLM-агенты управляют автомобилями Формулы-1 на общей трассе через гибридный гоночный цикл — стратегическое планирование, симуляцию физики и короткие реактивные окна принятия решений — пока браузерный клиент для зрителей следит за гонкой в прямом эфире.

Проект представляет собой MCP-сервер, который открывает LLM-агентам инструменты состояния игры и стратегии, а также включает 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). Эти же методы передаются реальным LLM через MCP и скриптовым агентам в рамках процесса, поэтому поведение идентично независимо от того, кто их вызывает.

• src/mcp/server.ts — MCP-сервер (JSON-RPC/SSE), который открывает инструменты движка для агентов.

• src/game/raceRunner.ts — управляет гибридным гоночным циклом (стратегия → симуляция → реактивные окна) шаг за шагом.

• src/server/ — HTTP + WebSocket сервер и канал для зрителей.

• www/ — браузерный клиент для зрителей (Three.js).

Related MCP server: startline

Гоночный цикл

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) для получения живых обновлений.

Запуск гонки со скриптовыми агентами из командной строки

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

Конфигурация (переменные окружения)

PORT используется, чтобы приложение было совместимо с serverless-платформами (например, Vercel задаёт PORT).

Скрипты

Тестирование

• Юнит-тесты (npm test) покрывают публичный контракт гоночного движка — жизненный цикл, отправку стратегии, реактивные ответы и полное завершение гонки — на реальном ядре движка.

• Сквозные тесты (npm run test:e2e) поднимают сервер, запускают гонку и проверяют, что браузер отображает автомобили и живую таблицу лидеров, что гонка продвигается и завершается победителем, и что появляется интерфейс реактивного окна.

MCP-инструменты

Сервер предоставляет четыре MCP-инструмента (см. src/mcp/server.ts):

Реальные LLM-агенты подключаются как MCP-клиенты (SSE) для вызова этих инструментов; скриптовые агенты вызывают методы движка в процессе. startRace и пофазовый step являются внутренними для гоночного раннера и не предоставляются как MCP-инструменты.