Metadata-Version: 2.4
Name: ue5rc-mcp
Version: 0.2.0
Summary: 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.
Project-URL: Repository, https://github.com/Team-Yarn-UE/ue5rc-mcp
Project-URL: Documentation, https://github.com/Team-Yarn-UE/ue5rc-mcp/blob/main/README.md
Project-URL: Bug Tracker, https://github.com/Team-Yarn-UE/ue5rc-mcp/issues
Project-URL: Changelog, https://github.com/Team-Yarn-UE/ue5rc-mcp/blob/main/CHANGELOG.md
Author: I2:Highwind & Project SP
License: MIT
Keywords: ai-automation,anthropic,bpdsl,claude-code,editor-scripting,mcp,remote-control,ue5,unreal,unreal-engine,yarn-spinner
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: MacOS
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Games/Entertainment
Classifier: Topic :: Multimedia :: Graphics :: 3D Modeling
Classifier: Topic :: Software Development :: Build Tools
Classifier: Topic :: Software Development :: Code Generators
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: httpx>=0.27
Requires-Dist: mcp>=1.27.0
Requires-Dist: pydantic-settings>=2.0
Requires-Dist: pydantic>=2.0
Requires-Dist: sqlite-vec>=0.1.9
Provides-Extra: all
Requires-Dist: anthropic>=0.40; extra == 'all'
Requires-Dist: build>=1.0; extra == 'all'
Requires-Dist: httpx>=0.27; extra == 'all'
Requires-Dist: lark>=1.1; extra == 'all'
Requires-Dist: pillow>=10.0; extra == 'all'
Requires-Dist: pytest-asyncio>=0.23; extra == 'all'
Requires-Dist: pytest>=8.0; extra == 'all'
Requires-Dist: ruff>=0.6; extra == 'all'
Requires-Dist: twine>=5.0; extra == 'all'
Provides-Extra: assets
Requires-Dist: diffusers>=0.30; extra == 'assets'
Requires-Dist: pillow>=10.0; extra == 'assets'
Requires-Dist: segment-anything>=1.0; extra == 'assets'
Requires-Dist: torch>=2.1; extra == 'assets'
Provides-Extra: assets-api
Requires-Dist: httpx>=0.27; extra == 'assets-api'
Provides-Extra: bpdsl
Requires-Dist: lark>=1.1; extra == 'bpdsl'
Provides-Extra: dev
Requires-Dist: build>=1.0; extra == 'dev'
Requires-Dist: lark>=1.1; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.6; extra == 'dev'
Requires-Dist: twine>=5.0; extra == 'dev'
Provides-Extra: nl-ko
Provides-Extra: vision
Requires-Dist: anthropic>=0.40; extra == 'vision'
Requires-Dist: pillow>=10.0; extra == 'vision'
Description-Content-Type: text/markdown

# UE5RC-MCP

> **U**nreal **E**ngine **5** **R**emote **C**ontrol **MCP** — AI 어시스턴트(Claude Code · Cursor · Windsurf · VS Code Copilot) 가 UE 5.7 에디터를 직접 제어하게 해 주는 MCP 서버.

- **Handbook**: [`ue-project/docs/handbook/ue5rcmcp.md`](../ue-project/docs/handbook/ue5rcmcp.md)
- **Tool API**: [`ue-project/docs/references/ue5rcmcp-api.md`](../ue-project/docs/references/ue5rcmcp-api.md)
- **Design**: [`ue-project/docs/02-design/features/WP-M1.design.md`](../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. 설치

```bash
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 연결

```bash
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`](../ue-project/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. 테스트

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

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

```powershell
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`](../ue-project/docs/01-plan/features/WP-M2.plan.md) · [Design](../ue-project/docs/02-design/features/WP-M2.design.md) 참조.

## 8. 라이선스 · 감사

MIT · Copyright I2:Highwind & Project SP.

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

## 9. 기여

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