# Unreal MCP Server - Plan d'Implementation

## Vision

MCP server Python pour Unreal Engine offrant :
- Generation C++ production-ready (via CLAUDE.md)
- Workflow bidirectionnel Blueprint <-> C++
- Runtime interaction + debug

**Differentiation** : Seul MCP avec generation C++ + manipulation Blueprint + analyse statique.

---

## Architecture

```
┌─────────────────────────────────────────┐
│         UNREAL MCP SERVER (Python)      │
├─────────────────────────────────────────┤
│  Tools MCP                              │
│  ├── Project: get_spawnable_classes     │
│  ├── Scene: spawn_actor                 │
│  ├── Debug: get_console_logs            │
│  └── Blueprint: create_blueprint        │
├─────────────────────────────────────────┤
│  Core                                   │
│  ├── Unreal Connection (port 9998)      │
│  ├── uasset Parser (fallback)           │
│  └── IR (Intermediate Representation)   │
└─────────────────────────────────────────┘
```

---

## Stack Technique

```python
{
    "runtime": "Python 3.11+",
    "mcp": "mcp (official Python SDK)",
    "validation": "pydantic",
    "blueprint_parser": "unreal_asset / custom",
    "unreal_connection": "Remote Execution (port 9998)",
    "testing": "pytest",
    "linting": "ruff"
}
```

---

## Phases d'Implementation

### Phase 0 : Setup (Current)
- [x] Architecture definie
- [ ] Init projet Python (pyproject.toml)
- [ ] Setup MCP SDK Python
- [ ] Structure dossiers
- [ ] Tests (pytest)

### Phase 1 : Project Intelligence
- [ ] `get_spawnable_classes` - Liste classes spawnables
- [ ] `get_project_assets` - Inventaire assets
- [ ] `scan_cpp_classes` - Parse Source/

### Phase 2 : Scene Manipulation
- [ ] `spawn_actor` - Spawn via Unreal API
- [ ] `get_scene_hierarchy` - Arbre acteurs
- [ ] `modify_actor_transform` - Deplacer acteurs

### Phase 3 : Debug Tools
- [ ] `get_console_logs` - Logs temps reel
- [ ] `analyze_crash_dump` - Debug crashes
- [ ] `profile_blueprint` - Performance BP

### Phase 4 : Blueprint Operations
- [ ] `read_blueprint` - Parse .uasset
- [ ] `create_blueprint_from_cpp` - C++ -> BP
- [ ] `execute_python_script` - Scripts custom

### Phase 5 : Advanced (Future)
- [ ] `blueprint_to_cpp` - BP -> C++ optimise
- [ ] `transform_blueprint` - Round-trip modifications
- [ ] `optimize_blueprint` - Auto-optimization

---

## Structure Projet

```
unreal-mcp/
├── pyproject.toml            # Project config + dependencies
├── README.md
├── CLAUDE.md                 # Dev guide
├── src/
│   └── unreal_mcp/
│       ├── __init__.py
│       ├── server.py         # MCP entry point
│       ├── tools/
│       │   ├── __init__.py
│       │   ├── project.py    # get_spawnable_classes, get_project_assets
│       │   ├── scene.py      # spawn_actor, get_scene_hierarchy
│       │   ├── debug.py      # get_console_logs, analyze_crash
│       │   └── blueprint.py  # read_blueprint, create_blueprint
│       ├── core/
│       │   ├── __init__.py
│       │   ├── unreal_connection.py  # Connection Unreal Editor
│       │   └── uasset_parser.py      # Parse .uasset files
│       └── utils/
│           ├── __init__.py
│           ├── logger.py
│           └── validation.py
├── tests/
│   ├── __init__.py
│   ├── test_tools/
│   └── test_core/
├── skills/
│   └── blueprint-workflow/
│       ├── skill.yaml
│       └── prompt.md
└── docs/
    ├── SPEC.md
    ├── IMPLEMENTATION_PLAN.md
    └── REFERENCES.md
```

---

## Challenges & Solutions

| Challenge | Solution |
|-----------|----------|
| Format .uasset proprietaire | unreal_asset lib + fallback UAssetAPI |
| Editeur ferme | Fallback: scan Content/ + scripts Python |
| Equivalence BP->C++ | Tests comportementaux + warnings |
| Validation compilation | Syntax check + Epic standards |

---

## Metriques Succes

- 100% code genere compile
- Response time < 2s
- 90%+ equivalence comportementale BP->C++

---

## Next Steps

1. `pyproject.toml` + structure dossiers
2. Setup MCP SDK Python basique
3. Implementer `get_spawnable_classes`
4. Unreal connection (Remote Execution)

---

*Last update: 2026-01-20*