MCP Arena MCP Server

mcp-arena (prototype)

Firebase Hosting + Functions + Firestore + Storage 기반의 MCP 연동 로봇 배틀 프로토타입입니다. (TypeScript)

핵심 아이디어

사람은 에이전트에게 이렇게 말합니다.

• "mcp arena에 ai 로봇 만들어서 업로드해줘"

그러면 에이전트가 MCP 툴 체인을 사용해 다음 순서로 진행합니다.

1. 상담 플로우 확인 (get_build_flow)
2. 전략/스크립트 초안 생성 (coach_robot_design)
3. 사용자에게 부족한 정보 질문 (playStyle/risk/objective)
4. 스크립트 검증 (validate_robot_script)
5. 프리뷰 대전 (preview_robot_duel)
6. 사용자 승인 후 최종 업로드 (upload_robot_script)

즉, 단순 업로드가 아니라 전술 상담 -> 검증 -> 시뮬레이션 -> 업로드를 MCP 안에서 지원합니다.

에이전트 응답 매너 메모

• 기본적으로 존댓말로 응답합니다.
• 사용자가 승인/허락/협업 제안을 해주면 감사 인사를 명시합니다. (감사합니다.)
• 말투는 간결하게 유지하되, 실행 결과와 근거는 분명하게 전달합니다.

구성

• 모노레포(yarn workspaces)
• apps/web: Next.js 프론트엔드(로봇 업로드, 배틀 실행, 캔버스 리플레이)
• apps/functions: Firebase Functions API + MCP(JSON-RPC)
• apps/mcp-bridge: stdio MCP 브리지(에이전트 연결용)
• Firestore: 로봇/배틀 메타데이터 저장
• Storage: 로봇 원본 스크립트 저장

디렉터리

.
├─ apps/
│  ├─ functions/
│  │  └─ src/
│  │     ├─ index.ts         # REST + MCP endpoint (consultative tools 포함)
│  │     ├─ parser.ts        # 로봇 스크립트 DSL parser
│  │     └─ battleEngine.ts  # 전투 엔진 + replay timeline 생성
│  ├─ web/
│  │  ├─ app/
│  │  │  ├─ page.tsx
│  │  │  └─ globals.css
│  │  ├─ components/
│  │  │  └─ ArenaReplay.tsx  # 캔버스 리플레이
│  │  └─ .env.local          # 로컬 API base
│  └─ mcp-bridge/
│     ├─ index.ts            # stdio MCP bridge source
│     └─ index.js            # 실행 엔트리 (dist 로더)
├─ .mcp.json
├─ firebase.json
├─ firestore.rules
└─ storage.rules

parser.js DSL

한 줄에 한 규칙(매 틱 전체 규칙을 위에서 아래로 평가):

• SET THROTTLE <-1..1>: 전/후진 입력 (+ 전진, - 후진)
• SET STRAFE <-1..1>: 좌/우 횡이동 입력 (+ 우, - 좌)
• SET TURN <-1..1>: 좌/우 회전 입력 (+ 우회전, - 좌회전)
• FIRE 또는 FIRE ON|OFF: 사격 트리거 (에너지 소모)
• BOOST LEFT|RIGHT: 에너지를 소모해 좌/우 횡부스터 대시
• IF ENEMY_VISIBLE THEN <COMMAND>
• IF NOT ENEMY_VISIBLE THEN <COMMAND>
• IF <EXPR> <OP> <EXPR> THEN <COMMAND>
• IF (<COND>) AND (<COND>) THEN <COMMAND>
• IF (<COND>) OR (<COND>) THEN <COMMAND>
• IF NOT (<COND>) THEN <COMMAND>
  • 센서: ARENA_SIZE, SHOT_RANGE, SHOT_HIT_RADIUS, SELF_X, SELF_Y, SELF_HEADING, SELF_ENERGY, BOOST_COOLDOWN, TICKS_SINCE_ENEMY_SEEN, ENEMY_X, ENEMY_Y, ENEMY_HEADING, ENEMY_DX, ENEMY_DY, ENEMY_DISTANCE, ENEMY_FORWARD_DISTANCE, ENEMY_LATERAL_OFFSET, PREV_ENEMY_X, PREV_ENEMY_Y, PREV_ENEMY_HEADING, PREV_ENEMY_DX, PREV_ENEMY_DY, PREV_ENEMY_DISTANCE, ENEMY_DX_DELTA, ENEMY_DY_DELTA, ENEMY_DISTANCE_DELTA, WALL_AHEAD_DISTANCE, WALL_LEFT_DISTANCE, WALL_RIGHT_DISTANCE, WALL_BACK_DISTANCE, WALL_NEAREST_DISTANCE
  • 수식: +, -, *, /, (), 상수 PI, TAU
  • 함수: ATAN2(y, x), ANGLE_DIFF(targetDeg, currentDeg), NORMALIZE_ANGLE(angleDeg), ABS(x), MIN(a,b), MAX(a,b), CLAMP(x,min,max)
  • 비교 연산자: >, >=, <, <=, ==, !=
  • 논리 연산자: AND, OR, NOT (괄호 우선순위 지원)
• # 주석

예시:

SET THROTTLE 0.7
SET STRAFE 0.15
SET TURN 0.2
FIRE OFF
IF ANGLE_DIFF(ATAN2(ENEMY_DY, ENEMY_DX), SELF_HEADING) > 4 THEN SET TURN 1
IF ANGLE_DIFF(ATAN2(ENEMY_DY, ENEMY_DX), SELF_HEADING) < -4 THEN SET TURN -1
IF ENEMY_DISTANCE < 1.8 THEN SET THROTTLE -0.6
IF ENEMY_VISIBLE THEN FIRE ON

자동 시야 규칙

• 매 틱 자동으로 시야 정보가 갱신됩니다 (별도 SCAN 불필요)
• 시야 범위: 전방 반원, 반경 8칸
• 총 사거리: 전방 5칸 (시야와 별도)
• 시야 데이터: enemyVisible, enemy.dx, enemy.dy, enemy.distance, enemy.bearing, enemy.headingDeg, enemy.headingDirection, wall.aheadDistance, wall.leftDistance, wall.rightDistance, wall.backDistance, wall.sightArc(leftEdge/center/rightEdge)
• 배틀 로그(timeline)에도 각 액션의 perceptionBefore/perceptionAfter가 포함됩니다.

실시간 틱 규칙

• 전투는 턴제가 아니라 실시간 틱 기반으로 진행됩니다.
• 이동/회전/사격 입력은 같은 틱에 중복 적용됩니다.
• 이동 속도 우선순위: 전진(빠름) > 횡이동(중간) > 후진(느림)
• FIRE ON 상태에서는 이동 속도와 회전 속도가 각각 절반으로 감소합니다.
• 사격은 쿨다운 1틱 개념이며(실질적으로 매 틱 발사 가능), 에너지(SELF_ENERGY)를 소모합니다.
• 발사체는 즉시 명중하지 않고 비행 시간을 가집니다(현재 2틱/칸, 사거리 5칸이면 최대 약 10틱 비행).
• 사이드 부스터(BOOST LEFT|RIGHT)는 발동 후 5틱 동안 5→4→3→2→1 강제 횡이동(총 15틱 분량)을 수행합니다.
• 사이드 부스터는 에너지(SELF_ENERGY)를 소모하고 쿨다운(BOOST_COOLDOWN, 10틱)을 사용합니다.

API

기본 경로: /api

• GET /api/health
• GET /api/robots
• POST /api/robots
• GET /api/robots/:robotId/avatar (업로드된 SVG 로봇 이미지)
• POST /api/battles
• GET /api/battles/:battleId
• POST /api/mcp (JSON-RPC)

배틀 결과에는 리플레이용 데이터가 포함됩니다.

• maxTicks
• tickDurationMs
• projectileTiming
• movementTiming
• initialState
• timeline (액션별 before/after, 탄환 궤적)
• ticks (turns는 하위호환 alias)
• finalState

MCP 툴 목록 (상담형)

• get_build_flow
  • 에이전트가 사람과 어떤 순서로 상담할지 안내
• coach_robot_design
  • 사람의 의도/성향을 받아 로봇 초안(규칙+스크립트) 생성
  • 부족 정보가 있으면 followUpQuestions 반환
• validate_robot_script
  • DSL 문법 + 전술 품질 체크(경고/추천)
• preview_robot_duel
  • 후보 스크립트를 프리뷰 배틀로 점검
  • 서버 모드에서는 opponentScript를 직접 넣어야 하며 preset 상대는 제공되지 않음
• upload_robot_script
  • 최종 로봇 업로드
  • collaboratorAgents는 최소 1개 이상이며 각 항목은 {name, version, role?} 형식을 권장
  • robotImageSvg(SVG 문자열)는 필수이며, 로봇 전용 이미지를 저장
  • `userApproval