# Unreal MCP Server - Dev Guide

MCP server Python pour Unreal Engine : Runtime + Project Intelligence

---

## Architecture

```
┌─────────────────────────────────┐
│   UNREAL MCP SERVER (Python)   │
├─────────────────────────────────┤
│  MCP Tools (12)                 │
│  └── Remote Execution Protocol  │
├─────────────────────────────────┤
│  Fallback (éditeur fermé)       │
│  └── .uasset parser + scan      │
└─────────────────────────────────┘

User's CLAUDE.md → Expertise Unreal C++ (PAS NOUS!)
Skills           → /blueprint-workflow
MCP Tools        → get_spawnable_classes(), spawn_actor(), debug...
```

---

## Structure

```
src/unreal_mcp/
├── server.py                   # MCP entry point
├── tools/
│   ├── project.py              # get_spawnable_classes, get_project_assets, scan_cpp_classes
│   ├── scene.py                # spawn_actor, get_scene_hierarchy, modify_actor_transform
│   ├── debug.py                # get_console_logs, analyze_crash_dump, profile_blueprint
│   └── blueprint.py            # read_blueprint, create_blueprint_from_cpp, execute_python_script
├── core/
│   ├── unreal_connection.py    # Remote Execution Protocol (UDP+TCP)
│   └── uasset_parser.py        # Parse .uasset (fallback)
└── utils/
    ├── config.py               # Settings (pydantic-settings)
    ├── logger.py
    └── validation.py

skills/
└── blueprint-workflow/
    ├── skill.yaml              # 5 commands: analyze, bp-to-cpp, cpp-to-bp, transform, optimize
    └── prompt.md
```

---

## MCP Tools (12)

| Category | Tools |
|----------|-------|
| Project | `get_spawnable_classes`, `get_project_assets`, `scan_cpp_classes` |
| Scene | `spawn_actor`, `get_scene_hierarchy`, `modify_actor_transform` |
| Debug | `get_console_logs`, `analyze_crash_dump`, `profile_blueprint` |
| Blueprint | `read_blueprint`, `create_blueprint_from_cpp`, `execute_python_script` |

---

## Remote Execution Protocol

**UDP Multicast** (Node Discovery)
- Group: `239.0.0.1`
- Port: `6766`
- Messages: `ping`, `pong`, `open_connection`, `close_connection`

**TCP** (Commands)
- Port: `6776`
- Messages: `command`, `command_result`
- Format: 4-byte length prefix + JSON UTF-8

```python
from unreal_mcp.core.unreal_connection import UnrealConnection

with UnrealConnection(project_path=Path("/path/to/project")) as conn:
    result = await conn.execute("print('Hello from Unreal!')")
```

---

## Env

```bash
# Project path (for offline mode)
UE_PROJECT_PATH=/path/to/project

# TCP Command port (default: 6776)
UE_COMMAND_PORT=6776

# UDP Multicast (default: 239.0.0.1:6766)
UE_MULTICAST_GROUP=239.0.0.1
UE_MULTICAST_PORT=6766

# Logging
LOG_LEVEL=INFO
```

---

## Guidelines

- Python 3.11+
- Type hints partout
- Validation avec Pydantic
- Graceful fallback si éditeur fermé
- Return `{ "success": True/False, "data"/"error": ... }`
- Tests avec pytest (21 tests)

---

## Status

- ✅ Architecture
- ✅ MCP SDK setup
- ✅ 12 tools implémentés
- ✅ Remote Execution Protocol (real)
- ✅ /blueprint-workflow skill
- ✅ Tests (21 passed)
- ✅ Fallback offline mode

---

**Remember**: L'expertise Unreal C++ sera dans le CLAUDE.md des users, pas ici.