unreal_mcp

Unreal Engine MCP Server는 네이티브 C++ Automation Bridge 플러그인을 통해 AI 어시스턴트가 Unreal Engine 5를 작동할 수 있게 해주는 Model Context Protocol 서버입니다. TypeScript와 C++로 작성되었으며, npm에 unreal-engine-mcp-server로 게시되었고 MIT 라이선스로 배포됩니다. 기능은 영역별로 그룹화됩니다: 자산 관리(탐색, 가져오기, 복제, 이름 변경, 삭제, 머티리얼 생성), 액터 제어(스폰, 삭제, 변형, 물리, 태그, 컴포넌트), 에디터 제어(PIE 세션, 카메라, 뷰포트, 스크린샷, 북마크), 레벨 관리(로드/저장, 스트리밍, 라이팅), 애니메이션 및 물리(애니메이션 블루프린트, 상태 머신, 래그돌, 차량, 제약 조건), 시각 효과(Niagara 파티클, GPU 시뮬레이션, 디버그 셰이프), 시퀀서(시네마틱, 타임라인 제어, Movie Render Queue, 미디어, Take Recorder, 리플레이), 그래프 편집(블루프린트, Niagara, 머티리얼, 비헤이비어 트리), 오디오(사운드 큐, 컴포넌트, 믹스, 앰비언트 사운드) 및 시스템 작업(콘솔 명령, UBT, 테스트, 로그, 프로젝트 설정, CVars). 두 가지 전송 방식이 제공됩니다. 네이티브 MCP 전송은 플러그인에 내장된 Streamable HTTP/SSE 서버로, http://localhost:3000/mcp에서 접근 가능하며 Node.js, npm 또는 브리지가 필요 없습니다. TypeScript 브리지는 WebSocket을 통해 플러그인과 통신하는 stdio 서버입니다. 둘 다 동일한 단일 unreal 게이트웨이 도구를 노출하며, 네 가지 작업(검색, 설명, 실행, 구성)을 제공합니다. 23개의 표준 상위 도구는 내부용이며 게이트웨이를 통해서만 접근할 수 있습니다. 표준 이름에 대한 직접 호출은 제안된 다음 호출과 함께 마이그레이션 영수증을 반환합니다. 프로토콜 버전 협상은 두 표면 간에 다르며, 네이티브 전송은 최신 버전만 지원합니다. 설정에는 TypeScript 브리지용 Node.js 20.19 이상이 필요하며, McpAutomationBridge 플러그인은 프로젝트의 Plugins 폴더에 복사하거나 외부 플러그인 디렉터리를 추가하거나 특정 엔진 버전에 연결된 사전 빌드 바이너리를 사용하여 설치할 수 있습니다. 소스 설치에는 코드 타깃이 필요하며, 블루프린트 전용 프로젝트는 먼저 C++ 클래스를 추가해야 합니다. 여러 핵심 플러그인(Python Editor Script Plugin, Editor Scripting Utilities, Niagara, Gameplay Abilities, Smart Objects)이 필요하며, 많은 선택적 플러그인은 필요 시 자동으로 활성화됩니다. 엔진 버전 5.0~5.8이 지원되는 것으로 명시되어 있습니다. 구성은 UE_PROJECT_PATH, MCP_AUTOMATION_HOST, MCP_AUTOMATION_PORT, 타임아웃, 로그 수준 및 추가 콘텐츠 경로 접두사와 같은 환경 변수를 사용합니다. LAN 액세스는 기본적으로 꺼져 있으며 보안 경고와 함께 명시적으로 활성화해야 합니다. 기능 토큰 인증은 기본적으로 켜져 있으며, 자동 생성된 비밀 파일 또는 수동 구성 토큰을 사용합니다. 기타 언급된 동작에는 동적 타입 발견, 활성 Unreal 연결 없이도 정상 시작, 지수 백오프를 사용한 핸드셰이크 재시도, 위험한 콘솔 명령 차단, 10초 자산 캐시, Prometheus 메트릭 엔드포인트의 IP별 속도 제한이 포함됩니다. Dockerfile이 포함되어 있으며, 저장소에는 빌드, 린트, 타입 검사, 단위 테스트, 스모크 테스트, 매니페스트 드리프트 검사, 네이티브 패리티 테스트, 매개변수 감사 및 버전 검사를 위한 개발 스크립트와 CI 게이트 및 게이트웨이 매니페스트 생성 스크립트가 문서화되어 있습니다. 문서는 작업 참조, 플러그인 확장 아키텍처, 테스트 및 로드맵을 다룹니다.