UEBPCracker

AI-driven Blueprint automation plugin for Unreal Engine 5.8

MCP-native toolset that lets AI agents (VS Code Copilot, Claude, Codex, any MCP client) safely create, read, edit, compile, and save Blueprints through a contract-validated, transactional API — without arbitrary file access or unguarded engine calls.

---

What is UEBPCracker?

UEBPCracker is an editor-only C++ Unreal Engine plugin that bridges MCP-compatible AI agents and Unreal's Blueprint Editor API. The AI speaks natural language; UEBPCracker validates every request, translates it into official Editor API calls, and returns structured results.

The plugin does not host its own LLM, produce .uasset binaries directly, replace the Unreal compiler, or give the AI unrestricted engine access. It is a controlled, contract-validated bridge.

User (natural language)
    │
    ▼
MCP-compatible AI agent (VS Code Copilot / Claude / Codex / …)
    │  JSON-RPC tool call
    ▼
Unreal MCP  (localhost:8000/mcp)
    │  Toolset Registry
    ▼
UEBPCracker Toolset  (12+ tools)
    │
    ├─ Preflight → Schema & permission validation
    ├─ Transaction → Mutation inside FScopedTransaction
    ├─ Postcondition → Structural assertion
    └─ Commit Pipeline → Engine compile → Data validation → Save

---

Features

Reading

Tool	Description
inspect_blueprint	Full Blueprint dump: variables, components, graphs, nodes, pins, connections
inspect_blueprint_graph	Graph-level detail with node/pin/connection data
resolve_unreal_type	Type resolution for C++ classes, enums, structs, assets
get_blueprint_snapshot	Semantic + layout + full fingerprint (Blake3)
compare_blueprint_snapshots	Element-level diff with logical path labels
health_check	Plugin/engine version, write roots, policy fingerprint
get_capabilities	Tool surface, resource limits, security policy summary

Writing (contract-validated)

Tool	Description
create_blueprint	Actor Blueprint creation with conflict policy
add_variable	Typed variable with default value and metadata
add_component	SCS component (SceneComponent, StaticMeshComponent, …)
add_function_graph	Named function graph
add_node	K2 node (9 allow-listed types: event override, function call, variable get/set, flow control, comment, …)
set_pin_default	Pin default value with codec round-trip validation
connect_pins	Type-checked pin connection via schema API

Spec System (.uebp.json)

Tool	Description
validate_blueprint_spec	Schema + semantic validation, plan preview
plan_blueprint_spec	Deterministic execution plan with command list
apply_blueprint_spec	Single-transaction create-only executor; no save on failure

Patch & Recovery

Tool	Description
plan_blueprint_patch	Three-way ownership diff (base vs. current vs. spec)
apply_blueprint_patch	Sealed plan hash, conflict detection, idempotent apply
get_recovery_status	Pending recovery operations
restore_operation_backup	Restore from durable backup asset
discard_operation_backup	Discard backup after manual resolution

Completion Gate

Tool	Description
check_completion	DoD evaluation: 31 criteria across code, behavior, security, and test/release

---

Architecture

flowchart LR
    U[User] -->|natural language| A["MCP AI Agent\nVS Code / Copilot / Claude / Codex"]
    A -->|JSON-RPC tool call| M["Unreal MCP\nlocalhost:8000/mcp"]
    M -->|Toolset Registry| T["UEBPCracker Toolset\n12+ tools"]
    T --> P["Preflight → Transaction\n→ Mutation → Postcondition"]
    P --> C["Engine Compile\n+ Data Validation + Save"]
    C -->|Structured JSON result| A

Loading

Security layers:

• L0 Read — Inspect, snapshot, capabilities (always allowed)
• L1 Create — New assets in allowed content roots
• L2 Patch — Managed mutation of plugin-owned content; requires sealed plan hash
• L3 Destructive — Backup restore/discard; disabled by default

---

Project Status

MVP Complete — 28/28 core modules + 4/22 extra modules shipped.

Final acceptance: check_completion DoD 31/31 ready (automation 18/18, MCP harness 469–480).
Tested on UE 5.8.2 (CL 56702186), Windows x64 Editor.

Phase	Modules	Status
Phase 1 — Core architecture, MCP registration, contracts	01–06	✅ Complete
Phase 2 — Inspector, types, creation, variable, component	07–13	✅ Complete
Phase 3 — Graph, node, pin, .uebp.json, compile/save pipeline	14–20	✅ Complete (35/35 assertions + PIE smoke)
Phase 4 — Snapshot/fingerprint	21	✅ Complete (59/59 assertions)
Phase 4 — Idempotency/ownership/patch	22	✅ Complete (42/42 assertions)
Phase 4 — Transaction/undo/recovery	23	✅ Complete (342–391 matrix + restart)
Phase 4 — Security policies	24	✅ Complete (29/29 assertions)
Phase 4 — Limits, timeouts, cancellation	25	✅ Complete (11/11 MCP + 17/17 boundary)
Phase 4 — Automation & integration tests	26	✅ Complete (14/14 automation + 14/14 MCP)
Phase 4 — Versioning, migration, release	27	✅ Complete (17/17 automation + 9/9 MCP)
Phase 4 — Project completion criteria	28	✅ Complete (DoD 31/31)

Extra Feature Modules (domain extension)

Module	Domain	Status
Extra 01	Common architecture & domain registry (ai/data/fx/gameplay/input/project/ui)	✅ Complete (20/20 automation + 8/8 MCP)
Extra 02	Asset factory, inspector & commit infrastructure	✅ Complete (20/20 automation + 4/4 MCP boundary)
Extra 03	Enhanced Input Action (UInputAction, 4 value types)	✅ Complete (21/21 automation + 10/10 MCP)
Extra 04	Input Mapping Context & key mapping (keyboard/mouse/gamepad/motion)	✅ Complete (22/22 automation + 14/14 MCP)
Extra 05+	Input Modifier, Trigger, Gameplay Tags, Data Assets, Animation BP, Niagara, UMG…	🗺️ Planned — see roadmap

---

Getting Started

Prerequisites

Requirement	Version
Unreal Engine	5.8.x (tested on 5.8.2 CL 56702186)
OS	Windows 10/11 x64
Compiler	MSVC — Visual Studio 2022 17.14+ or VS 2026 18.0+
Unreal MCP	Bundled with UE 5.8 (ModelContextProtocol plugin)

Installation

1. Copy the plugin into your UE 5.8 project:

   <YourProject>/Plugins/UEBPCracker/
   

   (Reference host project: UEBPCrackerHost/)

2. Right-click your .uproject → Generate Visual Studio project files.

3. Build (Development Editor / Win64).

4. In Unreal Editor, open Edit → Plugins and enable:

   • ModelContextProtocol (Unreal MCP)
   • UEBPCracker

5. Enable write operations in Config/DefaultUEBPCracker.ini:

   [/Script/UEBPCrackerEditor.UEBPCrackerSettings]
   bEnableWriteOperations=True

6. Start the MCP server (choose one method):

   Method A — Editor console:

   ModelContextProtocol.StartServer 8000
   

   Method B — Command-line launch:

   UnrealEditor.exe "UEBPCrackerHost.uproject" -ExecCmds="ModelContextProtocol.StartServer 8000"
   

7. Connect your AI client to http://127.0.0.1:8000/mcp with toolset UEBPCrackerEditor.UEBPCrackerToolset.

   Example MCP client config:

   {
     "mcpServers": {
       "unreal-mcp": {
         "type": "http",
         "url": "http://127.0.0.1:8000/mcp"
       }
     }
   }

Quick Smoke Test

Ask your AI agent:

"Call health_check on the UEBPCracker toolset."

Expected response:

{
  "success": true,
  "engineVersion": "5.8.x",
  "pluginVersion": "0.1.0",
  "writeRoots": ["/Game/AI/"],
  "bLoopbackBind": true
}

First Blueprint (end-to-end)

Create an Actor Blueprint at /Game/AI/BP_HealthActor.
Add a float variable named Health with default value 100.
Connect Event BeginPlay to a Print String node.
Compile and save.

The plugin will:

1. Validate the path and class
2. Create the Blueprint in a single transaction
3. Add the variable with codec-validated default
4. Spawn and connect the K2 nodes
5. Run the engine compiler
6. Pass data validation
7. Save the asset
8. Return a structured JSON result with compile status, node GUIDs, and fingerprint

---

.uebp.json Spec Format

For reproducible, version-controlled Blueprint generation:

{
  "schema_version": "2.0",
  "target": "/Game/AI/BP_HealthActor",
  "parent_class": "/Script/Engine.Actor",
  "variables": [
    { "name": "Health", "type": "float", "default_value": "100.0", "instance_editable": true }
  ],
  "graphs": [
    {
      "kind": "event_graph",
      "use_existing": true,
      "nodes": [
        { "id": "n_begin", "kind": "event_override", "event_name": "ReceiveBeginPlay" },
        { "id": "n_print", "kind": "function_call", "function_path": "/Script/Engine.KismetSystemLibrary:PrintString",
          "pin_defaults": [{ "pin": "InString", "value": "Hello from UEBPCracker!" }] }
      ],
      "connections": [
        { "from_node": "n_begin", "from_pin": "then", "to_node": "n_print", "to_pin": "execute" }
      ]
    }
  ]
}

Apply with:

validate_blueprint_spec → plan_blueprint_spec → apply_blueprint_spec

---

Security Model

Layer	Guard	Default
Network	Loopback-only bind (bAllowRemoteMCPBind=false)	Locked
Content root	Configurable allow-list (default /Game/AI/)	Locked
Write gate	bEnableWriteOperations in INI	Off
Destructive ops	bEnableDestructiveOperations	Off
Patch integrity	Sealed plan hash required (bRequirePlanHashForPatch)	On
Dirty guard	Mutation blocked on unsaved packages	On
Reflection	Function/component allow-list	Enforced
Path traversal	Segment-boundary containment check	Enforced

Error codes follow a structured taxonomy: UEBP.<CATEGORY>_<DETAIL> (e.g. UEBP.PATH_OUTSIDE_ALLOWED_ROOT, UEBP.PLAN_HASH_MISMATCH).

---

Repository Layout

UEBPCracker/
├── memory-bank/                   # All project documentation
│   ├── Project_Phases/            # 28-module design & exit criteria docs
│   ├── Additional_Feature_Modules/# Extra domain modules (22 planned)
│   ├── Test_Reports/              # Phase/module test reports
│   ├── Build_Baselines/UE_5.8/   # MCP test outputs & PowerShell harnesses
│   ├── Project_Documantion/       # Architecture decisions, setup & work guides
│   └── gotchas_export.md          # UE 5.8 engine gotchas & proven workarounds
├── UEBPCrackerHost/               # Reference host UE project
│   └── Plugins/UEBPCracker/
│       ├── UEBPCracker.uplugin
│       ├── Config/DefaultUEBPCracker.ini
│       └── Source/
│           ├── UEBPCrackerEditor/     # Core plugin (editor-only)
│           │   ├── Public/            # Toolset, contracts, snapshot, spec API
│           │   └── Private/           # Inspector, mutators, graph/node/pin,
│           │                          # spec system, compile/save, snapshot/fp
│           └── UEBPCrackerEditorTests/# Automation test module
├── CHANGELOG.md
├── CONTRIBUTING.md
├── SECURITY.md
└── LICENSE

---

Roadmap

Core (Complete)

• Phase 1–4 core modules (28/28)
• Extra modules 01–04 (Enhanced Input foundation)

Extra Modules (Planned)

• Extra 05 — Input Modifier system
• Extra 06 — Input Trigger system
• Extra 07 — Player Mappable Profile, Input Mode & runtime binding
• Extra 08 — Blueprint Enhanced Input graph integration
• Extra 09 — Enhanced Input spec/patch & exit criteria
• Extra 10 — Project Settings & Developer Settings
• Extra 11 — Gameplay Tags system
• Extra 12 — Data Asset & Data Table
• Extra 13 — Collision Channel, Profile & Trace
• Extra 14 — Physical Material, Surface & Layer
• Extra 15 — Game Framework defaults & World Settings
• Extra 16 — Animation Blueprint
• Extra 17 — Behavior Tree & Blackboard
• Extra 18 — Niagara
• Extra 19 — Material & Material Instance
• Extra 20 — Widget Blueprint & UMG
• Extra 21 — Multi-system spec ownership & dependency planner
• Extra 22 — Automation, security & release criteria

Future Considerations (Out of Scope for v1)

• Packaged game runtime support
• Marketplace / Fab distribution
• Multi-user remote server
• Older UE version compatibility

---

Known Limitations

• UE 5.8 only — Engine API surface is pinned to 5.8.x; older/newer versions untested.
• Editor-only — The plugin does not load in packaged games.
• Windows x64 — Other platforms not verified.
• Actor Blueprint focus — Specialized graph types (Control Rig, StateTree, PCG) require dedicated adapters (see Extra Modules roadmap).
• No BeginPlay in transient worlds — Runtime proof uses CDO/ProcessEvent, not UWorld::CreateWorld transient spawns.
• Serial mutation — Concurrent writes to the same Blueprint are rejected (OPERATION_BUSY); cancellation is not supported for in-flight UObject calls.

---

Contributing

See CONTRIBUTING.md for build setup, code standards, and the pull request process.

---

Security

See SECURITY.md for the vulnerability reporting policy.

---

License

MIT © 2026 Recep Samet Yıldız

---

Author

Designed and built end-to-end by Recep Samet Yıldız — architecture, C++ plugin development, MCP tool surface design, spec language, snapshot/fingerprint system, and 200+ assertion test matrices.

• 🌐 yildizportfolio.com
• 🐙 github.com/ThePecerowski

---

UEBPCracker is experimental/local-development software. Unreal MCP itself is provided as experimental by Epic Games.