From aa610289a0ffd654206f513a2de5a1a0d2874177 Mon Sep 17 00:00:00 2001 From: swrring Date: Tue, 21 Apr 2026 23:41:33 +0900 Subject: [PATCH] =?UTF-8?q?feat(BT=C2=B7UnityMCP):=20Unity=20MCP=20?= =?UTF-8?q?=EB=8F=84=EC=9E=85=20=EC=85=8B=EC=97=85=20=E2=80=94=20A?= =?UTF-8?q?=EC=95=88=20+=20setup=20=EC=9E=90=EB=8F=99=20clone=20+=20Claude?= =?UTF-8?q?=20Desktop=20HTTP?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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) --- .gitignore | 6 + setup/setup_macos.sh | 16 +++ setup/setup_windows.ps1 | 23 ++++ 공유/PD_지시_트래킹/개발팀_PD_지시_로그.md | 3 +- 공유/개발팀_자산/Unity_MCP_연동_가이드_v1.md | 125 ++++++++++++++++++ .../claude_desktop_config.example.json | 39 ++++++ 공유/대화로그/조직운영/2026-04-21.md | 42 ++++++ 7 files changed, 252 insertions(+), 2 deletions(-) create mode 100644 공유/개발팀_자산/Unity_MCP_연동_가이드_v1.md create mode 100644 공유/개발팀_자산/claude_desktop_config.example.json diff --git a/.gitignore b/.gitignore index d8bc317..861ade9 100644 --- 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/ + diff --git a/setup/setup_macos.sh b/setup/setup_macos.sh index b8ddf1f..166ea52 100644 --- 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 "셋업 완료." diff --git a/setup/setup_windows.ps1 b/setup/setup_windows.ps1 index 1689b26..605324e 100644 --- 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을 부서 디렉토리로 복제. diff --git a/공유/PD_지시_트래킹/개발팀_PD_지시_로그.md b/공유/PD_지시_트래킹/개발팀_PD_지시_로그.md index 1cdabfb..e8f8a4a 100644 --- 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 조직공지 발행 | --- diff --git a/공유/개발팀_자산/Unity_MCP_연동_가이드_v1.md b/공유/개발팀_자산/Unity_MCP_연동_가이드_v1.md new file mode 100644 index 0000000..9adf1bf --- /dev/null +++ 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 포함) diff --git a/공유/개발팀_자산/claude_desktop_config.example.json b/공유/개발팀_자산/claude_desktop_config.example.json new file mode 100644 index 0000000..f6752cd --- /dev/null +++ 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" + } + } +} diff --git a/공유/대화로그/조직운영/2026-04-21.md b/공유/대화로그/조직운영/2026-04-21.md index 0bae1d9..7cdf816 100644 --- 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 #조직자산