geuneda-mcp-unity: Instructions file for Codex

MCP Unity — AI 에이전트 가이드 (MCP 패키지)

목적 (이 저장소가 하는 일)

MCP Unity는 MCP 지원 클라이언트에 Unity Editor 기능을 노출합니다. 다음을 실행하여 동작합니다:

• Unity 측 "클라이언트" (C# Editor 스크립트): Unity Editor 내부에서 도구/리소스를 실행하는 WebSocket 서버.
• Node 측 "서버" (TypeScript): MCP 도구/리소스를 등록하고 WebSocket을 통해 Unity로 요청을 전달하는 MCP stdio 서버.

동작 방식 (상위 수준 데이터 흐름)

• MCP 클라이언트 ⇄ (stdio / MCP SDK) ⇄ Node 서버 (Server~/src/index.ts)
• Node 서버 ⇄ (WebSocket JSON-RPC 유사) ⇄ Unity Editor (Editor/UnityBridge/McpUnityServer.cs + McpUnitySocketHandler.cs)
• 도구/리소스 이름은 Node와 Unity에서 정확히 일치해야 합니다 (일반적으로 lower_snake_case).

기본값 및 불변 사항

• Unity WebSocket 엔드포인트: 기본값 ws://localhost:8090/McpUnity.
• 설정 파일: ProjectSettings/McpUnitySettings.json (Unity에서 작성/읽기; Node에서 기회적으로 읽기).
• 실행 스레드: 도구/리소스 실행은 EditorCoroutineUtility를 통해 디스패치되며 Unity 메인 스레드에서 실행됩니다. 동기 작업은 짧게 유지하세요; 긴 작업에는 비동기 패턴을 사용하세요.

저장소 레이아웃 (어디에서 무엇을 변경할지)

/
├── Editor/                       # Unity Editor 패키지 코드 (C#)
│   ├── Tools/                    # 도구 (McpToolBase 상속)
│   ├── Resources/                # 리소스 (McpResourceBase 상속)
│   ├── UnityBridge/              # WebSocket 서버 + 메시지 라우팅
│   ├── Services/                 # 도구/리소스에서 사용하는 테스트/로그 서비스
│   └── Utils/                    # 공유 헬퍼 (설정, 로깅, 워크스페이스 통합)
├── Server~/                      # Node MCP 서버 (TypeScript, ESM)
│   ├── src/index.ts              # 도구/리소스/프롬프트를 MCP SDK에 등록
│   ├── src/tools/                # MCP 도구 정의 (zod 스키마 + 핸들러)
│   ├── src/resources/            # MCP 리소스 정의
│   └── src/unity/mcpUnity.ts      # Unity와 통신하는 WebSocket 클라이언트
└── server.json                   # MCP 레지스트리 메타데이터 (이름/버전/패키지)

빠른 시작 (로컬 개발)

• Unity 측

  • 이 패키지가 설치된 Unity 프로젝트를 엽니다.
  • 서버가 실행 중인지 확인합니다 (자동 시작은 McpUnitySettings.AutoStartServer로 제어됩니다).
  • 설정은 ProjectSettings/McpUnitySettings.json에 저장됩니다.

• Node 측 (빌드)

  • cd Server~ && npm run build
  • MCP 진입점은 Server~/build/index.js입니다 (MCP stdio 서버로 게시됨).

• Node 측 (디버그/검사)

  • cd Server~ && npm run inspector로 MCP Inspector를 사용합니다.