blueprint-extractor-mcp 3.0.0 → 3.1.0

package/dist/helpers/project-resolution.js

@@ -1,3 +1,6 @@
+import { access } from 'node:fs/promises';
+import { constants as fsConstants } from 'node:fs';
+import { resolve } from 'node:path';
 export function rememberExternalBuild(result) {
     return {
         success: result.success === true,
@@ -27,6 +30,31 @@ export async function getProjectAutomationContext(deps) {
     setCachedContext(nextContext);
     return nextContext;
 }
+let cachedHeuristicEngineRoot;
+const HEURISTIC_ENGINE_CANDIDATES = [
+    'C:/Program Files/Epic Games/UE_5.6',
+    'C:/Program Files/Epic Games/UE_5.5',
+    'C:/Program Files/Epic Games/UE_5.4',
+    'C:/Program Files/Epic Games/UE_5.3',
+];
+const ENGINE_MARKER = 'Engine/Build/BatchFiles/Build.bat';
+async function probeEngineRootHeuristic() {
+    if (cachedHeuristicEngineRoot !== undefined) {
+        return cachedHeuristicEngineRoot || undefined;
+    }
+    for (const candidate of HEURISTIC_ENGINE_CANDIDATES) {
+        try {
+            await access(resolve(candidate, ENGINE_MARKER), fsConstants.F_OK);
+            cachedHeuristicEngineRoot = candidate;
+            return candidate;
+        }
+        catch {
+            // not found, try next
+        }
+    }
+    cachedHeuristicEngineRoot = '';
+    return undefined;
+}
 export async function resolveProjectInputs(request, deps) {
     const { getProjectAutomationContext, firstDefinedString, env = process.env, } = deps;
     let context = null;
@@ -45,7 +73,28 @@ export async function resolveProjectInputs(request, deps) {
     const engineRootFromEnv = firstDefinedString(env.UE_ENGINE_ROOT);
     const projectPathFromEnv = firstDefinedString(env.UE_PROJECT_PATH);
     const targetFromEnv = firstDefinedString(env.UE_PROJECT_TARGET, env.UE_EDITOR_TARGET);
-    const engineRoot = firstDefinedString(request.engine_root, engineRootFromContext, engineRootFromEnv);
+    let engineRoot = firstDefinedString(request.engine_root, engineRootFromContext, engineRootFromEnv);
+    let engineRootSource;
+    if (request.engine_root) {
+        engineRootSource = 'explicit';
+    }
+    else if (engineRootFromContext) {
+        engineRootSource = 'editor_context';
+    }
+    else if (engineRootFromEnv) {
+        engineRootSource = 'environment';
+    }
+    else {
+        // Filesystem heuristic: probe common UE installation paths
+        const heuristicRoot = await probeEngineRootHeuristic();
+        if (heuristicRoot) {
+            engineRoot = heuristicRoot;
+            engineRootSource = 'filesystem_heuristic';
+        }
+        else {
+            engineRootSource = 'missing';
+        }
+    }
     const projectPath = firstDefinedString(request.project_path, projectPathFromContext, projectPathFromEnv);
     const target = firstDefinedString(request.target, targetFromContext, targetFromEnv);
     return {
@@ -55,7 +104,7 @@ export async function resolveProjectInputs(request, deps) {
         context,
         contextError,
         sources: {
-            engineRoot: request.engine_root ? 'explicit' : engineRootFromContext ? 'editor_context' : engineRootFromEnv ? 'environment' : 'missing',
+            engineRoot: engineRootSource,
             projectPath: request.project_path ? 'explicit' : projectPathFromContext ? 'editor_context' : projectPathFromEnv ? 'environment' : 'missing',
             target: request.target ? 'explicit' : targetFromContext ? 'editor_context' : targetFromEnv ? 'environment' : 'missing',
         },

package/dist/helpers/subsystem.d.ts

@@ -1,13 +1,29 @@
 import type { CallToolResult, ContentBlock } from '@modelcontextprotocol/sdk/types.js';
+export interface SubsystemCallOptions {
+    timeoutMs?: number;
+}
 type SubsystemClientLike = {
-    callSubsystem(method: string, params: Record<string, unknown>): Promise<string>;
+    callSubsystem(method: string, params: Record<string, unknown>, options?: SubsystemCallOptions): Promise<string>;
 };
-export declare function callSubsystemJson(client: SubsystemClientLike, method: string, params: Record<string, unknown>): Promise<Record<string, unknown>>;
+export declare function callSubsystemJson(client: SubsystemClientLike, method: string, params: Record<string, unknown>, options?: SubsystemCallOptions): Promise<Record<string, unknown>>;
 export declare function jsonToolSuccess(parsed: unknown, options?: {
     extraContent?: ContentBlock[];
 }): CallToolResult & {
     structuredContent: Record<string, unknown>;
 };
+/**
+ * Strips the C++ 'F' prefix from USTRUCT script paths.
+ * UE registers USTRUCTs without the F prefix in script paths.
+ * e.g., /Script/Module.FSTCFoo → /Script/Module.STCFoo
+ *
+ * Only strips when the class name starts with F followed by an uppercase letter,
+ * matching the UE USTRUCT naming convention.
+ */
+export declare function normalizeUStructPath(path: string): string;
+export declare function normalizeUStructPaths(paths: string[]): {
+    normalized: string[];
+    warnings: string[];
+};
 export declare function jsonToolError(e: unknown): {
     content: {
         type: "text";

package/dist/helpers/subsystem.js

@@ -1,10 +1,29 @@
 import { isRecord } from './formatting.js';
-export async function callSubsystemJson(client, method, params) {
-    const result = await client.callSubsystem(method, params);
+export async function callSubsystemJson(client, method, params, options) {
+    const result = await client.callSubsystem(method, params, options);
+    if (process.env.MCP_DEBUG_RESPONSES) {
+        process.stderr.write(`[MCP_DEBUG] ${method} raw response: ${result}\n`);
+    }
     const parsed = JSON.parse(result);
     if (typeof parsed.error === 'string' && parsed.error.length > 0) {
         throw new Error(parsed.error);
     }
+    // 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
+    // through so tool code can inspect them for orchestration (e.g., fallback strategies).
+    if (parsed.success === false) {
+        const explicitMessage = parsed.message ?? parsed.errorMessage;
+        if (typeof explicitMessage === 'string' && explicitMessage.length > 0) {
+            throw new Error(explicitMessage);
+        }
+    }
+    if (Array.isArray(parsed.errors) && parsed.errors.length > 0) {
+        const firstError = parsed.errors[0];
+        throw new Error(typeof firstError === 'string' ? firstError : JSON.stringify(firstError));
+    }
+    if (Object.keys(parsed).length === 0) {
+        throw new Error('Empty response from subsystem');
+    }
     return parsed;
 }
 export function jsonToolSuccess(parsed, options = {}) {
@@ -14,6 +33,28 @@ export function jsonToolSuccess(parsed, options = {}) {
         structuredContent,
     };
 }
+/**
+ * Strips the C++ 'F' prefix from USTRUCT script paths.
+ * UE registers USTRUCTs without the F prefix in script paths.
+ * e.g., /Script/Module.FSTCFoo → /Script/Module.STCFoo
+ *
+ * Only strips when the class name starts with F followed by an uppercase letter,
+ * matching the UE USTRUCT naming convention.
+ */
+export function normalizeUStructPath(path) {
+    return path.replace(/^(\/Script\/[^.]+\.)F([A-Z])/, '$1$2');
+}
+export function normalizeUStructPaths(paths) {
+    const warnings = [];
+    const normalized = paths.map(p => {
+        const result = normalizeUStructPath(p);
+        if (result !== p) {
+            warnings.push(`Auto-normalized F-prefix: "${p}" → "${result}"`);
+        }
+        return result;
+    });
+    return { normalized, warnings };
+}
 export function jsonToolError(e) {
     return {
         content: [{ type: 'text', text: `Error: ${e instanceof Error ? e.message : String(e)}` }],

package/dist/helpers/tool-results.js

@@ -68,8 +68,15 @@ export function createToolResultNormalizers({ taskAwareTools, classifyRecoverabl
         const firstDiagnostic = diagnostics.find((candidate) => (isRecord(candidate)
             && typeof candidate.message === 'string'
             && candidate.message.length > 0));
+        const existingContentText = existingResult
+            && Array.isArray(existingResult.content)
+            && isRecord(existingResult.content[0])
+            && existingResult.content[0].type === 'text'
+            && typeof existingResult.content[0].text === 'string'
+            ? existingResult.content[0].text.replace(/^Error:\s*/, '')
+            : undefined;
         const message = typeof payload.message === 'string'
-            ? payload.message
+            ? payload.message.replace(/^Error:\s*/, '')
             : typeof payload.error === 'string'
                 ? payload.error
                 : (isRecord(firstDiagnostic) && typeof firstDiagnostic.message === 'string')
@@ -78,7 +85,26 @@ export function createToolResultNormalizers({ taskAwareTools, classifyRecoverabl
                         ? payloadOrError.message
                         : typeof payloadOrError === 'string'
                             ? payloadOrError.replace(/^Error:\s*/, '')
-                            : `Tool '${toolName}' failed.`;
+                            : typeof existingContentText === 'string'
+                                ? existingContentText
+                                : payloadOrError == null
+                                    ? `Tool '${toolName}' failed with no error details (received ${String(payloadOrError)})`
+                                    : (() => {
+                                        const type = payloadOrError?.constructor?.name ?? typeof payloadOrError;
+                                        const keys = isRecord(payloadOrError) ? Object.keys(payloadOrError).join(', ') : '';
+                                        const truncatedJson = (() => {
+                                            try {
+                                                const s = JSON.stringify(payloadOrError);
+                                                return s.length > 500 ? s.slice(0, 500) + '…' : s;
+                                            }
+                                            catch {
+                                                return '[unserializable]';
+                                            }
+                                        })();
+                                        return keys
+                                            ? `Tool '${toolName}' failed — received ${type} with keys [${keys}]: ${truncatedJson}`
+                                            : `Tool '${toolName}' failed — received ${type}: ${truncatedJson}`;
+                                    })();
         const classification = classifyRecoverableToolFailure(toolName, message);
         const envelope = {
             ...payload,
@@ -109,7 +135,10 @@ export function createToolResultNormalizers({ taskAwareTools, classifyRecoverabl
         }
         return {
             ...(existingResult ?? {}),
-            content: extractNonTextContent(existingResult),
+            content: [
+                { type: 'text', text: message },
+                ...extractNonTextContent(existingResult),
+            ],
             structuredContent: envelope,
             isError: true,
         };

package/dist/register-server-tools.d.ts

@@ -4,7 +4,9 @@ import { type ToolHelpEntry } from './helpers/tool-help.js';
 import type { ProjectControllerLike, CompileProjectCodeResult } from './project-controller.js';
 import type { ProjectAutomationContext, ResolvedProjectInputs } from './tool-context.js';
 import { UEClient } from './ue-client.js';
-type JsonSubsystemCaller = (method: string, params: Record<string, unknown>) => Promise<Record<string, unknown>>;
+type JsonSubsystemCaller = (method: string, params: Record<string, unknown>, options?: {
+    timeoutMs?: number;
+}) => Promise<Record<string, unknown>>;
 type UEClientLike = Pick<UEClient, 'callSubsystem'> & Partial<Pick<UEClient, 'checkConnection'>>;
 type ResolveProjectInputsFn = (request: {
     engine_root?: string;

package/dist/server-config.d.ts

@@ -6,4 +6,9 @@ export declare function classifyRecoverableToolFailure(toolName: string, message
     recoverable: boolean;
     retry_after_ms: number;
     next_steps: string[];
+} | {
+    code: string;
+    recoverable: boolean;
+    next_steps: string[];
+    retry_after_ms?: undefined;
 } | null;

package/dist/server-config.js

@@ -59,5 +59,60 @@ export function classifyRecoverableToolFailure(toolName, message) {
             ],
         };
     }
+    if (message.includes('requires engine_root or UE_ENGINE_ROOT')) {
+        return {
+            code: 'engine_root_missing',
+            recoverable: false,
+            next_steps: [
+                'Pass engine_root explicitly: { "engine_root": "C:/Program Files/Epic Games/UE_5.6" }',
+                'Or set the UE_ENGINE_ROOT environment variable to your Unreal Engine root directory.',
+            ],
+        };
+    }
+    if (message.includes('timed out') || message.includes('timeout') || message.includes('ETIMEDOUT') || message.includes('ESOCKETTIMEDOUT')) {
+        return {
+            code: 'timeout',
+            recoverable: true,
+            retry_after_ms: 5000,
+            next_steps: [
+                'Retry with simpler payload or increase timeout',
+                'Check if UE editor is responding (call wait_for_editor)',
+                'For StateTree tools, try splitting complex payloads into multiple calls',
+            ],
+        };
+    }
+    if (message.includes('JSON') || message.includes('Unexpected token') || message.includes('SyntaxError')) {
+        return {
+            code: 'invalid_response',
+            recoverable: true,
+            next_steps: [
+                'Check UE editor output log for errors',
+                'The editor may have returned an HTML error page instead of JSON',
+                'Retry the operation — this may be a transient serialization issue',
+            ],
+        };
+    }
+    if (message.includes('locked by another process') || message.includes('locked file') || message.includes('cannot access the file')) {
+        return {
+            code: 'locked_file',
+            recoverable: true,
+            next_steps: [
+                'Close UE editor to release DLL locks',
+                'Call restart_editor, then retry the build',
+                'If editor was just restarted, the cached build may apply automatically',
+            ],
+        };
+    }
+    if (message.includes('Empty response') || message.includes('empty response') || message === '') {
+        return {
+            code: 'empty_response',
+            recoverable: true,
+            next_steps: [
+                'Verify the asset path exists',
+                'Check editor connection with wait_for_editor',
+                'The UE subsystem may have crashed — check editor logs',
+            ],
+        };
+    }
     return null;
 }

package/dist/server-factory.js

@@ -17,7 +17,7 @@ export function createBlueprintExtractorServer(client = new UEClient(), projectC
     const toolHelpRegistry = new Map();
     const server = new McpServer({
         name: 'blueprint-extractor',
-        version: '3.0.0',
+        version: '3.1.0',
     }, {
         instructions: serverInstructions,
     });
@@ -32,7 +32,7 @@ export function createBlueprintExtractorServer(client = new UEClient(), projectC
         normalizeToolError,
         normalizeToolSuccess,
     });
-    const callSubsystemJson = (method, params) => (callSubsystemJsonWithClient(client, method, params));
+    const callSubsystemJson = (method, params, options) => (callSubsystemJsonWithClient(client, method, params, options));
     function rememberExternalBuild(result) {
         lastExternalBuildContext = buildExternalBuildContext(result);
     }

package/dist/tool-context.d.ts

@@ -14,7 +14,7 @@ export type ProjectAutomationContext = {
     liveCodingStarted?: boolean;
     liveCodingError?: string;
 };
-export type ProjectInputSource = 'explicit' | 'editor_context' | 'environment' | 'missing';
+export type ProjectInputSource = 'explicit' | 'editor_context' | 'environment' | 'filesystem_heuristic' | 'missing';
 export type ResolvedProjectInputs = {
     engineRoot?: string;
     projectPath?: string;

package/dist/tools/project-control.js

@@ -1,3 +1,4 @@
+import * as path from 'path';
 import { z } from 'zod';
 import { sleep } from '../helpers/formatting.js';
 import { canFallbackFromLiveCoding, enrichLiveCodingResult, } from '../helpers/live-coding.js';
@@ -205,11 +206,52 @@ export function registerProjectControlTools({ server, client, projectController,
         },
     }, async ({ save_dirty_assets, wait_for_reconnect, disconnect_timeout_seconds, reconnect_timeout_seconds }) => {
         try {
-            const restartRequest = await callSubsystemJson('RestartEditor', {
-                bWarn: false,
-                bSaveDirtyAssets: save_dirty_assets,
-                bRelaunch: true,
-            });
+            // Pre-flight: verify editor is connected before attempting restart
+            const probe = supportsConnectionProbe(client);
+            if (probe) {
+                try {
+                    const connected = await probe();
+                    if (!connected) {
+                        return jsonToolError(new Error('Editor is not connected. Cannot restart.'));
+                    }
+                }
+                catch {
+                    return jsonToolError(new Error('Editor is not connected. Cannot restart.'));
+                }
+            }
+            // Pre-flight: reject restart if editor is in PIE mode
+            try {
+                const ctx = await getProjectAutomationContext(true);
+                if (ctx.isPlayingInEditor === true) {
+                    return jsonToolError(new Error('Cannot restart during Play-In-Editor session. Stop PIE first.'));
+                }
+            }
+            catch {
+                // Context query failed — proceed with restart attempt anyway
+            }
+            // Attempt restart with one retry on transient failure
+            let restartRequest;
+            try {
+                restartRequest = await callSubsystemJson('RestartEditor', {
+                    bWarn: false,
+                    bSaveDirtyAssets: save_dirty_assets,
+                    bRelaunch: true,
+                });
+            }
+            catch (firstError) {
+                await sleep(2000);
+                try {
+                    restartRequest = await callSubsystemJson('RestartEditor', {
+                        bWarn: false,
+                        bSaveDirtyAssets: save_dirty_assets,
+                        bRelaunch: true,
+                    });
+                }
+                catch (retryError) {
+                    return jsonToolError(new Error(`restart_editor failed after retry: ${retryError instanceof Error ? retryError.message : String(retryError)}` +
+                        ` (first attempt: ${firstError instanceof Error ? firstError.message : String(firstError)})`));
+                }
+            }
             clearProjectAutomationContext();
             if (!wait_for_reconnect || restartRequest.success === false) {
                 return jsonToolSuccess({
@@ -218,7 +260,7 @@ export function registerProjectControlTools({ server, client, projectController,
                     saveDirtyAssetsAppliedByEditor: save_dirty_assets,
                 });
             }
-            const reconnect = await projectController.waitForEditorRestart(supportsConnectionProbe(client), {
+            const reconnect = await projectController.waitForEditorRestart(probe, {
                 disconnectTimeoutMs: disconnect_timeout_seconds * 1000,
                 reconnectTimeoutMs: reconnect_timeout_seconds * 1000,
             });
@@ -263,15 +305,38 @@ export function registerProjectControlTools({ server, client, projectController,
         },
     }, 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, }) => {
         try {
-            const plan = projectController.classifyChangedPaths(changed_paths, force_rebuild);
             const resolvedProjectInputs = await resolveProjectInputs({ engine_root, project_path, target });
+            // Normalize changed_paths to absolute paths
+            const projectRoot = resolvedProjectInputs.projectPath
+                ? path.dirname(resolvedProjectInputs.projectPath)
+                : '';
+            const pathWarnings = [];
+            const normalizedPaths = changed_paths.map((p) => {
+                if (path.isAbsolute(p))
+                    return p;
+                if (projectRoot)
+                    return path.resolve(projectRoot, p);
+                // No project root available — keep as-is but warn
+                pathWarnings.push(`Cannot resolve relative path without project root: "${p}"`);
+                return p;
+            });
+            changed_paths.forEach((original, i) => {
+                if (normalizedPaths[i] !== original) {
+                    pathWarnings.push(`Normalized relative path: "${original}" → "${normalizedPaths[i]}"`);
+                }
+            });
+            const stepErrors = {};
+            const plan = projectController.classifyChangedPaths(normalizedPaths, force_rebuild);
             const structuredResult = {
                 success: false,
                 operation: 'sync_project_code',
-                changedPaths: changed_paths,
+                changedPaths: normalizedPaths,
                 plan,
                 inputResolution: buildInputResolution(resolvedProjectInputs),
             };
+            if (pathWarnings.length > 0) {
+                structuredResult.pathWarnings = pathWarnings;
+            }
             if (plan.strategy === 'live_coding') {
                 if (!projectController.liveCodingSupported) {
                     structuredResult.plan = {
@@ -281,19 +346,31 @@ export function registerProjectControlTools({ server, client, projectController,
                     };
                 }
                 else {
-                    const liveCoding = enrichLiveCodingResult(await callSubsystemJson('TriggerLiveCoding', {
-                        bEnableForSession: true,
-                        bWaitForCompletion: true,
-                    }), changed_paths, getLastExternalBuildContext());
+                    let liveCoding;
+                    try {
+                        liveCoding = enrichLiveCodingResult(await callSubsystemJson('TriggerLiveCoding', {
+                            bEnableForSession: true,
+                            bWaitForCompletion: true,
+                        }), normalizedPaths, getLastExternalBuildContext());
+                    }
+                    catch (lcError) {
+                        stepErrors.liveCoding = lcError instanceof Error ? lcError.message : String(lcError);
+                        liveCoding = { success: false, error: stepErrors.liveCoding };
+                    }
                     if (!canFallbackFromLiveCoding(liveCoding)) {
-                        return jsonToolSuccess({
+                        const lcResult = {
                             success: liveCoding.success === true,
                             operation: 'sync_project_code',
                             strategy: 'live_coding',
-                            changedPaths: changed_paths,
+                            changedPaths: normalizedPaths,
                             plan,
                             liveCoding,
-                        });
+                        };
+                        if (pathWarnings.length > 0)
+                            lcResult.pathWarnings = pathWarnings;
+                        if (Object.keys(stepErrors).length > 0)
+                            lcResult.stepErrors = stepErrors;
+                        return jsonToolSuccess(lcResult);
                     }
                     structuredResult.liveCoding = liveCoding;
                     structuredResult.plan = {
@@ -305,102 +382,199 @@ export function registerProjectControlTools({ server, client, projectController,
             }
             if (restart_first) {
                 if (Array.isArray(save_asset_paths) && save_asset_paths.length > 0) {
-                    const preSave = await callSubsystemJson('SaveAssets', {
-                        AssetPathsJson: JSON.stringify(save_asset_paths),
+                    try {
+                        const preSave = await callSubsystemJson('SaveAssets', {
+                            AssetPathsJson: JSON.stringify(save_asset_paths),
+                        });
+                        structuredResult.preSave = preSave;
+                    }
+                    catch (preSaveError) {
+                        stepErrors.preSave = preSaveError instanceof Error ? preSaveError.message : String(preSaveError);
+                        // Pre-save is non-critical — continue to restart
+                    }
+                }
+                try {
+                    const preRestart = await callSubsystemJson('RestartEditor', {
+                        bWarn: false,
+                        bSaveDirtyAssets: save_dirty_assets,
+                        bRelaunch: false,
                     });
-                    structuredResult.preSave = preSave;
+                    clearProjectAutomationContext();
+                    structuredResult.preRestart = preRestart;
+                    if (preRestart.success === false) {
+                        stepErrors.preRestart = 'RestartEditor returned success=false';
+                        structuredResult.strategy = 'restart_first';
+                        if (Object.keys(stepErrors).length > 0)
+                            structuredResult.stepErrors = stepErrors;
+                        return jsonToolSuccess(structuredResult);
+                    }
                 }
-                const preRestart = await callSubsystemJson('RestartEditor', {
-                    bWarn: false,
-                    bSaveDirtyAssets: save_dirty_assets,
-                    bRelaunch: false,
-                });
-                clearProjectAutomationContext();
-                structuredResult.preRestart = preRestart;
-                if (preRestart.success === false) {
+                catch (preRestartError) {
+                    stepErrors.preRestart = preRestartError instanceof Error ? preRestartError.message : String(preRestartError);
                     structuredResult.strategy = 'restart_first';
+                    structuredResult.success = false;
+                    if (Object.keys(stepErrors).length > 0)
+                        structuredResult.stepErrors = stepErrors;
                     return jsonToolSuccess(structuredResult);
                 }
-                const preDisconnect = await projectController.waitForEditorRestart(supportsConnectionProbe(client), {
-                    disconnectTimeoutMs: disconnect_timeout_seconds * 1000,
-                    reconnectTimeoutMs: reconnect_timeout_seconds * 1000,
-                    waitForReconnect: false,
-                });
-                structuredResult.preDisconnect = preDisconnect;
-                if (!preDisconnect.success) {
+                try {
+                    const preDisconnect = await projectController.waitForEditorRestart(supportsConnectionProbe(client), {
+                        disconnectTimeoutMs: disconnect_timeout_seconds * 1000,
+                        reconnectTimeoutMs: reconnect_timeout_seconds * 1000,
+                        waitForReconnect: false,
+                    });
+                    structuredResult.preDisconnect = preDisconnect;
+                    if (!preDisconnect.success) {
+                        stepErrors.preDisconnect = 'Editor did not disconnect within timeout';
+                        structuredResult.strategy = 'restart_first';
+                        if (Object.keys(stepErrors).length > 0)
+                            structuredResult.stepErrors = stepErrors;
+                        return jsonToolSuccess(structuredResult);
+                    }
+                }
+                catch (preDisconnectError) {
+                    stepErrors.preDisconnect = preDisconnectError instanceof Error ? preDisconnectError.message : String(preDisconnectError);
                     structuredResult.strategy = 'restart_first';
+                    structuredResult.success = false;
+                    if (Object.keys(stepErrors).length > 0)
+                        structuredResult.stepErrors = stepErrors;
                     return jsonToolSuccess(structuredResult);
                 }
             }
-            const build = await projectController.compileProjectCode({
-                engineRoot: resolvedProjectInputs.engineRoot,
-                projectPath: resolvedProjectInputs.projectPath,
-                target: resolvedProjectInputs.target,
-                platform: platform,
-                configuration: configuration,
-                buildTimeoutMs: typeof build_timeout_seconds === 'number' ? build_timeout_seconds * 1000 : undefined,
-                includeOutput: include_output,
-                clearUhtCache: clear_uht_cache,
-            });
-            rememberExternalBuild(build);
+            let build;
+            try {
+                build = await projectController.compileProjectCode({
+                    engineRoot: resolvedProjectInputs.engineRoot,
+                    projectPath: resolvedProjectInputs.projectPath,
+                    target: resolvedProjectInputs.target,
+                    platform: platform,
+                    configuration: configuration,
+                    buildTimeoutMs: typeof build_timeout_seconds === 'number' ? build_timeout_seconds * 1000 : undefined,
+                    includeOutput: include_output,
+                    clearUhtCache: clear_uht_cache,
+                });
+                rememberExternalBuild(build);
+            }
+            catch (buildError) {
+                stepErrors.build = buildError instanceof Error ? buildError.message : String(buildError);
+                structuredResult.strategy = restart_first ? 'restart_first' : 'build_and_restart';
+                structuredResult.success = false;
+                if (Object.keys(stepErrors).length > 0)
+                    structuredResult.stepErrors = stepErrors;
+                return jsonToolSuccess(structuredResult);
+            }
             structuredResult.strategy = restart_first ? 'restart_first' : 'build_and_restart';
             structuredResult.build = build;
             if (!build.success) {
+                if (Object.keys(stepErrors).length > 0)
+                    structuredResult.stepErrors = stepErrors;
                 return jsonToolSuccess(structuredResult);
             }
             if (!restart_first && Array.isArray(save_asset_paths) && save_asset_paths.length > 0) {
-                const saveResult = await callSubsystemJson('SaveAssets', {
-                    AssetPathsJson: JSON.stringify(save_asset_paths),
-                });
-                structuredResult.save = saveResult;
-                if (saveResult.success === false) {
-                    return jsonToolSuccess(structuredResult);
+                try {
+                    const saveResult = await callSubsystemJson('SaveAssets', {
+                        AssetPathsJson: JSON.stringify(save_asset_paths),
+                    });
+                    structuredResult.save = saveResult;
+                    if (saveResult.success === false) {
+                        stepErrors.save = 'SaveAssets returned success=false';
+                        if (Object.keys(stepErrors).length > 0)
+                            structuredResult.stepErrors = stepErrors;
+                        return jsonToolSuccess(structuredResult);
+                    }
+                }
+                catch (saveError) {
+                    stepErrors.save = saveError instanceof Error ? saveError.message : String(saveError);
+                    // Save is non-critical before restart — continue
                 }
             }
             let reconnect;
             if (restart_first) {
-                const launch = await projectController.launchEditor({
-                    engineRoot: resolvedProjectInputs.engineRoot,
-                    projectPath: resolvedProjectInputs.projectPath,
-                });
-                clearProjectAutomationContext();
-                structuredResult.editorLaunch = launch;
-                if (!launch.success) {
+                try {
+                    const launch = await projectController.launchEditor({
+                        engineRoot: resolvedProjectInputs.engineRoot,
+                        projectPath: resolvedProjectInputs.projectPath,
+                    });
+                    clearProjectAutomationContext();
+                    structuredResult.editorLaunch = launch;
+                    if (!launch.success) {
+                        stepErrors.editorLaunch = 'launchEditor returned success=false';
+                        if (Object.keys(stepErrors).length > 0)
+                            structuredResult.stepErrors = stepErrors;
+                        return jsonToolSuccess(structuredResult);
+                    }
+                }
+                catch (launchError) {
+                    stepErrors.editorLaunch = launchError instanceof Error ? launchError.message : String(launchError);
+                    structuredResult.success = false;
+                    if (Object.keys(stepErrors).length > 0)
+                        structuredResult.stepErrors = stepErrors;
                     return jsonToolSuccess(structuredResult);
                 }
-                reconnect = await projectController.waitForEditorRestart(supportsConnectionProbe(client), {
-                    disconnectTimeoutMs: disconnect_timeout_seconds * 1000,
-                    reconnectTimeoutMs: reconnect_timeout_seconds * 1000,
-                    waitForDisconnect: false,
-                });
+                try {
+                    reconnect = await projectController.waitForEditorRestart(supportsConnectionProbe(client), {
+                        disconnectTimeoutMs: disconnect_timeout_seconds * 1000,
+                        reconnectTimeoutMs: reconnect_timeout_seconds * 1000,
+                        waitForDisconnect: false,
+                    });
+                }
+                catch (reconnectError) {
+                    stepErrors.reconnect = reconnectError instanceof Error ? reconnectError.message : String(reconnectError);
+                }
             }
             else {
-                const restartRequest = await callSubsystemJson('RestartEditor', {
-                    bWarn: false,
-                    bSaveDirtyAssets: save_dirty_assets,
-                    bRelaunch: true,
-                });
-                clearProjectAutomationContext();
-                structuredResult.restartRequest = restartRequest;
-                structuredResult.restartRequestSaveDirtyAssetsAccepted = save_dirty_assets;
-                if (restartRequest.success === false) {
+                try {
+                    const restartRequest = await callSubsystemJson('RestartEditor', {
+                        bWarn: false,
+                        bSaveDirtyAssets: save_dirty_assets,
+                        bRelaunch: true,
+                    });
+                    clearProjectAutomationContext();
+                    structuredResult.restartRequest = restartRequest;
+                    structuredResult.restartRequestSaveDirtyAssetsAccepted = save_dirty_assets;
+                    if (restartRequest.success === false) {
+                        stepErrors.restart = 'RestartEditor returned success=false';
+                        if (Object.keys(stepErrors).length > 0)
+                            structuredResult.stepErrors = stepErrors;
+                        return jsonToolSuccess(structuredResult);
+                    }
+                }
+                catch (restartError) {
+                    stepErrors.restart = restartError instanceof Error ? restartError.message : String(restartError);
+                    structuredResult.success = false;
+                    if (Object.keys(stepErrors).length > 0)
+                        structuredResult.stepErrors = stepErrors;
                     return jsonToolSuccess(structuredResult);
                 }
-                reconnect = await projectController.waitForEditorRestart(supportsConnectionProbe(client), {
-                    disconnectTimeoutMs: disconnect_timeout_seconds * 1000,
-                    reconnectTimeoutMs: reconnect_timeout_seconds * 1000,
-                });
+                try {
+                    reconnect = await projectController.waitForEditorRestart(supportsConnectionProbe(client), {
+                        disconnectTimeoutMs: disconnect_timeout_seconds * 1000,
+                        reconnectTimeoutMs: reconnect_timeout_seconds * 1000,
+                    });
+                }
+                catch (reconnectError) {
+                    stepErrors.reconnect = reconnectError instanceof Error ? reconnectError.message : String(reconnectError);
+                }
+            }
+            if (reconnect) {
+                structuredResult.reconnect = reconnect;
+                structuredResult.success = reconnect.success === true;
+            }
+            else {
+                structuredResult.success = false;
             }
-            structuredResult.reconnect = reconnect;
-            structuredResult.success = reconnect.success === true;
             if (structuredResult.success && structuredResult.build) {
                 structuredResult.build = trimBuildOutput(structuredResult.build);
             }
+            if (Object.keys(stepErrors).length > 0) {
+                structuredResult.stepErrors = stepErrors;
+            }
             return jsonToolSuccess(structuredResult);
         }
         catch (error) {
             const resolved = await resolveProjectInputs({ engine_root, project_path, target });
-            return jsonToolError(explainProjectResolutionFailure(error instanceof Error ? error.message : String(error), resolved));
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            return jsonToolError(explainProjectResolutionFailure(errorMessage, resolved));
         }
     });
 }

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

@@ -1,6 +1,8 @@
 import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { z } from 'zod';
-type JsonSubsystemCaller = (method: string, params: Record<string, unknown>) => Promise<Record<string, unknown>>;
+type JsonSubsystemCaller = (method: string, params: Record<string, unknown>, options?: {
+    timeoutMs?: number;
+}) => Promise<Record<string, unknown>>;
 type RegisterSchemaAndAiAuthoringToolsOptions = {
     server: Pick<McpServer, 'registerTool'>;
     callSubsystemJson: JsonSubsystemCaller;

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

@@ -1,5 +1,65 @@
 import { z } from 'zod';
-import { jsonToolError, jsonToolSuccess } from '../helpers/subsystem.js';
+import { jsonToolError, jsonToolSuccess, normalizeUStructPath } from '../helpers/subsystem.js';
+/**
+ * Recursively walks a payload object and normalizes all `nodeStructType` values
+ * by stripping the C++ F-prefix from USTRUCT script paths.
+ */
+function normalizePayloadPaths(obj, warnings) {
+    if (Array.isArray(obj))
+        return obj.map(item => normalizePayloadPaths(item, warnings));
+    if (obj && typeof obj === 'object') {
+        const record = obj;
+        const result = {};
+        for (const [key, value] of Object.entries(record)) {
+            if (key === 'nodeStructType' && typeof value === 'string') {
+                const normalized = normalizeUStructPath(value);
+                if (normalized !== value) {
+                    warnings.push(`Auto-normalized F-prefix in nodeStructType: "${value}" → "${normalized}"`);
+                }
+                result[key] = normalized;
+            }
+            else {
+                result[key] = normalizePayloadPaths(value, warnings);
+            }
+        }
+        return result;
+    }
+    return obj;
+}
+/**
+ * Checks transition targetState.stateName references against the flat list of
+ * state names in the payload. Collects warnings for unresolvable targets.
+ */
+function validateTransitionTargets(payload, warnings) {
+    if (!payload)
+        return;
+    const states = (payload.states ?? payload.stateTree?.states);
+    if (!Array.isArray(states) || states.length === 0)
+        return;
+    const stateNames = new Set();
+    for (const s of states) {
+        if (typeof s.stateName === 'string')
+            stateNames.add(s.stateName);
+        if (typeof s.name === 'string')
+            stateNames.add(s.name);
+    }
+    if (stateNames.size === 0)
+        return;
+    for (const s of states) {
+        const transitions = (s.transitions ?? []);
+        if (!Array.isArray(transitions))
+            continue;
+        for (const t of transitions) {
+            const target = t.targetState;
+            if (!target)
+                continue;
+            const targetName = (target.stateName ?? target.name);
+            if (typeof targetName === 'string' && targetName.length > 0 && !stateNames.has(targetName)) {
+                warnings.push(`Warning: transition references targetState "${targetName}" which is not in the states list`);
+            }
+        }
+    }
+}
 export function registerSchemaAndAiAuthoringTools({ server, callSubsystemJson, jsonObjectSchema, userDefinedStructMutationOperationSchema, userDefinedStructFieldSchema, userDefinedEnumMutationOperationSchema, userDefinedEnumEntrySchema, blackboardMutationOperationSchema, blackboardKeySchema, behaviorTreeMutationOperationSchema, behaviorTreeNodeSelectorSchema, stateTreeMutationOperationSchema, stateTreeStateSelectorSchema, stateTreeEditorNodeSelectorSchema, stateTreeTransitionSelectorSchema, }) {
     server.registerTool('create_user_defined_struct', {
         title: 'Create UserDefinedStruct',
@@ -303,12 +363,13 @@ export function registerSchemaAndAiAuthoringTools({ server, callSubsystemJson, j
             asset_path: z.string().describe('UE content path for the new StateTree asset.'),
             payload: z.object({
                 stateTree: jsonObjectSchema.optional(),
-                schema: z.string().optional(),
+                schema: z.string().optional().describe('UE class path of the StateTree schema. Required by the editor. E.g. /Script/GameplayStateTreeModule.StateTreeComponentSchema'),
                 states: z.array(jsonObjectSchema).optional(),
                 evaluators: z.array(jsonObjectSchema).optional(),
                 globalTasks: z.array(jsonObjectSchema).optional(),
             }).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.'),
         },
         annotations: {
             title: 'Create StateTree',
@@ -319,13 +380,35 @@ export function registerSchemaAndAiAuthoringTools({ server, callSubsystemJson, j
         },
     }, async (args) => {
         try {
-            const { asset_path, payload, validate_only } = args;
+            const { asset_path, payload, validate_only, timeout_seconds } = args;
+            // Validate schema is present
+            if (!payload?.schema && !payload?.stateTree?.schema) {
+                return jsonToolError(new Error('schema is required for create_state_tree. Provide it at payload.schema or payload.stateTree.schema '
+                    + '(e.g., "/Script/GameplayStateTreeModule.StateTreeComponentSchema")'));
+            }
+            const warnings = [];
+            // Lightweight payload validation (non-blocking)
+            const schema = (payload?.schema ?? payload?.stateTree?.schema);
+            if (typeof schema === 'string' && !schema.startsWith('/Script/')) {
+                warnings.push(`Warning: schema path "${schema}" does not match expected /Script/... pattern`);
+            }
+            validateTransitionTargets(payload, warnings);
+            const normWarnings = [];
+            const normalizedPayload = normalizePayloadPaths(payload ?? {}, normWarnings);
+            warnings.push(...normWarnings);
+            const timeoutMs = (timeout_seconds ?? 120) * 1000;
             const parsed = await callSubsystemJson('CreateStateTree', {
                 AssetPath: asset_path,
-                PayloadJson: JSON.stringify(payload ?? {}),
+                PayloadJson: JSON.stringify(normalizedPayload),
                 bValidateOnly: validate_only,
-            });
-            return jsonToolSuccess(parsed);
+            }, { timeoutMs });
+            const result = warnings.length > 0
+                ? { ...parsed, warnings }
+                : parsed;
+            const extraContent = normWarnings.length > 0
+                ? [{ type: 'text', text: normWarnings.join('\n') }]
+                : undefined;
+            return jsonToolSuccess(result, { extraContent });
         }
         catch (error) {
             return jsonToolError(error);
@@ -354,6 +437,7 @@ export function registerSchemaAndAiAuthoringTools({ server, callSubsystemJson, j
                 transitionId: z.string().optional(),
             }).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.'),
         },
         annotations: {
             title: 'Modify StateTree',
@@ -364,14 +448,26 @@ export function registerSchemaAndAiAuthoringTools({ server, callSubsystemJson, j
         },
     }, async (args) => {
         try {
-            const { asset_path, operation, payload, validate_only } = args;
+            const { asset_path, operation, payload, validate_only, timeout_seconds } = args;
+            const warnings = [];
+            validateTransitionTargets(payload, warnings);
+            const normWarnings = [];
+            const normalizedPayload = normalizePayloadPaths(payload ?? {}, normWarnings);
+            warnings.push(...normWarnings);
+            const timeoutMs = (timeout_seconds ?? 90) * 1000;
             const parsed = await callSubsystemJson('ModifyStateTree', {
                 AssetPath: asset_path,
                 Operation: operation,
-                PayloadJson: JSON.stringify(payload ?? {}),
+                PayloadJson: JSON.stringify(normalizedPayload),
                 bValidateOnly: validate_only,
-            });
-            return jsonToolSuccess(parsed);
+            }, { timeoutMs });
+            const result = warnings.length > 0
+                ? { ...parsed, warnings }
+                : parsed;
+            const extraContent = normWarnings.length > 0
+                ? [{ type: 'text', text: normWarnings.join('\n') }]
+                : undefined;
+            return jsonToolSuccess(result, { extraContent });
         }
         catch (error) {
             return jsonToolError(error);

package/dist/ue-client.d.ts

@@ -35,6 +35,8 @@ export declare class UEClient {
     private clearDiscoveredSubsystemPath;
     private formatCallFailure;
     private rawCall;
-    callSubsystem(method: string, params: Record<string, unknown>): Promise<string>;
+    callSubsystem(method: string, params: Record<string, unknown>, options?: {
+        timeoutMs?: number;
+    }): Promise<string>;
 }
 export {};

package/dist/ue-client.js

@@ -135,7 +135,8 @@ export class UEClient {
         }
         return `Failed to call ${method} on BlueprintExtractorSubsystem (${details.join(', ')})`;
     }
-    async rawCall(objectPath, functionName, parameters) {
+    async rawCall(objectPath, functionName, parameters, timeoutMs) {
+        const effectiveTimeout = timeoutMs ?? this.timeoutMs;
         const body = {
             objectPath,
             functionName,
@@ -143,7 +144,7 @@ export class UEClient {
             generateTransaction: false,
         };
         const controller = new AbortController();
-        const timeout = setTimeout(() => controller.abort(), this.timeoutMs);
+        const timeout = setTimeout(() => controller.abort(), effectiveTimeout);
         try {
             const res = await this.fetchImpl(`${this.baseUrl}/remote/object/call`, {
                 method: 'PUT',
@@ -153,16 +154,17 @@ export class UEClient {
             });
             clearTimeout(timeout);
             if (!res.ok) {
-                let errorDetail = res.statusText || `HTTP ${res.status}`;
+                let responseBody = '';
                 try {
-                    const responseText = await res.text();
-                    if (responseText.trim().length > 0) {
-                        errorDetail = responseText;
-                    }
+                    responseBody = await res.text();
                 }
                 catch {
-                    // Keep the HTTP status text when the body cannot be read.
+                    // Body cannot be read — leave empty.
                 }
+                const truncatedBody = responseBody.length > 500 ? responseBody.slice(0, 500) + '...' : responseBody;
+                const errorDetail = truncatedBody.trim().length > 0
+                    ? `UE editor returned HTTP ${res.status}: ${truncatedBody}`
+                    : `UE editor returned HTTP ${res.status}: ${res.statusText || 'no response body'}`;
                 return {
                     response: null,
                     status: res.status,
@@ -178,27 +180,28 @@ export class UEClient {
             if (error instanceof Error && error.name === 'AbortError') {
                 return {
                     response: null,
-                    error: `Request timed out after ${this.timeoutMs}ms`,
+                    error: `Request timed out after ${effectiveTimeout}ms`,
                     timedOut: true,
                 };
             }
+            const networkMsg = error instanceof Error ? error.message : String(error);
             return {
                 response: null,
-                error: error instanceof Error ? error.message : String(error),
+                error: `Network error connecting to UE editor: ${networkMsg}`,
             };
         }
     }
-    async callSubsystem(method, params) {
+    async callSubsystem(method, params, options) {
         const connected = await this.checkConnection();
         if (!connected) {
             throw new Error(`UE Editor not running or Remote Control not available on ${this.host}:${this.port}`);
         }
         let objectPath = await this.discoverSubsystem();
-        let res = await this.rawCall(objectPath, method, params);
+        let res = await this.rawCall(objectPath, method, params, options?.timeoutMs);
         if (res.response === null && this.subsystemPathSource === 'discovered') {
             this.clearDiscoveredSubsystemPath();
             objectPath = await this.discoverSubsystem();
-            res = await this.rawCall(objectPath, method, params);
+            res = await this.rawCall(objectPath, method, params, options?.timeoutMs);
         }
         if (res.response === null) {
             this.invalidateConnectionStatus();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "blueprint-extractor-mcp",
-  "version": "3.0.0",
+  "version": "3.1.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",
+    "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: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",