feat(BT·UnityMCP): Unity MCP 도입 셋업 — A안 + setup 자동 clone + Claude Desktop HTTP

PD님 2026-04-21 BT3 지시 4개 결정 집행. ## 집행 내역 (PM 영역) 1. paths.local.json UNITY_PROJECT_ROOT 한 단계 정정 (/EerieVillage/EerieVillage) 2. .gitignore에 코어코드/unity-mcp/ 추가 (A안 외부 저장소 분리) 3. setup_windows.ps1 / setup_macos.sh §3.7 unity-mcp 자동 clone 로직 추가 4. 공유/개발팀_자산/claude_desktop_config.example.json — HTTP 방식(localhost:8080) 기본 + stdio(uvx) 대안 5. 공유/개발팀_자산/Unity_MCP_연동_가이드_v1.md — 6단계 설치·편집 표준 워크플로우 v2 (이전 v1 계승) 6. uv 0.11.7 winget 설치 완료 ## PD 수동 집행 대기 - Claude Desktop config merge + 완전 재시작 - Unity Editor Package Manager로 MCP for Unity 설치 - mcp__unity-mcp__* 도구 호출 테스트 ## PD 지시 로그 BT3 활성 지시 신규 등록 (진행중 · PD 수동 집행 대기) ## 보류 연동 검증 완료 시 Unity MCP 편집 표준 워크플로우 v2 조직공지 승격 Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-04-21 23:41:33 +09:00 · 2026-04-21 23:41:33 +09:00 · aa610289a0
parent 0bda9d3fb6
commit aa610289a0
7 changed files with 252 additions and 2 deletions
--- a/.gitignore
+++ b/.gitignore
@ -103,3 +103,9 @@ build/
 .live.bak-*/
 .live.bak_*/

+# ===== Unity MCP 외부 저장소 (A안 + setup 자동 clone, 2026-04-21 PD님 직접 승인) =====
+# 코어코드/unity-mcp/는 CoplayDev의 MCP for Unity 외부 저장소. BT 조직이 fork하지 않고
+# 외부 저장소로 유지하며, setup 스크립트가 최초 1회 `git clone` 자동 실행.
+# 업데이트는 `cd 코어코드/unity-mcp && git pull`로 수동.
+코어코드/unity-mcp/
+
--- a/setup/setup_macos.sh
+++ b/setup/setup_macos.sh
@ -127,4 +127,20 @@ if [ -d "$CLAUDE_BASE" ]; then
    done
 fi

+# 3.7. Unity MCP 외부 저장소 자동 clone (A안, 2026-04-21 PD님 직접 승인)
+UNITY_MCP_PATH="$BURNINGTIMES_ROOT/코어코드/unity-mcp"
+if [ ! -d "$UNITY_MCP_PATH" ]; then
+    echo "[setup] unity-mcp 외부 저장소 clone 시작..."
+    mkdir -p "$(dirname "$UNITY_MCP_PATH")"
+    if git clone https://github.com/CoplayDev/unity-mcp.git "$UNITY_MCP_PATH"; then
+        echo "✅ unity-mcp clone 완료: $UNITY_MCP_PATH"
+    else
+        echo "⚠️ unity-mcp clone 실패 — 네트워크·권한 확인 후 수동 실행:"
+        echo "    git clone https://github.com/CoplayDev/unity-mcp.git \"$UNITY_MCP_PATH\""
+    fi
+else
+    echo "[setup] unity-mcp 이미 존재: $UNITY_MCP_PATH"
+    echo "  (업데이트는 수동: cd \"$UNITY_MCP_PATH\" && git pull)"
+fi
+
 echo "셋업 완료."
--- a/setup/setup_windows.ps1
+++ b/setup/setup_windows.ps1
@ -213,6 +213,29 @@ foreach ($d in $allHashDirs) {
    }
 }

+# 3.7. Unity MCP 외부 저장소 자동 clone (A안, 2026-04-21 PD님 직접 승인)
+# - CoplayDev/unity-mcp 외부 저장소를 BT 레포 내부에 clone
+# - BT 레포 `.gitignore`로 추적 제외 (외부 저장소 분리 유지)
+# - 업데이트는 `cd 코어코드/unity-mcp && git pull` 수동
+Write-Host "=== Unity MCP 외부 저장소 셋업 ==="
+$unityMcpPath = Join-Path $BurningTimesRoot "코어코드\unity-mcp"
+if (-not (Test-Path $unityMcpPath)) {
+    $parent = Split-Path $unityMcpPath -Parent
+    if (-not (Test-Path $parent)) {
+        New-Item -ItemType Directory -Path $parent -Force | Out-Null
+    }
+    Write-Host "[setup] unity-mcp clone 시작..."
+    git clone https://github.com/CoplayDev/unity-mcp.git $unityMcpPath
+    if ($LASTEXITCODE -eq 0) {
+        Write-Host "✅ unity-mcp clone 완료: $unityMcpPath"
+    } else {
+        Write-Warning "unity-mcp clone 실패 — 네트워크·권한 확인 후 수동 실행 필요: git clone https://github.com/CoplayDev/unity-mcp.git `"$unityMcpPath`""
+    }
+} else {
+    Write-Host "[setup] unity-mcp 이미 존재: $unityMcpPath"
+    Write-Host "  (업데이트는 수동: cd '$unityMcpPath'; git pull)"
+}
+
 # 4. .claude/settings.json 부서 동기화 (루트 SOT → 개발팀/기획팀 복제)
 # Claude Code는 .claude/ 계층 auto-merge를 지원하지 않으므로 자식 디렉토리에서 세션 시작 시
 # 루트 settings.json을 인식하지 못함. 이를 우회하기 위해 루트 settings.json을 부서 디렉토리로 복제.
--- a/공유/PD_지시_트래킹/개발팀_PD_지시_로그.md
+++ b/공유/PD_지시_트래킹/개발팀_PD_지시_로그.md
@ -33,8 +33,7 @@ C3·C13 위반에 해당. **즉시 자진 보고 후 소급 등록**.

 | # | 일시 | 지시 요지 | 처리 상태 | 산출물 경로 | 중단 사유 | 사후 조치 |
 |---|------|----------|----------|-----------|----------|----------|
-
-(활성 지시 없음 — BurningTimes 조직 신설 전환 작업 BT1·BT2 모두 완료 아카이브로 이동됨. Phase 3 EerieVillage 착수 시 PD님 지시 수령 후 신규 항목 등록)
+| BT3 | 2026-04-21 | **Unity MCP 도입 셋업** — `E:\BurningTimes\코어코드\unity-mcp`에 CoplayDev MCP for Unity 저장소 배치 (PD 사전 clone 완료). BT 조직은 A안(gitignore + setup 자동 clone)으로 관리. Claude Desktop 클라이언트 기반 HTTP 방식 (localhost:8080) 연동 | **진행중 (PM 집행분 완료 · PD 수동 집행 대기)** | `paths.local.json` Unity 경로 정정 · `.gitignore` 코어코드/unity-mcp/ 제외 · `setup/setup_windows.ps1`·`setup_macos.sh` 3.7절 자동 clone 로직 · `공유/개발팀_자산/claude_desktop_config.example.json` · `공유/개발팀_자산/Unity_MCP_연동_가이드_v1.md` · uv 0.11.7 winget 설치 완료 | — | PD 수동 집행: ①`%APPDATA%\Claude\claude_desktop_config.json`에 예시 내용 merge ②Claude Desktop **완전 재시작** (Quit 후 재실행) ③EerieVillage Unity 프로젝트에서 Package Manager로 `https://github.com/CoplayDev/unity-mcp.git?path=/MCPForUnity#main` 추가 ④연동 검증 (Claude에서 `mcp__unity-mcp__*` 호출 테스트) 완료 후 PM 감독하에 Unity MCP 편집 표준 워크플로우 v2 조직공지 발행 |

 ---

--- a/공유/개발팀_자산/Unity_MCP_연동_가이드_v1.md
+++ b/공유/개발팀_자산/Unity_MCP_연동_가이드_v1.md
@ -0,0 +1,125 @@
+# 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 포함)
--- a/공유/개발팀_자산/claude_desktop_config.example.json
+++ b/공유/개발팀_자산/claude_desktop_config.example.json
@ -0,0 +1,39 @@
+{
+  "_description_ko": "Claude Desktop MCP 서버 등록 예시 — Unity MCP HTTP 방식 (CoplayDev MCP for Unity 공식 권장).",
+  "_설치_경로": {
+    "Windows": "%APPDATA%\\Claude\\claude_desktop_config.json (= C:\\Users\\USERNAME\\AppData\\Roaming\\Claude\\claude_desktop_config.json)",
+    "macOS": "~/Library/Application Support/Claude/claude_desktop_config.json",
+    "Linux": "~/.config/Claude/claude_desktop_config.json"
+  },
+  "_적용_방법": [
+    "1. 본 파일 내용을 claude_desktop_config.json에 복사 (기존 mcpServers가 있으면 병합)",
+    "2. Claude Desktop 완전 재시작 (작업 표시줄 아이콘 우클릭 → Quit → 재실행. 창만 닫으면 인식 안 됨)",
+    "3. Unity Editor에서 BT.Framework 프로젝트를 열고 MCP for Unity 패키지 활성화 (HTTP 서버 localhost:8080 자동 구동)",
+    "4. Claude 세션에서 mcp__unity-mcp__* 도구 호출 가능 확인"
+  ],
+  "_대안_stdio_uvx": {
+    "_설명": "HTTP 방식이 작동 안 하거나 Unity 미실행 상태에서 도구 등록만 확인하려면 stdio(uvx) 방식 사용",
+    "_Windows_예시": {
+      "mcpServers": {
+        "unityMCP": {
+          "command": "C:/Users/YOUR_USERNAME/AppData/Local/Microsoft/WinGet/Links/uvx.exe",
+          "args": ["--from", "mcpforunityserver", "mcp-for-unity", "--transport", "stdio"]
+        }
+      }
+    },
+    "_macOS_Linux_예시": {
+      "mcpServers": {
+        "unityMCP": {
+          "command": "uvx",
+          "args": ["--from", "mcpforunityserver", "mcp-for-unity", "--transport", "stdio"]
+        }
+      }
+    }
+  },
+
+  "mcpServers": {
+    "unityMCP": {
+      "url": "http://localhost:8080/mcp"
+    }
+  }
+}
--- a/공유/대화로그/조직운영/2026-04-21.md
+++ b/공유/대화로그/조직운영/2026-04-21.md
@ -197,6 +197,48 @@ Phase 2-B content-designer Agent 경계 위반 2회차 — `feedback_agent_path_

 ---

+## [Unity MCP 도입] BT3 지시 수령·PM 집행분 완료
+
+**태그**: #UnityMCP #BT3 #PD지시 #A안 #setup자동화 #HTTP방식
+
+### 배경
+- PD님 2026-04-21 지시: "Unity MCP를 이용해 프로젝트 개발 진행"
+- `E:/BurningTimes/코어코드/unity-mcp/` 에 CoplayDev MCP for Unity 저장소 PD 사전 clone
+- 클라이언트: **Claude Desktop** (Claude Code 아님 — 설정 방식 상이)
+
+### PD 결정 요약
+1. Unity 실제 경로 `E:/NerdNavis/EerieVillage/EerieVillage` 확정
+2. **A안 (gitignore + setup 자동 clone) 승인** — PM 권고 수용
+3. uv 설치 승인
+
+### PM 집행분 완료 (본 커밋)
+1. `paths.local.json` `UNITY_PROJECT_ROOT` 한 단계 정정 (`/EerieVillage/EerieVillage`)
+2. `.gitignore` `코어코드/unity-mcp/` 추가 (A안 외부 저장소 분리)
+3. `setup/setup_windows.ps1` §3.7 신설 — unity-mcp 미존재 시 자동 `git clone https://github.com/CoplayDev/unity-mcp.git`
+4. `setup/setup_macos.sh` 동일 로직 신설
+5. `공유/개발팀_자산/claude_desktop_config.example.json` — HTTP 방식(localhost:8080) 기본 + stdio(uvx) 대안 주석
+6. `공유/개발팀_자산/Unity_MCP_연동_가이드_v1.md` — 6단계 설치·편집 표준 워크플로우 v2 (이전 v1 계승)
+7. `uv 0.11.7` winget 설치 성공 (`C:\Users\sw\AppData\Local\Microsoft\WinGet\Packages\astral-sh.uv_*\uv.exe`)
+
+### PD 수동 집행 대기 (Claude Desktop·Unity Editor UI)
+1. `%APPDATA%\Claude\claude_desktop_config.json`에 예시 내용 merge
+2. Claude Desktop **완전 재시작** (작업 표시줄 Quit 후 재실행 — 창만 닫는 건 미반영)
+3. EerieVillage Unity 프로젝트 Package Manager에서 `https://github.com/CoplayDev/unity-mcp.git?path=/MCPForUnity#main` 추가
+4. `mcp__unity-mcp__*` 도구 호출 테스트
+
+### 연동 검증 완료 후 후속 안건
+- Unity MCP 편집 표준 워크플로우 v2 조직공지 발행 (가이드 v1을 조직공지로 승격)
+- EerieVillage Phase 3 착수 시 MCP 기반 작업 패턴 실증 축적
+- BT.Framework Tier 1 항목 중 EerieVillage 적용 가능 항목 MCP로 도입 테스트
+
+### 기각안
+1. **Claude Code `.mcp.json` 방식** — 기각. PD님 4번 답변 "Claude Desktop" 명시. `.mcp.json`은 Claude Code 전용
+2. **stdio(uvx) 방식 기본 채택** — 기각. 공식 README 권장은 HTTP. stdio는 Unity 미실행 상태 테스트용 대안. PC별 uvx 절대 경로 하드코딩 필요 — `claude_desktop_config.example.json` 주석 대안으로만 기재
+3. **B안 submodule** — 기각 (PM 권고 A안 + setup 자동화로 B안 장점 흡수)
+4. **C안 BT fork commit** — 기각 (unity-mcp 활발 업데이트·BT fork 이유 없음·레포 비대화)
+
+---
+
 ## [Phase 2-B 완료] 전 에이전트 시행착오 아카이브 14종 (README 포함)

 **태그**: #Phase2B #시행착오아카이브 #BurningTimes #조직자산