soft-ue-cli (+mcp)

Python 3.10+

License: MIT

AI agents

skills

commands

MCP

AI built for coding agents

GitHub Sponsors

Ko-fi

단독 개발자가 구축하고 유지 관리합니다. 이 프로젝트가 시간을 절약해 주었다면 지원하기를 부탁드립니다.

AI 에이전트나 터미널에서 Unreal Engine 5 제어. soft-ue-cli는 MCP 서버 또는 CLI를 통해 모든 LLM에게 액터 생성, 블루프린트 편집, 머티리얼 및 MetaSounds 검사, UMG 화면 구축, UE 설정 파일 읽기 및 패치, Play-In-Editor 세션 실행, 토큰 효율적인 스크린샷 캡처, 성능 프로파일링, 로컬 Unreal 에셋 검사 등 120개 이상의 명령어와 도구를 제공합니다.

두 가지 연결 경로. 하나의 패키지. Unreal이 실행 중일 때는 브릿지 도구(Bridge tools)를, 실행 중이지 않을 때는 오프라인 도구를 제공하며, 어떤 명령군이 지원되는지, 어떤 런타임/에디터 요구 사항이 적용되는지, 그리고 어떤 선택적 Unreal 플러그인이 필요한지를 알려주는 명령어 카탈로그를 갖추고 있습니다.

LLM 클라이언트 / 셸 / CI
    |
    v
...

soft-ue-cli가 필요한 이유?

• MCP 서버 + CLI 통합 패키지: Claude Desktop, Cursor, Windsurf 및 기타 MCP 클라이언트용 MCP 서버(mcp-serve)로 사용하거나, Claude Code, 셸 스크립트 및 CI/CD를 위한 표준 CLI로 사용할 수 있습니다. 어느 쪽이든 120개 이상의 도구 표면을 제공합니다.

• AI 네이티브 UE 자동화: LLM 에이전트가 사람이 에디터를 만지지 않고도 언리얼 엔진(Unreal Engine) 프로젝트를 읽고, 수정하고, 테스트할 수 있도록 목적에 맞게 설계되었습니다.

• 서로를 인식하는 에이전트: 여러 세션이 하나의 에디터를 구동할 때, session 패밀리는 브릿지 트래픽에서 파생된 공유 명단을 제공하여, 한 에이전트가 다른 에이전트의 PIE 테스트를 위해 에디터 재구축을 중단시키는 것을 방지합니다. 참고용 정보만 제공하며, 절대 차단하지는 않습니다.

• 120개 이상의 명령어 및 도구: 액터(actors), 블루프린트(Blueprints), 머티리얼(materials), MetaSounds, StateTrees, Mutable/CustomizableObject, 위젯(widgets), 에셋(assets), 설정 파일(config files), PIE 세션, 프로파일링, 스크린샷 및 로컬 언리얼 파일 분석을 포괄합니다.

• 명령어 패밀리, 개별 이름 아님: UMG, 캡처(capture), Mutable, StateTree, MetaSound, 애니메이션(animation), 에셋(asset), 블루프린트(blueprint) 워크플로우가 각각 umg, capture, mutable, statetree, metasound, anim, asset, blueprint 아래에 그룹화되어 있습니다.

• 플러그인 인식 메타데이터: soft-ue-cli commands --json은 브릿지/에디터/PIE 요구 사항과 선택적 언리얼 플러그인 종속성을 보고하며, 브릿지 도구는 플러그인이 누락된 경우 구조화된 plugin_unavailable 오류를 반환합니다.

• 토큰 인식 시각 피드백: 뷰포트 및 스크린샷 캡처가 배율(scale), 너비 또는 높이에 따라 출력을 크기 조정할 수 있으며, 낮은 LLM 토큰 비용을 위해 색상, 그레이스케일 또는 모노크롬 이미지를 방출할 수 있습니다.

• 온라인 + 오프라인 워크플로우: 언리얼이 열려 있을 때는 브릿지 기반 UE 변형 및 런타임 검사가 가능하고, 그렇지 않을 때는 직접적인 로컬 검사, 비교(diff), 설정 도구 사용이 가능합니다.

• 설정 인식 워크플로우: 하나의 config 명령어 그룹에서 계층 구조 검사, 오버라이드 추적, 레이어 비교, 그리고 .ini, BuildConfiguration.xml, .uproject 데이터 패치가 가능합니다.

• UMG 작성 루프 (authoring loop) -- 편집 가능한 Widget Blueprint 트리 초안을 만들고, 네비게이션 계약(navigation contracts)을 연결하며, PIE 상호작용 검사를 실행하고, 디자이너/런타임 레이아웃 아티팩트를 비교합니다.

• LLM 스킬 프롬프트 (skill prompts) -- 마크다운 워크플로우(예: Blueprint-to-C++ 변환)가 MCP 프롬프트 또는 CLI 명령으로 노출된 상태로 제공됩니다.

• UE가 실행되는 모든 곳에서 작동 -- 에디터, 구워진 빌드(cooked builds), Windows, macOS, Linux를 지원합니다.

• 작은 종속성 크기 (small dependency footprint) -- httpx와 Pillow만 필요합니다. MCP 서버 모드를 사용하려면 [mcp]를 추가하세요.

• 팀 친화적 -- SOFT_UE_BRIDGE 환경 변수를 통한 조건부 컴파일 덕분에 브릿지가 필요한 개발자에게만 코드가 컴파일됩니다.

현재 방향 (Current Direction)

최근 릴리스에서는 soft-ue-cli를 일회성 브릿지 호출의 단순 목록에서 에이전트를 위한 발견 가능한 자동화 표면(discoverable automation surface)으로 이동시켰습니다:

• commands가 명령어 상태, 대체 이름, 런타임 요구 사항, 선택적 플러그인 요구 사항 및 예시에 대한 진실 공급원(source of truth)입니다.
• 표준 계열(canonical families) (umg, capture, mutable, statetree, metasound, anim, asset, blueprint)이 지원되는 공개 명령어 표면입니다.
• UMG 및 스크린샷 워크플로우는 이제 전체 에이전트 루프를 지원합니다: 작성(author), 검사(inspect), PIE 실행, 시각적 증거 캡처, 레이아웃 비교, 그리고 이미지 페이로드 크기 유지.
• 선택적 플러그인 워크플로우는 해당 플러그인이 설치되지 않은 상태에서도 깨끗하게 컴파일될 것으로 예상되며, 런타임에 실행 가능한 plugin_unavailable 진단으로 실패합니다.
• CLI/Python/브릿지 탐색은 탐색 계층(exploration layer)으로 간주되며, 지속적인 게임플레이 회귀(durable gameplay regressions)는 프로젝트 네이티브 C++ 자동화 사양(Automation Specs)으로 이동해야 합니다.

릴리스 하이라이트: 1.45.0 (Release highlights: 1.45.0)

• 레거시 cloth apply-weightmap은 활성 Chaos 의상 런타임(active Chaos clothing runtime)에서 노출하는 모든 웨이트맵 대상(weight-map target), 즉 테더(tether), 드래그/리프트(drag/lift), 강성(stiffness), 압력(pressure), 평탄도(flatness) 대상을 수락합니다. 병합된 의상 에셋의 경우, --section-index를 반복하거나 쉼표로 구분된 인덱스를 전달하여 해당 소스 섹션만 업데이트할 수 있습니다. 선택되지 않은 웨이트는 보존됩니다.

  soft-ue-cli cloth apply-weightmap /Game/Characters/SK_Cape --asset-name CapeCloth \
    --target edge-stiffness --rule constant --value 0.75 \
    --section-index 1,3 --section-index 5 --save

• AnimGraph의 blueprint node property 및 blueprint node add에서 발생하는 property-path 실패는 이제 노드 클래스, 검색된 내부 구조체(inner struct), 해결되지 않은 필드(unresolved field), 사용 가능한 필드(available fields), 그리고 설정 가능한 핀(settable pins)을 식별합니다. 유효하지 않은 배열 인덱스는 집중적인 오류와 함께 거부됩니다.

• cloth query는 기존 응답 필드를 유지하며, 가져온 섹션 의상 메타데이터가 잘못되었거나 지원되지 않을 경우 binding_warnings 및 binding_warning_count를 추가합니다.

• find-references node는 Find in Blueprints가 여전히 인덱싱 중이거나 캐시 항목에 실패한 경우, 그리고 완전한 폴백 순회(fallback traversal)가 불가능할 때 불완전할 수 있는 결과를 거부합니다. 의도적인 --limit 절단은 유효하게 유지됩니다.

• 다중 클라이언트 PIE 상태는 pie-session get-state를 통해 확인할 수 있으며, 이 명령어는 첫 번째 월드의 레거시 최상위 수준 필드를 유지하면서 worlds와 world_count를 추가합니다. 콘솔 명령을 실행할 때 대상이 되는 하나의 PIE 클라이언트와 그 로컬 플레이어 하나를 명시적으로 지정해야 합니다:

  복사

  soft-ue-cli pie-session get-state
  soft-ue-cli exec-console-command --pie-instance 1 --player-index 0 stat net
  

  1

  2

  3

UE 5.8 MCP 포지셔닝

필요한 워크플로우에 대해 네이티브 실행을 지원하는 경우, UE 5.8 공식 MCP를 사용하는 것이 좋습니다.

UE 5.8은 퍼스트파티 언리얼 MCP 지원 기능을 추가하고 있습니다. Epic에서 관리하는 UE 5.8 네이티브 MCP 엔드포인트를 원하며 이미 필요한 워크플로우를 커버한다면 이를 사용하십시오.

soft-ue-cli의 주요 개발 목표는 이제 Unreal Engine 5.8입니다. UE 5.7 호환성은 여전히 유지되므로, 릴리스 노트에 명시적으로 달리 언급되지 않는 한 수정 사항 및 브릿지 코드는 계속해서 UE 5.7에서 컴파일되고 실행되어야 합니다.

soft-ue-cli는 퍼스트파티 MCP를 대체하기보다는 의도적으로 다른 계층(layer)으로 설계되었습니다.

• 일반 터미널 CLI와 MCP 서버 역할을 모두 수행하므로, Claude Code, 셸 스크립트, CI 또는 모든 MCP 클라이언트에서 동일한 자동화가 실행될 수 있습니다.
• 에디터가 닫혀 있는 경우에도 .uasset, .uexp, .ini, .uproject, .uplugin, BuildConfiguration.xml 파일에 대한 오프라인 명령을 포함합니다.
• 단순한 에디터 작업뿐만 아니라 반복 가능한 에이전트 실행을 위해 선별된 LLM 스킬 프롬프트와 test-tools 스모크 워크플로우를 제공합니다.
• 오늘날 UE 5.7을 지원하며, 일반 터미널 CLI와 MCP 서버를 동일한 패키지에서 노출하는 동시에 Development/DebugGame 빌드된 Cooked 빌드에서도 실행됩니다.
• 런타임 브릿지 지원 및 향후 바이너리 설치/업데이트 워크플로우는 UE-5.8-MCP의 주요 차별화 요소로 간주되며, 특히 패키징된 Development/DebugGame 빌드와 CI 자동화를 위한 것입니다.
• 에이전트가 추측할 필요 없이 올바른 워크플로우를 선택할 수 있도록 명령 요구 사항과 선택적 플러그인 종속성을 구조화된 메타데이터로 보고합니다.
• 에이전트가 추측하는 대신 복구할 수 있도록 선택적 플러그인 요구 사항 및 누락된 플러그인 실패를 구조화된 JSON으로 보고합니다.

두 가지는 공존할 수 있습니다. 적합한 경우 네이티브 UE 5.8 에디터 커버리지를 위해 UE의 퍼스트파티 MCP를 사용하고, soft-ue-cli는 UE 5.7 프로젝트, Cooked Development/DebugGame 빌드, CLI/CI 자동화, 오프라인 검사, 선별된 워크플로우, 시각적 캡처 변환(visual capture transforms), 선택적 플러그인 진단, 그리고 엔진 릴리스와 독립적으로 이동하는 브릿지 도구에 사용합니다.

프로젝트 작업 공간 내에서 soft-ue-cli mcp-surface-status를 실행하여 로컬 UE 5.8 공식 MCP 엔드포인트와 SoftUEBridge 상태 엔드포인트를 프로빙할 수 있습니다. 이는 에디터 변형(editor mutations)을 실행하지 않고도 official-only, bridge-only, both, 또는 neither 중 하나, 그리고 권장 사항을 보고합니다.

Private soft-ue-expert Pro 배포판은 이 공개 패키지와 별개입니다. Expert Pack은 로컬 소유자 운영을 통해 스킬, 사례(cases), 규칙, 에이전트 및 검증 기능을 제공하며, 호스팅되는 Pro는 보류됩니다.

Quick Start

1. Install

pip install soft-ue-cli # CLI 전용
pip install soft-ue-cli[mcp] # CLI + MCP 서버

### 2. 플러그인을 UE 프로젝트에 설치하기

**LLM 클라이언트 내부** (Claude Code, Cursor 등)에서 설정 명령을 실행합니다. 이 명령어는 AI 에이전트가 플러그인을 복사하고 `.uproject` 파일을 편집하며 자체적으로 구성하는 단계별 지침을 출력합니다:

```bash
soft-ue-cli setup /path/to/YourProject

수동으로 실행하는 경우 (LLM을 통하지 않는 경우), 출력된 지침을 직접 따르세요. 플러그인 디렉토리를 복사하고, .uproject 파일에 "Plugins" 항목을 추가하며, CLAUDE.md 스니펫을 생성해야 합니다.

3. 언리얼 엔진 재빌드 및 실행

프로젝트 파일을 재생성하고 재빌드한 후, 에디터를 실행합니다. 브릿지가 실행 중인지 확인하려면 다음 로그 라인을 찾으세요:

LogSoftUEBridge: Bridge server started on port 8080

4. 연결 확인하기

soft-ue-cli check-setup

모든 검사가 통과된 것을 확인할 수 있어야 합니다:

[OK]   플러그인 파일 발견됨.
[OK]   YourGame.uproject에 SoftUEBridge 활성화됨.
[OK]   브릿지 서버 연결 가능함.

5. (선택 사항) MCP 클라이언트 연결하기

MCP 클라이언트 설정(Claude Desktop, Cursor, Windsurf 등)에 다음 내용을 추가하세요:

{
  "mcpServers": {
    "soft-ue-cli": {
...

이제 AI 에디터는 터미널이 필요 없이 120개 이상의 UE 도구 및 스킬 프롬프트에 직접 접근할 수 있습니다.

작동 방식 (How It Works)

soft-ue-cli 명령어
    |
    +-- Bridge 기반 명령어 ----------------------------------------+
...

SoftUEBridge 플러그인은 언리얼 엔진(UE)이 실행될 때 포트 8080에서 임베디드 HTTP 서버를 시작하는 경량의 C++ UGameInstanceSubsystem입니다. 브릿지 기반 명령어는 이 서버로 JSON-RPC 요청을 보내고, 플러그인이 게임 스레드에서 해당 UE 작업을 실행하며 구조화된 JSON 응답을 반환합니다. 오프라인 명령어는 브릿지를 완전히 우회하고 로컬 파일에 직접 작동합니다.

Automation 명령은 stdout에 구조화된 JSON을 반환합니다 (단, get-logs --raw 제외). 검색 및 지원 명령어는 기본적으로 사람이 읽기 쉬운 출력을 사용하며, 해당되는 경우 --json 옵션을 노출합니다. 종료 코드 0은 성공을 의미하고, 1은 오류를 의미합니다.

Skills 아키텍처

LLM 클라이언트 (Claude Code, Cursor 등)
    |
    |  soft-ue-cli skills get <name>
...

Skills는 cli/soft_ue_cli/skills/*.md에 있는 마크다운 파일이며, pip 배포 패키지 데이터로 포함됩니다. 각 skill은 독립적입니다: 워크플로우 지침, 참조 테이블, 예시 CLI 명령어, 그리고 검증 테스트 케이스를 포함합니다. CLI는 skills list / skills get을 통해 이를 검색합니다. MCP 서버로 실행될 때는 동일한 파일들이 prompts/list 및 prompts/get 프로토콜을 통해 노출됩니다.

테스트 워크플로우

soft-ue-cli를 사용하여 게임플레이 버그를 빠르게 탐색하고 디버깅한 다음, 최종 회귀(regression)는 프로젝트의 C++ Automation Spec 스위트로 옮깁니다.