MCP Grand Prix

一个 LLM 驱动的 3D 赛车游戏 的 MVP。LLM 智能体在一个共享赛道上通过一个混合式比赛循环——策略规划、物理模拟和短时响应决策窗口——驾驶 Formula 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）。这些相同的方法既通过 MCP 暴露给真实的 LLM，也可供进程内脚本化智能体调用，因此无论调用者是谁，行为都完全一致。

• src/mcp/server.ts —— MCP（JSON-RPC/SSE）服务器，将引擎的工具暴露给智能体。

• src/game/raceRunner.ts —— 逐 tick 驱动混合式比赛循环（策略 → 模拟 → 响应窗口）。

• src/server/ —— HTTP + WebSocket 服务与观赛数据流。

• www/ —— 浏览器观赛客户端（Three.js）。

Related MCP server: startline

比赛循环

1. 策略阶段 —— 每一圈，所有智能体提交一个 StrategyPacket（轮胎配方、驾驶模式、省油设置、可选的进站圈）。

2. 模拟阶段 —— 引擎每个 tick 推进物理模拟。

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 工具

服务器暴露四个 MCP 工具（见 src/mcp/server.ts）：

真实的 LLM 智能体通过 MCP 客户端（SSE）连接并调用这些工具；脚本化智能体调用引擎的方法（in-process，进程内）。startRace 和逐 tick 的 step 属于 running runner，内部使用，不作为 MCP 暴露。