5.4 KiB

Raw Blame History

Unity MCP 연동 가이드 v1 (BurningTimes)

목적: BT 조직 개발자가 Unity MCP를 처음 연동·재설치할 때 따를 표준 절차.

대상: 개발팀·기획팀 (MCP 도구로 Unity Editor 조작 필요한 전원)

최종 수정: 2026-04-21

참조 규칙: C6-1 원본 보호 · C30 git 동기화 · C34-11 Agent 경계 · C11 개발 관점

1. 구성 개요

구성	역할
CoplayDev MCP for Unity (v9.6.x)	Python 기반 MCP 서버 + Unity 에디터 패키지 2종
uv (Astral)	Python 패키지·스크립트 실행 환경 (MCP 서버 구동에 필요)
Claude Desktop	MCP 클라이언트. 본 BT 조직 기본 환경
EerieVillage Unity 프로젝트	MCP 대상 Unity 프로젝트 (`E:/NerdNavis/EerieVillage/EerieVillage/`)

통신 방식: HTTP (권장, 기본값) — Unity 에디터 내 패키지가 localhost:8080/mcp 서버 자동 구동 → Claude Desktop이 해당 URL로 연결

2. 사전 요구 사항

Python 3.10+ (python --version 확인)
uv 설치 (없으면 Step 3-B 참조)
Unity 2021.3 LTS+ (EerieVillage는 6000.3.13f1 LTS)
본 레포 git clone + setup/setup_windows.ps1 또는 setup/setup_macos.sh 실행 (unity-mcp 자동 clone 포함)

3. 설치 절차 (신규 PC 기준)

3-A. BT 레포 셋업

# Windows
git clone https://burning.i234.me/NerdNavis_AiDev/BurningTimesAi.git "E:/BurningTimes"
cd E:/BurningTimes
cp paths.local.json.template paths.local.json
# UNITY_PROJECT_ROOT 등 실값 입력
.\setup\setup_windows.ps1

→ 자동으로 코어코드/unity-mcp/에 CoplayDev 저장소 clone됨.

3-B. uv 설치

# Windows (winget 권장)
winget install --id=astral-sh.uv -e

# macOS / Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

설치 후 PATH 반영을 위해 터미널 재시작.

3-C. Claude Desktop MCP 설정

공유/개발팀_자산/claude_desktop_config.example.json 내용을 복사
Claude Desktop 설정 파일 위치에 붙여넣기 (기존 mcpServers 있으면 병합)
- Windows: %APPDATA%\Claude\claude_desktop_config.json
- macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Claude Desktop 완전 재시작 (작업 표시줄 아이콘 우클릭 → Quit → 재실행)

3-D. Unity Editor에 MCP 패키지 설치

Unity Hub에서 EerieVillage 프로젝트 열기
Window > Package Manager > + > Add package from git URL...
입력: https://github.com/CoplayDev/unity-mcp.git?path=/MCPForUnity#main
설치 완료 시 Unity 메뉴에 MCP 관련 메뉴 생성
MCP 서버 자동 구동 확인 (localhost:8080 리스닝)

3-E. 연동 검증

Claude Desktop 재시작 완료 상태 + Unity Editor + EerieVillage 프로젝트 열려 있음
Claude 세션에서 mcp__unity-mcp__* 도구 호출 테스트 (예: mcp__unity-mcp__manage_editor action: get_state)
Unity Editor에서 응답 반영 확인 (GameObject·씬·asset 조작 가능 여부)

4. BT 조직 Unity MCP 편집 표준 워크플로우 v2

v1 계승 근거: 공유/조직자산/시행착오_아카이브/개발_클라이언트팀장_v1.md §Unity MCP 편집 6단계 표준 워크플로우. v1은 이전 프로젝트에서 실증된 패턴.

v2 변경점: EerieVillage(2D PlatformerMicrogame, Unity 6000.3.13f1 LTS) 맥락 반영.

6단계 표준 절차 (씬·프리팹·ScriptableObject 편집 시)

단계	액션	근거 규칙
1. SHA 기록	Unity 프로젝트 `git rev-parse HEAD` 실측 기록 (편집 전 시점 커밋 확정)	C30 git 동기화
2. Read 선행	`mcp__unity-mcp__` 또는 파일 직접 Read로 편집 전 상태 전수 파악*	C5 정직성
3. 백업	원본 파일 `.bak_{YYYYMMDD_HHMM}.{ext}` 복사 (씬·프리팹·ScriptableObject·asmdef 등)	C6-1 원본 보호
4. Unity 프로젝트 commit	편집 전 현 상태를 Unity 레포에 commit (롤백 지점 확보)	C6-2 프로덕션 보호
5. 편집 집행	MCP 도구로 실제 변경. 상대 경로 또는 `$UNITY_PROJECT_ROOT` 변수 사용	C34-11 Agent 경계
6. 검증	Unity Editor 콘솔 오류 0건·의도 결과 반영 확인 → 커밋	P14 QA 게이트

금지 행위

절대 경로 하드코딩 (E:\NerdNavis\EerieVillage\... 같이 PC별 달라지는 경로) — C34-11 위반
백업 없이 씬·프리팹 직접 편집 — C6-1 위반
Unity 콘솔 오류 잔존 상태로 작업 종료 — P14 위반
MCP 응답의 "완료"만 신뢰하고 Unity Editor 실체 미검증 — C23 위반

5. 업데이트·유지보수

unity-mcp 업스트림 업데이트

cd 코어코드/unity-mcp
git pull

Unity 패키지 업데이트는 Unity Editor Package Manager에서 별도.

충돌·연동 실패 시

Claude Desktop 로그 확인 (%APPDATA%\Claude\logs\)
Unity Console 탭에서 MCP 서버 상태 확인
포트 8080 충돌 여부 확인 (netstat -an | findstr 8080)

6. 관련 자산

공유/조직자산/시행착오_아카이브/개발_클라이언트팀장_v1.md — Unity MCP v1 시행착오
공유/개발팀_자산/claude_desktop_config.example.json — Claude Desktop 설정 템플릿
paths.local.json — PC별 UNITY_PROJECT_ROOT 등 로컬 경로
setup/setup_windows.ps1 / setup_macos.sh — 자동 셋업 (3.7절 unity-mcp clone 포함)

5.4 KiB Raw Blame History