HullForge MCP 커넥터

Claude가 실행 중인 Unreal Engine 5 에디터를 구동할 수 있게 해주는 HullForge의 MCP 서버 부분입니다.

MIT 라이선스. 이 저장소는 커넥터만 포함합니다.

이것이 무엇이며, 무엇이 아닌지

HullForge는 두 개의 프로그램으로 구성됩니다.

커넥터에는 Unreal Engine 로직이 전혀 포함되어 있지 않습니다. 전송, 프레이밍, 세션 검색 및 MCP 표면입니다. 단독으로는 유용한 작업을 수행하지 않습니다. 실행 중인 에디터가 없으면 정확히 하나의 도구를 노출하며, 이 도구는 에디터가 실행 중이 아니라고 알려줍니다.

Related MCP server: unreal-engine-mcp

별도 프로세스인 이유

MCP 서버를 C++ 플러그인에 직접 포함시키면 두 개 대신 하나의 프로그램이 되어 더 간단해 보일 수 있습니다. 하지만 그렇지 않습니다.

MCP 표면은 엔진 바인딩보다 훨씬 자주 변경됩니다. 분리하면 프로토콜 계층을 C++ 모듈을 다시 컴파일하고 에디터를 다시 시작하지 않고도 몇 초 만에 다시 빌드할 수 있습니다.

에디터의 게임 스레드는 소중합니다. UObject에 접촉하는 모든 것은 그 스레드에서 실행되어야 하며, 느린 작업은 에디터를 멈추게 합니다. 프로토콜, 프레이밍, 재시도 및 전송을 외부에 유지하면 실제 작업만 해당 스레드로 마샬링됩니다.

충돌 격리. 프로토콜 처리의 오류는 저장되지 않은 작업이 있는 에디터가 아닌 작은 외부 프로세스를 중단시킵니다.

에디터를 찾는 방법

아무것도 구성되지 않습니다. 각 실행 중인 에디터는 사용자 전역 레지스트리에서 자신을 알립니다:

%LOCALAPPDATA%/HullForge/sessions/<project>-<pid>.json

각 항목은 포트, 세션별 토큰, 프로젝트 이름 및 경로, 프로세스 ID를 보유합니다. 커넥터는 해당 디렉터리를 스캔하고 프로세스가 실제로 살아 있는지 필터링하며, 이미 연결된 에디터를 선호하여 두 번째 에디터가 열릴 때 대화 중에 조용히 대상이 변경되지 않도록 합니다.

MCP listChanged 기능을 선언하고 해당 레지스트리를 감시하여 에디터가 열리면 도구가 나타나고 닫히면 사라지며, 클라이언트를 다시 시작할 필요가 없습니다. 이는 MCP 서버가 클라이언트에 의해 시작되기 때문에 중요합니다. 에디터보다 먼저 시작된 커넥터는 그렇지 않으면 영원히 빈 도구 목록을 보고하게 됩니다. 클라이언트가 다시 요청할 이유가 없기 때문입니다.

하나의 도구인 hf_bridge_status는 에디터가 아닌 여기에서 구현됩니다. 따라서 항상 사용 가능하므로 '도구 없음'이 조용한 상태가 되는 일은 없습니다.

신뢰성

여기에 있는 두 가지는 대안이 작업을 잃어버리기 때문에 존재합니다.

멱등성. 모든 변경 호출에는 operation_id가 포함됩니다. 커넥터는 호출당 하나를 생성하고 전송 재시도 시 재사용하므로, 연결이 끊어져도 동일한 변경이 두 번 적용되지 않습니다. 에디터는 반복된 ID를 인식하고 원래 결과를 반환합니다.

정직한 실패 상태. 확실히 실패한 호출과 결과를 알 수 없는 호출은 다른 답변으로, 다르게 보고됩니다. '알 수 없음'은 아무 일도 일어나지 않았다는 것이 아니라 커넥터가 대기를 중단했음을 의미하며, 호출자는 재시도 전에 확인하라는 메시지를 받습니다.

개발

Python 3.13 및 uv가 필요합니다.

uv sync
uv run pytest                       # unit tests, no editor needed
uv run pytest -m integration        # needs a running editor with the plugin

배포 가능한 바이너리 빌드:

.\Build-Sidecar.ps1                 # Nuitka, for release
.\Build-Sidecar.ps1 -Fast           # PyInstaller, local iteration only

Build-Sidecar.ps1은 릴리스 빌드가 PyInstaller 대신 Nuitka를 사용하는 이유를 설명하고, 결과를 가정하지 않고 모든 빌드 후에 누수 감사를 다시 실행합니다.

설치

대부분의 사람들은 이것을 빌드할 필요가 없습니다. 컴파일된 바이너리가 포함되어 있고 Python이 필요 없는 패키지된 .mcpb 번들을 설치하세요.

Claude Desktop에서: 설정 > 확장 프로그램 > 고급 설정 > 확장 프로그램 개발자 > 확장 프로그램 설치...

.mcpb 파일을 더블 클릭하는 것도 OS에 연결이 등록된 경우 작동하지만, 위의 메뉴는 모든 곳에서 안정적입니다.

전체 지침: jigwright.com/hullforge/docs

개인정보 보호

커넥터는 아무것도 수집하지 않고, 전송하지 않으며, 서버에 접촉하지 않습니다. 모든 통신은 루프백을 통해 이루어집니다. 전체 정책: jigwright.com/privacy.

지원

• 문서: https://jigwright.com/hullforge/docs

• 이 저장소의 이슈 (커넥터 관련)

• 에디터 플러그인 관련 문의는 이메일 support@jigwright.com

라이선스

MIT, LICENSE 참조. 이는 이 저장소의 커넥터에만 적용됩니다. HullForge 에디터 플러그인은 자체 조건에 따른 별도의 독점 제품입니다.