MCP GPS76famous

Hmm, that doesn't seem right. Let me restart.

MCP Grand Prix

LLM이 이끄는 3D 레이싱 게임의 MVP입니다. LLM 에이전트가 공유 서킷 위에서 하이브리드 레이스 루프 — 전략 계획, 물리 시뮬레이션, 짧은 반응형 의사결정 창 — 를 통해 Formula 1 차량을 조종합니다. 그동안 브라우저 관전 클라이언트가 레이스를 실시간으로 지켜봅니다.

이 프로젝트는 LLM 에이전트에게 게임 상태와 전략 도구를 제공하는 MCP 서버입니다. 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 — 서버가 최종 권한을 가지는(server-authoritative) 게임 코어입니다. 모든 게임 상태를 소유하며 결정적(deterministic)이고 멱등적(idempotent)인 도구 메서드(startRace, submitPhaseStrategy, reactToEvent, step)를 노출합니다. 동일한 메서드는 MCP를 통해 실제 LLM과 프로세스 내부의 스크립트 에이전트 양쪽에 제공되므로, 호출하는 주체가 누구든 동작은 동일합니다.

• src/mcp/server.ts — 엔진의 도구를 에이전트에 노출하는 MCP(JSON-RPC/SSE) 서버입니다.

• src/game/raceRunner.ts — 하이브리드 레이스 루프(전략 → 시뮬레이션 → 반응형 윈도우)를 틱 단위로 구동합니다.

• src/server/ — HTTP + WebSocket 서버와 관전 피드를 담당합니다.

• www/ — 브라우저 관전 클라이언트(Three.js)입니다.

Related MCP server: fastf1-mcp

레이스 루프

1. 전략 단계(Strategy Phase) — 모든 랩마다 모든 에이전트가 StrategyPacket(타이어 커파운드, 주행 모드, 연료 절약, 선택적 피트 랩)을 제출합니다.

2. 시뮬레이션 단계(Simulation Phase) — 엔진이 각 틱마다 물리 시뮬레이션을 진행합니다.

3. 반응형 윈도우(Reactive Windows) — 근접 접전, 세이프티 카, 날씨, 타이어 마모 같은 트리거 이벤트가 랩 중반에 짧은 윈도우를 열면, 관련 에이전트들이 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)로 연결되어 이 도구들을 호출하고, 스크립트 에이전트는 엔진 메서드를 프로세스 내부에서 호출합니다. startRace는과 틱 단위 step은 레이스 러너 내부 전용이며, MCP 도구로 노출되지 않습니다.