126 lines
5.4 KiB
Markdown
126 lines
5.4 KiB
Markdown
|
# 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 포함)
|