NerdNavis_AiDev
/
BurningTimesAi
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

feat(BT·MCP·자산): Unity MCP 연동 완결 + 조직 자산 4종 축적 

PD님 "이번 세션 디버깅 노하우·MCP 연동 경험 조직 자산화" 지시 이행.

## BT3 완결
- Unity MCP 연동 완전 성공 실증 (`mcp__unityMCP__read_console` 실수신)
- PD 지시 로그 BT3 완료 아카이브 이동
- 활성 지시 0건 상태

## 조직 자산 축적 (4종 산출물)
1. Unity_MCP_연동_가이드_v1.md — v2 실전 개정 (Transport stdio 강제·Configure 자동·트러블슈팅 7종)
2. claude_desktop_config.example.json — stdio 기본 + HTTP 미지원 경고 + 수동 워밍업 안내
3. memory/org/feedback_mcp_setup_pitfalls.md — 함정 5종 재발 방지 SOT
4. 공유/조직자산/시행착오_아카이브/개발_MCP연동_v1.md — 7단계 타임라인
5. 공유/조직공지/2026-04-22_Unity_MCP_연동_표준_워크플로우_v2.md — 조직공지 승격본
+ MEMORY.md 인덱스 항목 append

## 실증된 함정 5종 (조직 계승 핵심)
(1) Claude Desktop HTTP 거부 → stdio 전용
(2) uvx pywin32 캐시 락 → 수동 사전 워밍업 + Defender 예외
(3) Claude 좀비 인스턴스 "Could not attach" → 트레이 Quit·작업관리자 전수 종료
(4) 다른 PC config 경로 무효 → PC별 재구성, template만 git 추적
(5) Unity Package Transport 기본 HTTP → Claude Desktop 대상 stdio 전환

## 대화로그
공유/대화로그/조직운영/2026-04-21.md에 BT3 완결 섹션 append (성공 검증·자산화 내역·계승 원칙·Phase 3 이관 안건)

## 매니페스트
bt-mcp-knowledge-capture
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
깃 관리자 2026-04-22 01:06:38 +09:00
parent 6550dc73bc
commit 5a161fc8b2
8 changed files with 679 additions and 88 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
memory/org/MEMORY.md
View File

@ -43,3 +43,4 @@
- [PM 실측 가능 범위 자의적 축소 — 환경·능력 과소평가 금지](feedback_pm_capability_underestimation.md) — 2026-04-20 5회차 PM 의무 4종 후속. PM이 `mcp__unity-mcp__*` deferred tools를 실측 없이 "환경 부재"로 반복 단언하여 선행 조건 2를 "스켈레톤만"으로 축소. PD님 "유니티 MCP 연결 환경은 이미 확보되어 있어" 지적으로 정정. **ToolSearch + 간이 실측 의무화** + 환경·능력 주장 전 실측 근거 첨부 필수. C23 "추정의 사실화" 특수 유형. 과거 시점 설계 문서 "미확인 고지"를 현 시점 상태로 재적용 금지 - [PM 실측 가능 범위 자의적 축소 — 환경·능력 과소평가 금지](feedback_pm_capability_underestimation.md) — 2026-04-20 5회차 PM 의무 4종 후속. PM이 `mcp__unity-mcp__*` deferred tools를 실측 없이 "환경 부재"로 반복 단언하여 선행 조건 2를 "스켈레톤만"으로 축소. PD님 "유니티 MCP 연결 환경은 이미 확보되어 있어" 지적으로 정정. **ToolSearch + 간이 실측 의무화** + 환경·능력 주장 전 실측 근거 첨부 필수. C23 "추정의 사실화" 특수 유형. 과거 시점 설계 문서 "미확인 고지"를 현 시점 상태로 재적용 금지
- [git 레포 점검 범위 축소 — 상위 디렉토리만 확인 후 "레포 아님" 단언](feedback_git_scope_shortcut.md) — 2026-04-20 #57 자진 고지 오류 양축. 개발팀장이 `D:\BurningTimes\FilGoodBandits` 상위만 확인 → "C30 점검 불가" 단언. 실제로는 하위 `DeckBuilding`이 git 레포 (remote `BurningTimes/DeckBuilding.git`). PM도 Agent 응답을 추가 재실측 없이 수용 (C27 변형 위반). **해결**: Unity 프로젝트 SessionStart 자동 pull 구축(옵션 A PD 승인) · `.git` 존재 검사 2~3단계 하위까지 · Agent 환경 판정 주장은 PM 재실측 의무. C30-1 조항 "수동 점검" → "자동 이행"으로 정비 - [git 레포 점검 범위 축소 — 상위 디렉토리만 확인 후 "레포 아님" 단언](feedback_git_scope_shortcut.md) — 2026-04-20 #57 자진 고지 오류 양축. 개발팀장이 `D:\BurningTimes\FilGoodBandits` 상위만 확인 → "C30 점검 불가" 단언. 실제로는 하위 `DeckBuilding`이 git 레포 (remote `BurningTimes/DeckBuilding.git`). PM도 Agent 응답을 추가 재실측 없이 수용 (C27 변형 위반). **해결**: Unity 프로젝트 SessionStart 자동 pull 구축(옵션 A PD 승인) · `.git` 존재 검사 2~3단계 하위까지 · Agent 환경 판정 주장은 PM 재실측 의무. C30-1 조항 "수동 점검" → "자동 이행"으로 정비
- [정부 지원 사업 문서 처리 도구 (조직 자산)](reference_govt_support_docs_toolkit.md) — docx·hwp·pdf 처리용 Python 라이브러리 세트(pypdf·pyhwp·olefile·lxml·six·pywin32) 대표자 PC 로컬 설치 완료. 한컴 2018 + MS Word 환경. 향후 정부 지원 사업 공고 대응·양식 편집·평가 반영 시 즉시 재활용 가능 - [정부 지원 사업 문서 처리 도구 (조직 자산)](reference_govt_support_docs_toolkit.md) — docx·hwp·pdf 처리용 Python 라이브러리 세트(pypdf·pyhwp·olefile·lxml·six·pywin32) 대표자 PC 로컬 설치 완료. 한컴 2018 + MS Word 환경. 향후 정부 지원 사업 공고 대응·양식 편집·평가 반영 시 즉시 재활용 가능
- [MCP 도구 셋업 실전 함정 5종 — 재발 방지 SOT](feedback_mcp_setup_pitfalls.md) — 2026-04-21~22 BT3 Unity MCP 도입 실증. (1) Claude Desktop HTTP 미지원 → stdio 전용 (2) uvx 첫 설치 시 `pywin32` 캐시 락 → 수동 사전 워밍업·Defender 예외 (3) Claude 좀비 인스턴스 "Could not attach" → 트레이 Quit·작업관리자 전수 종료 (4) 다른 PC config 경로 무효 → PC별 재구성 (5) Unity Package Transport 기본 HTTP → Claude Desktop 대상 stdio 전환. 차기 MCP 도구 도입 시 첫 참조 자산. 연관 `공유/조직자산/시행착오_아카이브/개발_MCP연동_v1.md` · `공유/조직공지/2026-04-22_Unity_MCP_연동_표준_워크플로우_v2.md`

132
memory/org/feedback_mcp_setup_pitfalls.md Normal file
View File

@ -0,0 +1,132 @@
---
name: MCP (Model Context Protocol) 도구 셋업 실전 함정 5종 — 재발 방지 SOT
description: 2026-04-21~22 BT3 Unity MCP 도입 시 실증된 셋업 함정 5종. Claude Desktop HTTP 미지원·uvx 캐시 pywin32 락·좀비 인스턴스·Transport 불일치·재시작 완전성. 차기 MCP 도입 시 첫 참조 자산
type: feedback
created: 2026-04-22
---
# MCP 도구 셋업 실전 함정 5종 — 재발 방지 SOT (v1)
## 배경
2026-04-21~22 BurningTimes 조직 BT3 지시 "Unity MCP 도입" 집행 중 다단계 트러블슈팅 발생. 최종 연동은 성공했으나 **같은 유형의 함정이 모든 MCP 도구 셋업에 재발 가능**하므로 재발 방지 SOT로 아카이브.
## 함정 1 — Claude Desktop은 HTTP `url` 방식 거부
**실증**:
```json
"unityMCP": {
"url": "http://localhost:8080/mcp"
}
```
→ Claude Desktop 경고: "유효한 MCP 서버 구성이 아닙니다".
**근본 원인**: Claude Desktop은 공식적으로 **stdio 방식만 지원**. HTTP `url` 방식은 Claude Code·Cursor 등 다른 클라이언트 전용. unity-mcp 공식 README가 HTTP를 "기본 권장"으로 서술해도 Claude Desktop에는 해당 안 됨.
**재발 방지**:
- 신규 MCP 도구 문서에서 "HTTP 권장" 문구 보면 **클라이언트별 호환성 재확인** 필수
- Claude Desktop 대상 시 **stdio(`command`+`args`) 형식만 사용**
- Unity MCP for Unity Package의 "Transport" 설정도 Claude Desktop 대상 시 **stdio로 전환**
## 함정 2 — uvx 첫 설치 시 pywin32 캐시 락
**실증 로그**:
```
error: Failed to install: pywin32-311-cp312-cp312-win_amd64.whl (pywin32==311)
Caused by: failed to remove directory ...pywin32-311.data:
다른 프로세스가 파일을 사용 중이기 때문에 프로세스가 액세스 할 수 없습니다. (os error 32)
```
**근본 원인**:
- uvx는 `$LOCALAPPDATA\uv\cache`에 패키지 임시 전개 후 설치
- `pywin32`는 `.data` 하위에 `.pyd` 바이너리 포함 — Windows Defender 실시간 검사가 즉시 스캔하며 일시 락
- 또는 이전 uvx 시도의 잔재 Python 프로세스가 캐시 락
**재발 방지**:
1. **수동 사전 워밍업 필수** — Claude Desktop 자동 시동 전 `uvx --from <pkg> <entry> --help` 1회 실행
2. **Windows Defender 예외 등록** (관리자 PowerShell):
```powershell
Add-MpPreference -ExclusionPath "$env:LOCALAPPDATA\uv\cache"
```
3. **잔재 프로세스 전수 종료** 후 재시도
4. 이는 **Python 기반 모든 MCP 서버**에 공통 (mcpforunityserver·mcp-server-sqlite·mcp-server-memory 등)
## 함정 3 — Claude Desktop 좀비 인스턴스 "Could not attach"
**실증**: 4개 MCP 서버 동시 "Could not attach to MCP server" 경고.
**근본 원인**:
- Claude Desktop 창 X 닫기는 **트레이 잔류** (Quit 아님)
- 잔재 인스턴스가 MCP 서버 프로세스 잡고 있어 새 인스턴스 attach 실패
- `uvx.exe`·`python.exe`·`node.exe` 등 MCP 서버가 띄운 프로세스도 함께 잔류
**재발 방지**:
- Claude Desktop 재시작 시 **트레이 아이콘 우클릭 → Quit** 또는 **작업관리자 전수 종료**
- 재시작 전 작업관리자에서 `Claude.exe`·`uvx.exe`·`uv.exe`·`python.exe`·`node.exe` 중 MCP 관련 프로세스 검색·종료
- "창 닫기 = 종료"가 **아니라는 점**을 모든 PC 셋업 가이드에 명시
## 함정 4 — 다른 PC에서 가져온 config의 경로 무효
**실증**:
- `C:\Users\silve\AppData\Roaming\npm\...` 경로의 memory 서버 → **silve 사용자 없는 PC에서 disconnected**
- `D:\Dev\SurgeCoin` 경로의 filesystem·sqlite → **해당 폴더 없는 PC에서 disconnected**
**근본 원인**:
- `claude_desktop_config.json`은 **PC별·사용자별 경로**가 하드코딩되기 쉬움
- 다른 PC에서 가져온 config를 그대로 쓰면 사용자명·드라이브 경로 불일치로 실패
**재발 방지**:
- **config는 PC별 별도 구성**, git 추적 금지 (BT는 `공유/개발팀_자산/claude_desktop_config.example.json` 템플릿 제공)
- Unity MCP for Unity **Configure 자동화 활용** — PC별 실경로를 Unity가 탐지·기입
- 다른 PC config 복사 시 **경로 전수 수정** 체크리스트
## 함정 5 — Unity 쪽 Transport 기본값 불일치
**실증**: Unity MCP for Unity 창의 Transport 기본값은 `HTTP Local`. 이 상태로 Claude Desktop용 Configure 누르면 에러:
> "Claude Desktop does not support HTTP transport. Switch to stdio in settings before configuring."
**근본 원인**:
- Unity Package 쪽 Transport = Python MCP 서버가 Unity와 통신하는 방식
- Claude Desktop 대상 시 Python MCP 서버가 **stdio 모드로 Claude Desktop과 통신** + Unity와도 stdio로 통신해야 함
- HTTP Local로 두면 Python 서버가 HTTP 클라이언트로 동작하여 Claude Desktop의 stdio 호출과 충돌
**재발 방지**:
- Unity MCP for Unity 창 열면 **Transport 드롭다운부터 stdio로 변경**
- Configure 누르기 전 체크리스트 4항:
1. Transport = `stdio`
2. Server Status = `Running`
3. Client = `Claude Desktop`
4. Configure 클릭
## 공통 진단 도구
### 가장 빠른 진단 — Claude Desktop MCP 로그
```
%APPDATA%\Claude\logs\mcp-server-<서버명>.log
```
서버별 로그 파일에 정확한 에러 출력됨. "Server disconnected" 같은 UI 메시지보다 **실체 원인 즉시 파악**.
### Unity 연동 검증 명령
Claude에게: "Unity Console 로그 읽어줘"
→ `mcp__unityMCP__read_console` 호출 → Unity Editor 실제 로그 수신 여부로 연동 완전성 판별.
## 차기 MCP 도입 시 체크리스트 (BT 조직 표준)
- [ ] 대상 MCP 도구 공식 README에서 **Claude Desktop 호환성** 재확인 (HTTP만 문서화되어 있으면 stdio 별도 경로 확인)
- [ ] Python 기반 서버면 **uvx 수동 사전 워밍업** (캐시 구축)
- [ ] Windows Defender 예외 등록 고려 (uv cache 경로)
- [ ] Claude Desktop 재시작은 **트레이 Quit** 필수 (창 X 아님)
- [ ] 서버 추가·변경 후 30초~1분 기다려서 Claude Desktop의 MCP 상태 UI 재확인
- [ ] 연동 검증 — 실제 도구 호출로 대상 시스템 응답 확인 (UI "Running" 표시만으로는 불충분)
- [ ] 에러 발생 시 `%APPDATA%\Claude\logs\mcp-server-*.log` 선행 확인
## 연관 자산
- **가이드**: `공유/개발팀_자산/Unity_MCP_연동_가이드_v1.md` (v2 개정)
- **조직공지**: `공유/조직공지/2026-04-22_Unity_MCP_연동_표준_워크플로우_v2.md`
- **시행착오 아카이브**: `공유/조직자산/시행착오_아카이브/개발_MCP연동_v1.md`
- **이전 프로젝트 Unity MCP v1 경험**: `공유/조직자산/시행착오_아카이브/개발_클라이언트팀장_v1.md`
## 교훈 (BT 조직 원칙)
**MCP 도구 도입은 "설치" 이상의 협업 체계 구축**이다. 클라이언트 호환성·패키지 매니저 캐시·OS 보안 정책·재시작 완전성이 모두 얽혀 있어 **한 번에 성공하기 어려움**. 그러나 **같은 함정이 다음 도구에서도 반복**되므로 본 SOT를 첫 참조로 삼아 시행착오 반복 차단.

4
공유/PD_지시_트래킹/개발팀_PD_지시_로그.md
View File

@ -33,7 +33,8 @@ C3·C13 위반에 해당. **즉시 자진 보고 후 소급 등록**.
| # | 일시 | 지시 요지 | 처리 상태 | 산출물 경로 | 중단 사유 | 사후 조치 | | # | 일시 | 지시 요지 | 처리 상태 | 산출물 경로 | 중단 사유 | 사후 조치 |
|---|------|----------|----------|-----------|----------|----------| |---|------|----------|----------|-----------|----------|----------|
| 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 조직공지 발행 |
(활성 지시 없음 — BT3 완료 아카이브 이동. 추가 Unity 작업·EerieVillage Phase 3 착수 시 PD님 지시 수령 후 신규 항목 등록)
--- ---
@ -47,3 +48,4 @@ C3·C13 위반에 해당. **즉시 자진 보고 후 소급 등록**.
|---|------|----------|----------|-----------|----------|----------| |---|------|----------|----------|-----------|----------|----------|
| BT1 | 2026-04-20 | BurningTimes 조직 신설 — git remote 교체 + 중앙 저장소 A안 분리 + NerdNavisAi 영향 차단 | **완료** | [완료: 2026-04-21 02:10 · commit: `4911b74`→`5d5b1dd`→`44f7fb1`→`616e3d3`→`8ff5a1f` · 참조: `공유/대화로그/조직운영/2026-04-21.md` 전체 · `공유/조직공지/2026-04-21_BT_조직_출범_인계서.md`] Phase 1 완료 (git remote·중앙 저장소 A안 분리·scripts 치환·NerdNavisAi 영향 차단 확인) | — | 조직 전환 완결. 다른 PC 이관 절차는 인계서 §2 참조 | | BT1 | 2026-04-20 | BurningTimes 조직 신설 — git remote 교체 + 중앙 저장소 A안 분리 + NerdNavisAi 영향 차단 | **완료** | [완료: 2026-04-21 02:10 · commit: `4911b74`→`5d5b1dd`→`44f7fb1`→`616e3d3`→`8ff5a1f` · 참조: `공유/대화로그/조직운영/2026-04-21.md` 전체 · `공유/조직공지/2026-04-21_BT_조직_출범_인계서.md`] Phase 1 완료 (git remote·중앙 저장소 A안 분리·scripts 치환·NerdNavisAi 영향 차단 확인) | — | 조직 전환 완결. 다른 PC 이관 절차는 인계서 §2 참조 |
| BT2 | 2026-04-21 | BT 조직 전환 8개 지시: ①시행착오 노하우 조직 자산화 (전 에이전트 동원) ②너드나비스→BurningTimes ③수상한잡화점 삭제+교훈 보존 ④BT.Framework 이름 갱신 ⑤영문화 ⑥Unity 경로 `E:/NerdNavis/EerieVillage` (하드코딩 금지) ⑦Discord 웹훅 등록 ⑧새 프로젝트 "기묘한 고을: 조선퇴마뎐" (EerieVillage, Unity 6000.3.13f1 LTS, 2D PlatformerMicrogame) | **완료** | [완료: 2026-04-21 02:10 · commit: `5d5b1dd`→`8ff5a1f` · 참조: `공유/대화로그/조직운영/2026-04-21.md` · 시행착오 아카이브 14종 `공유/조직자산/시행착오_아카이브/` · `프로젝트/EerieVillage/` · `paths.local.json` (gitignore) · SKILL.md P17 폐기 + P29 EerieVillage 재작성 · `공유/조직공지/2026-04-21_BT_조직_출범_인계서.md`] 8개 지시 전수 집행 완료 | — | EerieVillage 착수 안건 7종은 Phase 3로 분리 (PD 결정 6) | | BT2 | 2026-04-21 | BT 조직 전환 8개 지시: ①시행착오 노하우 조직 자산화 (전 에이전트 동원) ②너드나비스→BurningTimes ③수상한잡화점 삭제+교훈 보존 ④BT.Framework 이름 갱신 ⑤영문화 ⑥Unity 경로 `E:/NerdNavis/EerieVillage` (하드코딩 금지) ⑦Discord 웹훅 등록 ⑧새 프로젝트 "기묘한 고을: 조선퇴마뎐" (EerieVillage, Unity 6000.3.13f1 LTS, 2D PlatformerMicrogame) | **완료** | [완료: 2026-04-21 02:10 · commit: `5d5b1dd`→`8ff5a1f` · 참조: `공유/대화로그/조직운영/2026-04-21.md` · 시행착오 아카이브 14종 `공유/조직자산/시행착오_아카이브/` · `프로젝트/EerieVillage/` · `paths.local.json` (gitignore) · SKILL.md P17 폐기 + P29 EerieVillage 재작성 · `공유/조직공지/2026-04-21_BT_조직_출범_인계서.md`] 8개 지시 전수 집행 완료 | — | EerieVillage 착수 안건 7종은 Phase 3로 분리 (PD 결정 6) |
| BT3 | 2026-04-21 | **Unity MCP 도입 셋업** — BT 조직은 A안(gitignore + setup 자동 clone)으로 관리. Claude Desktop 클라이언트 연동 | **완료** | [완료: 2026-04-22 · commit: `aa61028`→`6550dc7`→(본 세션 후속 commit) · 참조: `공유/대화로그/조직운영/2026-04-21.md` Unity MCP 섹션 · `공유/개발팀_자산/Unity_MCP_연동_가이드_v1.md` · `공유/개발팀_자산/claude_desktop_config.example.json`] **연동 완전 성공 실증** — `mcp__unityMCP__read_console` 호출로 Unity Console 5건 실수신 확인. uvx `mcpforunityserver==9.6.6` stdio 방식, Unity Editor MCP for Unity v9.6.6 Package bridge 정상. PD 수동 집행 5종(Claude Desktop config merge·완전 재시작·Unity Package 설치·Transport stdio 전환·Configure)·PM 집행 7종 (paths 정정·gitignore·setup 자동 clone·config 템플릿·가이드 v1·uv 0.11.7 winget·ToolSearch·Agent 권한 추가) 모두 완결 | — | Phase 3 EerieVillage 착수 시 Unity MCP 편집 표준 워크플로우 v2 조직공지 승격 집행. 트러블슈팅 경위(HTTP 미지원·좀비 인스턴스·pywin32 캐시 락·Transport 스위칭)는 `공유/개발팀_자산/Unity_MCP_연동_가이드_v1.md` §트러블슈팅 섹션에 영구 아카이브 |

185
공유/개발팀_자산/Unity_MCP_연동_가이드_v1.md
View File

@ -1,10 +1,12 @@
# Unity MCP 연동 가이드 v1 (BurningTimes) # Unity MCP 연동 가이드 v2 (BurningTimes — 실전 검증 개정)
> **목적**: BT 조직 개발자가 Unity MCP를 처음 연동·재설치할 때 따를 표준 절차. > **목적**: BT 조직 개발자가 Unity MCP를 처음 연동·재설치할 때 따를 **실전 검증** 절차. 2026-04-21~22 BT3 도입 시 실제 겪은 이슈·해결안 반영.
> >
> **대상**: 개발팀·기획팀 (MCP 도구로 Unity Editor 조작 필요한 전원) > **대상**: 개발팀·기획팀 (Unity Editor 조작에 MCP 도구 활용 전원)
> >
> **최종 수정**: 2026-04-21 > **개정 이력**:
> - v1 (2026-04-21): HTTP 방식 기반 초안
> - **v2 (2026-04-22)**: 실전 검증 — HTTP 거부·uvx 캐시 락·Transport 스위칭·Configure 자동화 반영
> >
> **참조 규칙**: C6-1 원본 보호 · C30 git 동기화 · C34-11 Agent 경계 · C11 개발 관점 > **참조 규칙**: C6-1 원본 보호 · C30 git 동기화 · C34-11 Agent 경계 · C11 개발 관점
@ -14,25 +16,35 @@
| 구성 | 역할 | | 구성 | 역할 |
|------|------| |------|------|
| **CoplayDev MCP for Unity** (v9.6.x) | Python 기반 MCP 서버 + Unity 에디터 패키지 2종 | | **CoplayDev MCP for Unity** (v9.6.x+) | Python 기반 MCP 서버 + Unity 에디터 패키지 2종 |
| **uv** (Astral) | Python 패키지·스크립트 실행 환경 (MCP 서버 구동에 필요) | | **uv / uvx** (Astral) | Python 패키지·MCP 서버 실행 환경 |
| **Claude Desktop** | MCP 클라이언트. 본 BT 조직 기본 환경 | | **Claude Desktop** | MCP 클라이언트 (BT 조직 기본 환경) |
| **EerieVillage Unity 프로젝트** | MCP 대상 Unity 프로젝트 (`E:/NerdNavis/EerieVillage/EerieVillage/`) | | **EerieVillage Unity 프로젝트** | MCP 대상 Unity 프로젝트 |
**통신 방식**: HTTP (권장, 기본값) — Unity 에디터 내 패키지가 `localhost:8080/mcp` 서버 자동 구동 → Claude Desktop이 해당 URL로 연결 ### 🔴 중요 — Claude Desktop은 **stdio 방식 전용**
Claude Desktop은 공식적으로 **HTTP MCP 서버 연결을 지원하지 않음**. 실증: `{"url": "http://..."}` 방식은 "유효한 MCP 서버 구성이 아님" 경고로 거부됨. **반드시 stdio(uvx) 방식 사용**.
### 통신 구조
```
Claude Desktop ←stdio(uvx)→ mcpforunityserver (Python) ←HTTP/WebSocket→ Unity Editor (MCP for Unity Package)
```
- Claude Desktop → Python 서버: **stdio(uvx)** 전용
- Python 서버 → Unity Editor: Unity Package가 Transport를 HTTP·stdio 둘 다 지원. **Claude Desktop 대상 시 Unity 쪽 Transport도 stdio**로 설정 필수 (Configure 시 자동 검증 경고)
--- ---
## 2. 사전 요구 사항 ## 2. 사전 요구 사항
- Python 3.10+ (`python --version` 확인) - Python 3.10+
- uv 설치 (없으면 Step 3-B 참조) - **uv** (Astral 배포) — winget 권장
- Unity 2021.3 LTS+ (EerieVillage는 6000.3.13f1 LTS) - Unity 2021.3 LTS+ (EerieVillage는 6000.3.13f1 LTS)
- 본 레포 `git clone` + `setup/setup_windows.ps1` 또는 `setup/setup_macos.sh` 실행 (unity-mcp 자동 clone 포함) - BT 레포 clone + setup 스크립트 실행 (unity-mcp 자동 clone 포함)
- Git 명령줄
--- ---
## 3. 설치 절차 (신규 PC 기준) ## 3. 설치 절차 (신규 PC 기준 표준 7단계)
### 3-A. BT 레포 셋업 ### 3-A. BT 레포 셋업
```powershell ```powershell
@ -40,86 +52,143 @@
git clone https://burning.i234.me/NerdNavis_AiDev/BurningTimesAi.git "E:/BurningTimes" git clone https://burning.i234.me/NerdNavis_AiDev/BurningTimesAi.git "E:/BurningTimes"
cd E:/BurningTimes cd E:/BurningTimes
cp paths.local.json.template paths.local.json cp paths.local.json.template paths.local.json
# UNITY_PROJECT_ROOT 등 실값 입력 # paths.local.json 편집:
# UNITY_PROJECT_ROOT = 실제 Unity 프로젝트 경로 (ProjectSettings 폴더 있는 경로)
# FRAMEWORK_PKG_ROOT = BT.Framework 경로 (선택)
# DISCORD_WEBHOOK = BT 공용 웹훅 URL
.\setup\setup_windows.ps1 .\setup\setup_windows.ps1
``` ```
→ 자동으로 `코어코드/unity-mcp/`에 CoplayDev 저장소 clone됨. → setup 스크립트가 `코어코드/unity-mcp/`에 CoplayDev 저장소를 자동 `git clone`.
### 3-B. uv 설치 ### 3-B. uv 설치
```powershell ```powershell
# Windows (winget 권장) # Windows (winget 권장)
winget install --id=astral-sh.uv -e winget install --id=astral-sh.uv -e --accept-source-agreements --accept-package-agreements
``` ```
```bash ```bash
# macOS / Linux # macOS / Linux
curl -LsSf https://astral.sh/uv/install.sh | sh curl -LsSf https://astral.sh/uv/install.sh | sh
``` ```
설치 후 PATH 반영을 위해 **터미널 재시작**. **설치 후 터미널 재시작** (PATH 반영).
### 3-C. Claude Desktop MCP 설정 ### 3-C. uvx 경로 확인
1. `공유/개발팀_자산/claude_desktop_config.example.json` 내용을 복사 ```powershell
2. Claude Desktop 설정 파일 위치에 붙여넣기 (기존 `mcpServers` 있으면 병합) Get-Command uvx | Select-Object Source
- Windows: `%APPDATA%\Claude\claude_desktop_config.json` ```
- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json` 보통 경로: `C:\Users\{USERNAME}\AppData\Local\Microsoft\WinGet\Packages\astral-sh.uv_*\uvx.exe`
3. **Claude Desktop 완전 재시작** (작업 표시줄 아이콘 우클릭 → Quit → 재실행)
### 3-D. Unity Editor에 MCP 패키지 설치 ### 3-D. uv 캐시 사전 워밍업 (중요 — pywin32 락 이슈 회피)
1. Unity Hub에서 EerieVillage 프로젝트 열기 ```powershell
2. `Window > Package Manager > + > Add package from git URL...` & "C:\Users\{USERNAME}\AppData\Local\Microsoft\WinGet\Packages\astral-sh.uv_Microsoft.Winget.Source_8wekyb3d8bbwe\uvx.exe" --from mcpforunityserver mcp-for-unity --help
3. 입력: `https://github.com/CoplayDev/unity-mcp.git?path=/MCPForUnity#main` ```
4. 설치 완료 시 Unity 메뉴에 MCP 관련 메뉴 생성 **3~5분 소요**. `--help` 출력이 뜨면 성공 (의존성 `pywin32·fastmcp·pydantic` 등 캐시 구축 완료). 이 단계 건너뛰면 Claude Desktop 자동 시동 때 **"pywin32.data 디렉토리 락" 에러로 disconnected** 반복.
5. MCP 서버 자동 구동 확인 (`localhost:8080` 리스닝)
### 3-E. 연동 검증 **에러 시 대처**:
1. Claude Desktop 재시작 완료 상태 + Unity Editor + EerieVillage 프로젝트 열려 있음 - Defender 예외 등록 (관리자 PowerShell):
2. Claude 세션에서 `mcp__unity-mcp__*` 도구 호출 테스트 (예: `mcp__unity-mcp__manage_editor` `action: get_state`) ```powershell
3. Unity Editor에서 응답 반영 확인 (GameObject·씬·asset 조작 가능 여부) Add-MpPreference -ExclusionPath "$env:LOCALAPPDATA\uv\cache"
```
- 캐시 삭제 후 재시도:
```powershell
Remove-Item -Recurse -Force "$env:LOCALAPPDATA\uv\cache" -ErrorAction SilentlyContinue
```
### 3-E. Unity Editor + MCP for Unity Package 설치
1. Unity Hub → EerieVillage 프로젝트 열기
2. `Window → Package Manager → + → Install package from git URL...`
3. 입력:
```
https://github.com/CoplayDev/unity-mcp.git?path=/MCPForUnity#main
```
4. 설치·컴파일 완료 대기 (우하단 스피너 멈춤)
### 3-F. Unity MCP for Unity 창 설정 (**v2 핵심**)
Unity 상단 메뉴: `Window → MCP for Unity` 창 열기
#### ① Transport를 **stdio**로 변경 (필수)
- 기본값은 `HTTP Local` — Claude Desktop 대상 시 그대로 Configure 누르면 **"Claude Desktop does not support HTTP transport"** 에러
- Transport 드롭다운 → **`stdio`** 선택
#### ② Server 구동
- "Start Server" 버튼 → 🟢 Running 상태 확인
#### ③ Client = **Claude Desktop** 선택
- Client Configuration 드롭다운에서 "Claude Desktop" 선택
#### ④ Configure 버튼 클릭 (자동 설정)
- Unity가 `%APPDATA%\Claude\claude_desktop_config.json`을 **자동으로 올바른 stdio 포맷**으로 덮어씀
- uvx 절대 경로·args 자동 탐지·기록
- 기존 수동 설정보다 안정적
### 3-G. Claude Desktop 완전 재시작 + 검증
1. **트레이 아이콘 우클릭 → Quit** (창 X는 트레이 잔류 — 미반영)
2. Claude Desktop 재실행
3. Claude 세션에서 요청: "Unity Console 로그 읽어줘"
4. 제가 `mcp__unityMCP__read_console` 호출 → Unity Console 로그 실수신 확인
**실증 (2026-04-22)**: 위 순서로 진행하면 5단계 만에 연동 성공. `success: true` + Unity Console 로그 배열 수신.
--- ---
## 4. BT 조직 Unity MCP 편집 표준 워크플로우 v2 ## 4. BT 조직 Unity MCP 편집 표준 워크플로우 v2
> **v1 계승 근거**: `공유/조직자산/시행착오_아카이브/개발_클라이언트팀장_v1.md` §Unity MCP 편집 6단계 표준 워크플로우. v1은 이전 프로젝트에서 실증된 패턴. > **v1 계승 근거**: `공유/조직자산/시행착오_아카이브/개발_클라이언트팀장_v1.md` §Unity MCP 편집 6단계 표준 워크플로우
>
> **v2 변경점**: EerieVillage(2D PlatformerMicrogame, Unity 6000.3.13f1 LTS) 맥락 반영.
### 6단계 표준 절차 (씬·프리팹·ScriptableObject 편집 시) ### 편집 6단계 표준 (씬·프리팹·ScriptableObject·스크립트 편집 시)
| 단계 | 액션 | 근거 규칙 | | 단계 | 액션 | 근거 규칙 |
|------|------|----------| |------|------|----------|
| 1. **SHA 기록** | Unity 프로젝트 `git rev-parse HEAD` 실측 기록 (편집 전 시점 커밋 확정) | C30 git 동기화 | | 1. **SHA 기록** | Unity 프로젝트 `git rev-parse HEAD` 기록 (편집 전 커밋 확정) | C30 git 동기화 |
| 2. **Read 선행** | `mcp__unity-mcp__*` 또는 파일 직접 Read로 **편집 전 상태 전수 파악** | C5 정직성 | | 2. **Read 선행** | MCP 도구 또는 파일 직접 Read로 편집 전 상태 전수 파악 | C5 정직성 |
| 3. **백업** | 원본 파일 `.bak_{YYYYMMDD_HHMM}.{ext}` 복사 (씬·프리팹·ScriptableObject·asmdef 등) | C6-1 원본 보호 | | 3. **백업** | 원본 파일 `.bak_{YYYYMMDD_HHMM}.{ext}` 복사 | C6-1 원본 보호 |
| 4. **Unity 프로젝트 commit** | 편집 전 현 상태를 Unity 레포에 commit (롤백 지점 확보) | C6-2 프로덕션 보호 | | 4. **Unity 프로젝트 commit** | 편집 전 현 상태 Unity 레포 commit (롤백 지점) | C6-2 프로덕션 보호 |
| 5. **편집 집행** | MCP 도구로 실제 변경. 상대 경로 또는 `$UNITY_PROJECT_ROOT` 변수 사용 | C34-11 Agent 경계 | | 5. **편집 집행** | MCP 도구 호출. 상대 경로·`$UNITY_PROJECT_ROOT` 사용 | C34-11 Agent 경계 |
| 6. **검증** | Unity Editor 콘솔 오류 0건·의도 결과 반영 확인 → 커밋 | P14 QA 게이트 | | 6. **검증** | Unity Console 오류 0건·의도 결과 반영 → 커밋 | P14 QA 게이트 |
### 금지 행위 ### 금지 행위
- 절대 경로 하드코딩 (`E:\NerdNavis\EerieVillage\...` 같이 PC별 달라지는 경로) — **C34-11 위반** - 절대 경로 하드코딩 (PC별 달라지는 경로)
- 백업 없이 씬·프리팹 직접 편집 — **C6-1 위반** - 백업 없이 씬·프리팹 직접 편집
- Unity 콘솔 오류 잔존 상태로 작업 종료 — **P14 위반** - Unity Console 오류 잔존 상태로 작업 종료
- MCP 응답의 "완료"만 신뢰하고 Unity Editor 실체 미검증 — **C23 위반** - MCP 응답 "완료" 신뢰하고 Unity Editor 실체 미검증
--- ---
## 5. 업데이트·유지보수 ## 5. 트러블슈팅 — 실전 검증 이슈 7종
| 증상 | 원인 | 해결 |
|------|------|------|
| `{"url": "..."}` 설정 시 **"유효한 MCP 서버 구성이 아닙니다"** | Claude Desktop HTTP 미지원 | stdio(uvx) 방식으로 전환 |
| **"Could not attach to MCP server"** 다수 서버 동시 | Claude Desktop 좀비 인스턴스가 MCP 프로세스 락 | 작업관리자에서 `Claude.exe`·`uvx.exe`·`uv.exe`·`python.exe`·`node.exe` 전수 종료 후 재실행 |
| **"Server disconnected" 반복** (unityMCP) | uvx 첫 설치 시 `pywin32.data` 폴더 락 (Defender 실시간 검사·이전 프로세스) | 3-D 수동 사전 워밍업 + 필요 시 Defender 예외 + `uv cache clean` |
| **"MCP memory: Server disconnected"** 또는 유사 | 다른 PC에서 가져온 config의 경로(`C:\Users\silve\...`) 무효 | 해당 PC 실제 경로로 수정 또는 불필요하면 제거 |
| Unity Package 설치 후에도 **"No Unity Editor instances found"** | MCP for Unity 브릿지 서버 미구동 | Unity → `Window → MCP for Unity` 창에서 "Start Server" 클릭 |
| Configure 버튼 클릭 시 **"Claude Desktop does not support HTTP transport"** | Unity 쪽 Transport가 `HTTP Local` (기본값) | Transport 드롭다운 → `stdio` 선택 후 재Configure |
| Claude Desktop 재시작해도 변경 미반영 | 트레이 좀비 인스턴스 잔류 (창 X 닫기는 미종료) | 트레이 아이콘 우클릭 Quit 또는 작업관리자 전수 종료 |
---
## 6. 업데이트·유지보수
### unity-mcp 업스트림 업데이트 ### unity-mcp 업스트림 업데이트
```bash ```bash
cd 코어코드/unity-mcp cd 코어코드/unity-mcp
git pull git pull
``` ```
Unity 패키지 업데이트는 Unity Editor Package Manager에서 별도. Unity Package는 Package Manager에서 별도 업데이트 (버전 변경 시 Unity에서 수동 수행).
### 충돌·연동 실패 시 ### 충돌·연동 실패 시 로그 확인
1. Claude Desktop 로그 확인 (`%APPDATA%\Claude\logs\`) - Claude Desktop 로그: `%APPDATA%\Claude\logs\mcp-server-unityMCP.log`
2. Unity Console 탭에서 MCP 서버 상태 확인 - Unity Console: `Window → General → Console`
3. 포트 8080 충돌 여부 확인 (`netstat -an | findstr 8080`) - Unity MCP for Unity 창 하단 상태 표시
--- ---
## 6. 관련 자산 ## 7. 관련 자산 (BT 조직 계승)
- `공유/조직자산/시행착오_아카이브/개발_클라이언트팀장_v1.md` — Unity MCP v1 시행착오
- `공유/개발팀_자산/claude_desktop_config.example.json` — Claude Desktop 설정 템플릿 - `공유/조직공지/2026-04-22_Unity_MCP_연동_표준_워크플로우_v2.md` — 조직공지 승격본 (본 가이드 요지)
- `paths.local.json` — PC별 `UNITY_PROJECT_ROOT` 등 로컬 경로 - `공유/조직자산/시행착오_아카이브/개발_MCP연동_v1.md` — BT3 도입 시행착오 타임라인·교훈
- `setup/setup_windows.ps1` / `setup_macos.sh` — 자동 셋업 (3.7절 unity-mcp clone 포함) - `memory/org/feedback_mcp_setup_pitfalls.md` — MCP 셋업 재발 방지 패턴 5종
- `공유/조직자산/시행착오_아카이브/개발_클라이언트팀장_v1.md` — 이전 프로젝트 Unity MCP v1 경험
- `공유/개발팀_자산/claude_desktop_config.example.json` — Claude Desktop 설정 예시 (stdio 기본)
- `paths.local.json.template` — PC별 경로 템플릿
- `setup/setup_windows.ps1` / `setup_macos.sh` — 자동 셋업 스크립트 (§3.7 unity-mcp clone)

70
공유/개발팀_자산/claude_desktop_config.example.json
View File

@ -1,39 +1,55 @@
{ {
"_description_ko": "Claude Desktop MCP 서버 등록 예시 — Unity MCP HTTP 방식 (CoplayDev MCP for Unity 공식 권장).", "_description_ko": "Claude Desktop MCP 서버 등록 예시 — Unity MCP stdio(uvx) 방식. Claude Desktop은 HTTP url 방식을 공식 지원하지 않으므로 stdio가 유일한 선택.",
"_중요_경고": [
"Claude Desktop은 {\"url\": \"...\"} HTTP 방식 MCP를 거부한다 (\"유효한 MCP 서버 구성이 아닙니다\" 경고).",
"stdio(uvx) 방식만 사용 가능.",
"Unity 쪽 Transport도 stdio로 설정해야 한다 (MCP for Unity 창 → Transport 드롭다운)."
],
"_설치_경로": { "_설치_경로": {
"Windows": "%APPDATA%\\Claude\\claude_desktop_config.json (= C:\\Users\\USERNAME\\AppData\\Roaming\\Claude\\claude_desktop_config.json)", "Windows": "%APPDATA%\\Claude\\claude_desktop_config.json",
"macOS": "~/Library/Application Support/Claude/claude_desktop_config.json", "macOS": "~/Library/Application Support/Claude/claude_desktop_config.json",
"Linux": "~/.config/Claude/claude_desktop_config.json" "Linux": "~/.config/Claude/claude_desktop_config.json"
}, },
"_적용_방법": [ "_권장_방법": [
"1. 본 파일 내용을 claude_desktop_config.json에 복사 (기존 mcpServers가 있으면 병합)", "1. Unity Editor 실행 + EerieVillage 프로젝트 열기",
"2. Claude Desktop 완전 재시작 (작업 표시줄 아이콘 우클릭 → Quit → 재실행. 창만 닫으면 인식 안 됨)", "2. MCP for Unity Package 설치 (Package Manager, git URL: https://github.com/CoplayDev/unity-mcp.git?path=/MCPForUnity#main)",
"3. Unity Editor에서 BT.Framework 프로젝트를 열고 MCP for Unity 패키지 활성화 (HTTP 서버 localhost:8080 자동 구동)", "3. Unity 상단 메뉴 'Window → MCP for Unity' 창 열기",
"4. Claude 세션에서 mcp__unity-mcp__* 도구 호출 가능 확인" "4. Transport 드롭다운을 stdio로 변경",
"5. 'Start Server' 클릭",
"6. Client 드롭다운을 Claude Desktop 선택",
"7. 'Configure' 버튼 클릭 — Unity가 claude_desktop_config.json을 자동으로 정확하게 덮어씀",
"8. Claude Desktop 완전 재시작 (트레이 Quit → 재실행)"
], ],
"_대안_stdio_uvx": { "_수동_설정_참고": "위 자동 Configure 가 어려우면 아래 unityMCP 블록을 수동으로 mcpServers에 추가. uvx.exe 경로는 'Get-Command uvx | Select-Object Source' 로 확인 후 교체.",
"_설명": "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": { "mcpServers": {
"unityMCP": { "unityMCP": {
"url": "http://localhost:8080/mcp" "command": "C:\\Users\\YOUR_USERNAME\\AppData\\Local\\Microsoft\\WinGet\\Packages\\astral-sh.uv_Microsoft.Winget.Source_8wekyb3d8bbwe\\uvx.exe",
"args": [
"--from",
"mcpforunityserver",
"mcp-for-unity",
"--transport",
"stdio"
]
} }
},
"_함께_권장": {
"_설명": "BT 조직 Claude Desktop 기본 설정에 함께 고려할 수 있는 항목. 필수 아님.",
"mcp-installer": {
"command": "npx",
"args": ["@anaisbetts/mcp-installer"]
} }
},
"_사전_워밍업_필수": [
"Claude Desktop에서 자동 시동 전, 아래 명령을 수동 실행하여 uv cache에 패키지 사전 설치.",
"미수행 시 pywin32 설치 중 Windows Defender 실시간 검사·이전 프로세스 락으로 'Server disconnected' 반복 발생.",
"",
"PowerShell:",
" & 'C:\\Users\\YOUR_USERNAME\\AppData\\Local\\Microsoft\\WinGet\\Packages\\astral-sh.uv_Microsoft.Winget.Source_8wekyb3d8bbwe\\uvx.exe' --from mcpforunityserver mcp-for-unity --help",
"",
"3~5분 소요. --help 출력이 뜨면 성공."
]
} }

53
공유/대화로그/조직운영/2026-04-21.md
View File

@ -233,12 +233,63 @@ Phase 2-B content-designer Agent 경계 위반 2회차 — `feedback_agent_path_
### 기각안 ### 기각안
1. **Claude Code `.mcp.json` 방식** — 기각. PD님 4번 답변 "Claude Desktop" 명시. `.mcp.json`은 Claude Code 전용 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` 주석 대안으로만 기재 2. **stdio(uvx) 방식 기본 채택 (초기 판정)** — 초기 기각 후 **번복 반영**. 공식 README 권장은 HTTP였지만 Claude Desktop은 HTTP 미지원 실증 → stdio가 **유일한 선택**으로 확정. 가이드 v2·조직공지·feedback 메모리에 모두 stdio 기본 명시
3. **B안 submodule** — 기각 (PM 권고 A안 + setup 자동화로 B안 장점 흡수) 3. **B안 submodule** — 기각 (PM 권고 A안 + setup 자동화로 B안 장점 흡수)
4. **C안 BT fork commit** — 기각 (unity-mcp 활발 업데이트·BT fork 이유 없음·레포 비대화) 4. **C안 BT fork commit** — 기각 (unity-mcp 활발 업데이트·BT fork 이유 없음·레포 비대화)
--- ---
## [BT3 완결] Unity MCP 연동 완전 성공 + 조직 자산 축적
**태그**: #BT3완결 #UnityMCP성공 #조직자산축적 #가이드v2 #feedback신설
### 2026-04-22 연동 성공
- **검증 명령**: `mcp__unityMCP__read_console` (read-only)
- **응답**: `success: true` + Unity Console 로그 5건 실수신
- **확인**: `mcpforunityserver==9.6.6` uvx stdio 모드 + Unity MCP for Unity Package bridge 정상
- **전 구간**: Claude Desktop ↔ Python MCP 서버 ↔ Unity Editor 완전 연결
### PD님 수동 집행 요약 (트러블슈팅 경위)
1. HTTP url 방식 → "유효한 MCP 서버 구성 아님" 거부 → stdio 전환
2. 4개 서버 "Could not attach" → Claude 좀비 인스턴스 → 작업관리자 전수 종료
3. unityMCP "Server disconnected" 반복 → `pywin32` 캐시 락 → uv cache 삭제 + 수동 사전 워밍업
4. "No Unity Editor instances found" → Unity Package 미설치 → Package Manager로 MCP for Unity v9.6.6 설치
5. Configure 실패 "HTTP transport not supported" → Unity 쪽 Transport → stdio 전환 → 성공
### 조직 자산 축적 — PD 지시 "이번 세션 경험 조직 자산으로 축적" 이행
| 산출물 | 경로 | 성격 |
|-------|------|------|
| 연동 가이드 v2 | `공유/개발팀_자산/Unity_MCP_연동_가이드_v1.md` | 실전 검증 개정 (v1 덮어씀) — 표준 7단계·트러블슈팅 7종·편집 6단계 |
| Claude Desktop config 예시 | `공유/개발팀_자산/claude_desktop_config.example.json` | stdio 기본 + HTTP 미지원 경고·수동 사전 워밍업 안내 |
| 재발 방지 SOT | `memory/org/feedback_mcp_setup_pitfalls.md` | 함정 5종 + 차기 MCP 도입 체크리스트 |
| 시행착오 아카이브 | `공유/조직자산/시행착오_아카이브/개발_MCP연동_v1.md` | 7단계 타임라인 + PM 보고 안건 + 참조 원본 |
| 조직공지 | `공유/조직공지/2026-04-22_Unity_MCP_연동_표준_워크플로우_v2.md` | 7개 핵심 규범 + 표준 8단계 + 트러블슈팅 표 (승격본) |
| MEMORY.md 인덱스 | `memory/org/MEMORY.md` | feedback_mcp_setup_pitfalls 항목 append |
| settings.json 권한 | ToolSearch·Agent 자동 승인 (`6550dc7`) | PD 별도 지시 반영 — 다른 PC 재시작 시 자동 반영 |
### 계승 원칙 (조직 운영 관점)
- **경험 축적은 "성공"뿐 아니라 "실패·재시도"까지 기록**해야 차기 참조 가치가 있음
- MCP 도구 도입 시 **클라이언트별 호환성** 검증이 최우선 (README 권장과 Claude Desktop 호환이 다를 수 있음)
- 트러블슈팅은 **로그 선행 Read + 실체 도구 호출 검증**이 UI 관찰보다 빠름
- 조직 자산은 **다층 구조**로 배포 — SOT(feedback) + 상세(시행착오) + 실행(가이드) + 공지(조직공지) 역할 분리
### Phase 3 이관 안건 (기존 보류 7종 + 신규 1종)
- [기존 7종] 서버 아키텍처·BT.Framework Tier 2·3·Unity MCP 워크플로우 v2·조선 퇴마 세계관 SOT·2D 플랫포머 UX·Prove-2-of-3 이식성·어뷰징 경계값
- **[신규 8종]** 조직공지 `2026-04-22_Unity_MCP_연동_표준_워크플로우_v2` 는 **정식 발행 완료** 상태. 차기 프로젝트 MCP 도입 시 이 공지가 1차 참조 — **Phase 3 진입 시 가장 먼저 Read**
### BT3 최종 상태
- PD 지시 로그: **완료 아카이브 이동 완료**
- 원격 main HEAD: (본 세션 commit 예정)
- 활성 지시: **없음** (Phase 3 PD님 지시 수령 대기)
### 기각안 (본 자산화 작업)
1. **feedback 메모리를 가이드와 통합** — 기각. feedback 메모리는 `memory/org/` 하위 고유 SOT, 가이드는 `공유/개발팀_자산/` 하위 실행 문서. 역할 분리가 토큰 효율·재사용 측면에서 우수
2. **시행착오 아카이브를 가이드 내부 섹션으로 병합** — 기각. 시행착오 아카이브는 BT 조직 14종 구조를 따라 영역별 독립 문서 유지. 가이드는 "지금 바로 따라하는 매뉴얼", 시행착오는 "왜 이렇게 설계됐는지 근거"로 역할 분리
3. **조직공지 발행 생략** — 기각. PC 독립 셋업 표준은 조직공지 형태로 공식화해야 신규 PC·다른 세션이 SessionStart hook 스캔 시 자동 인지 가능
---
## [Phase 2-B 완료] 전 에이전트 시행착오 아카이브 14종 (README 포함) ## [Phase 2-B 완료] 전 에이전트 시행착오 아카이브 14종 (README 포함)
**태그**: #Phase2B #시행착오아카이브 #BurningTimes #조직자산 **태그**: #Phase2B #시행착오아카이브 #BurningTimes #조직자산

113
공유/조직공지/2026-04-22_Unity_MCP_연동_표준_워크플로우_v2.md Normal file
View File

@ -0,0 +1,113 @@
# [조직공지] 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** 노하우 축적 (본 공지 자체가 실증)

207
공유/조직자산/시행착오_아카이브/개발_MCP연동_v1.md Normal file
View File

@ -0,0 +1,207 @@
---
type: 시행착오 아카이브
scope: Unity MCP (Model Context Protocol) 도입·연동
source_project: BurningTimes (BT3 지시)
source_date: 2026-04-21 ~ 2026-04-22
target_org: BurningTimes
target_project: EerieVillage + 차기 프로젝트
maintainer: 개발팀장 · 총괄PM
created: 2026-04-22
version: v1
related_rules: C6-1 · C11 · C16 · C23 · C30 · C34-11 · P10 · P14
related_feedback: feedback_mcp_setup_pitfalls.md
rationale: BT3 Unity MCP 도입 시 실증된 7종 트러블슈팅 타임라인·해결 순서·교훈을 조직 자산으로 영구 보존. 차기 MCP 도구 도입·신규 PC 셋업 시 첫 참조 자산
---
# BurningTimes · Unity MCP 연동 시행착오 아카이브 v1
## 1. 개요 — BT3 지시 요약
| 항목 | 값 |
|------|---|
| **지시일** | 2026-04-21 |
| **지시 내용** | "Unity MCP를 이용해 프로젝트 개발 진행" + Unity MCP 저장소 `E:\BurningTimes\코어코드\unity-mcp`에 사전 clone |
| **완결일** | 2026-04-22 |
| **소요 세션** | 약 3 세션 (경계: SessionStart hook resume 3회) |
| **최종 결과** | ✅ 완전 연동 성공 (`mcp__unityMCP__read_console` 실수신 확인) |
| **관리 방침 결정** | A안 (gitignore + setup 자동 clone) — PD 승인 |
## 2. 시행착오 타임라인 — 7단계
### 단계 1. HTTP url 방식 실패
**시도**: unity-mcp 공식 README의 "기본 권장" HTTP 설정 채택
```json
"unityMCP": {"url": "http://localhost:8080/mcp"}
```
**결과**: Claude Desktop 경고 **"유효한 MCP 서버 구성이 아닙니다: unityMCP"** (유일한 거부 이유 메시지)
**근본 원인**: Claude Desktop은 **stdio 방식만 공식 지원**. README의 "HTTP 권장"은 Claude Code·Cursor·Windsurf 등 타 클라이언트 대상이었고, Claude Desktop 호환성은 별도 명시되지 않음.
**해결**: stdio(uvx) 방식으로 전환
```json
"unityMCP": {
"command": "<uvx.exe 절대 경로>",
"args": ["--from", "mcpforunityserver", "mcp-for-unity", "--transport", "stdio"]
}
```
**교훈**: MCP 공식 문서의 "권장" 방식 ≠ 모든 클라이언트 지원. **클라이언트별 stdio/HTTP 호환성 재확인** 필수.
---
### 단계 2. "Server disconnected" 반복 (memory·filesystem)
**증상**: JSON 문법 수정 후에도 `MCP memory / filesystem: Server disconnected` 경고 반복.
**근본 원인**:
- `memory` 서버: `C:\Users\silve\...` 경로 — **다른 PC(silve 사용자)에서 가져온 config**. 이 PC는 `sw` 사용자
- `filesystem` 서버: `D:\Dev\SurgeCoin` — **해당 프로젝트 폴더 자체 미존재**
- BT 조직 작업과 무관한 다른 프로젝트(SurgeCoin) 잔재 경로
**해결**:
- BT 작업에 불필요한 서버(filesystem·sqlite)는 config에서 제거
- memory는 `sw` 경로로 수정 유지 또는 제거 (옵션 A: minimal config 권장 채택)
**교훈**: **config는 PC별·사용자별 경로가 혼입되기 쉬움**. 다른 PC에서 복사 시 전수 경로 수정 + 불필요 서버 제거. BT 조직은 **template만 git 추적**, 실제 config는 PC별 개별 관리.
---
### 단계 3. "Could not attach" 4개 서버 동시 실패
**증상**: Claude Desktop 재시작 후에도 4개 MCP 서버(sqlite·filesystem·memory·unityMCP) 모두 `Could not attach to MCP server` 경고.
**근본 원인**: Claude Desktop **좀비 인스턴스** 잔류. 창 X 닫기는 트레이 잔존이라 이전 인스턴스가 MCP 프로세스 락. 새 인스턴스가 attach 시도하나 실패.
**해결**:
1. 작업관리자에서 `Claude.exe` 프로세스 **전수 종료** (복수 인스턴스 모두)
2. MCP 서버 잔재 프로세스(`uvx.exe`·`python.exe`·`node.exe`) 검색·종료
3. Claude Desktop 재실행
**교훈**: "창 닫기 ≠ 종료". **트레이 아이콘 우클릭 Quit** 또는 **작업관리자 전수 종료** 필수. 가이드·조직공지에 명시화.
---
### 단계 4. unityMCP "Server disconnected" 반복 — pywin32 캐시 락
**증상**: 3개 서버 disconnected 해소 후에도 `MCP unityMCP: Server disconnected` 지속.
**로그** (`%APPDATA%\Claude\logs\mcp-server-unityMCP.log`):
```
error: Failed to install: pywin32-311-cp312-cp312-win_amd64.whl (pywin32==311)
Caused by: failed to remove directory ...pywin32-311.data:
다른 프로세스가 파일을 사용 중이기 때문에 프로세스가 액세스 할 수 없습니다. (os error 32)
```
**근본 원인**: uvx 첫 설치 시 `mcpforunityserver` 의존성 `pywin32-311` 전개 중 **Windows Defender 실시간 스캔**이 `.pyd` 바이너리 일시 락. 또는 이전 uvx 시도 잔재 프로세스가 캐시 락.
**해결**:
1. 모든 Claude·uvx·python 프로세스 전수 종료
2. `uv cache` 삭제:
```powershell
Remove-Item -Recurse -Force "$env:LOCALAPPDATA\uv\cache"
```
3. 수동 사전 워밍업 — Claude Desktop 밖에서 먼저 uvx 실행:
```powershell
& "<uvx.exe 경로>" --from mcpforunityserver mcp-for-unity --help
```
성공하면 캐시에 모든 의존성 완전 설치됨 (3~5분)
4. Claude Desktop 재실행 → uvx는 캐시에서 즉시 시동 (수 초)
**교훈**: Python 기반 MCP 서버는 **첫 실행 시 의존성 다운로드·설치가 수 분 소요**. Claude Desktop의 자동 시동은 타임아웃 짧아 실패 가능. **반드시 수동 사전 워밍업** 후 재시작.
---
### 단계 5. Python 서버 연결 성공 · Unity 연결 미완
**증상**: Claude Desktop에서 `mcp-installer (running)`·`unityMCP` 표시. `mcp__unityMCP__read_console` 호출 응답 수신:
```
"No Unity Editor instances found. Please ensure Unity is running with MCP for Unity bridge."
```
**근본 원인**: **Claude ↔ Python 서버는 연결**되었으나 **Python 서버 ↔ Unity Editor 미연결**. Unity Editor 실행만 하고 MCP for Unity Package 미설치.
**해결**:
1. Unity Hub에서 EerieVillage 프로젝트 열기
2. Package Manager → + → "Install package from git URL..."
3. `https://github.com/CoplayDev/unity-mcp.git?path=/MCPForUnity#main`
4. 설치·컴파일 완료 대기
**교훈**: "MCP 서버 연결 = 도구 작동"이 아님. **대상 시스템(Unity)과의 최종 연결**까지 별도 검증 필요. 구간별 단계 체크가 효율적.
---
### 단계 6. Unity Transport HTTP → stdio 전환
**증상**: Unity MCP for Unity 창 열림. Configure 버튼 클릭 시 에러 팝업:
> **"Claude Desktop does not support HTTP transport. Switch to stdio in settings before configuring."**
**근본 원인**: Unity 쪽 Transport 기본값은 `HTTP Local`. Claude Desktop 대상 시 stdio 필요 — Unity MCP Package가 자체 검증해서 친절히 차단.
**해결**:
1. Unity MCP for Unity 창 → Transport 드롭다운 → **stdio** 선택
2. Client 드롭다운 → **Claude Desktop** 선택
3. Configure 버튼 재클릭 → 성공
**교훈**: MCP 도구 양쪽(서버·클라이언트) **Transport 일치 필수**. Unity MCP Package는 자체 검증 로직 있어 에러 메시지가 정확한 방향 제시.
---
### 단계 7. 연동 완전 성공 검증
**시점**: 2026-04-22
**명령**: `mcp__unityMCP__read_console action=get count=5`
**응답**:
```json
{
"success": true,
"message": "Retrieved 5 log entries.",
"data": [
"MCP-FOR-UNITY: Setup marked as completed",
"MCP-FOR-UNITY: Started local HTTP server in terminal: <uvx> --offline --from mcpforunityserver==9.6.6 mcp-for-unity --transport http --http-url http://127.0.0.1:8080 ...",
"[WebSocket] Receive loop error: ...",
...
]
}
```
**검증 포인트**:
- ✅ Unity Editor 실체 로그 수신
- ✅ `mcpforunityserver==9.6.6` 실행 확인
- ⚠️ WebSocket 경고 3건 — Configure 전환 시점 임시 재연결 로그 (현재 연결 정상이므로 무해)
## 3. BT 조직 계승 체크리스트
### 신규 PC Unity MCP 셋업 시 (필독)
1. BT 레포 clone + `paths.local.json` 생성 + `setup_windows.ps1` 실행 → unity-mcp 자동 clone
2. `winget install astral-sh.uv` → 터미널 재시작
3. **수동 사전 워밍업** (필수): `uvx --from mcpforunityserver mcp-for-unity --help` (3~5분)
4. Unity Editor + Package Manager로 MCP for Unity 설치
5. MCP for Unity 창 → **Transport: stdio** + Server Start + Client: Claude Desktop + Configure
6. Claude Desktop **트레이 Quit** 후 재실행
7. 연동 검증: "Unity Console 로그 읽어줘" 요청 → 실수신 확인
### 차기 MCP 도구 도입 시
1. 공식 README의 "권장 방식"이 HTTP이면 **Claude Desktop 호환성 재확인**
2. Python 기반 서버는 **uvx 수동 사전 워밍업** 우선
3. 재시작은 **트레이 Quit** 체크
4. 연동 검증은 **실체 도구 호출**로 판정 (UI 표시만으로 성공 단정 금지)
## 4. PM 보고 안건 (Phase 3 이관 검토)
- **Unity MCP 편집 표준 워크플로우 v2** 조직공지 정식 발행 (`2026-04-22_Unity_MCP_연동_표준_워크플로우_v2.md` 완료)
- **C23 정직성 관점 재발 방지**: 단계 5·6 같이 "MCP 서버 연결 = 도구 작동" 오인 차단 — 체크리스트에 실체 검증 단계 고정화
- **ToolSearch·Agent 권한 추가 반영** (`.claude/settings.json` commit `6550dc7`): 차기 MCP 도구 도입 시 유사 자동 승인 패턴 적용 검토
- **C34-11 Agent 경계 재확인**: Unity MCP 도구 호출 시 PC별 경로 하드코딩 금지 — `$UNITY_PROJECT_ROOT` 변수 활용 표준 유지
## 5. 참조 원본
### 대화로그·로그
- `공유/대화로그/조직운영/2026-04-21.md` — BT3 지시·집행·트러블슈팅 세션 경위
- `%APPDATA%\Claude\logs\mcp-server-unityMCP.log` — pywin32 락 에러 로그 (로컬)
- `%APPDATA%\Claude\logs\main.log` — Claude Desktop MCP 전반 로그 (로컬)
### 관련 자산
- `공유/개발팀_자산/Unity_MCP_연동_가이드_v1.md` (v2 개정본)
- `공유/개발팀_자산/claude_desktop_config.example.json` (stdio 기본)
- `공유/조직공지/2026-04-22_Unity_MCP_연동_표준_워크플로우_v2.md`
- `memory/org/feedback_mcp_setup_pitfalls.md` — 재발 방지 SOT (본 아카이브 축약판)
- `공유/조직자산/시행착오_아카이브/개발_클라이언트팀장_v1.md` — 이전 Unity MCP v1 경험 계승
### 커밋 타임라인
- `aa61028` — Unity MCP 도입 셋업 PM 집행분
- `6550dc7` — ToolSearch·Agent 권한 자동 승인 추가
- (본 세션 후속 commit) — BT3 완료 + 조직 자산 축적