geuneda-mcp-unity: Instructions file for Claude Code

CLAUDE.md

이 파일은 이 저장소의 코드를 작업할 때 Claude Code (claude.ai/code)에게 지침을 제공합니다.

프로젝트 개요

MCP Unity는 MCP 지원 클라이언트(Cursor, Windsurf, Claude Code, Codex CLI, GitHub Copilot)에 2계층 아키텍처를 통해 Unity Editor 기능을 노출합니다:

• Unity Editor (C#): 도구/리소스를 실행하는 Unity 내부 WebSocket 서버
• Node.js 서버 (TypeScript): WebSocket을 통해 AI 클라이언트와 Unity를 연결하는 MCP stdio 서버

데이터 흐름: MCP 클라이언트 ⇄ (stdio) ⇄ Node 서버 (Server~/src/index.ts) ⇄ (WebSocket) ⇄ Unity Editor (Editor/UnityBridge/McpUnityServer.cs)

빌드 및 개발 명령어

Node.js 서버 (Server~/)

npm install          # 의존성 설치
npm run build        # TypeScript를 build/로 컴파일
npm run watch        # 감시 모드 컴파일
npm start            # 서버 실행 (node build/index.js)
npm test             # Jest 테스트 실행 (--experimental-vm-modules 사용)
npm run test:watch   # 감시 모드 테스트
npm run inspector    # 디버깅을 위한 MCP Inspector 실행

Unity 측

• Unity Editor를 통한 빌드/테스트
• Tools > MCP Unity > Server Window에서 설정
• Window > General > Test Runner에서 EditMode 테스트

주요 디렉토리

Editor/                       # Unity Editor 패키지 (C#)
├── Tools/                    # MCP 도구 (McpToolBase 상속)
├── Resources/                # MCP 리소스 (McpResourceBase 상속)
├── Services/                 # TestRunnerService, ConsoleLogsService
├── UnityBridge/              # WebSocket 서버 + 메시지 라우팅
│   ├── McpUnityServer.cs     # 서버 생명주기를 관리하는 싱글톤
│   └── McpUnitySocketHandler.cs  # WebSocket 핸들러
└── Utils/                    # 로깅, 설정, 워크스페이스 헬퍼

Server~/                      # Node.js MCP 서버 (TypeScript/ESM)
├── src/index.ts              # 진입점 - 도구/리소스 등록
├── src/tools/                # MCP 도구 정의 (zod + 핸들러)
├── src/resources/            # MCP 리소스 정의
└── src/unity/mcpUnity.ts     # Unity에 연결하는 WebSocket 클라이언트

주요 불변 사항

• WebSocket 엔드포인트: ws://localhost:8090/McpUnity (설정 가능)
• 설정 파일: ProjectSettings/McpUnitySettings.json
• 도구/리소스 이름은 Node와 Unity 간 정확히 일치해야 합니다 (lower_snake_case 사용)
• 실행 스레드: 모든 도구 실행은 EditorCoroutineUtility를 통해 Unity 메인 스레드에서 실행

새 도구 추가