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>
This commit is contained in:
parent
0bda9d3fb6
commit
aa610289a0
|
|
@ -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/
|
||||
|
||||
|
|
|
|||
|
|
@ -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 "셋업 완료."
|
||||
|
|
|
|||
|
|
@ -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을 부서 디렉토리로 복제.
|
||||
|
|
|
|||
|
|
@ -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 조직공지 발행 |
|
||||
|
||||
---
|
||||
|
||||
|
|
|
|||
|
|
@ -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 포함)
|
||||
|
|
@ -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"
|
||||
}
|
||||
}
|
||||
}
|
||||
|
|
@ -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 #조직자산
|
||||
|
|
|
|||
Loading…
Reference in New Issue