# [조직공지] Unity MCP 연동 표준 워크플로우 v2

> **발행일**: 2026-04-22
> **성격**: BurningTimes 개발 환경 표준 — 전 PC·전 개발자 공통 적용
> **근거 지시**: PD님 2026-04-21 BT3 "Unity MCP로 프로젝트 개발 진행"
> **실증 세션**: 2026-04-21 ~ 2026-04-22 BT3 집행 · 최종 연동 성공 commit `aa61028`~(본 세션)
> **단일 SOT**: 본 공지가 Unity MCP 연동의 조직 표준. 개별 개발자·세션 판단으로 우회 금지

---

## 1. 목적

이전 프로젝트 Unity MCP v1 경험을 계승하고, BT3 도입 시 실증된 트러블슈팅 7단계 교훈을 반영한 **표준 워크플로우**를 공시한다. 차기 프로젝트·신규 PC 셋업·다른 MCP 도구 도입 시 본 공지의 원칙을 1차 참조 자산으로 삼는다.

---

## 2. 표준 선언 — 7개 핵심 규범

### 규범 1. **Claude Desktop은 stdio(uvx) 방식 전용**
HTTP `url` 방식은 공식 미지원. `command`+`args` 형태로만 등록한다.

### 규범 2. **`.claude_desktop_config.json`은 PC별 실값, git 추적 금지**
BT 레포에는 `공유/개발팀_자산/claude_desktop_config.example.json` 템플릿만 보존. 각 PC는 Unity MCP for Unity **Configure 자동 생성** 또는 수동 편집으로 개별 구성.

### 규범 3. **uvx 첫 실행은 수동 사전 워밍업 필수**
Claude Desktop 자동 시동 전 터미널에서 `uvx --from mcpforunityserver mcp-for-unity --help` 실행하여 의존성(`pywin32` 등) 캐시 완전 구축. 3~5분 소요.

### 규범 4. **Unity Package Transport = stdio**
MCP for Unity 창의 Transport 드롭다운을 **stdio**로 전환 후 Configure. HTTP Local 기본값 그대로 두면 Claude Desktop 대상 에러.

### 규범 5. **Claude Desktop 재시작은 트레이 Quit 필수**
창 X 닫기는 트레이 잔류. 좀비 인스턴스가 MCP 프로세스 락 → "Could not attach" 에러. 트레이 아이콘 우클릭 Quit 또는 작업관리자 전수 종료 후 재실행.

### 규범 6. **연동 검증은 실체 도구 호출로**
"Running" UI 표시만으로 성공 단정 금지. Claude에게 "Unity Console 로그 읽어줘" 요청 → `mcp__unityMCP__read_console` 실수신 확인으로 완전 판정.

### 규범 7. **에러 진단은 MCP 로그 선행 Read**
UI 메시지보다 `%APPDATA%\Claude\logs\mcp-server-<서버명>.log` 가 실체 원인 즉시 제공. 트러블슈팅 1차 참조.

---

## 3. 신규 PC 셋업 표준 절차 (8단계)

1. **BT 레포 clone**: `git clone https://burning.i234.me/NerdNavis_AiDev/BurningTimesAi.git "E:/BurningTimes"`
2. **paths.local.json 생성**: template 복사 + 실값 입력 (`UNITY_PROJECT_ROOT` 등)
3. **setup 스크립트 실행**: `setup_windows.ps1` 또는 `setup_macos.sh` — unity-mcp 자동 clone 포함
4. **uv 설치**: `winget install --id=astral-sh.uv -e` → 터미널 재시작
5. **uvx 사전 워밍업** (규범 3): `uvx --from mcpforunityserver mcp-for-unity --help` 실행
6. **Unity + MCP Package 설치**: Unity Hub → 프로젝트 열기 → Package Manager → `https://github.com/CoplayDev/unity-mcp.git?path=/MCPForUnity#main`
7. **MCP for Unity 창 설정**: Transport = stdio, Server Start, Client = Claude Desktop, Configure 클릭
8. **Claude Desktop 재시작** (규범 5) + 연동 검증 (규범 6)

---

## 4. 편집 6단계 표준 워크플로우 (Unity MCP 도구 사용 시)

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

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

---

## 5. 트러블슈팅 빠른 진단 표

| 증상 | 원인 | 해결 |
|------|------|------|
| "유효한 MCP 서버 구성이 아닙니다" | HTTP url 방식 | 규범 1 적용 (stdio 전환) |
| "Could not attach" 다수 서버 | 좀비 Claude 인스턴스 | 규범 5 (트레이 Quit) |
| "Server disconnected" (unityMCP) | pywin32 캐시 락 | 규범 3 (수동 워밍업) + Defender 예외 |
| "Server disconnected" (memory/filesystem) | 다른 PC 경로 잔재 | 해당 PC 실경로 수정 또는 서버 제거 |
| "No Unity Editor instances found" | Unity Package 미설치 or 브릿지 미구동 | 표준 절차 6·7단계 |
| "Claude Desktop does not support HTTP transport" | Unity Transport = HTTP Local | 규범 4 (stdio 전환) |

---

## 6. 연관 자산

- **가이드**: `공유/개발팀_자산/Unity_MCP_연동_가이드_v1.md` (v2 개정, 상세 절차)
- **config 템플릿**: `공유/개발팀_자산/claude_desktop_config.example.json`
- **시행착오 아카이브**: `공유/조직자산/시행착오_아카이브/개발_MCP연동_v1.md` (7단계 타임라인)
- **feedback 재발 방지 SOT**: `memory/org/feedback_mcp_setup_pitfalls.md` (함정 5종)
- **이전 프로젝트 Unity MCP v1 경험**: `공유/조직자산/시행착오_아카이브/개발_클라이언트팀장_v1.md`
- **인계서**: `공유/조직공지/2026-04-21_BT_조직_출범_인계서.md` (조직 전환 맥락)

---

## 7. 조직 적용

- **적용 범위**: BurningTimes 전 프로젝트 · 전 PC · 전 개발자
- **적용 시점**: 2026-04-22 즉시
- **계승 대상**: EerieVillage(첫 게임 프로젝트) · BT.Framework(Tier 2·3 확장) · 차기 프로젝트
- **개정 권한**: 총괄PM + 개발팀장 합의 + PD님 승인 (본 공지는 조직 표준이므로 단독 수정 금지)

---

## 8. 연관 규칙
- **C34-11** Agent 경계 보호 (절대 경로 하드코딩 금지)
- **C30** git 동기화 선행 (Unity 프로젝트 레포 외부 저장소)
- **C6-1** 원본 보호 (씬·프리팹 백업)
- **C23** 정직성 (MCP 응답 완료 실체 검증)
- **C16** PC 독립 셋업 (template + PC별 개별 구성)
- **P10** 노하우 축적 (본 공지 자체가 실증)
