Unreal-mcp/docs/IMPLEMENTATION_PLAN.md

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

{
    "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)

• 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