blueprint-extractor-mcp 3.1.0 → 3.2.0

package/dist/helpers/subsystem.js

@@ -6,7 +6,9 @@ export async function callSubsystemJson(client, method, params, options) {
     }
     const parsed = JSON.parse(result);
     if (typeof parsed.error === 'string' && parsed.error.length > 0) {
-        throw new Error(parsed.error);
+        const err = new Error(parsed.error);
+        err.ueResponse = parsed;
+        throw err;
     }
     // Check for error-only failure responses (success: false with an explicit error message
     // but no business-level fields). Structured responses with success: false are passed
@@ -14,12 +16,31 @@ export async function callSubsystemJson(client, method, params, options) {
     if (parsed.success === false) {
         const explicitMessage = parsed.message ?? parsed.errorMessage;
         if (typeof explicitMessage === 'string' && explicitMessage.length > 0) {
-            throw new Error(explicitMessage);
+            const err = new Error(explicitMessage);
+            err.ueResponse = parsed;
+            throw err;
         }
     }
+    // Catch structured error responses with diagnostics but no explicit message.
+    // These come from FAssetMutationContext.BuildResult(false) in the C++ plugin.
+    if (parsed.success === false
+        && 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);
+        const synthesized = messages.length > 0
+            ? messages.join('; ')
+            : `Operation failed with ${parsed.diagnostics.length} diagnostic(s)`;
+        const err = new Error(synthesized);
+        err.ueResponse = parsed;
+        throw err;
+    }
     if (Array.isArray(parsed.errors) && parsed.errors.length > 0) {
         const firstError = parsed.errors[0];
-        throw new Error(typeof firstError === 'string' ? firstError : JSON.stringify(firstError));
+        const err = new Error(typeof firstError === 'string' ? firstError : JSON.stringify(firstError));
+        err.ueResponse = parsed;
+        throw err;
     }
     if (Object.keys(parsed).length === 0) {
         throw new Error('Empty response from subsystem');
@@ -28,6 +49,15 @@ export async function callSubsystemJson(client, method, params, options) {
 }
 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) {
+        return {
+            content: [{ type: 'text', text: `Error: ${typeof parsed.message === 'string' ? parsed.message : 'Operation failed'}` }],
+            structuredContent,
+            isError: true,
+        };
+    }
     return {
         content: options.extraContent ? [...options.extraContent] : [],
         structuredContent,

package/dist/helpers/tool-results.js

@@ -65,6 +65,15 @@ export function createToolResultNormalizers({ taskAwareTools, classifyRecoverabl
         const diagnostics = Array.isArray(payload.diagnostics)
             ? payload.diagnostics
             : [];
+        // Merge diagnostics from ueResponse if the error carries one (set by callSubsystemJson).
+        if (diagnostics.length === 0
+            && payloadOrError instanceof Error
+            && isRecord(payloadOrError.ueResponse)) {
+            const ueResp = payloadOrError.ueResponse;
+            if (Array.isArray(ueResp.diagnostics)) {
+                diagnostics.push(...ueResp.diagnostics);
+            }
+        }
         const firstDiagnostic = diagnostics.find((candidate) => (isRecord(candidate)
             && typeof candidate.message === 'string'
             && candidate.message.length > 0));

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, 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, StateTreeBindingSchema, 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,6 +166,7 @@ export function registerServerTools({ server, client, projectController, automat
         stateTreeStateSelectorSchema: StateTreeStateSelectorSchema,
         stateTreeEditorNodeSelectorSchema: StateTreeEditorNodeSelectorSchema,
         stateTreeTransitionSelectorSchema: StateTreeTransitionSelectorSchema,
+        stateTreeBindingSchema: StateTreeBindingSchema,
     });
     registerAnimationAuthoringTools({
         server,

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

@@ -68,7 +68,7 @@ export function registerStaticDocResources(server) {
         '- 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.',
-        '- Blueprint members: selectors by variableName, componentName, and functionName; operations replace_variables, patch_variable, replace_components, patch_component, replace_function_stubs, patch_class_defaults, compile.',
+        '- Blueprint members: selectors by variableName, componentName, and functionName; operations replace_variables, patch_variable, replace_components, patch_component, add_component, replace_function_stubs, patch_class_defaults, compile.',
         '- Blueprint graphs: operation upsert_function_graphs preserves unrelated graphs; append_function_call_to_sequence patches an existing sequence-style initializer without replacing the whole graph.',
         '',
         'WidgetBlueprint guidance:',

package/dist/schemas/tool-inputs.d.ts

@@ -3038,7 +3038,7 @@ export declare const StateTreeMutationOperationSchema: z.ZodEnum<["replace_tree"
 export declare const AnimSequenceMutationOperationSchema: z.ZodEnum<["replace_notifies", "patch_notify", "replace_sync_markers", "replace_curve_metadata"]>;
 export declare const AnimMontageMutationOperationSchema: z.ZodEnum<["replace_notifies", "patch_notify", "replace_sections", "replace_slots"]>;
 export declare const BlendSpaceMutationOperationSchema: z.ZodEnum<["replace_samples", "patch_sample", "set_axes"]>;
-export declare const BlueprintMemberMutationOperationSchema: z.ZodEnum<["replace_variables", "patch_variable", "replace_components", "patch_component", "replace_function_stubs", "patch_class_defaults", "compile"]>;
+export declare const BlueprintMemberMutationOperationSchema: z.ZodEnum<["replace_variables", "patch_variable", "replace_components", "patch_component", "add_component", "replace_function_stubs", "patch_class_defaults", "compile"]>;
 export declare const BlueprintGraphMutationOperationSchema: z.ZodEnum<["upsert_function_graphs", "append_function_call_to_sequence", "compile"]>;
 export declare const UserDefinedStructFieldSchema: z.ZodObject<{
     guid: z.ZodOptional<z.ZodString>;
@@ -3146,6 +3146,22 @@ export declare const StateTreeTransitionSelectorSchema: z.ZodObject<{
     transitionId: z.ZodOptional<z.ZodString>;
     id: z.ZodOptional<z.ZodString>;
 }, z.ZodTypeAny, "passthrough">>;
+export declare const StateTreeBindingSchema: z.ZodObject<{
+    sourceTask: z.ZodString;
+    sourceProperty: z.ZodString;
+    targetTask: z.ZodString;
+    targetProperty: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    sourceTask: string;
+    sourceProperty: string;
+    targetTask: string;
+    targetProperty: string;
+}, {
+    sourceTask: string;
+    sourceProperty: string;
+    targetTask: string;
+    targetProperty: string;
+}>;
 export declare const AnimationNotifySelectorSchema: z.ZodObject<{
     notifyId: z.ZodOptional<z.ZodString>;
     notifyGuid: z.ZodOptional<z.ZodString>;

package/dist/schemas/tool-inputs.js

@@ -359,6 +359,7 @@ export const BlueprintMemberMutationOperationSchema = z.enum([
     'patch_variable',
     'replace_components',
     'patch_component',
+    'add_component',
     'replace_function_stubs',
     'patch_class_defaults',
     'compile',
@@ -408,6 +409,12 @@ export const StateTreeTransitionSelectorSchema = z.object({
     transitionId: z.string().optional(),
     id: z.string().optional(),
 }).passthrough();
+export const StateTreeBindingSchema = z.object({
+    sourceTask: z.string().describe('Name of the source task whose output provides the value'),
+    sourceProperty: z.string().describe('Property name on the source task to read from'),
+    targetTask: z.string().describe('Name of the target task whose input receives the value'),
+    targetProperty: z.string().describe('Property name on the target task to write to'),
+}).describe('Task output-to-input binding (requires C++ plugin support — not yet implemented)');
 export const AnimationNotifySelectorSchema = z.object({
     notifyId: z.string().optional(),
     notifyGuid: z.string().optional(),

package/dist/tools/project-control.js

@@ -304,6 +304,8 @@ export function registerProjectControlTools({ server, client, projectController,
             openWorldHint: false,
         },
     }, async ({ changed_paths, force_rebuild, engine_root, project_path, target, platform, configuration, save_dirty_assets, save_asset_paths, build_timeout_seconds, disconnect_timeout_seconds, reconnect_timeout_seconds, include_output, clear_uht_cache, restart_first, }) => {
+        const stepErrors = {};
+        let currentStep = 'init';
         try {
             const resolvedProjectInputs = await resolveProjectInputs({ engine_root, project_path, target });
             // Normalize changed_paths to absolute paths
@@ -325,7 +327,6 @@ export function registerProjectControlTools({ server, client, projectController,
                     pathWarnings.push(`Normalized relative path: "${original}" → "${normalizedPaths[i]}"`);
                 }
             });
-            const stepErrors = {};
             const plan = projectController.classifyChangedPaths(normalizedPaths, force_rebuild);
             const structuredResult = {
                 success: false,
@@ -337,6 +338,7 @@ export function registerProjectControlTools({ server, client, projectController,
             if (pathWarnings.length > 0) {
                 structuredResult.pathWarnings = pathWarnings;
             }
+            currentStep = 'live_coding';
             if (plan.strategy === 'live_coding') {
                 if (!projectController.liveCodingSupported) {
                     structuredResult.plan = {
@@ -365,6 +367,7 @@ export function registerProjectControlTools({ server, client, projectController,
                             changedPaths: normalizedPaths,
                             plan,
                             liveCoding,
+                            failedStep: liveCoding.success !== true ? currentStep : undefined,
                         };
                         if (pathWarnings.length > 0)
                             lcResult.pathWarnings = pathWarnings;
@@ -381,6 +384,7 @@ export function registerProjectControlTools({ server, client, projectController,
                 }
             }
             if (restart_first) {
+                currentStep = 'pre_save';
                 if (Array.isArray(save_asset_paths) && save_asset_paths.length > 0) {
                     try {
                         const preSave = await callSubsystemJson('SaveAssets', {
@@ -393,6 +397,7 @@ export function registerProjectControlTools({ server, client, projectController,
                         // Pre-save is non-critical — continue to restart
                     }
                 }
+                currentStep = 'pre_restart';
                 try {
                     const preRestart = await callSubsystemJson('RestartEditor', {
                         bWarn: false,
@@ -404,6 +409,7 @@ export function registerProjectControlTools({ server, client, projectController,
                     if (preRestart.success === false) {
                         stepErrors.preRestart = 'RestartEditor returned success=false';
                         structuredResult.strategy = 'restart_first';
+                        structuredResult.failedStep = currentStep;
                         if (Object.keys(stepErrors).length > 0)
                             structuredResult.stepErrors = stepErrors;
                         return jsonToolSuccess(structuredResult);
@@ -413,6 +419,7 @@ export function registerProjectControlTools({ server, client, projectController,
                     stepErrors.preRestart = preRestartError instanceof Error ? preRestartError.message : String(preRestartError);
                     structuredResult.strategy = 'restart_first';
                     structuredResult.success = false;
+                    structuredResult.failedStep = currentStep;
                     if (Object.keys(stepErrors).length > 0)
                         structuredResult.stepErrors = stepErrors;
                     return jsonToolSuccess(structuredResult);
@@ -427,6 +434,7 @@ export function registerProjectControlTools({ server, client, projectController,
                     if (!preDisconnect.success) {
                         stepErrors.preDisconnect = 'Editor did not disconnect within timeout';
                         structuredResult.strategy = 'restart_first';
+                        structuredResult.failedStep = currentStep;
                         if (Object.keys(stepErrors).length > 0)
                             structuredResult.stepErrors = stepErrors;
                         return jsonToolSuccess(structuredResult);
@@ -436,11 +444,13 @@ export function registerProjectControlTools({ server, client, projectController,
                     stepErrors.preDisconnect = preDisconnectError instanceof Error ? preDisconnectError.message : String(preDisconnectError);
                     structuredResult.strategy = 'restart_first';
                     structuredResult.success = false;
+                    structuredResult.failedStep = currentStep;
                     if (Object.keys(stepErrors).length > 0)
                         structuredResult.stepErrors = stepErrors;
                     return jsonToolSuccess(structuredResult);
                 }
             }
+            currentStep = 'build';
             let build;
             try {
                 build = await projectController.compileProjectCode({
@@ -459,6 +469,7 @@ export function registerProjectControlTools({ server, client, projectController,
                 stepErrors.build = buildError instanceof Error ? buildError.message : String(buildError);
                 structuredResult.strategy = restart_first ? 'restart_first' : 'build_and_restart';
                 structuredResult.success = false;
+                structuredResult.failedStep = currentStep;
                 if (Object.keys(stepErrors).length > 0)
                     structuredResult.stepErrors = stepErrors;
                 return jsonToolSuccess(structuredResult);
@@ -466,10 +477,12 @@ export function registerProjectControlTools({ server, client, projectController,
             structuredResult.strategy = restart_first ? 'restart_first' : 'build_and_restart';
             structuredResult.build = build;
             if (!build.success) {
+                structuredResult.failedStep = currentStep;
                 if (Object.keys(stepErrors).length > 0)
                     structuredResult.stepErrors = stepErrors;
                 return jsonToolSuccess(structuredResult);
             }
+            currentStep = 'save';
             if (!restart_first && Array.isArray(save_asset_paths) && save_asset_paths.length > 0) {
                 try {
                     const saveResult = await callSubsystemJson('SaveAssets', {
@@ -478,6 +491,7 @@ export function registerProjectControlTools({ server, client, projectController,
                     structuredResult.save = saveResult;
                     if (saveResult.success === false) {
                         stepErrors.save = 'SaveAssets returned success=false';
+                        structuredResult.failedStep = currentStep;
                         if (Object.keys(stepErrors).length > 0)
                             structuredResult.stepErrors = stepErrors;
                         return jsonToolSuccess(structuredResult);
@@ -488,6 +502,7 @@ export function registerProjectControlTools({ server, client, projectController,
                     // Save is non-critical before restart — continue
                 }
             }
+            currentStep = 'restart';
             let reconnect;
             if (restart_first) {
                 try {
@@ -499,6 +514,7 @@ export function registerProjectControlTools({ server, client, projectController,
                     structuredResult.editorLaunch = launch;
                     if (!launch.success) {
                         stepErrors.editorLaunch = 'launchEditor returned success=false';
+                        structuredResult.failedStep = currentStep;
                         if (Object.keys(stepErrors).length > 0)
                             structuredResult.stepErrors = stepErrors;
                         return jsonToolSuccess(structuredResult);
@@ -507,10 +523,12 @@ export function registerProjectControlTools({ server, client, projectController,
                 catch (launchError) {
                     stepErrors.editorLaunch = launchError instanceof Error ? launchError.message : String(launchError);
                     structuredResult.success = false;
+                    structuredResult.failedStep = currentStep;
                     if (Object.keys(stepErrors).length > 0)
                         structuredResult.stepErrors = stepErrors;
                     return jsonToolSuccess(structuredResult);
                 }
+                currentStep = 'reconnect';
                 try {
                     reconnect = await projectController.waitForEditorRestart(supportsConnectionProbe(client), {
                         disconnectTimeoutMs: disconnect_timeout_seconds * 1000,
@@ -534,6 +552,7 @@ export function registerProjectControlTools({ server, client, projectController,
                     structuredResult.restartRequestSaveDirtyAssetsAccepted = save_dirty_assets;
                     if (restartRequest.success === false) {
                         stepErrors.restart = 'RestartEditor returned success=false';
+                        structuredResult.failedStep = currentStep;
                         if (Object.keys(stepErrors).length > 0)
                             structuredResult.stepErrors = stepErrors;
                         return jsonToolSuccess(structuredResult);
@@ -542,10 +561,12 @@ export function registerProjectControlTools({ server, client, projectController,
                 catch (restartError) {
                     stepErrors.restart = restartError instanceof Error ? restartError.message : String(restartError);
                     structuredResult.success = false;
+                    structuredResult.failedStep = currentStep;
                     if (Object.keys(stepErrors).length > 0)
                         structuredResult.stepErrors = stepErrors;
                     return jsonToolSuccess(structuredResult);
                 }
+                currentStep = 'reconnect';
                 try {
                     reconnect = await projectController.waitForEditorRestart(supportsConnectionProbe(client), {
                         disconnectTimeoutMs: disconnect_timeout_seconds * 1000,
@@ -572,9 +593,21 @@ export function registerProjectControlTools({ server, client, projectController,
             return jsonToolSuccess(structuredResult);
         }
         catch (error) {
-            const resolved = await resolveProjectInputs({ engine_root, project_path, target });
+            // Preserve accumulated step context even in unhandled exception path.
+            const resolved = await resolveProjectInputs({ engine_root, project_path, target }).catch(() => ({}));
             const errorMessage = error instanceof Error ? error.message : String(error);
-            return jsonToolError(explainProjectResolutionFailure(errorMessage, resolved));
+            const failurePayload = {
+                success: false,
+                operation: 'sync_project_code',
+                message: String(explainProjectResolutionFailure(errorMessage, resolved)),
+                failedStep: currentStep,
+                stepErrors,
+                changedPaths: changed_paths,
+            };
+            if (error instanceof Error && error.stack) {
+                failurePayload.stack = error.stack;
+            }
+            return jsonToolSuccess(failurePayload);
         }
     });
 }

package/dist/tools/schema-and-ai-authoring.d.ts

@@ -19,6 +19,7 @@ type RegisterSchemaAndAiAuthoringToolsOptions = {
     stateTreeStateSelectorSchema: z.ZodTypeAny;
     stateTreeEditorNodeSelectorSchema: z.ZodTypeAny;
     stateTreeTransitionSelectorSchema: z.ZodTypeAny;
+    stateTreeBindingSchema: z.ZodTypeAny;
 };
-export declare function registerSchemaAndAiAuthoringTools({ server, callSubsystemJson, jsonObjectSchema, userDefinedStructMutationOperationSchema, userDefinedStructFieldSchema, userDefinedEnumMutationOperationSchema, userDefinedEnumEntrySchema, blackboardMutationOperationSchema, blackboardKeySchema, behaviorTreeMutationOperationSchema, behaviorTreeNodeSelectorSchema, stateTreeMutationOperationSchema, stateTreeStateSelectorSchema, stateTreeEditorNodeSelectorSchema, stateTreeTransitionSelectorSchema, }: RegisterSchemaAndAiAuthoringToolsOptions): void;
+export declare function registerSchemaAndAiAuthoringTools({ server, callSubsystemJson, jsonObjectSchema, userDefinedStructMutationOperationSchema, userDefinedStructFieldSchema, userDefinedEnumMutationOperationSchema, userDefinedEnumEntrySchema, blackboardMutationOperationSchema, blackboardKeySchema, behaviorTreeMutationOperationSchema, behaviorTreeNodeSelectorSchema, stateTreeMutationOperationSchema, stateTreeStateSelectorSchema, stateTreeEditorNodeSelectorSchema, stateTreeTransitionSelectorSchema, stateTreeBindingSchema, }: RegisterSchemaAndAiAuthoringToolsOptions): void;
 export {};

package/dist/tools/schema-and-ai-authoring.js

@@ -3,6 +3,7 @@ import { jsonToolError, jsonToolSuccess, normalizeUStructPath } from '../helpers
 /**
  * Recursively walks a payload object and normalizes all `nodeStructType` values
  * by stripping the C++ F-prefix from USTRUCT script paths.
+ * Also validates that nodeStructType paths match the expected `/Script/...` pattern.
  */
 function normalizePayloadPaths(obj, warnings) {
     if (Array.isArray(obj))
@@ -26,6 +27,47 @@ function normalizePayloadPaths(obj, warnings) {
     }
     return obj;
 }
+/**
+ * Validates that all `nodeStructType` values in the payload use the correct
+ * `/Script/Module.ClassName` path format. Collects warnings for paths that
+ * look like Blueprint asset paths, raw class names, or other incorrect formats.
+ *
+ * This runs AFTER normalizePayloadPaths so F-prefix issues are already resolved.
+ */
+function validateNodeStructTypes(obj, warnings) {
+    if (Array.isArray(obj)) {
+        for (const item of obj)
+            validateNodeStructTypes(item, warnings);
+        return;
+    }
+    if (obj && typeof obj === 'object') {
+        const record = obj;
+        for (const [key, value] of Object.entries(record)) {
+            if (key === 'nodeStructType' && typeof value === 'string') {
+                if (!value.startsWith('/Script/')) {
+                    if (value.startsWith('/Game/') || value.startsWith('/Content/')) {
+                        warnings.push(`Warning: nodeStructType "${value}" looks like a Blueprint asset path. `
+                            + 'nodeStructType should be a C++ USTRUCT script path (e.g., "/Script/Module.ClassName")');
+                    }
+                    else if (!value.includes('/')) {
+                        warnings.push(`Warning: nodeStructType "${value}" is a bare class name. `
+                            + 'Use the full script path format: "/Script/ModuleName.ClassName"');
+                    }
+                    else {
+                        warnings.push(`Warning: nodeStructType "${value}" does not match the expected /Script/Module.ClassName pattern`);
+                    }
+                }
+                else if (!value.includes('.')) {
+                    warnings.push(`Warning: nodeStructType "${value}" is missing the class name after the module path. `
+                        + 'Expected format: "/Script/Module.ClassName"');
+                }
+            }
+            else {
+                validateNodeStructTypes(value, warnings);
+            }
+        }
+    }
+}
 /**
  * Checks transition targetState.stateName references against the flat list of
  * state names in the payload. Collects warnings for unresolvable targets.
@@ -60,7 +102,56 @@ function validateTransitionTargets(payload, warnings) {
         }
     }
 }
-export function registerSchemaAndAiAuthoringTools({ server, callSubsystemJson, jsonObjectSchema, userDefinedStructMutationOperationSchema, userDefinedStructFieldSchema, userDefinedEnumMutationOperationSchema, userDefinedEnumEntrySchema, blackboardMutationOperationSchema, blackboardKeySchema, behaviorTreeMutationOperationSchema, behaviorTreeNodeSelectorSchema, stateTreeMutationOperationSchema, stateTreeStateSelectorSchema, stateTreeEditorNodeSelectorSchema, stateTreeTransitionSelectorSchema, }) {
+/**
+ * Collects all task names from a states array, recursively walking children.
+ */
+function collectTaskNames(states) {
+    const taskNames = new Set();
+    function walkStates(stateList) {
+        for (const state of stateList) {
+            const tasks = state.tasks;
+            if (Array.isArray(tasks)) {
+                for (const task of tasks) {
+                    if (typeof task.name === 'string')
+                        taskNames.add(task.name);
+                }
+            }
+            const children = state.children;
+            if (Array.isArray(children))
+                walkStates(children);
+        }
+    }
+    walkStates(states);
+    return taskNames;
+}
+/**
+ * Validates that binding sourceTask and targetTask references point to task
+ * names that exist in the payload's states. Collects warnings for unresolvable references.
+ */
+function validateBindingTaskReferences(payload, warnings) {
+    if (!payload)
+        return;
+    const bindings = (payload.bindings ?? payload.stateTree?.bindings);
+    if (!Array.isArray(bindings) || bindings.length === 0)
+        return;
+    const states = (payload.states ?? payload.stateTree?.states);
+    if (!Array.isArray(states) || states.length === 0)
+        return;
+    const taskNames = collectTaskNames(states);
+    if (taskNames.size === 0)
+        return;
+    for (const binding of bindings) {
+        const source = binding.sourceTask;
+        const target = binding.targetTask;
+        if (typeof source === 'string' && source.length > 0 && !taskNames.has(source)) {
+            warnings.push(`Warning: binding references sourceTask "${source}" which is not found in the states' tasks`);
+        }
+        if (typeof target === 'string' && target.length > 0 && !taskNames.has(target)) {
+            warnings.push(`Warning: binding references targetTask "${target}" which is not found in the states' tasks`);
+        }
+    }
+}
+export function registerSchemaAndAiAuthoringTools({ server, callSubsystemJson, jsonObjectSchema, userDefinedStructMutationOperationSchema, userDefinedStructFieldSchema, userDefinedEnumMutationOperationSchema, userDefinedEnumEntrySchema, blackboardMutationOperationSchema, blackboardKeySchema, behaviorTreeMutationOperationSchema, behaviorTreeNodeSelectorSchema, stateTreeMutationOperationSchema, stateTreeStateSelectorSchema, stateTreeEditorNodeSelectorSchema, stateTreeTransitionSelectorSchema, stateTreeBindingSchema, }) {
     server.registerTool('create_user_defined_struct', {
         title: 'Create UserDefinedStruct',
         description: 'Create a UE5 UserDefinedStruct asset from extractor-shaped field definitions.',
@@ -367,6 +458,7 @@ export function registerSchemaAndAiAuthoringTools({ server, callSubsystemJson, j
                 states: z.array(jsonObjectSchema).optional(),
                 evaluators: z.array(jsonObjectSchema).optional(),
                 globalTasks: z.array(jsonObjectSchema).optional(),
+                bindings: z.array(stateTreeBindingSchema).optional().describe('Task output-to-input bindings. Declares data flow between tasks (requires C++ plugin support — not yet implemented).'),
             }).passthrough().default({}).describe('Extractor-shaped StateTree payload.'),
             validate_only: z.boolean().default(false).describe('Validate and compile without creating the asset.'),
             timeout_seconds: z.number().positive().optional().describe('Timeout in seconds for the subsystem call. Default 120. Complex payloads may need more time.'),
@@ -393,9 +485,12 @@ export function registerSchemaAndAiAuthoringTools({ server, callSubsystemJson, j
                 warnings.push(`Warning: schema path "${schema}" does not match expected /Script/... pattern`);
             }
             validateTransitionTargets(payload, warnings);
+            validateBindingTaskReferences(payload, warnings);
             const normWarnings = [];
             const normalizedPayload = normalizePayloadPaths(payload ?? {}, normWarnings);
             warnings.push(...normWarnings);
+            // Validate nodeStructType path formats after normalization
+            validateNodeStructTypes(normalizedPayload, warnings);
             const timeoutMs = (timeout_seconds ?? 120) * 1000;
             const parsed = await callSubsystemJson('CreateStateTree', {
                 AssetPath: asset_path,
@@ -405,8 +500,9 @@ export function registerSchemaAndAiAuthoringTools({ server, callSubsystemJson, j
             const result = warnings.length > 0
                 ? { ...parsed, warnings }
                 : parsed;
-            const extraContent = normWarnings.length > 0
-                ? [{ type: 'text', text: normWarnings.join('\n') }]
+            const allWarnings = [...normWarnings, ...warnings.filter(w => !normWarnings.includes(w))];
+            const extraContent = allWarnings.length > 0
+                ? [{ type: 'text', text: allWarnings.join('\n') }]
                 : undefined;
             return jsonToolSuccess(result, { extraContent });
         }
@@ -435,6 +531,7 @@ export function registerSchemaAndAiAuthoringTools({ server, callSubsystemJson, j
                 statePath: z.string().optional(),
                 editorNodeId: z.string().optional(),
                 transitionId: z.string().optional(),
+                bindings: z.array(stateTreeBindingSchema).optional().describe('Task output-to-input bindings. Declares data flow between tasks (requires C++ plugin support — not yet implemented).'),
             }).passthrough().default({}).describe('Operation payload. Selectors support stateId/statePath, editorNodeId, and transitionId.'),
             validate_only: z.boolean().default(false).describe('Validate and compile without changing the asset.'),
             timeout_seconds: z.number().positive().optional().describe('Timeout in seconds for the subsystem call. Default 90. Complex payloads may need more time.'),
@@ -451,9 +548,12 @@ export function registerSchemaAndAiAuthoringTools({ server, callSubsystemJson, j
             const { asset_path, operation, payload, validate_only, timeout_seconds } = args;
             const warnings = [];
             validateTransitionTargets(payload, warnings);
+            validateBindingTaskReferences(payload, warnings);
             const normWarnings = [];
             const normalizedPayload = normalizePayloadPaths(payload ?? {}, normWarnings);
             warnings.push(...normWarnings);
+            // Validate nodeStructType path formats after normalization
+            validateNodeStructTypes(normalizedPayload, warnings);
             const timeoutMs = (timeout_seconds ?? 90) * 1000;
             const parsed = await callSubsystemJson('ModifyStateTree', {
                 AssetPath: asset_path,
@@ -464,8 +564,9 @@ export function registerSchemaAndAiAuthoringTools({ server, callSubsystemJson, j
             const result = warnings.length > 0
                 ? { ...parsed, warnings }
                 : parsed;
-            const extraContent = normWarnings.length > 0
-                ? [{ type: 'text', text: normWarnings.join('\n') }]
+            const allWarnings = [...normWarnings, ...warnings.filter(w => !normWarnings.includes(w))];
+            const extraContent = allWarnings.length > 0
+                ? [{ type: 'text', text: allWarnings.join('\n') }]
                 : undefined;
             return jsonToolSuccess(result, { extraContent });
         }

package/dist/ue-client.js

@@ -133,6 +133,12 @@ export class UEClient {
         if (result.timedOut) {
             details.push(`timeoutMs=${this.timeoutMs}`);
         }
+        if (typeof result.responseBody === 'string' && result.responseBody.length > 0) {
+            const truncated = result.responseBody.length > 500
+                ? result.responseBody.slice(0, 500) + '…'
+                : result.responseBody;
+            details.push(`body=${truncated}`);
+        }
         return `Failed to call ${method} on BlueprintExtractorSubsystem (${details.join(', ')})`;
     }
     async rawCall(objectPath, functionName, parameters, timeoutMs) {
@@ -169,10 +175,13 @@ export class UEClient {
                     response: null,
                     status: res.status,
                     error: errorDetail,
+                    responseBody,
                 };
             }
+            const text = await res.text();
             return {
-                response: await res.json(),
+                response: JSON.parse(text),
+                responseBody: text,
             };
         }
         catch (error) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "blueprint-extractor-mcp",
-  "version": "3.1.0",
+  "version": "3.2.0",
   "description": "MCP server for the Unreal Engine BlueprintExtractor plugin over Remote Control",
   "type": "module",
   "main": "dist/index.js",
@@ -39,7 +39,7 @@
     "build": "tsc",
     "start": "node dist/index.js",
     "test": "npm run test:unit && npm run test:stdio",
-    "test:unit": "vitest run tests/ue-client.test.ts tests/project-controller.test.ts tests/animation-authoring.test.ts tests/automation-controller.test.ts tests/automation-runs.test.ts tests/blueprint-authoring.test.ts tests/capture.test.ts tests/commonui-button-style.test.ts tests/compactor.test.ts tests/data-and-input.test.ts tests/extraction-tools.test.ts tests/formatting.test.ts tests/helper-utils.test.ts tests/import-jobs.test.ts tests/material-authoring.test.ts tests/material-instance.test.ts tests/project-control.test.ts tests/schema-and-ai-authoring.test.ts tests/tables-and-curves.test.ts tests/tool-results.test.ts tests/utility-tools.test.ts tests/verification.test.ts tests/widget-animation-authoring.test.ts tests/widget-extraction.test.ts tests/widget-structure.test.ts tests/widget-verification.test.ts tests/window-ui.test.ts tests/server-bootstrap.test.ts tests/server-contract.test.ts tests/schema-validation.test.ts tests/server-config.test.ts tests/subsystem.test.ts",
+    "test:unit": "vitest run tests/ue-client.test.ts tests/project-controller.test.ts tests/animation-authoring.test.ts tests/automation-controller.test.ts tests/automation-runs.test.ts tests/blueprint-authoring.test.ts tests/capture.test.ts tests/commonui-button-style.test.ts tests/compactor.test.ts tests/data-and-input.test.ts tests/extraction-tools.test.ts tests/formatting.test.ts tests/helper-utils.test.ts tests/import-jobs.test.ts tests/live-coding.test.ts tests/material-authoring.test.ts tests/material-instance.test.ts tests/project-control.test.ts tests/project-resolution.test.ts tests/schema-and-ai-authoring.test.ts tests/tables-and-curves.test.ts tests/tool-help.test.ts tests/tool-results.test.ts tests/utility-tools.test.ts tests/verification.test.ts tests/widget-animation-authoring.test.ts tests/widget-extraction.test.ts tests/widget-structure.test.ts tests/widget-verification.test.ts tests/window-ui.test.ts tests/server-bootstrap.test.ts tests/server-contract.test.ts tests/schema-validation.test.ts tests/server-config.test.ts tests/subsystem.test.ts",
     "test:stdio": "npm run build && vitest run tests/stdio.integration.test.ts",
     "test:live": "npm run build && vitest run tests/live.e2e.test.ts",
     "test:pack-smoke": "node tests/pack-smoke.mjs",