Overview

Blueprint Extractor MCP is a Model Context Protocol server that bridges AI coding assistants (Claude Code, Codex, OpenCode, etc.) to Unreal Engine through two execution lanes:

• Editor lane via the Remote Control HTTP API for editor-bound and interactive workflows
• Commandlet lane for headless-safe extraction and authoring when no reachable editor session is available

For compatible tools, the server can also execute through a commandlet lane when no reachable editor session is available. When an editor is already running, editor execution stays preferred for editor-only flows and for save paths that need to avoid package-lock contention.

 AI Assistant         stdio           MCP Server         HTTP :30010        Unreal Editor
 ─────────────  ◄────────────►  ─────────────────  ◄──────────────────►  ─────────────────
  Claude Code                     Node.js process                         Remote Control API
  Codex / OpenCode                112 tools                               BlueprintExtractor
  ...                             38 resources                            plugin
                                  4 resource templates
                                  12 prompts

What the assistant can do through this server:

| Capability | Examples | |:-----------|:---------| | Extract | Read Blueprints, widgets, materials, animations, data assets, state trees, and more | | Author | Create and modify widgets, materials, Blueprints, input actions, AI assets, data tables | | Build | Compile project code, trigger Live Coding, restart the editor, sync changes | | PIE | Start, stop, and relaunch Play-In-Editor sessions from the active editor | | Import | Bring in textures, meshes, and generic assets with async job polling | | Test | Run UE automation tests, collect results and artifacts | | Verify | Capture widget previews, editor screenshots, runtime screenshots, compare against references, inspect motion checkpoints |

Quick Start

Prerequisites

You need these prerequisites:

1. Node.js 18+
2. BlueprintExtractor plugin installed in your project
3. One execution lane configured:
   • Editor lane: Unreal Editor running with the Remote Control API plugin enabled
   • Commandlet lane: resolvable UE_ENGINE_ROOT and UE_PROJECT_PATH so headless-safe tools can launch UnrealEditor-Cmd

Run

npx blueprint-extractor-mcp

Connects to the editor at 127.0.0.1:30010 by default.

For headless-safe tools, also set UE_ENGINE_ROOT and UE_PROJECT_PATH so the MCP server can resolve the commandlet lane when no editor is reachable.

Add to Your AI Client

claude mcp add -s user -t stdio blueprint-extractor \
  -e UE_REMOTE_CONTROL_PORT=30010 \
  -- npx -y blueprint-extractor-mcp@latest

codex mcp add --env UE_REMOTE_CONTROL_PORT=30010 \
  blueprint-extractor -- npx -y blueprint-extractor-mcp@latest

# Optional for headless-safe tools when no editor is running
codex mcp add \
  --env UE_REMOTE_CONTROL_PORT=30010 \
  --env UE_ENGINE_ROOT="C:\\Program Files\\Epic Games\\UE_5.7" \
  --env UE_PROJECT_PATH="D:\\Development\\V2\\CyberVolleyball6vs6.uproject" \
  blueprint-extractor -- npx -y blueprint-extractor-mcp@latest

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

// ~/.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.

Tool Surface

Use activate_tool_profile to switch between the compact default surface and the full expert surface. The default profile keeps the context window lean with a retrieval-first core and loads specialized families on demand via activate_workflow_scope.

| Scope | What It Unlocks | |:------|:----------------| | Core (always on in default profile) | Retrieval-first discovery and persistence: search_assets, find_and_extract, extract_blueprint, extract_asset, check_asset_exists, save_assets, get_tool_help, activate_tool_profile, and activate_workflow_scope | | widget_authoring | Parent scope that loads widget_authoring_structure, widget_authoring_visual, and widget_verification together | | widget_authoring_structure | Recipe-first widget authoring, tree replacement, unified-diff patching, and focused structure edits without the deprecated widget aliases | | widget_authoring_visual | Widget compile flows, CommonUI styles, widget animations, and widget preview capture | | widget_verification | Widget capture, checkpoint bundles, capture listing, cleanup, and reference comparison | | material_authoring | create_material_setup, modify_material, material_graph_operation, compile, and material-instance edits | | blueprint_authoring | scaffold_blueprint, graph/member edits, Blueprint creation, and Live Coding trigger | | schema_ai_authoring | Structs, enums, Blackboards, Behavior Trees, and State Trees | | animation_authoring | Anim sequences, montages, blend spaces, and widget motion authoring | | data_tables | Data assets, data tables, curves, Input Actions, and Input Mapping Contexts | | import | Async asset import and import-job polling | | project_control | Editor-session binding, launch/wait, project automation context, Output Log and Message Log inspection, PIE lifecycle control, host build/restart/sync, and apply_window_ui_changes | | automation_testing | Host-side automation runs and automation-run polling | | analysis | Deterministic Blueprint review and low-noise project asset audits | | project_intelligence | Bounded editor context, project indexing, freshness status, and snippet-first context search | | verification | Editor/runtime screenshots, capture comparison, motion verification, and artifact inspection |

Contract Design

The tool contract is optimized for model reliability:

• snake_case inputs on all public tools
• outputSchema on every tool for structured JSON responses
• structuredContent carries the canonical success and error payload for MCP clients that consume structured results directly
• Structured error envelopes with diagnostic codes and recovery hints
• Explicit-save semantics — nothing persists until save_assets is called
• Dual execution lanes — compatible tools can fall back to commandlet execution when no editor is reachable, while save_assets prefers a running editor and can reroute there on file-lock contention
• Next-step hints guiding the assistant toward the logical follow-up action

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

Configuration

| Variable | Default | Purpose | |:---------|:--------|:--------| | UE_REMOTE_CONTROL_HOST | 127.0.0.1 | Editor host address | | UE_REMOTE_CONTROL_PORT | 30010 | Editor Remote Control port | | UE_BLUEPRINT_EXTRACTOR_SUBSYSTEM_PATH | auto-probe | Force a specific subsystem object path | | UE_ENGINE_ROOT | — | Engine root (needed for builds & automation) | | UE_PROJECT_PATH | — | Path to your .uproject | | UE_PROJECT_TARGET | — | Build target name (or UE_EDITOR_TARGET) | | UE_BUILD_PLATFORM | — | e.g. Win64 | | UE_BUILD_CONFIGURATION | — | e.g. Development |

get_tool_help now reports execution compatibility per tool, including whether the tool is editor-only or headless-safe.

get_project_automation_context surfaces the coarse editor-derived engineRoot, projectFilePath, editorTarget, and isPlayingInEditor state that project-control and verification flows use for fallback or guard logic.

get_editor_context is the separate read-only editor-state snapshot for selection, open asset editors, active level, and PIE summary. It stays session-bound and intentionally does not open assets, change focus, or switch viewports.

Resources & Prompts

Beyond tools, the server exposes MCP resources for reference data and prompts for guided multi-step workflows.

Resource Templates

blueprint://examples/{family}              Example payloads for each tool family
blueprint://widget-patterns/{pattern}      Reusable widget-tree patterns
blueprint://captures/{capture_id}          Captured widget screenshots
blueprint://test-runs/{run_id}/{artifact}  Automation test artifacts

Prompts

| Prompt | Guides the assistant through... | |:-------|:-------------------------------| | normalize_ui_design_input | Converting text/image/Figma/HTML into a shared design_spec_json | | design_menu_from_design_spec | Planning a full menu implementation from a normalized spec | | design_menu_screen | Safe widget redesign with pre-flight inspection | | author_material_button_style | Composable material authoring for button states | | author_widget_motion_from_design_spec | Turning motion specs into animation authoring steps | | plan_widget_motion_verification | Keyframe-bundle verification planning | | wire_hud_widget_classes | Class-default wiring for HUD assets | | debug_widget_compile_errors | Diagnosing and recovering from compile failures | | understand_blueprint_project | Building a project-understanding pass over indexed assets, docs, prompts, and resources | | review_blueprint_asset | Running a deterministic read-only Blueprint review flow | | snapshot_editor_context | Inspecting bounded editor state without changing editor focus | | audit_blueprint_project | Running a low-noise project asset audit |

Development

cd MCP
npm install
npm run build
npm test            # unit + stdio integration

| Command | What It Validates | |:--------|:------------------| | npm run test:pack-smoke | Packaged tarball contract and README inclusion | | npm run test:publish-gate | Version consistency and publish readiness | | BLUEPRINT_EXTRACTOR_LIVE_E2E=1 npm run test:live | Full end-to-end against a running editor |

The live suite exercises texture/mesh import via HTTP fixtures, material authoring workflows, Enhanced Input round-trips, widget authoring, and project-control round-trips.

The UE runner keeps two explicit lanes:

• headless/default: BlueprintExtractor with -NullRHI
• rendered verification: targeted filters with -NoNullRHI and optional -AllowSoftwareRendering

Further Reading

• Repository & UE Plugin
• MCP v2 Reference
• Widget Motion Authoring
• Motion Verification Workflow
• Prompt Catalog