blueprint-extractor-mcp 2.4.0 → 3.0.0

package/README.md

@@ -1,26 +1,33 @@
-# `blueprint-extractor-mcp`
-
-MCP server for the Unreal Engine `BlueprintExtractor` plugin.
-
-This package exposes the `blueprint-extractor` server over stdio and talks to a running Unreal Editor through the Remote Control HTTP API.
-
-The current v2 MCP contract exposes 92 tools, 12 resources, 4 resource templates, and 4 prompts.
-Public tools use canonical `snake_case` inputs and return structured JSON success or error envelopes.
-
-Current surface area includes:
-
-- read-only extraction tools for Blueprints, AI assets, data assets, curves, materials, and animation metadata
-- explicit-save authoring tools for the supported editor-side asset families, including compact widget extraction, incremental widget-structure ops, widget class-default routing, composable material authoring (`set_material_settings`, `add_material_expression`, `connect_material_expressions`, `bind_material_property`), and the advanced `modify_material` escape hatch
-- dedicated Enhanced Input authoring tools for `InputAction` and `InputMappingContext` assets (`create_input_action`, `modify_input_action`, `create_input_mapping_context`, `modify_input_mapping_context`)
-- dedicated CommonUI button-style tools (`create_commonui_button_style`, `extract_commonui_button_style`, `modify_commonui_button_style`, `apply_commonui_button_style`) for `CommonButtonBase` wrapper surfaces instead of raw `UButton` field mutation
-- async import and reimport tools with polling for generic assets plus typed texture and mesh helpers
-- host-side project automation tools for external builds, Live Coding requests, restart/reconnect orchestration, `wait_for_editor` recovery polling, a thin window-polish helper, and runtime automation artifacts that surface verification screenshots back to the caller
-- a shared visual-verification artifact contract across widget captures, capture diffs, and automation-run screenshots so the caller can inspect rendered results instead of relying on semantic success alone
-- static guidance resources, resource templates, and prompts for authoring conventions, selector rules, font roles, project automation, example payloads, widget patterns, unsupported surfaces, safe UI redesign, and classic material graph guidance
-
-## Requirements
-
-- Node.js 18+
+# `blueprint-extractor-mcp`
+
+MCP server for the Unreal Engine `BlueprintExtractor` plugin.
+
+This package exposes the `blueprint-extractor` server over stdio and talks to a running Unreal Editor through the Remote Control HTTP API.
+
+The current v3 contract exposes consolidated extraction, authoring, automation, import, verification, resource, and prompt surfaces for Blueprint Extractor workflows.
+Public tools use canonical `snake_case` inputs. Structured success payloads are returned through `structuredContent`, and non-text artifacts such as capture links or inline images may be attached in `content`.
+
+Current surface area includes:
+
+- read-only extraction tools for Blueprints, widgets, materials, and consolidated asset-family extraction through `extract_asset`
+- explicit-save authoring tools for the supported editor-side asset families, including dedicated widget animation authoring (`extract_widget_animation`, `create_widget_animation`, `modify_widget_animation`), incremental widget-structure ops, widget class-default routing, `material_graph_operation` for single-step classic material graph edits, and the advanced `modify_material` escape hatch
+- dedicated Enhanced Input authoring tools for `InputAction` and `InputMappingContext` assets (`create_input_action`, `modify_input_action`, `create_input_mapping_context`, `modify_input_mapping_context`)
+- dedicated CommonUI button-style tools (`create_commonui_button_style`, `extract_commonui_button_style`, `modify_commonui_button_style`, `apply_commonui_button_style`) for `CommonButtonBase` wrapper surfaces instead of raw `UButton` field mutation
+- utility and discovery helpers such as `search_assets`, `save_assets`, and `get_tool_help` for schema summaries, related resources, and example families
+- async import and reimport tools with polling for generic assets plus typed texture and mesh helpers
+- host-side project automation tools for external builds, Live Coding requests, restart/reconnect orchestration, `wait_for_editor` recovery polling, a thin window-polish helper, and runtime automation artifacts that surface verification screenshots back to the caller
+- a shared visual-verification artifact contract across widget captures, motion checkpoint bundles, capture diffs, and automation-run screenshots so the caller can inspect rendered results instead of relying on semantic success alone
+- static guidance resources, resource templates, and prompts for authoring conventions, selector rules, font roles, project automation, example payloads, widget patterns, multimodal design specs, widget motion authoring, motion verification, unsupported surfaces, safe UI redesign, and classic material graph guidance
+
+## Migration From Legacy Entrypoints
+
+- Use `extract_asset` with `asset_type` for the removed asset-family extract tools, including StateTree, DataAsset, DataTable, BehaviorTree, Blackboard, user-defined struct/enum, curve, curve table, material instance, anim sequence, anim montage, and blend space extraction.
+- Use `material_graph_operation` with `operation` for the removed single-step material graph tools: `set_material_settings`, `add_material_expression`, `connect_material_expressions`, and `bind_material_property`.
+- Call `get_tool_help` when you need the current parameter shape, output summary, related resources, or example families for any registered tool.
+
+## Requirements
+
+- Node.js 18+
 - Unreal Editor with the `Remote Control API` plugin enabled
 - The `BlueprintExtractor` UE plugin loaded in the editor
 
@@ -34,7 +41,7 @@ The server reads `UE_REMOTE_CONTROL_PORT` and defaults to `30010`.
 
 You can also set `UE_BLUEPRINT_EXTRACTOR_SUBSYSTEM_PATH` to force a specific subsystem object path instead of using the built-in probe list.
 
-For workflow-oriented guidance, the server also exposes prompts such as `design_menu_screen`, `author_material_button_style`, `wire_hud_widget_classes`, and `debug_widget_compile_errors`.
+For workflow-oriented guidance, the server also exposes prompts such as `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`, and `debug_widget_compile_errors`.
 
 For host-side code automation, these optional env vars are supported:
 
@@ -64,11 +71,13 @@ codex mcp add --env UE_REMOTE_CONTROL_PORT=30010 blueprint-extractor -- npx -y b
 npm install
 npm run build
 npm test
-npm run test:pack-smoke
-npm run test:publish-gate
-```
-
-For the gated live smoke test:
+npm run test:pack-smoke
+npm run test:publish-gate
+```
+
+`npm run test:pack-smoke` validates the packaged tarball contract and the packaged README. `npm run test:publish-gate` checks publish readiness for the current version.
+
+For the gated live smoke test:
 
 ```bash
 BLUEPRINT_EXTRACTOR_LIVE_E2E=1 npm run test:live
@@ -76,7 +85,7 @@ BLUEPRINT_EXTRACTOR_LIVE_E2E=1 npm run test:live
 
 The live suite imports a texture over a local HTTP fixture server, verifies request-header forwarding, imports a local mesh fixture, polls both jobs to completion, smoke-tests the composable material workflow plus material function and material instance authoring, and round-trips the dedicated Enhanced Input authoring tools before saving the returned asset paths.
 
-The default unit/stdio suites also cover prompt registration, resource-template registration, the narrowed widget surfaces (`extract_widget_blueprint`, `modify_widget`, `modify_widget_blueprint`), the host-side project-control tools (`compile_project_code`, `trigger_live_coding`, `restart_editor`, `sync_project_code`, `apply_window_ui_changes`), the compact material graph surfaces (`extract_material`, `modify_material`), and output-schema exposure for the specialized import and cascade tools.
+The default unit/stdio suites also cover prompt registration, resource-template registration, the narrowed widget surfaces (`extract_widget_blueprint`, `extract_widget_animation`, `modify_widget`, `modify_widget_blueprint`, `modify_widget_animation`), the host-side project-control tools (`compile_project_code`, `trigger_live_coding`, `restart_editor`, `sync_project_code`, `apply_window_ui_changes`), motion checkpoint capture/compare, the compact material graph surfaces (`extract_material`, `modify_material`), and output-schema exposure for the specialized import and cascade tools.
 
 Repository and full documentation:
 

package/dist/automation-controller.d.ts

@@ -74,6 +74,8 @@ export interface AutomationControllerOptions {
     now?: () => Date;
     spawnProcess?: typeof spawn;
     resolveEditorCommand?: (engineRoot: string, platform: NodeJS.Platform) => Promise<string>;
+    maxRunHistory?: number;
+    terminalRunRetentionMs?: number;
 }
 export declare class AutomationController implements AutomationControllerLike {
     private readonly env;
@@ -81,6 +83,8 @@ export declare class AutomationController implements AutomationControllerLike {
     private readonly now;
     private readonly spawnProcess;
     private readonly resolveEditorCommandFn;
+    private readonly maxRunHistory;
+    private readonly terminalRunRetentionMs;
     private readonly runs;
     constructor(options?: AutomationControllerOptions);
     runAutomationTests(request: RunAutomationTestsRequest): Promise<AutomationRunResult>;
@@ -88,6 +92,8 @@ export declare class AutomationController implements AutomationControllerLike {
     listAutomationTestRuns(includeCompleted?: boolean): Promise<AutomationRunListResult>;
     readAutomationArtifact(runId: string, artifactName: string): Promise<AutomationArtifactReadResult | null>;
     private cloneRun;
+    private getRunSortTime;
+    private pruneRuns;
     private registerArtifact;
     private collectReportArtifacts;
     private buildRunSummary;

package/dist/automation-controller.js

@@ -5,6 +5,8 @@ import { createWriteStream } from 'node:fs';
 import { dirname, extname, join, relative, resolve } from 'node:path';
 import { resolveCommandInvocation, resolveEditorExecutable } from './project-controller.js';
 const DEFAULT_TIMEOUT_MS = 60 * 60 * 1000;
+const DEFAULT_MAX_RUN_HISTORY = 50;
+const DEFAULT_TERMINAL_RUN_RETENTION_MS = 24 * 60 * 60 * 1000;
 function defaultNow() {
     return new Date();
 }
@@ -96,6 +98,8 @@ export class AutomationController {
     now;
     spawnProcess;
     resolveEditorCommandFn;
+    maxRunHistory;
+    terminalRunRetentionMs;
     runs = new Map();
     constructor(options = {}) {
         this.env = options.env ?? process.env;
@@ -103,6 +107,8 @@ export class AutomationController {
         this.now = options.now ?? defaultNow;
         this.spawnProcess = options.spawnProcess ?? spawn;
         this.resolveEditorCommandFn = options.resolveEditorCommand ?? resolveEditorCommand;
+        this.maxRunHistory = Math.max(1, options.maxRunHistory ?? DEFAULT_MAX_RUN_HISTORY);
+        this.terminalRunRetentionMs = Math.max(0, options.terminalRunRetentionMs ?? DEFAULT_TERMINAL_RUN_RETENTION_MS);
     }
     async runAutomationTests(request) {
         if (!request.engineRoot) {
@@ -164,6 +170,7 @@ export class AutomationController {
             artifactMap: new Map(),
         };
         this.runs.set(runId, run);
+        this.pruneRuns(started.getTime());
         const stdoutStream = createWriteStream(stdoutPath, { encoding: 'utf8' });
         const stderrStream = createWriteStream(stderrPath, { encoding: 'utf8' });
         const child = this.spawnProcess(invocation.executable, invocation.args, {
@@ -217,6 +224,7 @@ export class AutomationController {
             }, null, 2), 'utf8');
             this.registerArtifact(run, 'summary', summaryPath, 'application/json');
             run.terminal = true;
+            this.pruneRuns(this.now().getTime());
         };
         const timeoutHandle = setTimeout(() => {
             if (!run.terminal) {
@@ -242,10 +250,12 @@ export class AutomationController {
         return this.cloneRun(run, 'run_automation_tests');
     }
     async getAutomationTestRun(runId) {
+        this.pruneRuns(this.now().getTime());
         const run = this.runs.get(runId);
         return run ? this.cloneRun(run, 'get_automation_test_run') : null;
     }
     async listAutomationTestRuns(includeCompleted = true) {
+        this.pruneRuns(this.now().getTime());
         const runs = Array.from(this.runs.values())
             .filter((run) => includeCompleted || !run.terminal)
             .sort((left, right) => {
@@ -263,6 +273,7 @@ export class AutomationController {
         };
     }
     async readAutomationArtifact(runId, artifactName) {
+        this.pruneRuns(this.now().getTime());
         const run = this.runs.get(runId);
         if (!run) {
             return null;
@@ -284,6 +295,46 @@ export class AutomationController {
             artifacts: [...run.artifacts],
         };
     }
+    getRunSortTime(run) {
+        if (run.completedAt) {
+            const completedAt = Date.parse(run.completedAt);
+            if (Number.isFinite(completedAt)) {
+                return completedAt;
+            }
+        }
+        if (run.startedAt) {
+            const startedAt = Date.parse(run.startedAt);
+            if (Number.isFinite(startedAt)) {
+                return startedAt;
+            }
+        }
+        return 0;
+    }
+    pruneRuns(referenceTime) {
+        const terminalRuns = [];
+        for (const [runId, run] of this.runs.entries()) {
+            if (!run.terminal) {
+                continue;
+            }
+            const sortTime = this.getRunSortTime(run);
+            if (this.terminalRunRetentionMs >= 0 && sortTime > 0 && referenceTime - sortTime > this.terminalRunRetentionMs) {
+                this.runs.delete(runId);
+                continue;
+            }
+            terminalRuns.push({ runId, run, sortTime });
+        }
+        const activeRunCount = Array.from(this.runs.values()).filter((run) => !run.terminal).length;
+        const allowedTerminalRuns = Math.max(0, this.maxRunHistory - activeRunCount);
+        if (terminalRuns.length <= allowedTerminalRuns) {
+            return;
+        }
+        terminalRuns
+            .sort((left, right) => right.sortTime - left.sortTime)
+            .slice(allowedTerminalRuns)
+            .forEach(({ runId }) => {
+            this.runs.delete(runId);
+        });
+    }
     registerArtifact(run, name, filePath, mimeType, relativePath) {
         const existing = run.artifactMap.get(name);
         const artifact = {

package/dist/catalogs/example-catalog.d.ts

@@ -0,0 +1,13 @@
+export type ToolExample = {
+    title: string;
+    tool: string;
+    arguments: Record<string, unknown>;
+    context?: Record<string, unknown>;
+    expectedSuccess?: boolean;
+};
+export type ExampleFamily = {
+    summary: string;
+    recommended_flow: string[];
+    examples: ToolExample[];
+};
+export declare const exampleCatalog: Record<string, ExampleFamily>;