Blueprint Extractor

Unreal Engine plugin + MCP server for assistants that need to read, build, modify, verify, and save real UE assets instead of guessing.

Blueprint Extractor connects Unreal projects to MCP clients such as Claude Code, Codex, and OpenCode. It exposes a strict machine-friendly contract for extraction, authoring, visual verification, imports, project automation, and code sync, using a running editor when one is available and a commandlet lane for compatible tools when it is not.

Current surface

See docs/CURRENT_STATUS.md for the current validation snapshot, the normative doc set, and the active one-shot ledger.

Why This Exists

Most assistants can describe Unreal work. Blueprint Extractor lets them do it.

• Extract assets into structured JSON that models can inspect safely.
• Create and patch UE assets without relying on brittle editor-click instructions.
• Run project automation flows like compile, live coding, restart, and sync.
• Capture widget previews, compare references, and verify motion checkpoints.
• Keep writes explicit: mutate first, save when you decide.

Supported families include Blueprint, WidgetBlueprint, StateTree, BehaviorTree, Blackboard, DataAsset, DataTable, Curve, CurveTable, Material, Material Function-family assets, MaterialInstance, AnimSequence, AnimMontage, BlendSpace, InputAction, and InputMappingContext.

What You Can Do

Quick Start

1. Install the Unreal plugin

Copy BlueprintExtractor/ into your project's Plugins/ directory, rebuild, then enable:

• EnhancedInput
• PropertyBindingUtils
• StateTree
• Web Remote Control

2. Register the MCP server

Use the included install scripts:

# Claude Code
./install-mcp.sh
.\install-mcp.ps1

# Codex
./install-codex-mcp.sh
.\install-codex-mcp.ps1

# OpenCode
./install-opencode-mcp.sh
.\install-opencode-mcp.ps1

Manual registration is also supported:

# Claude Code
claude mcp add -s user -t stdio blueprint-extractor -e UE_REMOTE_CONTROL_PORT=30010 -- npx -y blueprint-extractor-mcp@latest
claude mcp add -s user -t stdio blueprint-extractor -e UE_REMOTE_CONTROL_PORT=30010 -- cmd /c npx -y blueprint-extractor-mcp@latest

# Codex
codex mcp add --env UE_REMOTE_CONTROL_PORT=30010 blueprint-extractor -- npx -y blueprint-extractor-mcp@latest
codex mcp add --env UE_REMOTE_CONTROL_PORT=30010 blueprint-extractor -- cmd /c npx -y blueprint-extractor-mcp@latest

# OpenCode
npm install --prefix ~/.config/opencode --save-exact blueprint-extractor-mcp@latest

// OpenCode global config (~/.config/opencode/opencode.json)
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "blueprint-extractor": {
      "type": "local",
      "command": ["/absolute/path/to/.config/opencode/node_modules/.bin/blueprint-extractor-mcp"],
      "enabled": true,
      "environment": {
        "UE_REMOTE_CONTROL_PORT": "30010"
      }
    }
  }
}

On Windows, point command at C:\\Users\\you\\.config\\opencode\\node_modules\\.bin\\blueprint-extractor-mcp.cmd.

3. Verify the connection

Open a new MCP-enabled assistant session and ask for:

• search_assets on a known Blueprint
• get_tool_help for a tool you plan to use
• activate_workflow_scope with widget_verification or verification, then capture_widget_preview on a fixture widget if you want to confirm verification works end-to-end

What The Contract Feels Like

Blueprint Extractor is built around a few durable rules:

• Public inputs use snake_case.
• Tool results publish outputSchema.
• Success and failure responses come back as structured envelopes.
• Write tools mutate assets but do not silently save them.
• Static guidance lives in MCP resources and prompts, not buried in prose.

Key references:

• MCP v2 Reference
• Prompt Catalog
• Multimodal UI Design Workflow
• Widget Motion Authoring
• Motion Verification Workflow
• Unsupported Surfaces
• Safe UI Redesign Workflow

Workflow-Scoped Tool Surface

The server exposes a compact default tool profile and a full expert profile via activate_tool_profile. The default profile uses a retrieval-first core and expands into specialized families only when needed through activate_workflow_scope.

For dual-mode tools, the executor uses a running editor when one is actually reachable; otherwise it falls back to commandlet execution. save_assets stays biased toward the running editor and can reroute there when commandlet-side file locks block persistence.

Resources And Prompts

The server is more than a tool list. It also publishes reusable guidance and structured examples.

Resources

• blueprint://scopes
• blueprint://verification-workflows
• blueprint://project-automation
• blueprint://analysis-workflows
• blueprint://project-intelligence-workflows
• blueprint://material-graph-guidance
• blueprint://font-roles

Resource templates

• blueprint://examples/{family}
• blueprint://widget-patterns/{pattern}
• blueprint://captures/{capture_id}
• blueprint://test-runs/{run_id}/{artifact}

Prompts

• normalize_ui_design_input
• design_menu_from_design_spec
• author_widget_motion_from_design_spec
• plan_widget_motion_verification
• design_menu_screen
• author_material_button_style
• wire_hud_widget_classes
• debug_widget_compile_errors
• understand_blueprint_project
• review_blueprint_asset
• snapshot_editor_context
• audit_blueprint_project

Requirements

Environment variables used most often:

Development

MCP server

cd MCP
npm install
npm run build
npm test

Unreal automation tests

The repository includes a fixture project at tests/fixtures/BlueprintExtractorFixture/BPXFixture.uproject.

.\scripts\test-ue.ps1 -EngineRoot "C:\Program Files\Epic Games\UE_5.6"
./scripts/test-ue.sh --engine-root "/path/to/UE_5.6"

Default runs use the broader BlueprintExtractor filter with -NullRHI for logic and contract coverage. Use -NoNullRHI for rendered verification lanes such as widget capture, CommonUI style capture, editor screenshots, and automation-backed runtime screenshots. On software-rendered environments, scripts/test-ue.ps1 also supports -AllowSoftwareRendering.

Live MCP smoke tests

cd MCP
BLUEPRINT_EXTRACTOR_LIVE_E2E=1 npm run test:live

Repository Layout

BlueprintExtractor/   Unreal plugin source
MCP/                  MCP server package published as blueprint-extractor-mcp
docs/                 Contract and workflow documentation
scripts/              Cross-platform helper scripts
tests/                Fixture UE project and automation helpers

Contributing

Before opening a PR:

• run npm test in MCP/
• run the Unreal automation test script if you changed plugin behavior
• keep tool contracts, docs, and tests aligned in the same change

Package README

If you only need the npm package view, see MCP/README.md.