blueprint-extractor-mcp 6.0.1 → 6.0.2
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 +92 -116
- package/dist/server-factory.js +1 -1
- package/dist/tools/project-control.js +4 -1
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,178 +1,154 @@
|
|
|
1
1
|
# Blueprint Extractor MCP
|
|
2
2
|
|
|
3
|
-
>
|
|
3
|
+
> MCP server for Unreal Engine projects that need real asset extraction, authoring, verification, and project automation through a running editor.
|
|
4
4
|
|
|
5
5
|
[](https://www.npmjs.com/package/blueprint-extractor-mcp)
|
|
6
6
|
[](https://nodejs.org)
|
|
7
7
|
[](https://modelcontextprotocol.io)
|
|
8
8
|
[](https://github.com/SunGrow/ue-blueprint-extractor/blob/master/LICENSE)
|
|
9
9
|
|
|
10
|
-
|
|
10
|
+
Blueprint Extractor MCP connects assistants such as Claude Code and Codex to a live Unreal Editor over the Remote Control API. It exposes a structured contract for:
|
|
11
11
|
|
|
12
|
-
|
|
12
|
+
- asset extraction
|
|
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
|
|
13
17
|
|
|
14
|
-
|
|
18
|
+
## At A Glance
|
|
15
19
|
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
All communication happens over stdio (MCP protocol) on the AI side and HTTP (Remote Control API) on the Unreal side.
|
|
23
|
-
|
|
24
|
-
---
|
|
20
|
+
| Surface | Count |
|
|
21
|
+
|---|---:|
|
|
22
|
+
| Tools | 90 |
|
|
23
|
+
| Resources | 16 |
|
|
24
|
+
| Resource templates | 4 |
|
|
25
|
+
| Prompts | 8 |
|
|
25
26
|
|
|
26
27
|
## Quick Start
|
|
27
28
|
|
|
28
|
-
###
|
|
29
|
+
### Requirements
|
|
29
30
|
|
|
30
|
-
| Requirement |
|
|
31
|
-
|
|
32
|
-
|
|
|
33
|
-
|
|
|
34
|
-
|
|
|
31
|
+
| Requirement | Notes |
|
|
32
|
+
|---|---|
|
|
33
|
+
| Node.js | 18+ |
|
|
34
|
+
| Unreal Editor | Running with Remote Control enabled |
|
|
35
|
+
| BlueprintExtractor plugin | Installed in the target UE project |
|
|
35
36
|
|
|
36
|
-
###
|
|
37
|
+
### Run directly
|
|
37
38
|
|
|
38
39
|
```bash
|
|
39
40
|
npx blueprint-extractor-mcp
|
|
40
41
|
```
|
|
41
42
|
|
|
42
|
-
The server
|
|
43
|
-
|
|
44
|
-
### 3. Install in Your AI Client
|
|
43
|
+
The server talks to the editor on `127.0.0.1:30010` by default.
|
|
45
44
|
|
|
46
|
-
|
|
45
|
+
### Register with an MCP client
|
|
47
46
|
|
|
48
47
|
```bash
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
-- npx -y blueprint-extractor-mcp@latest
|
|
52
|
-
```
|
|
53
|
-
|
|
54
|
-
**Codex:**
|
|
48
|
+
# Claude Code
|
|
49
|
+
claude mcp add -s user -t stdio blueprint-extractor -e UE_REMOTE_CONTROL_PORT=30010 -- npx -y blueprint-extractor-mcp@latest
|
|
55
50
|
|
|
56
|
-
|
|
57
|
-
codex mcp add --env UE_REMOTE_CONTROL_PORT=30010
|
|
58
|
-
blueprint-extractor -- npx -y blueprint-extractor-mcp@latest
|
|
51
|
+
# Codex
|
|
52
|
+
codex mcp add --env UE_REMOTE_CONTROL_PORT=30010 blueprint-extractor -- npx -y blueprint-extractor-mcp@latest
|
|
59
53
|
```
|
|
60
54
|
|
|
61
|
-
|
|
55
|
+
On Windows, wrap `npx` with `cmd /c`.
|
|
62
56
|
|
|
63
57
|
## Tool Surface
|
|
64
58
|
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
| Scope |
|
|
68
|
-
|
|
69
|
-
|
|
|
70
|
-
| `widget_authoring` |
|
|
71
|
-
| `material_authoring` |
|
|
72
|
-
| `blueprint_authoring` |
|
|
73
|
-
| `schema_ai_authoring` |
|
|
74
|
-
| `animation_authoring` |
|
|
75
|
-
| `data_tables` |
|
|
76
|
-
| `import` |
|
|
77
|
-
| `automation_testing` |
|
|
78
|
-
| `verification` |
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
```
|
|
83
|
-
extract_asset
|
|
84
|
-
find_and_extract
|
|
85
|
-
search_assets
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
59
|
+
The server keeps a compact default tool surface and expands into specialized workflow families with `activate_workflow_scope`.
|
|
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
|
|
91
87
|
```
|
|
92
88
|
|
|
93
|
-
|
|
89
|
+
## Contract Shape
|
|
94
90
|
|
|
95
|
-
|
|
91
|
+
The public contract is designed for model reliability:
|
|
96
92
|
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
Dual-Mode Executor
|
|
103
|
-
/ \
|
|
104
|
-
Editor Mode Commandlet Mode
|
|
105
|
-
(live editor) (headless, no UI)
|
|
106
|
-
```
|
|
93
|
+
- `snake_case` public inputs
|
|
94
|
+
- `outputSchema` on public tools
|
|
95
|
+
- structured success and error envelopes
|
|
96
|
+
- explicit-save semantics
|
|
97
|
+
- reusable resources and prompts for guidance-heavy workflows
|
|
107
98
|
|
|
108
|
-
|
|
99
|
+
Useful docs:
|
|
109
100
|
|
|
110
|
-
|
|
101
|
+
- [Repository README](../README.md)
|
|
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)
|
|
111
106
|
|
|
112
107
|
## Environment Variables
|
|
113
108
|
|
|
114
109
|
| Variable | Default | Description |
|
|
115
|
-
|
|
116
|
-
| `
|
|
117
|
-
| `
|
|
118
|
-
| `
|
|
119
|
-
| `
|
|
120
|
-
| `
|
|
121
|
-
| `
|
|
122
|
-
| `UE_BUILD_CONFIGURATION` | — | Build configuration (e.g., `Development`) |
|
|
123
|
-
|
|
124
|
-
---
|
|
110
|
+
|---|---|---|
|
|
111
|
+
| `UE_REMOTE_CONTROL_HOST` | `127.0.0.1` | Remote Control host |
|
|
112
|
+
| `UE_REMOTE_CONTROL_PORT` | `30010` | Remote Control port |
|
|
113
|
+
| `UE_BLUEPRINT_EXTRACTOR_SUBSYSTEM_PATH` | auto-probe | Explicit subsystem object path |
|
|
114
|
+
| `UE_ENGINE_ROOT` | unset | Engine root for build and automation tools |
|
|
115
|
+
| `UE_PROJECT_PATH` | unset | `.uproject` path |
|
|
116
|
+
| `UE_PROJECT_TARGET` / `UE_EDITOR_TARGET` | unset | Build target |
|
|
125
117
|
|
|
126
|
-
## Resources
|
|
118
|
+
## Resources And Prompts
|
|
127
119
|
|
|
128
|
-
The
|
|
120
|
+
The package also exposes non-tool guidance surfaces.
|
|
129
121
|
|
|
130
|
-
|
|
122
|
+
Resource templates:
|
|
131
123
|
|
|
132
|
-
```
|
|
124
|
+
```text
|
|
133
125
|
blueprint://examples/{family}
|
|
134
126
|
blueprint://widget-patterns/{pattern}
|
|
135
127
|
blueprint://captures/{capture_id}
|
|
136
128
|
blueprint://test-runs/{run_id}/{artifact}
|
|
137
129
|
```
|
|
138
130
|
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
---
|
|
131
|
+
Prompt families cover design normalization, menu authoring, widget motion authoring, and motion verification planning.
|
|
142
132
|
|
|
143
133
|
## Local Development
|
|
144
134
|
|
|
145
135
|
```bash
|
|
146
136
|
cd MCP
|
|
147
137
|
npm install
|
|
148
|
-
npm run build
|
|
149
|
-
npm test
|
|
138
|
+
npm run build
|
|
139
|
+
npm test
|
|
150
140
|
```
|
|
151
141
|
|
|
152
|
-
|
|
153
|
-
|
|
154
|
-
| Command | What It Tests |
|
|
155
|
-
|---------|---------------|
|
|
156
|
-
| `npm run test:pack-smoke` | Packaged tarball contract and README inclusion |
|
|
157
|
-
| `npm run test:publish-gate` | Publish readiness for the current version |
|
|
158
|
-
| `BLUEPRINT_EXTRACTOR_LIVE_E2E=1 npm run test:live` | Full live E2E against a running editor |
|
|
159
|
-
|
|
160
|
-
The live suite exercises texture/mesh import over HTTP fixtures, material authoring workflows, Enhanced Input round-trips, and asset saving.
|
|
161
|
-
|
|
162
|
-
---
|
|
163
|
-
|
|
164
|
-
## Migration from v3/v4
|
|
165
|
-
|
|
166
|
-
| Before | Now |
|
|
167
|
-
|--------|-----|
|
|
168
|
-
| Individual `extract_<type>` tools | `extract_asset` with `asset_type` parameter |
|
|
169
|
-
| `set_material_settings`, `add_material_expression`, etc. | `material_graph_operation` with `operation` |
|
|
170
|
-
| Need parameter docs? | `get_tool_help` for any tool |
|
|
142
|
+
Additional suites:
|
|
171
143
|
|
|
172
|
-
|
|
144
|
+
| Command | Purpose |
|
|
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 |
|
|
173
149
|
|
|
174
150
|
## Links
|
|
175
151
|
|
|
176
|
-
-
|
|
177
|
-
-
|
|
178
|
-
-
|
|
152
|
+
- [Repository](https://github.com/SunGrow/ue-blueprint-extractor)
|
|
153
|
+
- [Issues](https://github.com/SunGrow/ue-blueprint-extractor/issues)
|
|
154
|
+
- [npm package](https://www.npmjs.com/package/blueprint-extractor-mcp)
|
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.2',
|
|
27
27
|
}, {
|
|
28
28
|
instructions: serverInstructions,
|
|
29
29
|
});
|
|
@@ -19,6 +19,9 @@ function buildInputResolution(resolved) {
|
|
|
19
19
|
contextError: resolved.contextError,
|
|
20
20
|
};
|
|
21
21
|
}
|
|
22
|
+
function isAbsoluteFilesystemPath(candidate) {
|
|
23
|
+
return path.posix.isAbsolute(candidate) || path.win32.isAbsolute(candidate);
|
|
24
|
+
}
|
|
22
25
|
export function registerProjectControlTools({ server, client, projectController, callSubsystemJson, getProjectAutomationContext, resolveProjectInputs, rememberExternalBuild, getLastExternalBuildContext, clearProjectAutomationContext, buildPlatformSchema, buildConfigurationSchema, editorPollIntervalMs, }) {
|
|
23
26
|
server.registerTool('get_project_automation_context', {
|
|
24
27
|
title: 'Get Project Automation Context',
|
|
@@ -337,7 +340,7 @@ export function registerProjectControlTools({ server, client, projectController,
|
|
|
337
340
|
: '';
|
|
338
341
|
const pathWarnings = [];
|
|
339
342
|
const normalizedPaths = changed_paths.map((p) => {
|
|
340
|
-
if (
|
|
343
|
+
if (isAbsoluteFilesystemPath(p))
|
|
341
344
|
return p;
|
|
342
345
|
if (projectRoot)
|
|
343
346
|
return path.resolve(projectRoot, p);
|