mcp-arena (prototype)

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

핵심 아이디어

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

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

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

상담 플로우 확인 (get_build_flow)
전략/스크립트 초안 생성 (coach_robot_design)
사용자에게 부족한 정보 질문 (playStyle/risk/objective)
스크립트 검증 (validate_robot_script)
프리뷰 대전 (preview_robot_duel)
사용자 승인 후 최종 업로드 (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.js         # REST + MCP endpoint (consultative tools 포함)
│  │     ├─ parser.js        # 로봇 스크립트 DSL parser
│  │     └─ battleEngine.js  # 전투 엔진 + replay timeline 생성
│  ├─ web/
│  │  ├─ app/
│  │  │  ├─ page.js
│  │  │  └─ globals.css
│  │  ├─ components/
│  │  │  └─ ArenaReplay.js   # 캔버스 리플레이
│  │  └─ .env.local          # 로컬 API base
│  └─ mcp-bridge/
│     └─ index.js            # stdio MCP bridge
├─ .mcp.json
├─ firebase.json
├─ firestore.rules
└─ storage.rules

parser.js DSL

한 줄에 한 명령:

MOVE <1-3>: 전진
ROTATE LEFT|RIGHT|NONE (또는 ROTATE 0)
SHOOT: 전방 5칸 시야 + 직선 사선이 맞으면 타격(원샷킬)
WAIT
IF_SEEN <MOVE|ROTATE|SHOOT|WAIT ...>: 적이 보일 때만 실행
IF_NOT_SEEN <MOVE|ROTATE|SHOOT|WAIT ...>: 적이 안 보일 때만 실행
# 주석

예시:

IF_SEEN SHOOT
MOVE 1
IF_NOT_SEEN ROTATE RIGHT
IF_SEEN SHOOT
WAIT

자동 시야 규칙

매 턴 자동으로 시야 정보가 갱신됩니다 (별도 SCAN 불필요)
시야 범위: 전방 반원, 반경 5칸
시야 데이터: enemyVisible, enemy.dx, enemy.dy, enemy.distance, enemy.bearing
배틀 로그(timeline)에도 각 액션의 perceptionBefore/perceptionAfter가 포함됩니다.

API

기본 경로: /api

GET /api/health
GET /api/robots
POST /api/robots
POST /api/battles
GET /api/battles/:battleId
POST /api/mcp (JSON-RPC)

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

initialState
timeline (액션별 before/after, 탄환 궤적)
turns
finalState

MCP 툴 목록 (상담형)

get_build_flow
- 에이전트가 사람과 어떤 순서로 상담할지 안내
coach_robot_design
- 사람의 의도/성향을 받아 로봇 초안(규칙+스크립트) 생성
- 부족 정보가 있으면 followUpQuestions 반환
validate_robot_script
- DSL 문법 + 전술 품질 체크(경고/추천)
preview_robot_duel
- 후보 스크립트를 프리뷰 배틀로 점검
upload_robot_script
- 최종 로봇 업로드
- userApprovalConfirmed=true가 아니면 업로드가 차단됨(최종 사용자 승인 강제)

로컬 실행 (Emulator)

현재 기본 로컬 ID:

.firebaserc -> mcp-arena-local

웹 API:

apps/web/.env.local
- NEXT_PUBLIC_API_BASE_URL=http://127.0.0.1:5001/mcp-arena-local/us-central1/api

실행:

yarn install
yarn emulators

별도 터미널:

yarn dev:web

브라우저 http://localhost:3000:

로봇 2개 이상 업로드
배틀 실행
Replay 재생/프레임 이동

Agent 연결용 MCP 브리지 (stdio)

에이전트는 stdio MCP 서버를 사용하므로 브리지를 연결합니다.

yarn dev:mcp-bridge

기본 포워딩 대상:

http://127.0.0.1:5001/mcp-arena-local/us-central1/api/mcp

원격 배포 API로 전환:

MCP_ARENA_API_BASE_URL=https://<region>-<project-id>.cloudfunctions.net/api yarn dev:mcp-bridge

Claude / Codex 등록 예시

Claude Code

claude mcp add mcp-arena node /ABSOLUTE/PATH/mcp-arena/apps/mcp-bridge/index.js

Codex CLI

codex mcp add mcp-arena --env MCP_ARENA_API_BASE_URL=http://127.0.0.1:5001/mcp-arena-local/us-central1/api -- node /ABSOLUTE/PATH/mcp-arena/apps/mcp-bridge/index.js

에이전트에게 줄 사용자 프롬프트 예시

mcp arena에 ai 로봇을 만들어 업로드해줘.
내 성향은 공격적이지만 너무 운빨은 싫어.
최종 업로드 전에 스크립트 검증하고 프리뷰 대전 결과도 보여줘.

이렇게 요청하면 에이전트는 보통 아래 방식으로 진행합니다.

get_build_flow 확인
coach_robot_design으로 초안 생성
사용자에게 follow-up 질문
validate_robot_script
preview_robot_duel
사용자 승인 후 upload_robot_script

배포 가이드

1) 실제 Firebase 프로젝트로 전환

.firebaserc의 default를 실제 프로젝트 ID로 변경
apps/web/.env.local의 API URL을 배포 URL로 변경

예시:

NEXT_PUBLIC_API_BASE_URL=https://<region>-<project-id>.cloudfunctions.net/api

2) 웹 빌드 + 배포

yarn build:web
firebase deploy --only hosting,functions,firestore,storage

배포 후 MCP 브리지도 같은 URL로 연결해 사용합니다.

라이선스

이 프로젝트는 PolyForm Noncommercial 1.0.0 라이선스를 따릅니다.

코드 다운로드/실행/수정/비상업적 배포: 허용
상업적 이용: 금지

자세한 내용은 루트 LICENSE 파일을 확인하세요.

현재 규칙

정사각형 아레나
로봇 2대
시작 위치 (0,0) vs (N-1,N-1)
명령 루프 실행
전방 5칸 자동 시야 갱신
조건 분기(IF_SEEN, IF_NOT_SEEN) 지원
SHOOT 적중 시 즉시 사망
승자 없으면 draw

주의

현재 firestore.rules, storage.rules는 프로토타입용 전체 허용입니다. 실제 서비스 전에는 인증/권한 규칙을 반드시 강화해야 합니다.

mcp-arena