Unreal-mcp/docs/SPEC.md

# Unreal MCP Server - Specification

## Overview

MCP Server Python pour Unreal Engine combinant :
1. **Runtime Control** - Manipulation scene en temps reel
2. **Project Intelligence** - Analyse codebase et assets
3. **Debug Tools** - Logs, crashes, profiling

---

## MCP Tools

### Project Intelligence

#### `get_spawnable_classes`
Liste toutes les classes spawnables du projet.

```python
# Input
{"filter": "blueprint" | "native" | "all"}  # optional

# Output
{
  "native_actors": [{"class_name": "ACharacter", "module": "Engine"}],
  "blueprint_actors": [{"name": "BP_Enemy", "path": "/Game/Enemies/BP_Enemy"}],
  "components": [{"name": "UHealthComponent", "is_custom": True}]
}
```

**Implementation:**
- Editor ouvert: API `unreal` directe
- Editor ferme: Scan Content/ + parse .uasset

#### `get_project_assets`
Inventaire des assets par type.

```python
# Output
{
  "blueprints": 127,
  "materials": 45,
  "by_folder": {"Enemies": ["BP_Enemy"], "Weapons": ["BP_Rifle"]}
}
```

#### `scan_cpp_classes`
Parse les classes C++ du projet.

```python
# Output
[{
  "name": "AWeapon",
  "file": "Source/MyGame/Weapon.h",
  "parent": "AActor",
  "is_blueprintable": True
}]
```

---

### Scene Manipulation

#### `spawn_actor`
Spawn un acteur dans la scene.

```python
# Input
{
  "class_name": "BP_Enemy",
  "location": [0, 0, 100],
  "rotation": [0, 0, 0],  # optional
  "properties": {"Health": 100}  # optional
}

# Output
{"success": True, "actor_id": "BP_Enemy_3", "location": [0, 0, 100]}
```

#### `get_scene_hierarchy`
Retourne l'arbre des acteurs.

```python
# Output
{
  "level": "MainLevel",
  "actors": [{
    "id": "actor_1234",
    "class": "BP_Enemy",
    "location": [120, 450, 100],
    "components": ["HealthComponent"]
  }]
}
```

#### `modify_actor_transform`
Modifie position/rotation d'un acteur.

```python
# Input
{"actor_id": "actor_1234", "location": [200, 500, 150], "rotation": [0, 90, 0]}
```

---

### Debug & Profiling

#### `get_console_logs`
Recupere les logs Unreal.

```python
# Input
{"filter": "Error" | "Warning" | "All", "limit": 100}  # optional

# Output
[
  {"timestamp": "14:23:47", "level": "Error", "message": "Null pointer in Weapon.cpp:145"}
]
```

#### `analyze_crash_dump`
Analyse un crash log.

```python
# Input
{"crash_log": "...", "callstack": "..."}  # callstack optional

# Output
{
  "root_cause": "Null pointer dereference",
  "file": "Weapon.cpp",
  "line": 145,
  "fix_suggestion": "if (CurrentTarget && IsValid(CurrentTarget)) {...}"
}
```

#### `profile_blueprint`
Profile les performances d'un Blueprint.

```python
# Input
{"blueprint_path": "BP_AI.uasset"}

# Output
{
  "avg_tick_time_ms": 2.3,
  "hotspots": [{"node": "Event Tick", "cost_ms": 1.8, "percentage": 78}],
  "optimization_potential": "HIGH"
}
```

---

### Blueprint Operations

#### `read_blueprint`
Parse un fichier .uasset.

```python
# Input
{"file_path": "Content/Blueprints/BP_Character.uasset"}

# Output
{
  "class_name": "BP_Character",
  "parent": "ACharacter",
  "variables": [{"name": "Health", "type": "float", "default": 100}],
  "functions": ["Fire", "Reload"],
  "events": ["OnDeath"]
}
```

#### `create_blueprint_from_cpp`
Cree un Blueprint depuis une classe C++.

```python
# Input
{
  "cpp_class": "AWeapon",
  "blueprint_name": "BP_Weapon",
  "output_path": "/Game/Weapons",
  "exposed_properties": ["MaxAmmo", "FireRate"]
}

# Output
{"success": True, "blueprint_path": "/Game/Weapons/BP_Weapon"}
```

#### `execute_python_script`
Execute un script Python dans l'editeur.

```python
# Input
{"script": "import unreal; unreal.log('Hello')"}
# ou
{"script_path": "scripts/create_actor.py"}
```

---

## Unreal Connection

### Mode 1: Direct (dans Unreal)
Quand le serveur MCP tourne dans le contexte Unreal Python.

```python
import unreal

# Accès direct
actors = unreal.EditorLevelLibrary.get_all_level_actors()
```

### Mode 2: Remote Execution (externe)
Quand le serveur MCP tourne en externe, connection via port 9998.

```python
class UnrealConnection:
    def __init__(self, host: str = "localhost", port: int = 9998):
        ...

    def connect(self) -> bool:
        ...

    def execute(self, script: str) -> Any:
        ...

    def is_connected(self) -> bool:
        ...

    def disconnect(self) -> None:
        ...
```

**Prerequis Unreal:**
- Plugin "Python Editor Script Plugin" active
- Remote Execution enable dans Project Settings

### Mode 3: Fallback (éditeur fermé)
- Scan fichiers Content/
- Parse .uasset avec unreal_asset ou UAssetAPI
- Generation scripts Python pour execution ulterieure

---

## Workflow Examples

### Spawn enemies in circle
```
User: "Spawn 10 BP_Enemy in a circle"

1. get_spawnable_classes() -> trouve BP_Enemy
2. Loop: spawn_actor() avec positions calculees
3. Return: "10 enemies spawned"
```

### Debug crash
```
User: "Game crashes when shooting"

1. get_console_logs(filter="Error")
2. analyze_crash_dump(crash_log)
3. Return fix suggestion
```

### Create Blueprint from C++
```
User: "Create BP from AWeapon class"

1. scan_cpp_classes() -> trouve AWeapon
2. create_blueprint_from_cpp()
3. Return: "BP_Weapon created at /Game/Weapons"
```

---

## Response Format

Tous les tools retournent :

```python
# Success
{"success": True, "data": {...}}

# Error
{"success": False, "error": "Description", "code": "ERROR_CODE"}
```

---

## Environment Variables

```bash
UE_PROJECT_PATH=/path/to/MyProject
UE_PYTHON_PORT=9998
LOG_LEVEL=debug
```

---

*Last update: 2026-01-20*