YetAnotherUnityMcp

이걸 사용하지 마세요. 이건 제가 클로드 코드로 뭘 할 수 있는지 시험해 보려고 만든 장난감 프로젝트입니다. 개발자가 바이브 코딩만으로 제대로 작업할 수 있는지 평가하려고 하는데, 아직은 아닌 것 같습니다!

AI 에이전트가 Unity를 제어하고 Unity와 상호 작용할 수 있게 해주는 Unity Master Control Protocol(MCP) 구현입니다.

개요

YetAnotherUnityMcp 는 모델 컨텍스트 프로토콜(MCP)을 사용하여 Unity 게임 엔진과 AI 기반 도구를 연결하는 시스템입니다. MCP TCP 서버 역할을 하는 Unity .NET/C# 플러그인 과 AI 에이전트의 요청을 처리하는 Python MCP 클라이언트 (FastMCP 기반)로 구성됩니다. Unity와 클라이언트 간의 통신은 커스텀 TCP 프로토콜을 통해 이루어지며, JSON 메시지와 이미지 데이터의 실시간 양방향 교환이 가능합니다.

이 아키텍처는 게임 엔진과 AI 로직을 명확하게 분리하여 확장성과 유지 관리성을 향상시킵니다. AI 에이전트(예: LLM 기반 어시스턴트)가 실행 중인 Unity 씬을 체계적이고 안전하게 검사하고 제어할 수 있도록 하는 것이 목표입니다. 컨테이너 기반 리소스 및 도구 구성 방식은 코드 구성을 더욱 개선하고 보일러플레이트 코드를 줄입니다.

주요 구성 요소는 다음과 같습니다.

1. Unity MCP 플러그인(서버) – TCP 서버를 호스팅하는 Unity Editor에 통합된 AC# 플러그인
2. FastMCP Python 클라이언트 – Unity용 MCP 인터페이스를 구현하는 Python 애플리케이션
3. MCP 클라이언트(AI 또는 외부) – MCP 요청을 보내는 외부 엔터티(예: AI 어시스턴트 또는 테스트 스크립트)

MCP란 무엇인가요?

모델 컨텍스트 프로토콜(MCP)은 AI 모델이 애플리케이션과 상호 작용하는 표준화된 방식입니다. 컨텍스트 제공과 LLM 상호 작용 자체를 분리하여 다음과 같은 기능을 제공합니다.

• 리소스 : LLM에 데이터 제공(Unity 장면 계층 구조 등)
• 도구 : LLM이 작업(예: Unity에서 코드 실행)을 수행할 수 있도록 허용
• 프롬프트 : 상호작용 템플릿 정의(게임 객체 생성 방법 등)

YetAnotherUnityMcp는 다음을 포함하여 완전한 규정 준수를 보장하는 공식 MCP 사양을 구현합니다.

• 콘텐츠 배열 기반 응답
• URI 기반 리소스 설명자
• 스키마 수준에서 필요한 매개변수 배열
• 리소스에 대한 MIME 유형 사양

특징

• AI 에이전트에서 Unity로 C# 코드 실행
• 동적 매개변수 처리를 통해 MCP 리소스를 통해 Unity Editor 상태 쿼리
• 더 나은 구성을 위해 MCP 리소스와 도구를 논리적 컨테이너에 구성합니다.
• AI 기반 매개변수로 스크린샷 캡처
• 실시간 모니터링 및 증분 검색을 통해 Unity에서 로그 및 디버그 정보를 가져옵니다.
• AI 지원을 통한 GameObject 속성 수정
• GameObject 계층 구조 나열 및 탐색
• MCP 프롬프트를 통해 상황에 맞는 템플릿 제공
• TCP 소켓을 통한 실시간 통신
• Unity에 직접 호스팅된 TCP 서버
• 빠르고 효율적인 JSON 직렬화
• 유형 안전 매개변수 매핑을 통한 동적 리소스 호출
• 도구 및 리소스에 대한 스키마 기반 입력 검증

시작하기

유니티 서버 설정

1. Unity 프로젝트(2020.3 이상)를 엽니다.
2. 다음 방법 중 하나를 사용하여 YetAnotherUnityMcp 플러그인을 가져옵니다.
   • plugin/Scripts 폴더를 Unity 프로젝트의 Assets 디렉토리에 복사합니다.
   • Unity 패키지를 생성하고 가져옵니다.
   • 개발을 위한 심볼릭 링크를 만듭니다(Windows PowerShell 예):지엑스피1
3. TCP 서버를 시작합니다.
   • 메뉴에서: MCP > TCP 서버 > 서버 시작
   • 또는: 창 > MCP 서버 > 서버 시작
4. TCP 서버 주소를 기록해 두세요(기본값: localhost:8080)

Python 클라이언트 설정

MCP 통합

프로젝트 구조

건축학

유니티 TCP 서버

Unity 플러그인은 MCP 클라이언트의 연결을 수신하는 TCP 서버를 호스팅합니다. 이 서버는 다음을 수행합니다.

• 간단한 프레이밍 프로토콜을 사용하여 클라이언트 연결 및 메시지 라우팅을 관리합니다.
• 연결 상태 모니터링을 위해 핸드셰이크 및 핑퐁을 지원합니다.
• 반사 기반 속성 검색을 통해 도구 및 리소스의 동적 레지스트리를 사용합니다.
• 이름으로 리소스 및 도구에 동적으로 액세스하기 위한 호출자를 제공합니다.
• 도구 및 리소스의 컨테이너 기반 구성을 지원합니다.
• 클라이언트가 보낸 명령을 실행합니다(예: C# 코드 실행, 스크린샷 찍기)
• 결과를 클라이언트에게 반환합니다.
• 연결 모니터링 및 디버깅을 위한 UI를 제공합니다.

컨테이너 기반 접근 방식에 대한 자세한 내용은 MCP 컨테이너 문서를 참조하세요.

Python MCP 클라이언트

Python 클라이언트는 Unity TCP 서버에 연결하여 AI 도구에 MCP 인터페이스를 제공합니다. 다음과 같은 기능을 제공합니다.

• MCP 요청을 Unity용 프레임화된 TCP 메시지로 변환합니다.
• 연결 재시도 및 연결 유지 ping을 처리합니다.
• Unity 응답을 MCP 리소스 데이터로 변환합니다.
• 연결 수명 주기를 위해 FastMCP의 수명 관리를 사용합니다.
• 표준화된 오류 처리 및 재연결 논리를 제공합니다.
• 모든 작업에 대해 통합 실행 패턴을 구현합니다.
• FastMCP 프레임워크를 통해 도구와 리소스를 제공합니다.

MCP 리소스 및 도구

자원

• unity://info - Unity 환경에 대한 기본 정보
• unity://logs - 디버깅을 위한 편집기 로그
• unity://scene/{scene_name} - 특정 장면에 대한 정보
• unity://object/{object_id} - 특정 GameObject에 대한 세부 정보

도구

• execute_code_in_unity - Unity Editor에서 C# 코드 실행
• unity_screenshot - Unity Editor의 스크린샷을 찍습니다.
• unity_modify_object - Unity 게임 객체의 속성 변경
• unity_logs - 새 로그만 검색하는 옵션과 함께 Unity에서 로그를 가져옵니다.

통신 프로토콜

Unity 서버와 Python 클라이언트 간의 모든 통신은 간단한 프레이밍 프로토콜을 사용하는 TCP 소켓 연결을 사용하며, 이를 통해 지속적이고 지연 시간이 짧은 양방향 메시징이 가능합니다. 연결은 Python 클라이언트가 Unity 서버의 TCP 엔드포인트(예: localhost:8080 )로 시작합니다.

이 프로토콜은 간단한 프레이밍 메커니즘을 사용합니다.

• 시작 마커(STX, 0x02)
• 4바이트 길이의 접두사
• JSON 메시지 내용
• 종료 마커(ETX, 0x03)

모든 메시지는 최소한 명령 또는 응답 유형 , 고유 ID (요청과 응답을 연결하는 데 사용), 그리고 매개변수 또는 결과 객체를 포함하는 JSON 객체입니다. 연결은 주기적인 핑퐁 메시지로 유지됩니다. 통신 프로토콜에 대한 자세한 내용은 기술 세부 정보 문서를 참조하십시오.

개발

특허

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

아키텍처, 구현 및 확장성에 대한 자세한 내용은 기술 세부 정보 문서를 참조하세요.