BurningTimesAi/공유/개발팀_자산/Unity_MCP_연동_가이드_v1.md

# Unity MCP 연동 가이드 v2 (BurningTimes — 실전 검증 개정)

> **목적**: BT 조직 개발자가 Unity MCP를 처음 연동·재설치할 때 따를 **실전 검증** 절차. 2026-04-21~22 BT3 도입 시 실제 겪은 이슈·해결안 반영.
>
> **대상**: 개발팀·기획팀 (Unity Editor 조작에 MCP 도구 활용 전원)
>
> **개정 이력**:
> - v1 (2026-04-21): HTTP 방식 기반 초안
> - **v2 (2026-04-22)**: 실전 검증 — HTTP 거부·uvx 캐시 락·Transport 스위칭·Configure 자동화 반영
>
> **참조 규칙**: C6-1 원본 보호 · C30 git 동기화 · C34-11 Agent 경계 · C11 개발 관점

---

## 1. 구성 개요

| 구성 | 역할 |
|------|------|
| **CoplayDev MCP for Unity** (v9.6.x+) | Python 기반 MCP 서버 + Unity 에디터 패키지 2종 |
| **uv / uvx** (Astral) | Python 패키지·MCP 서버 실행 환경 |
| **Claude Desktop** | MCP 클라이언트 (BT 조직 기본 환경) |
| **EerieVillage Unity 프로젝트** | MCP 대상 Unity 프로젝트 |

### 🔴 중요 — Claude Desktop은 **stdio 방식 전용**
Claude Desktop은 공식적으로 **HTTP MCP 서버 연결을 지원하지 않음**. 실증: `{"url": "http://..."}` 방식은 "유효한 MCP 서버 구성이 아님" 경고로 거부됨. **반드시 stdio(uvx) 방식 사용**.

### 통신 구조
```
Claude Desktop  ←stdio(uvx)→  mcpforunityserver (Python)  ←HTTP/WebSocket→  Unity Editor (MCP for Unity Package)
```

- Claude Desktop → Python 서버: **stdio(uvx)** 전용
- Python 서버 → Unity Editor: Unity Package가 Transport를 HTTP·stdio 둘 다 지원. **Claude Desktop 대상 시 Unity 쪽 Transport도 stdio**로 설정 필수 (Configure 시 자동 검증 경고)

---

## 2. 사전 요구 사항

- Python 3.10+
- **uv** (Astral 배포) — winget 권장
- Unity 2021.3 LTS+ (EerieVillage는 6000.3.13f1 LTS)
- BT 레포 clone + setup 스크립트 실행 (unity-mcp 자동 clone 포함)
- Git 명령줄

---

## 3. 설치 절차 (신규 PC 기준 표준 7단계)

### 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
# paths.local.json 편집:
#   UNITY_PROJECT_ROOT = 실제 Unity 프로젝트 경로 (ProjectSettings 폴더 있는 경로)
#   FRAMEWORK_PKG_ROOT = BT.Framework 경로 (선택)
#   DISCORD_WEBHOOK = BT 공용 웹훅 URL
.\setup\setup_windows.ps1
```
→ setup 스크립트가 `코어코드/unity-mcp/`에 CoplayDev 저장소를 자동 `git clone`.

### 3-B. uv 설치
```powershell
# Windows (winget 권장)
winget install --id=astral-sh.uv -e --accept-source-agreements --accept-package-agreements
```
```bash
# macOS / Linux
curl -LsSf https://astral.sh/uv/install.sh | sh
```
**설치 후 터미널 재시작** (PATH 반영).

### 3-C. uvx 경로 확인
```powershell
Get-Command uvx | Select-Object Source
```
보통 경로: `C:\Users\{USERNAME}\AppData\Local\Microsoft\WinGet\Packages\astral-sh.uv_*\uvx.exe`

### 3-D. uv 캐시 사전 워밍업 (중요 — pywin32 락 이슈 회피)
```powershell
& "C:\Users\{USERNAME}\AppData\Local\Microsoft\WinGet\Packages\astral-sh.uv_Microsoft.Winget.Source_8wekyb3d8bbwe\uvx.exe" --from mcpforunityserver mcp-for-unity --help
```
**3~5분 소요**. `--help` 출력이 뜨면 성공 (의존성 `pywin32·fastmcp·pydantic` 등 캐시 구축 완료). 이 단계 건너뛰면 Claude Desktop 자동 시동 때 **"pywin32.data 디렉토리 락" 에러로 disconnected** 반복.

**에러 시 대처**:
- Defender 예외 등록 (관리자 PowerShell):
  ```powershell
  Add-MpPreference -ExclusionPath "$env:LOCALAPPDATA\uv\cache"
  ```
- 캐시 삭제 후 재시도:
  ```powershell
  Remove-Item -Recurse -Force "$env:LOCALAPPDATA\uv\cache" -ErrorAction SilentlyContinue
  ```

### 3-E. Unity Editor + MCP for Unity Package 설치
1. Unity Hub → EerieVillage 프로젝트 열기
2. `Window → Package Manager → + → Install package from git URL...`
3. 입력:
   ```
   https://github.com/CoplayDev/unity-mcp.git?path=/MCPForUnity#main
   ```
4. 설치·컴파일 완료 대기 (우하단 스피너 멈춤)

### 3-F. Unity MCP for Unity 창 설정 (**v2 핵심**)
Unity 상단 메뉴: `Window → MCP for Unity` 창 열기

#### ① Transport를 **stdio**로 변경 (필수)
- 기본값은 `HTTP Local` — Claude Desktop 대상 시 그대로 Configure 누르면 **"Claude Desktop does not support HTTP transport"** 에러
- Transport 드롭다운 → **`stdio`** 선택

#### ② Server 구동
- "Start Server" 버튼 → 🟢 Running 상태 확인

#### ③ Client = **Claude Desktop** 선택
- Client Configuration 드롭다운에서 "Claude Desktop" 선택

#### ④ Configure 버튼 클릭 (자동 설정)
- Unity가 `%APPDATA%\Claude\claude_desktop_config.json`을 **자동으로 올바른 stdio 포맷**으로 덮어씀
- uvx 절대 경로·args 자동 탐지·기록
- 기존 수동 설정보다 안정적

### 3-G. Claude Desktop 완전 재시작 + 검증
1. **트레이 아이콘 우클릭 → Quit** (창 X는 트레이 잔류 — 미반영)
2. Claude Desktop 재실행
3. Claude 세션에서 요청: "Unity Console 로그 읽어줘"
4. 제가 `mcp__unityMCP__read_console` 호출 → Unity Console 로그 실수신 확인

**실증 (2026-04-22)**: 위 순서로 진행하면 5단계 만에 연동 성공. `success: true` + Unity Console 로그 배열 수신.

---

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

> **v1 계승 근거**: `공유/조직자산/시행착오_아카이브/개발_클라이언트팀장_v1.md` §Unity MCP 편집 6단계 표준 워크플로우

### 편집 6단계 표준 (씬·프리팹·ScriptableObject·스크립트 편집 시)

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

### 금지 행위
- 절대 경로 하드코딩 (PC별 달라지는 경로)
- 백업 없이 씬·프리팹 직접 편집
- Unity Console 오류 잔존 상태로 작업 종료
- MCP 응답 "완료" 신뢰하고 Unity Editor 실체 미검증

---

## 5. 트러블슈팅 — 실전 검증 이슈 7종

| 증상 | 원인 | 해결 |
|------|------|------|
| `{"url": "..."}` 설정 시 **"유효한 MCP 서버 구성이 아닙니다"** | Claude Desktop HTTP 미지원 | stdio(uvx) 방식으로 전환 |
| **"Could not attach to MCP server"** 다수 서버 동시 | Claude Desktop 좀비 인스턴스가 MCP 프로세스 락 | 작업관리자에서 `Claude.exe`·`uvx.exe`·`uv.exe`·`python.exe`·`node.exe` 전수 종료 후 재실행 |
| **"Server disconnected" 반복** (unityMCP) | uvx 첫 설치 시 `pywin32.data` 폴더 락 (Defender 실시간 검사·이전 프로세스) | 3-D 수동 사전 워밍업 + 필요 시 Defender 예외 + `uv cache clean` |
| **"MCP memory: Server disconnected"** 또는 유사 | 다른 PC에서 가져온 config의 경로(`C:\Users\silve\...`) 무효 | 해당 PC 실제 경로로 수정 또는 불필요하면 제거 |
| Unity Package 설치 후에도 **"No Unity Editor instances found"** | MCP for Unity 브릿지 서버 미구동 | Unity → `Window → MCP for Unity` 창에서 "Start Server" 클릭 |
| Configure 버튼 클릭 시 **"Claude Desktop does not support HTTP transport"** | Unity 쪽 Transport가 `HTTP Local` (기본값) | Transport 드롭다운 → `stdio` 선택 후 재Configure |
| Claude Desktop 재시작해도 변경 미반영 | 트레이 좀비 인스턴스 잔류 (창 X 닫기는 미종료) | 트레이 아이콘 우클릭 Quit 또는 작업관리자 전수 종료 |

---

## 6. 업데이트·유지보수

### unity-mcp 업스트림 업데이트
```bash
cd 코어코드/unity-mcp
git pull
```
Unity Package는 Package Manager에서 별도 업데이트 (버전 변경 시 Unity에서 수동 수행).

### 충돌·연동 실패 시 로그 확인
- Claude Desktop 로그: `%APPDATA%\Claude\logs\mcp-server-unityMCP.log`
- Unity Console: `Window → General → Console`
- Unity MCP for Unity 창 하단 상태 표시

---

## 7. 관련 자산 (BT 조직 계승)

- `공유/조직공지/2026-04-22_Unity_MCP_연동_표준_워크플로우_v2.md` — 조직공지 승격본 (본 가이드 요지)
- `공유/조직자산/시행착오_아카이브/개발_MCP연동_v1.md` — BT3 도입 시행착오 타임라인·교훈
- `memory/org/feedback_mcp_setup_pitfalls.md` — MCP 셋업 재발 방지 패턴 5종
- `공유/조직자산/시행착오_아카이브/개발_클라이언트팀장_v1.md` — 이전 프로젝트 Unity MCP v1 경험
- `공유/개발팀_자산/claude_desktop_config.example.json` — Claude Desktop 설정 예시 (stdio 기본)
- `paths.local.json.template` — PC별 경로 템플릿
- `setup/setup_windows.ps1` / `setup_macos.sh` — 자동 셋업 스크립트 (§3.7 unity-mcp clone)