blueprint-extractor-mcp 6.0.2 → 6.0.4
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +147 -105
- package/dist/helpers/subsystem.js +2 -0
- package/dist/server-factory.js +1 -1
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,154 +1,196 @@
|
|
|
1
|
-
|
|
1
|
+
<p align="center">
|
|
2
|
+
<h1 align="center">Blueprint Extractor MCP</h1>
|
|
3
|
+
<p align="center">
|
|
4
|
+
Give AI assistants full read/write access to Unreal Engine projects<br>
|
|
5
|
+
through a live editor connection.
|
|
6
|
+
</p>
|
|
7
|
+
</p>
|
|
2
8
|
|
|
3
|
-
>
|
|
9
|
+
<p align="center">
|
|
10
|
+
<a href="https://www.npmjs.com/package/blueprint-extractor-mcp"><img src="https://img.shields.io/npm/v/blueprint-extractor-mcp?style=flat-square&color=cb3837" alt="npm"></a>
|
|
11
|
+
<a href="https://nodejs.org"><img src="https://img.shields.io/badge/node-%E2%89%A518-339933?style=flat-square&logo=node.js&logoColor=white" alt="Node.js"></a>
|
|
12
|
+
<a href="https://modelcontextprotocol.io"><img src="https://img.shields.io/badge/MCP_SDK-1.12-5A67D8?style=flat-square" alt="MCP SDK"></a>
|
|
13
|
+
<a href="https://github.com/SunGrow/ue-blueprint-extractor/blob/master/LICENSE"><img src="https://img.shields.io/github/license/SunGrow/ue-blueprint-extractor?style=flat-square" alt="License"></a>
|
|
14
|
+
</p>
|
|
4
15
|
|
|
5
|
-
|
|
6
|
-
[](https://nodejs.org)
|
|
7
|
-
[](https://modelcontextprotocol.io)
|
|
8
|
-
[](https://github.com/SunGrow/ue-blueprint-extractor/blob/master/LICENSE)
|
|
16
|
+
<br>
|
|
9
17
|
|
|
10
|
-
|
|
18
|
+
## Overview
|
|
11
19
|
|
|
12
|
-
|
|
13
|
-
- widget, material, Blueprint, AI, data, and input authoring
|
|
14
|
-
- asset import with async job tracking
|
|
15
|
-
- visual capture and motion verification
|
|
16
|
-
- compile, live coding, editor restart, and automation execution
|
|
20
|
+
Blueprint Extractor MCP is a [Model Context Protocol](https://modelcontextprotocol.io) server that bridges AI coding assistants (Claude Code, Codex, etc.) to a running Unreal Editor instance via the Remote Control HTTP API.
|
|
17
21
|
|
|
18
|
-
|
|
22
|
+
```
|
|
23
|
+
AI Assistant stdio MCP Server HTTP :30010 Unreal Editor
|
|
24
|
+
───────────── ◄────────────► ───────────────── ◄──────────────────► ─────────────────
|
|
25
|
+
Claude Code Node.js process Remote Control API
|
|
26
|
+
Codex 89 tools BlueprintExtractor
|
|
27
|
+
... 4 resource templates plugin
|
|
28
|
+
8 prompts
|
|
29
|
+
```
|
|
30
|
+
|
|
31
|
+
**What the assistant can do through this server:**
|
|
32
|
+
|
|
33
|
+
| Capability | Examples |
|
|
34
|
+
|:-----------|:---------|
|
|
35
|
+
| **Extract** | Read Blueprints, widgets, materials, animations, data assets, state trees, and more |
|
|
36
|
+
| **Author** | Create and modify widgets, materials, Blueprints, input actions, AI assets, data tables |
|
|
37
|
+
| **Build** | Compile project code, trigger Live Coding, restart the editor, sync changes |
|
|
38
|
+
| **Import** | Bring in textures, meshes, and generic assets with async job polling |
|
|
39
|
+
| **Test** | Run UE automation tests, collect results and artifacts |
|
|
40
|
+
| **Verify** | Capture widget screenshots, compare against references, inspect motion checkpoints |
|
|
19
41
|
|
|
20
|
-
|
|
21
|
-
|---|---:|
|
|
22
|
-
| Tools | 90 |
|
|
23
|
-
| Resources | 16 |
|
|
24
|
-
| Resource templates | 4 |
|
|
25
|
-
| Prompts | 8 |
|
|
42
|
+
<br>
|
|
26
43
|
|
|
27
44
|
## Quick Start
|
|
28
45
|
|
|
29
|
-
###
|
|
46
|
+
### Prerequisites
|
|
30
47
|
|
|
31
|
-
|
|
32
|
-
|---|---|
|
|
33
|
-
| Node.js | 18+ |
|
|
34
|
-
| Unreal Editor | Running with Remote Control enabled |
|
|
35
|
-
| BlueprintExtractor plugin | Installed in the target UE project |
|
|
48
|
+
You need three things running:
|
|
36
49
|
|
|
37
|
-
|
|
50
|
+
1. **Node.js 18+**
|
|
51
|
+
2. **Unreal Editor** with the **Remote Control API** plugin enabled
|
|
52
|
+
3. **[BlueprintExtractor](https://github.com/SunGrow/ue-blueprint-extractor)** plugin installed in your project
|
|
53
|
+
|
|
54
|
+
### Run
|
|
38
55
|
|
|
39
56
|
```bash
|
|
40
57
|
npx blueprint-extractor-mcp
|
|
41
58
|
```
|
|
42
59
|
|
|
43
|
-
|
|
60
|
+
Connects to the editor at `127.0.0.1:30010` by default.
|
|
61
|
+
|
|
62
|
+
### Add to Your AI Client
|
|
44
63
|
|
|
45
|
-
|
|
64
|
+
<table>
|
|
65
|
+
<tr><td><b>Claude Code</b></td></tr>
|
|
66
|
+
<tr><td>
|
|
46
67
|
|
|
47
68
|
```bash
|
|
48
|
-
|
|
49
|
-
|
|
69
|
+
claude mcp add -s user -t stdio blueprint-extractor \
|
|
70
|
+
-e UE_REMOTE_CONTROL_PORT=30010 \
|
|
71
|
+
-- npx -y blueprint-extractor-mcp@latest
|
|
72
|
+
```
|
|
50
73
|
|
|
51
|
-
|
|
52
|
-
|
|
74
|
+
</td></tr>
|
|
75
|
+
<tr><td><b>Codex</b></td></tr>
|
|
76
|
+
<tr><td>
|
|
77
|
+
|
|
78
|
+
```bash
|
|
79
|
+
codex mcp add --env UE_REMOTE_CONTROL_PORT=30010 \
|
|
80
|
+
blueprint-extractor -- npx -y blueprint-extractor-mcp@latest
|
|
53
81
|
```
|
|
54
82
|
|
|
55
|
-
|
|
83
|
+
</td></tr>
|
|
84
|
+
</table>
|
|
85
|
+
|
|
86
|
+
> On Windows, wrap `npx` with `cmd /c` if your shell requires it.
|
|
87
|
+
|
|
88
|
+
<br>
|
|
56
89
|
|
|
57
90
|
## Tool Surface
|
|
58
91
|
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
| Scope | Focus |
|
|
62
|
-
|---|---|
|
|
63
|
-
| Core | Search, extract, save, help, verification entry points |
|
|
64
|
-
| `widget_authoring` | Widget tree work, compile flows, CommonUI |
|
|
65
|
-
| `material_authoring` | Material graphs, settings, instances |
|
|
66
|
-
| `blueprint_authoring` | Blueprint creation and patching |
|
|
67
|
-
| `schema_ai_authoring` | StateTree, BehaviorTree, Blackboard, enums, structs |
|
|
68
|
-
| `animation_authoring` | Anim sequences, montages, blend spaces, widget motion |
|
|
69
|
-
| `data_tables` | Data assets, tables, curves, input assets |
|
|
70
|
-
| `import` | Import jobs and job inspection |
|
|
71
|
-
| `automation_testing` | Automation runs and artifacts |
|
|
72
|
-
| `verification` | Captures, comparisons, motion verification |
|
|
73
|
-
|
|
74
|
-
Representative tools:
|
|
75
|
-
|
|
76
|
-
```text
|
|
77
|
-
extract_asset
|
|
78
|
-
find_and_extract
|
|
79
|
-
search_assets
|
|
80
|
-
material_graph_operation
|
|
81
|
-
capture_widget_preview
|
|
82
|
-
compare_motion_capture_bundle
|
|
83
|
-
compile_project_code
|
|
84
|
-
sync_project_code
|
|
85
|
-
run_automation_tests
|
|
86
|
-
get_tool_help
|
|
87
|
-
```
|
|
92
|
+
Only **~13 core tools** are visible by default to keep the context window lean. Specialized families are loaded on demand via `activate_workflow_scope`.
|
|
88
93
|
|
|
89
|
-
|
|
94
|
+
| Scope | Tools | What It Unlocks |
|
|
95
|
+
|:------|------:|:----------------|
|
|
96
|
+
| **Core** *(always on)* | ~13 | `extract_asset` `search_assets` `save_assets` `get_tool_help` `find_and_extract` |
|
|
97
|
+
| `widget_authoring` | 25 | Widget tree ops, compile, CommonUI button styles, widget animations, visual captures |
|
|
98
|
+
| `material_authoring` | 5 | `create_material` `modify_material` `material_graph_operation` + instances |
|
|
99
|
+
| `blueprint_authoring` | 4 | Blueprint members, graphs, `trigger_live_coding` |
|
|
100
|
+
| `schema_ai_authoring` | 11 | Structs, enums, Blackboards, Behavior Trees, State Trees |
|
|
101
|
+
| `animation_authoring` | 7 | Anim sequences, montages, blend spaces, widget motion |
|
|
102
|
+
| `data_tables` | 7 | Data assets, data tables, curves, Enhanced Input actions & mappings |
|
|
103
|
+
| `import` | 3 | `import_assets` with texture/mesh options, job polling |
|
|
104
|
+
| `automation_testing` | 4 | `run_automation_tests` + run inspection and artifact retrieval |
|
|
105
|
+
| `verification` | 7 | Widget captures, motion checkpoint bundles, reference comparisons |
|
|
90
106
|
|
|
91
|
-
|
|
107
|
+
### Contract Design
|
|
92
108
|
|
|
93
|
-
|
|
94
|
-
- `outputSchema` on public tools
|
|
95
|
-
- structured success and error envelopes
|
|
96
|
-
- explicit-save semantics
|
|
97
|
-
- reusable resources and prompts for guidance-heavy workflows
|
|
109
|
+
The tool contract is optimized for model reliability:
|
|
98
110
|
|
|
99
|
-
|
|
111
|
+
- **`snake_case`** inputs on all public tools
|
|
112
|
+
- **`outputSchema`** on every tool for structured JSON responses
|
|
113
|
+
- **`structuredContent`** carries the canonical success and error payload for MCP clients that consume structured results directly
|
|
114
|
+
- **Structured error envelopes** with diagnostic codes and recovery hints
|
|
115
|
+
- **Explicit-save semantics** — nothing persists until `save_assets` is called
|
|
116
|
+
- **Next-step hints** guiding the assistant toward the logical follow-up action
|
|
100
117
|
|
|
101
|
-
|
|
102
|
-
- [MCP v2 Reference](../docs/mcp-v2-reference.md)
|
|
103
|
-
- [Prompt Catalog](../docs/prompt-catalog.md)
|
|
104
|
-
- [Widget Motion Authoring](../docs/widget-motion-authoring.md)
|
|
105
|
-
- [Motion Verification Workflow](../docs/motion-verification-workflow.md)
|
|
118
|
+
<br>
|
|
106
119
|
|
|
107
|
-
##
|
|
120
|
+
## Configuration
|
|
108
121
|
|
|
109
|
-
| Variable | Default |
|
|
110
|
-
|
|
111
|
-
| `UE_REMOTE_CONTROL_HOST` | `127.0.0.1` |
|
|
112
|
-
| `UE_REMOTE_CONTROL_PORT` | `30010` | Remote Control port |
|
|
113
|
-
| `UE_BLUEPRINT_EXTRACTOR_SUBSYSTEM_PATH` | auto-probe |
|
|
114
|
-
| `UE_ENGINE_ROOT` |
|
|
115
|
-
| `UE_PROJECT_PATH` |
|
|
116
|
-
| `UE_PROJECT_TARGET`
|
|
122
|
+
| Variable | Default | Purpose |
|
|
123
|
+
|:---------|:--------|:--------|
|
|
124
|
+
| `UE_REMOTE_CONTROL_HOST` | `127.0.0.1` | Editor host address |
|
|
125
|
+
| `UE_REMOTE_CONTROL_PORT` | `30010` | Editor Remote Control port |
|
|
126
|
+
| `UE_BLUEPRINT_EXTRACTOR_SUBSYSTEM_PATH` | *auto-probe* | Force a specific subsystem object path |
|
|
127
|
+
| `UE_ENGINE_ROOT` | — | Engine root (needed for builds & automation) |
|
|
128
|
+
| `UE_PROJECT_PATH` | — | Path to your `.uproject` |
|
|
129
|
+
| `UE_PROJECT_TARGET` | — | Build target name (or `UE_EDITOR_TARGET`) |
|
|
130
|
+
| `UE_BUILD_PLATFORM` | — | e.g. `Win64` |
|
|
131
|
+
| `UE_BUILD_CONFIGURATION` | — | e.g. `Development` |
|
|
117
132
|
|
|
118
|
-
|
|
133
|
+
<br>
|
|
119
134
|
|
|
120
|
-
|
|
135
|
+
## Resources & Prompts
|
|
121
136
|
|
|
122
|
-
|
|
137
|
+
Beyond tools, the server exposes **MCP resources** for reference data and **prompts** for guided multi-step workflows.
|
|
123
138
|
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
blueprint://
|
|
128
|
-
blueprint://
|
|
139
|
+
### Resource Templates
|
|
140
|
+
|
|
141
|
+
```
|
|
142
|
+
blueprint://examples/{family} Example payloads for each tool family
|
|
143
|
+
blueprint://widget-patterns/{pattern} Reusable widget-tree patterns
|
|
144
|
+
blueprint://captures/{capture_id} Captured widget screenshots
|
|
145
|
+
blueprint://test-runs/{run_id}/{artifact} Automation test artifacts
|
|
129
146
|
```
|
|
130
147
|
|
|
131
|
-
|
|
148
|
+
### Prompts
|
|
132
149
|
|
|
133
|
-
|
|
150
|
+
| Prompt | Guides the assistant through... |
|
|
151
|
+
|:-------|:-------------------------------|
|
|
152
|
+
| `normalize_ui_design_input` | Converting text/image/Figma/HTML into a shared `design_spec_json` |
|
|
153
|
+
| `design_menu_from_design_spec` | Planning a full menu implementation from a normalized spec |
|
|
154
|
+
| `design_menu_screen` | Safe widget redesign with pre-flight inspection |
|
|
155
|
+
| `author_material_button_style` | Composable material authoring for button states |
|
|
156
|
+
| `author_widget_motion_from_design_spec` | Turning motion specs into animation authoring steps |
|
|
157
|
+
| `plan_widget_motion_verification` | Keyframe-bundle verification planning |
|
|
158
|
+
| `wire_hud_widget_classes` | Class-default wiring for HUD assets |
|
|
159
|
+
| `debug_widget_compile_errors` | Diagnosing and recovering from compile failures |
|
|
160
|
+
|
|
161
|
+
<br>
|
|
162
|
+
|
|
163
|
+
## Development
|
|
134
164
|
|
|
135
165
|
```bash
|
|
136
166
|
cd MCP
|
|
137
167
|
npm install
|
|
138
168
|
npm run build
|
|
139
|
-
npm test
|
|
169
|
+
npm test # unit + stdio integration
|
|
140
170
|
```
|
|
141
171
|
|
|
142
|
-
|
|
172
|
+
| Command | What It Validates |
|
|
173
|
+
|:--------|:------------------|
|
|
174
|
+
| `npm run test:pack-smoke` | Packaged tarball contract and README inclusion |
|
|
175
|
+
| `npm run test:publish-gate` | Version consistency and publish readiness |
|
|
176
|
+
| `BLUEPRINT_EXTRACTOR_LIVE_E2E=1 npm run test:live` | Full end-to-end against a running editor |
|
|
177
|
+
|
|
178
|
+
The live suite exercises texture/mesh import via HTTP fixtures, material authoring workflows, Enhanced Input round-trips, and asset persistence.
|
|
179
|
+
|
|
180
|
+
<br>
|
|
181
|
+
|
|
182
|
+
## Further Reading
|
|
183
|
+
|
|
184
|
+
- [Repository & UE Plugin](https://github.com/SunGrow/ue-blueprint-extractor)
|
|
185
|
+
- [MCP v2 Reference](../docs/mcp-v2-reference.md)
|
|
186
|
+
- [Widget Motion Authoring](../docs/widget-motion-authoring.md)
|
|
187
|
+
- [Motion Verification Workflow](../docs/motion-verification-workflow.md)
|
|
188
|
+
- [Prompt Catalog](../docs/prompt-catalog.md)
|
|
143
189
|
|
|
144
|
-
|
|
145
|
-
|---|---|
|
|
146
|
-
| `npm run test:pack-smoke` | Validate the packaged tarball |
|
|
147
|
-
| `npm run test:publish-gate` | Publish readiness checks |
|
|
148
|
-
| `BLUEPRINT_EXTRACTOR_LIVE_E2E=1 npm run test:live` | Live end-to-end editor validation |
|
|
190
|
+
<br>
|
|
149
191
|
|
|
150
|
-
|
|
192
|
+
---
|
|
151
193
|
|
|
152
|
-
|
|
153
|
-
-
|
|
154
|
-
|
|
194
|
+
<p align="center">
|
|
195
|
+
<a href="https://www.npmjs.com/package/blueprint-extractor-mcp">npm</a> • <a href="https://github.com/SunGrow/ue-blueprint-extractor/issues">Issues</a> • <a href="https://github.com/SunGrow/ue-blueprint-extractor">GitHub</a>
|
|
196
|
+
</p>
|
|
@@ -62,6 +62,8 @@ function extractFailureMessage(parsed) {
|
|
|
62
62
|
return parsed.errorMessage;
|
|
63
63
|
if (typeof parsed.error === 'string' && parsed.error.length > 0)
|
|
64
64
|
return parsed.error;
|
|
65
|
+
if (typeof parsed.errorSummary === 'string' && parsed.errorSummary.length > 0)
|
|
66
|
+
return parsed.errorSummary;
|
|
65
67
|
if (Array.isArray(parsed.diagnostics) && parsed.diagnostics.length > 0) {
|
|
66
68
|
const messages = parsed.diagnostics
|
|
67
69
|
.filter((d) => typeof d === 'object' && d !== null && typeof d.message === 'string')
|
package/dist/server-factory.js
CHANGED
|
@@ -23,7 +23,7 @@ export function createBlueprintExtractorServer(client = new UEClient(), projectC
|
|
|
23
23
|
const registeredToolMap = new Map();
|
|
24
24
|
const server = new McpServer({
|
|
25
25
|
name: 'blueprint-extractor',
|
|
26
|
-
version: '6.0.
|
|
26
|
+
version: '6.0.3',
|
|
27
27
|
}, {
|
|
28
28
|
instructions: serverInstructions,
|
|
29
29
|
});
|