ue5rc-mcp 0.2.0

UE5RC-MCP: MCP server bridging Claude Code / Cursor / Windsurf to Unreal Engine 5 Remote Control and custom editor plugin. 149 tools, BPDSL pipeline, PredictiveGuard, Vision Loop, auto-repair.

UE5RC-MCP

Unreal Engine 5 Remote Control MCP — AI 어시스턴트(Claude Code · Cursor · Windsurf · VS Code Copilot) 가 UE 5.7 에디터를 직접 제어하게 해 주는 MCP 서버.

• Handbook: ue-project/docs/handbook/ue5rcmcp.md
• Tool API: ue-project/docs/references/ue5rcmcp-api.md
• Design: ue-project/docs/02-design/features/WP-M1.design.md
• Status: v0.1.0 · MVP 완료 (S1–S13) · 39 tool · pytest 92/92 · FAutomationTest 20/20

---

1. 한 줄 소개

기존 Phase 3 Remote Control 은 HTTP 는 되지만 MCP 표준이 아니어서 Claude Code 가 tool 을 자동 디스커버리 못했습니다. UE5RC-MCP 는 그 사이에 서서,

• 외부에는 MCP 표준 (stdio / HTTP / SSE) 을 노출하고
• UE 에디터 쪽에는 (a) 커스텀 C++ 플러그인 HTTP (b) 대용량 File 채널 (c) execute_python fallback 으로 연결해

Yarn Spinner 마이그레이션과 실제 UE5 게임 개발 양쪽에서 AI 가 편집기를 안전하게 (FScopedTransaction Undo 래핑) 조작하게 합니다.

2. 설치

cd E:/works/yarn/ue5rc-mcp
pip install -e ".[dev]"          # Python 3.10+

C++ 플러그인 (UE5RCMCP) 은 ue-project/Plugins/UE5RCMCP/ 에 포함. SP 프로젝트로 복사 후 BuildSPEditor.bat 실행.

3. Claude Code 연결

claude mcp add ue5rc -- python -m ue5rc_mcp
claude mcp list-tools ue5rc       # 39 tool 확인

Cursor / Windsurf 는 각 앱 MCP 설정에 동일 command 등록.

4. 제공 Tool (요약)

카테고리	개수	대표
meta	3	mcp_health, mcp_info, execute_python
reflection	3	reflection_class_info, reflection_search
yarn	5	yarn_import_project, yarn_validate_nfc, yarn_run_automation
editor	3	editor_console, editor_pie_start/stop
actor	3	actor_spawn_static_mesh, actor_delete, actor_set_transform
blueprint	3	blueprint_create_class, blueprint_compile
asset/level/material/animation/ui	11	asset_list/rename/move, level_open/save, material_set_*_param …
niagara/sequencer/landscape/gas	4	(대부분 Stub, M2)
wizards (Yarn 고수준)	5	wizard_yarn_cook_demo, wizard_yarn_upgrade_all
합계	39

전체 목록: docs/references/ue5rcmcp-api.md.

5. 환경변수 (요약)

Var	기본	용도
UE5RC_TRANSPORT	stdio	stdio / http / sse
UE5RC_READ_ONLY	false	Plan SC-5 — mutating tool 차단
UE5RC_UE_PLUGIN_PORT	30020	C++ 플러그인 포트
UE5RC_HISTORY_DB_PATH	~/.ue5rc-mcp/history.sqlite	감사 DB
UE5RC_EMBEDDING_PROVIDER	noop	hash/openai/voyage (M2)

전체: Handbook §3.

6. 테스트

pytest                          # 92/92, ~3s (Ubuntu × Python 3.12/3.13 CI)

UE Automation (C++ 20 테스트):

pwsh scripts/ue-automation-headless.ps1 `
  -ProjectPath "E:/z/uesp/Unreal/SP/SP.uproject" `
  -TestFilter  "UE5RCMCP"

GitHub Actions:

• .github/workflows/python-tests.yml — pytest + ruff (hosted)
• .github/workflows/ue-build.yml — self-hosted Windows + UE5.7 (스텁)

7. 진행 상태

세션	내용	상태
S1	Python 패키지 골격	✅
S2	C++ 플러그인 뼈대	✅
S3	TransactionScope + GameThreadDispatcher	✅
S4	HTTP 브릿지 (30020/rpc)	✅
S5	File 채널 (대용량)	✅
S6	Reflection 덤프 + SpecValidator	✅
S7	CommandHistoryStore (sqlite-vec)	✅
S8	Tool Catalog 34	✅
S9	Yarn Wizard 5	✅
S10	Slate Chat Panel	✅
S11	read-only + history 자동 기록	✅
S12	FAutomationTest 20 + pytest CI	✅
S13	핸드북 + API 레퍼런스	✅
M2 S14	t1-infra (extras · session_id · 5 서브모듈 스켈레톤)	✅

M2 전체 계획 (~40 세션, 700-900h) 은 docs/01-plan/features/WP-M2.plan.md · Design 참조.

8. 라이선스 · 감사

MIT · Copyright I2:Highwind & Project SP.

차용 코드는 각 함수 상단에 # Source: <repo>/<file>@<commit> (<license>) 주석으로 출처 표기.

9. 기여

• ue-project/AGENTS.md 의 Classist TDD 규칙 준수.
• 새 tool 추가 시 Design §5 + API 레퍼런스 §19 확장 포인트 참조.
• 문서는 한국어 기본 (영문판은 요청 시).