blueprint-extractor-mcp 3.2.0 → 3.3.0

package/dist/catalogs/example-catalog.js

@@ -482,4 +482,92 @@ export const exampleCatalog = {
             },
         ],
     },
+    state_tree_bindings: {
+        summary: 'Wire task outputs to task inputs using property path bindings. Extract an existing StateTree to discover structIds and property names, then use binding operations to set up data flow.',
+        recommended_flow: [
+            'extract_asset (discover structIds and property names)',
+            'modify_state_tree (add_binding / set_bindings)',
+            'extract_asset (verify bindings)',
+            'save_assets',
+        ],
+        examples: [
+            {
+                title: 'add_single_binding',
+                tool: 'modify_state_tree',
+                arguments: {
+                    asset_path: '/Game/AI/ST_Character',
+                    operation: 'add_binding',
+                    payload: {
+                        sourcePath: {
+                            structId: 'EAB9611F4B07D7E2C25A948AFC790A50',
+                            segments: [{ name: 'SelectedGestureTag' }],
+                        },
+                        targetPath: {
+                            structId: 'F2A3B44C4D08E6A1C25A948AFC790A50',
+                            segments: [{ name: 'MontageTag' }],
+                        },
+                    },
+                },
+                context: { description: 'Wire SelectRandomGesture output → PlayMontage input. structIds from extract_asset output.' },
+            },
+            {
+                title: 'set_all_bindings',
+                tool: 'modify_state_tree',
+                arguments: {
+                    asset_path: '/Game/AI/ST_Character',
+                    operation: 'set_bindings',
+                    payload: {
+                        propertyBindings: [
+                            {
+                                sourcePath: { segments: [{ name: 'SelectedTag' }] },
+                                targetPath: { segments: [{ name: 'MontageTag' }] },
+                            },
+                            {
+                                sourcePath: { segments: [{ name: 'Duration' }] },
+                                targetPath: { segments: [{ name: 'WaitTime' }] },
+                            },
+                        ],
+                    },
+                },
+                context: { description: 'Replace all bindings on the StateTree with a new set.' },
+            },
+            {
+                title: 'remove_binding_by_target',
+                tool: 'modify_state_tree',
+                arguments: {
+                    asset_path: '/Game/AI/ST_Character',
+                    operation: 'remove_binding',
+                    payload: {
+                        targetPath: { segments: [{ name: 'MontageTag' }] },
+                    },
+                },
+                context: { description: 'Remove all bindings targeting the MontageTag property.' },
+            },
+            {
+                title: 'create_with_bindings',
+                tool: 'create_state_tree',
+                arguments: {
+                    asset_path: '/Game/AI/ST_NewWithBindings',
+                    payload: {
+                        schema: '/Script/GameplayStateTreeModule.StateTreeComponentSchema',
+                        states: [{
+                                name: 'Root',
+                                type: 'State',
+                                tasks: [
+                                    { nodeStructType: '/Script/MyMod.STCSelectGesture', name: 'SelectGesture' },
+                                    { nodeStructType: '/Script/MyMod.STCPlayMontage', name: 'PlayMontage' },
+                                ],
+                            }],
+                        bindings: {
+                            propertyBindings: [{
+                                    sourcePath: { segments: [{ name: 'SelectedGestureTag' }] },
+                                    targetPath: { segments: [{ name: 'MontageTag' }] },
+                                }],
+                        },
+                    },
+                },
+                context: { description: 'Create a StateTree with tasks and bindings in a single call.' },
+            },
+        ],
+    },
 };

package/dist/helpers/live-coding.js

@@ -36,6 +36,10 @@ export function enrichLiveCodingResult(result, changedPaths = [], lastExternalBu
         warnings.push('Live Coding cannot add, remove, or reorder UPROPERTYs or change class layouts. '
             + 'Use compile_project_code + restart_editor for class layout changes.');
     }
+    if (result.noOp && typeof result.compileResult === 'string' && result.compileResult.toLowerCase() === 'nochanges') {
+        warnings.push('Live Coding cannot compile newly added source files — it only detects changes to already-compiled .obj files. '
+            + 'Use compile_project_code for new files, then restart_editor to load the new module.');
+    }
     const fallbackRecommended = canFallbackFromLiveCoding(result);
     const reason = deriveLiveCodingFallbackReason(result);
     return {

package/dist/helpers/subsystem.js

@@ -47,13 +47,40 @@ export async function callSubsystemJson(client, method, params, options) {
     }
     return parsed;
 }
+/**
+ * Extracts the best available error message from a UE failure response,
+ * checking message, errorMessage, error, diagnostics[], and errors[] fields
+ * before falling back to listing the available response keys.
+ */
+function extractFailureMessage(parsed) {
+    if (typeof parsed.message === 'string' && parsed.message.length > 0)
+        return parsed.message;
+    if (typeof parsed.errorMessage === 'string' && parsed.errorMessage.length > 0)
+        return parsed.errorMessage;
+    if (typeof parsed.error === 'string' && parsed.error.length > 0)
+        return parsed.error;
+    if (Array.isArray(parsed.diagnostics) && parsed.diagnostics.length > 0) {
+        const messages = parsed.diagnostics
+            .filter((d) => typeof d === 'object' && d !== null && typeof d.message === 'string')
+            .map((d) => d.message);
+        if (messages.length > 0)
+            return messages.join('; ');
+    }
+    if (Array.isArray(parsed.errors) && parsed.errors.length > 0) {
+        const first = parsed.errors[0];
+        return typeof first === 'string' ? first : JSON.stringify(first);
+    }
+    const keys = Object.keys(parsed).join(', ');
+    return `Operation returned success:false with no diagnostic details. Response keys: [${keys}]`;
+}
 export function jsonToolSuccess(parsed, options = {}) {
     const structuredContent = isRecord(parsed) ? parsed : { data: parsed };
     // Guard: if the UE response indicates failure, route through error path.
     // This prevents tool handlers from accidentally passing error payloads as successes.
     if (isRecord(parsed) && parsed.success === false) {
+        const errorText = extractFailureMessage(parsed);
         return {
-            content: [{ type: 'text', text: `Error: ${typeof parsed.message === 'string' ? parsed.message : 'Operation failed'}` }],
+            content: [{ type: 'text', text: `Error: ${errorText}` }],
             structuredContent,
             isError: true,
         };

package/dist/project-controller.d.ts

@@ -51,6 +51,7 @@ export interface CompileProjectCodeResult {
     stdout?: string;
     stderr?: string;
     uhtCacheFilesDeleted?: string[];
+    compilationSucceeded: boolean;
     errorCategory?: BuildErrorCategory;
     errorSummary?: string;
     lockedFiles?: string[];
@@ -104,6 +105,10 @@ export interface ProjectControllerLike {
     readonly liveCodingSupported: boolean;
     classifyChangedPaths(changedPaths: string[], forceRebuild?: boolean): SyncStrategyPlan;
     compileProjectCode(request: CompileProjectCodeRequest): Promise<CompileProjectCodeResult>;
+    killEditorProcess(): Promise<{
+        killed: boolean;
+        error?: string;
+    }>;
     launchEditor(request: LaunchEditorRequest): Promise<LaunchEditorResult>;
     waitForEditorRestart(probeConnection: ProbeConnection, options?: {
         disconnectTimeoutMs?: number;
@@ -131,6 +136,10 @@ export declare class ProjectController implements ProjectControllerLike {
     get liveCodingSupported(): boolean;
     classifyChangedPaths(changedPaths: string[], forceRebuild?: boolean): SyncStrategyPlan;
     compileProjectCode(request: CompileProjectCodeRequest): Promise<CompileProjectCodeResult>;
+    killEditorProcess(): Promise<{
+        killed: boolean;
+        error?: string;
+    }>;
     launchEditor(request: LaunchEditorRequest): Promise<LaunchEditorResult>;
     waitForEditorRestart(probeConnection: ProbeConnection, options?: {
         disconnectTimeoutMs?: number;

package/dist/project-controller.js

@@ -1,4 +1,4 @@
-import { spawn } from 'node:child_process';
+import { execSync, spawn } from 'node:child_process';
 import { access, readdir, unlink } from 'node:fs/promises';
 import { constants as fsConstants } from 'node:fs';
 import { dirname, resolve } from 'node:path';
@@ -358,6 +358,7 @@ export class ProjectController {
             },
             durationMs: Date.now() - startedAt,
             exitCode: completed.exitCode,
+            compilationSucceeded: completed.exitCode === 0,
             restartRequired: true,
             restartReasons: ['external_build_completed'],
             outputIncluded: includeOutput,
@@ -380,9 +381,26 @@ export class ProjectController {
             if (classification.lockedFiles.length > 0) {
                 result.lockedFiles = classification.lockedFiles;
             }
+            // Compilation itself succeeded if the failure is only at the link/lock stage
+            result.compilationSucceeded = classification.errorCategory === 'locked_file'
+                || classification.errorCategory === 'link';
         }
         return result;
     }
+    async killEditorProcess() {
+        try {
+            if (this.platform === 'win32') {
+                execSync('taskkill /F /IM "UnrealEditor.exe"', { timeout: 10000 });
+            }
+            else {
+                execSync('pkill -9 -f UnrealEditor', { timeout: 10000 });
+            }
+            return { killed: true };
+        }
+        catch (err) {
+            return { killed: false, error: String(err) };
+        }
+    }
     async launchEditor(request) {
         const engineRoot = request.engineRoot ?? this.env.UE_ENGINE_ROOT;
         const projectPath = request.projectPath ?? this.env.UE_PROJECT_PATH;

package/dist/register-server-tools.js

@@ -1,7 +1,7 @@
 import { z } from 'zod';
 import { exampleCatalog } from './catalogs/example-catalog.js';
 import { collectRelatedResources, collectToolExampleFamilies as collectToolExampleFamiliesFromCatalog, summarizeOutputSchema, summarizeSchemaFields, } from './helpers/tool-help.js';
-import { AnimMontageMutationOperationSchema, AnimationNotifySelectorSchema, AnimSequenceMutationOperationSchema, BehaviorTreeMutationOperationSchema, BehaviorTreeNodeSelectorSchema, BlackboardKeySchema, BlackboardMutationOperationSchema, BlendParameterSchema, BlendSpaceMutationOperationSchema, BlendSpaceSampleSchema, BlueprintGraphMutationOperationSchema, BlueprintMemberMutationOperationSchema, BuildConfigurationSchema, BuildPlatformSchema, CurveChannelSchema, CurveKeyDeleteSchema, CurveKeyUpsertSchema, CurveTableModeSchema, CurveTableRowSchema, CurveTypeSchema, DataTableRowSchema, ExtractAssetTypeSchema, EnhancedInputValueTypeSchema, FontImportItemSchema, ImportJobListSchema, ImportJobSchema, ImportPayloadSchema, InputMappingSchema, JsonObjectSchema, MaterialConnectionSelectorFieldsSchema, MaterialFontParameterSchema, MaterialFunctionAssetKindSchema, MaterialGraphOperationKindSchema, MaterialGraphOperationSchema, MaterialGraphPayloadSchema, MaterialLayerStackSchema, MaterialNodePositionSchema, MaterialScalarParameterSchema, MaterialStaticSwitchParameterSchema, MaterialTextureParameterSchema, MaterialVectorParameterSchema, MeshImportPayloadSchema, StateTreeEditorNodeSelectorSchema, StateTreeMutationOperationSchema, StateTreeStateSelectorSchema, StateTreeTransitionSelectorSchema, StateTreeBindingSchema, TextureImportPayloadSchema, UserDefinedEnumEntrySchema, UserDefinedEnumMutationOperationSchema, UserDefinedStructFieldSchema, UserDefinedStructMutationOperationSchema, WidgetBlueprintMutationOperationSchema, WidgetNodeSchema, WidgetSelectorFieldsSchema, WindowFontApplicationSchema, } from './schemas/tool-inputs.js';
+import { AnimMontageMutationOperationSchema, AnimationNotifySelectorSchema, AnimSequenceMutationOperationSchema, BehaviorTreeMutationOperationSchema, BehaviorTreeNodeSelectorSchema, BlackboardKeySchema, BlackboardMutationOperationSchema, BlendParameterSchema, BlendSpaceMutationOperationSchema, BlendSpaceSampleSchema, BlueprintGraphMutationOperationSchema, BlueprintMemberMutationOperationSchema, BuildConfigurationSchema, BuildPlatformSchema, CurveChannelSchema, CurveKeyDeleteSchema, CurveKeyUpsertSchema, CurveTableModeSchema, CurveTableRowSchema, CurveTypeSchema, DataTableRowSchema, ExtractAssetTypeSchema, EnhancedInputValueTypeSchema, FontImportItemSchema, ImportJobListSchema, ImportJobSchema, ImportPayloadSchema, InputMappingSchema, JsonObjectSchema, MaterialConnectionSelectorFieldsSchema, MaterialFontParameterSchema, MaterialFunctionAssetKindSchema, MaterialGraphOperationKindSchema, MaterialGraphOperationSchema, MaterialGraphPayloadSchema, MaterialLayerStackSchema, MaterialNodePositionSchema, MaterialScalarParameterSchema, MaterialStaticSwitchParameterSchema, MaterialTextureParameterSchema, MaterialVectorParameterSchema, MeshImportPayloadSchema, StateTreeEditorNodeSelectorSchema, StateTreeMutationOperationSchema, StateTreeStateSelectorSchema, StateTreeTransitionSelectorSchema, StateTreeBindingsObjectSchema, TextureImportPayloadSchema, UserDefinedEnumEntrySchema, UserDefinedEnumMutationOperationSchema, UserDefinedStructFieldSchema, UserDefinedStructMutationOperationSchema, WidgetBlueprintMutationOperationSchema, WidgetNodeSchema, WidgetSelectorFieldsSchema, WindowFontApplicationSchema, } from './schemas/tool-inputs.js';
 import { applyWindowUiChangesResultSchema, AutomationRunListSchema, automationRunSchema, CaptureResultSchema, CascadeResultSchema, CleanupCapturesResultSchema, CompareCaptureResultSchema, CompareMotionCaptureBundleResultSchema, CreateModifyWidgetAnimationResultSchema, ExtractWidgetAnimationResultSchema, ListCapturesResultSchema, motionCaptureModeSchema, MotionCaptureBundleResultSchema, widgetAnimationCheckpointSchema, } from './schemas/tool-results.js';
 import { registerAnimationAuthoringTools } from './tools/animation-authoring.js';
 import { registerAutomationRunTools } from './tools/automation-runs.js';
@@ -166,7 +166,7 @@ export function registerServerTools({ server, client, projectController, automat
         stateTreeStateSelectorSchema: StateTreeStateSelectorSchema,
         stateTreeEditorNodeSelectorSchema: StateTreeEditorNodeSelectorSchema,
         stateTreeTransitionSelectorSchema: StateTreeTransitionSelectorSchema,
-        stateTreeBindingSchema: StateTreeBindingSchema,
+        stateTreeBindingsObjectSchema: StateTreeBindingsObjectSchema,
     });
     registerAnimationAuthoringTools({
         server,

package/dist/resources/static-doc-resources.js

@@ -64,7 +64,8 @@ export function registerStaticDocResources(server) {
         '- UserDefinedEnum: entry selector by name; operations replace_entries, rename_entry, remove_entry, reorder_entries.',
         '- Blackboard: key selector by entryName; operations replace_keys, patch_key, remove_key, set_parent.',
         '- BehaviorTree: node selector by nodePath; operations replace_tree, patch_node, patch_attachment, set_blackboard.',
-        '- StateTree: selectors by stateId/statePath, editorNodeId, or transitionId; operations replace_tree, patch_state, patch_editor_node, patch_transition, set_schema.',
+        '- StateTree: selectors by stateId/statePath, editorNodeId, or transitionId; operations replace_tree, patch_state, patch_editor_node, patch_transition, set_schema, set_bindings, add_binding, remove_binding. Blueprint-wrapped nodes (StateTreeBlueprintTaskWrapper / StateTreeBlueprintConditionWrapper) require instanceObjectClass for the backing instance to exist at runtime.',
+        '- StateTree property bindings wire task/evaluator outputs to task inputs. Use extract_asset to discover structIds and property names. Each binding has sourcePath and targetPath with segments: [{name, arrayIndex?, instanceStruct?}] and optional structId. Operations: set_bindings (replace all), add_binding (append), remove_binding (by targetPath). In replace_tree/create: include as { bindings: { propertyBindings: [...] } }.',
         '- AnimSequence: notify selector by notifyId/notifyGuid with notifyIndex or track metadata as fallback; operations replace_notifies, patch_notify, replace_sync_markers, replace_curve_metadata.',
         '- AnimMontage: notify selector by notifyId/notifyGuid with notifyIndex or track metadata as fallback; operations replace_notifies, patch_notify, replace_sections, replace_slots.',
         '- BlendSpace: sample selector by sampleIndex; operations replace_samples, patch_sample, set_axes.',