🚀 고급 Unity MCP 통합

이 패키지는 모델 컨텍스트 프로토콜(MCP) 과 Unity 에디터 간의 완벽한 통합을 제공하여 AI 어시스턴트가 Unity 프로젝트를 실시간으로 이해하고 상호작용할 수 있도록 지원합니다. 이러한 통합을 통해 AI 어시스턴트는 씬 계층 구조, 프로젝트 설정에 대한 정보에 접근하고 Unity 에디터 컨텍스트에서 직접 코드를 실행할 수 있습니다.

📚 특징

• 프로젝트 파일을 직접 탐색하고 조작하세요
• Unity 프로젝트에 대한 실시간 정보에 액세스하세요
• 장면 계층 구조와 게임 객체를 이해하세요
• Unity Editor에서 직접 C# 코드 실행
• 로그 및 오류 모니터링
• 편집기의 재생 모드를 제어합니다
• 코드 실행을 기다리세요

🚀 시작하기

필수 조건

• Unity 2021.3 이상
• Node.js 18+(MCP 서버 실행용)

설치

1. Unity 패키지 설치

Unity 패키지를 설치하는 데에는 여러 가지 옵션이 있습니다.

옵션 A: 패키지 관리자(Git URL)

1. Unity 패키지 관리자를 엽니다( Window > Package Manager )
2. + 버튼을 클릭하고 Add package from git URL... 선택합니다.
3. 저장소 URL을 입력하세요: https://github.com/quazaai/UnityMCPIntegration.git
4. Add 클릭하세요

옵션 B: 사용자 정의 패키지 가져오기

1. 이 저장소를 복제하거나 unityPackage로 다운로드하세요.
2. Unity에서 Assets > Import Package > Custom Package 로 이동합니다.
3. UnityMCPIntegration.unitypackage 파일을 선택하세요

2. MCP 서버 설정

MCP 서버를 실행하는 데는 두 가지 옵션이 있습니다.

옵션 A: 서버를 직접 실행

1. mcpServer (likely <path-to-project>\Library\PackageCache\com.quaza.unitymcp@d2b8f1260bca\mcpServer\) 디렉토리로 이동합니다.
2. 종속성 설치:지엑스피1
3. 서버를 실행합니다:
   node build/index.js

옵션 B: MCP 호스트 구성에 추가

Claude Desktop, 사용자 정의 구현 등을 위해 MCP 호스트 구성에 서버를 추가합니다.

데모 비디오

Smithery를 통해 설치

Smithery 를 통해 Claude Desktop용 Unity MCP 통합을 자동으로 설치하려면:

🔧 사용법

디버깅 및 모니터링

Unity에서 MCP 디버그 창을 열어 연결을 모니터링하고 기능을 테스트할 수 있습니다.

1. Window > MCP Debug 로 이동
2. 디버그 창을 사용하여 다음을 수행할 수 있습니다.
   • 연결 상태 확인
   • 테스트 코드 실행
   • 로그 보기
   • 이벤트 모니터링

사용 가능한 도구

Unity MCP 통합은 AI 어시스턴트에 다양한 도구를 제공합니다.

유니티 에디터 도구

• get_editor_state : Unity 프로젝트 및 편집기 상태에 대한 포괄적인 정보를 가져옵니다.
• get_current_scene_info : 현재 장면에 대한 자세한 정보를 가져옵니다.
• get_game_objects_info : 장면의 특정 게임 객체에 대한 정보를 가져옵니다.
• execute_editor_command : Unity Editor에서 C# 코드를 직접 실행합니다.
• get_logs : Unity 콘솔 로그 검색 및 필터링
• verify_connection : Unity Editor에 활성 연결이 있는지 확인합니다.

파일 시스템 도구

• read_file : Unity 프로젝트의 파일 내용을 읽습니다.
• read_multiple_files : 여러 파일을 한 번에 읽습니다.
• write_file : 새 콘텐츠로 파일을 생성하거나 덮어씁니다.
• edit_file : diff 미리보기로 기존 파일에 대한 타겟 편집을 수행합니다.
• list_directory : 디렉토리에 있는 파일과 폴더 목록을 가져옵니다.
• directory_tree : 디렉토리와 파일의 계층적 보기를 얻습니다.
• search_files : 검색 패턴과 일치하는 파일 찾기
• get_file_info : 특정 파일이나 디렉토리에 대한 메타데이터를 가져옵니다.
• find_assets_by_type : 특정 유형의 모든 자산 찾기(예: Material, Prefab)
• list_scripts : 프로젝트의 모든 C# 스크립트 목록을 가져옵니다.

파일 경로는 Unity 프로젝트의 Assets 폴더를 기준으로 절대 경로 또는 상대 경로일 수 있습니다. 예를 들어 "Scenes/MyScene.unity" 는 <project>/Assets/Scenes/MyScene.unity 를 나타냅니다.

🛠️ 건축

통합은 두 가지 주요 구성 요소로 구성됩니다.

1. Unity 플러그인(C#) : Unity Editor에 상주하며 Editor API에 대한 액세스를 제공합니다.
2. MCP 서버(TypeScript/Node.js) : MCP 프로토콜을 구현하고 Unity 플러그인과 통신합니다.

두 서버 간의 통신은 WebSocket을 통해 이루어지며, 명령과 데이터에 대한 JSON 메시지를 전송합니다.

파일 시스템 액세스

Unity MCP 통합에는 이제 AI 어시스턴트가 다음을 수행할 수 있는 강력한 파일 시스템 도구가 포함되었습니다.

• Unity 프로젝트에서 파일을 탐색, 읽기 및 편집합니다.
• 새 파일 및 디렉토리 만들기
• 특정 파일 또는 자산 유형 검색
• 프로젝트 구조 분석
• diff 미리보기로 타겟 코드 변경하기

보안을 위해 모든 파일 작업은 Unity 프로젝트 디렉터리로 제한됩니다. 시스템은 절대 경로와 상대 경로를 모두 지능적으로 처리하며, 편의를 위해 항상 프로젝트의 에셋 폴더를 기준으로 경로를 확인합니다.

사용 예:

• 디렉토리 목록 가져오기: list_directory(path: "Scenes")
• 스크립트 파일 읽기: read_file(path: "Scripts/Player.cs")
• 구성 파일 편집: edit_file(path: "Resources/config.json", edits: [{oldText: "value: 10", newText: "value: 20"}], dryRun: true)
• 모든 재료 찾기: find_assets_by_type(assetType: "Material")

👥 기여하기

참여를 환영합니다! 참여 방법은 다음과 같습니다.

1. 저장소를 포크하세요
2. 기능 브랜치를 생성합니다( git checkout -b feature/amazing-feature )
3. 변경 사항을 만드세요
4. 변경 사항을 커밋하세요( git commit -m 'Add some amazing feature' )
5. 브랜치에 푸시( git push origin feature/amazing-feature )
6. 풀 리퀘스트 열기

개발 설정

유니티 측 :

• Unity에서 프로젝트를 엽니다
• UnityMCPConnection/Editor 디렉토리의 C# 스크립트를 수정합니다.

서버 측 :

• mcpServer 디렉토리로 이동합니다.
• 종속성 설치: npm install
• src 디렉토리의 TypeScript 파일을 변경합니다.
• 서버 빌드: npm run build
• 서버를 실행합니다: node build/index.js

📄 라이센스

이 프로젝트는 MIT 라이선스에 따라 라이선스가 부여되었습니다. 자세한 내용은 라이선스 파일을 참조하세요.

📞 지원

문제가 발생하거나 질문이 있는 경우 GitHub 저장소에 문제를 제출하세요.