10 KiB

Raw Blame History

type	scope	source_project	source_date	target_org	target_project	maintainer	created	version	related_rules	related_feedback	rationale
시행착오 아카이브	Unity MCP (Model Context Protocol) 도입·연동	BurningTimes (BT3 지시)	2026-04-21 ~ 2026-04-22	BurningTimes	EerieVillage + 차기 프로젝트	개발팀장 · 총괄PM	2026-04-22	v1	C6-1 · C11 · C16 · C23 · C30 · C34-11 · P10 · P14	feedback_mcp_setup_pitfalls.md	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 설정 채택

"unityMCP": {"url": "http://localhost:8080/mcp"}

결과: Claude Desktop 경고 "유효한 MCP 서버 구성이 아닙니다: unityMCP" (유일한 거부 이유 메시지)

근본 원인: Claude Desktop은 stdio 방식만 공식 지원. README의 "HTTP 권장"은 Claude Code·Cursor·Windsurf 등 타 클라이언트 대상이었고, Claude Desktop 호환성은 별도 명시되지 않음.

해결: stdio(uvx) 방식으로 전환

"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 시도하나 실패.

해결:

작업관리자에서 Claude.exe 프로세스 전수 종료 (복수 인스턴스 모두)
MCP 서버 잔재 프로세스(uvx.exe·python.exe·node.exe) 검색·종료
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 시도 잔재 프로세스가 캐시 락.

해결:

모든 Claude·uvx·python 프로세스 전수 종료

uv cache 삭제:

Remove-Item -Recurse -Force "$env:LOCALAPPDATA\uv\cache"

수동 사전 워밍업 — Claude Desktop 밖에서 먼저 uvx 실행:
```
& "<uvx.exe 경로>" --from mcpforunityserver mcp-for-unity --help
```
성공하면 캐시에 모든 의존성 완전 설치됨 (3~5분)
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 미설치.

해결:

Unity Hub에서 EerieVillage 프로젝트 열기
Package Manager → + → "Install package from git URL..."
https://github.com/CoplayDev/unity-mcp.git?path=/MCPForUnity#main
설치·컴파일 완료 대기

교훈: "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가 자체 검증해서 친절히 차단.

해결:

Unity MCP for Unity 창 → Transport 드롭다운 → stdio 선택
Client 드롭다운 → Claude Desktop 선택
Configure 버튼 재클릭 → 성공

교훈: MCP 도구 양쪽(서버·클라이언트) Transport 일치 필수. Unity MCP Package는 자체 검증 로직 있어 에러 메시지가 정확한 방향 제시.

단계 7. 연동 완전 성공 검증

시점: 2026-04-22 명령: mcp__unityMCP__read_console action=get count=5 응답:

{
  "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 셋업 시 (필독)

BT 레포 clone + paths.local.json 생성 + setup_windows.ps1 실행 → unity-mcp 자동 clone
winget install astral-sh.uv → 터미널 재시작
수동 사전 워밍업 (필수): uvx --from mcpforunityserver mcp-for-unity --help (3~5분)
Unity Editor + Package Manager로 MCP for Unity 설치
MCP for Unity 창 → Transport: stdio + Server Start + Client: Claude Desktop + Configure
Claude Desktop 트레이 Quit 후 재실행
연동 검증: "Unity Console 로그 읽어줘" 요청 → 실수신 확인

차기 MCP 도구 도입 시

공식 README의 "권장 방식"이 HTTP이면 Claude Desktop 호환성 재확인
Python 기반 서버는 uvx 수동 사전 워밍업 우선
재시작은 트레이 Quit 체크
연동 검증은 실체 도구 호출로 판정 (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 전반 로그 (로컬)

커밋 타임라인

aa61028 — Unity MCP 도입 셋업 PM 집행분
6550dc7 — ToolSearch·Agent 권한 자동 승인 추가
(본 세션 후속 commit) — BT3 완료 + 조직 자산 축적

10 KiB Raw Blame History