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.

# 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.

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

scan_cpp_classes

Parse les classes C++ du projet.

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

---

Scene Manipulation

spawn_actor

Spawn un acteur dans la scene.

# 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.

# 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.

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

---

Debug & Profiling

get_console_logs

Recupere les logs Unreal.

# 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.

# 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.

# 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.

# 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++.

# 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.

# 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.

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.

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 :

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

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

---

Environment Variables

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

---

Last update: 2026-01-20