# 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 레포 셋업
```powershell
# 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 설치
```powershell
# Windows (winget 권장)
winget install --id=astral-sh.uv -e
```
```bash
# macOS / Linux
curl -LsSf https://astral.sh/uv/install.sh | sh
```
설치 후 PATH 반영을 위해 **터미널 재시작**.

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

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

### 3-E. 연동 검증
1. Claude Desktop 재시작 완료 상태 + Unity Editor + EerieVillage 프로젝트 열려 있음
2. Claude 세션에서 `mcp__unity-mcp__*` 도구 호출 테스트 (예: `mcp__unity-mcp__manage_editor` `action: get_state`)
3. 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 업스트림 업데이트
```bash
cd 코어코드/unity-mcp
git pull
```
Unity 패키지 업데이트는 Unity Editor Package Manager에서 별도.

### 충돌·연동 실패 시
1. Claude Desktop 로그 확인 (`%APPDATA%\Claude\logs\`)
2. Unity Console 탭에서 MCP 서버 상태 확인
3. 포트 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 포함)