blueprint-extractor-mcp 8.1.0 → 8.2.0

package/dist/editor-instance-registry.js

@@ -4,6 +4,8 @@ import path from 'node:path';
 import { z } from 'zod';
 const REGISTRY_ENV = 'BLUEPRINT_EXTRACTOR_EDITOR_REGISTRY_DIR';
 const DEFAULT_STALE_TTL_MS = 15_000;
+const WSL_WINDOWS_USERS_ROOT = '/mnt/c/Users';
+const WSL_WINDOWS_REGISTRY_SUFFIX = ['AppData', 'Local', 'Temp', 'BlueprintExtractor', 'EditorRegistry'];
 const editorInstanceSchema = z.object({
     instanceId: z.string(),
     projectName: z.string().optional(),
@@ -29,45 +31,82 @@ export function getEditorRegistryDir() {
         ? path.resolve(process.env[REGISTRY_ENV])
         : path.join(tmpdir(), 'BlueprintExtractor', 'EditorRegistry');
 }
-export async function listRegisteredEditors(staleTtlMs = DEFAULT_STALE_TTL_MS) {
-    const registryDir = getEditorRegistryDir();
-    let fileNames = [];
+async function getEditorRegistryDirs() {
+    const overrideDir = process.env[REGISTRY_ENV];
+    if (overrideDir) {
+        return [path.resolve(overrideDir)];
+    }
+    const dirs = new Set([getEditorRegistryDir()]);
+    if (process.platform !== 'linux') {
+        return Array.from(dirs);
+    }
     try {
-        fileNames = await readdir(registryDir);
+        const userEntries = await readdir(WSL_WINDOWS_USERS_ROOT, { withFileTypes: true });
+        for (const entry of userEntries) {
+            if (!entry.isDirectory()) {
+                continue;
+            }
+            dirs.add(path.join(WSL_WINDOWS_USERS_ROOT, entry.name, ...WSL_WINDOWS_REGISTRY_SUFFIX));
+        }
     }
     catch {
-        return {
-            editors: [],
-            registryDir,
-            staleEntryCount: 0,
-        };
+        // Ignore missing /mnt/c/Users on non-WSL or restricted hosts.
     }
-    const editors = [];
+    return Array.from(dirs);
+}
+export async function listRegisteredEditors(staleTtlMs = DEFAULT_STALE_TTL_MS) {
+    const registryDirs = await getEditorRegistryDirs();
+    const editorsByInstanceId = new Map();
     let staleEntryCount = 0;
-    for (const fileName of fileNames) {
-        if (!fileName.toLowerCase().endsWith('.json')) {
+    for (const registryDir of registryDirs) {
+        let fileNames = [];
+        try {
+            fileNames = await readdir(registryDir);
+        }
+        catch {
             continue;
         }
-        const fullPath = path.join(registryDir, fileName);
-        try {
-            const [raw, fileStat] = await Promise.all([
-                readFile(fullPath, 'utf8'),
-                stat(fullPath),
-            ]);
-            const parsed = editorInstanceSchema.parse(JSON.parse(raw));
-            const lastSeenAt = parseLastSeenAt(parsed.lastSeenAt) ?? fileStat.mtimeMs;
-            if ((Date.now() - lastSeenAt) > staleTtlMs) {
+        for (const fileName of fileNames) {
+            if (!fileName.toLowerCase().endsWith('.json')) {
+                continue;
+            }
+            const fullPath = path.join(registryDir, fileName);
+            try {
+                const [raw, fileStat] = await Promise.all([
+                    readFile(fullPath, 'utf8'),
+                    stat(fullPath),
+                ]);
+                const parsed = editorInstanceSchema.parse(JSON.parse(raw));
+                const lastSeenAt = parseLastSeenAt(parsed.lastSeenAt) ?? fileStat.mtimeMs;
+                if ((Date.now() - lastSeenAt) > staleTtlMs) {
+                    staleEntryCount += 1;
+                    await rm(fullPath, { force: true }).catch(() => undefined);
+                    continue;
+                }
+                // Verify the process is actually alive — registry files can outlive the editor
+                // process (e.g. after a crash, force-kill, or external build restart).
+                if (typeof parsed.processId === 'number') {
+                    try {
+                        process.kill(parsed.processId, 0);
+                    }
+                    catch {
+                        staleEntryCount += 1;
+                        await rm(fullPath, { force: true }).catch(() => undefined);
+                        continue;
+                    }
+                }
+                const existing = editorsByInstanceId.get(parsed.instanceId);
+                if (!existing || lastSeenAt >= existing.lastSeenAt) {
+                    editorsByInstanceId.set(parsed.instanceId, { snapshot: parsed, lastSeenAt });
+                }
+            }
+            catch {
                 staleEntryCount += 1;
                 await rm(fullPath, { force: true }).catch(() => undefined);
-                continue;
             }
-            editors.push(parsed);
-        }
-        catch {
-            staleEntryCount += 1;
-            await rm(fullPath, { force: true }).catch(() => undefined);
         }
     }
+    const editors = Array.from(editorsByInstanceId.values(), (entry) => entry.snapshot);
     editors.sort((left, right) => {
         const projectCompare = String(left.projectName ?? left.projectFilePath)
             .localeCompare(String(right.projectName ?? right.projectFilePath));
@@ -78,7 +117,7 @@ export async function listRegisteredEditors(staleTtlMs = DEFAULT_STALE_TTL_MS) {
     });
     return {
         editors,
-        registryDir,
+        registryDir: registryDirs[0] ?? getEditorRegistryDir(),
         staleEntryCount,
     };
 }

package/dist/helpers/formatting.js

@@ -104,7 +104,7 @@ export function extractExtraContent(result) {
     if (!isPlainObject(result) || !Array.isArray(result.content)) {
         return [];
     }
-    return result.content.filter((candidate) => (isContentBlock(candidate) && candidate.type !== 'text'));
+    return result.content.filter((candidate) => (isContentBlock(candidate)));
 }
 export function maybeBoolean(...values) {
     for (const value of values) {

package/dist/helpers/tool-results.js

@@ -1,5 +1,17 @@
 import { isPlainObject } from './formatting.js';
 export function createToolResultNormalizers({ taskAwareTools, classifyRecoverableToolFailure, }) {
+    function serializeSuccessEnvelope(envelope) {
+        try {
+            return JSON.stringify(envelope);
+        }
+        catch {
+            return JSON.stringify({
+                success: true,
+                operation: typeof envelope.operation === 'string' ? envelope.operation : 'unknown_operation',
+                message: 'Unable to serialize tool result payload.',
+            });
+        }
+    }
     function extractNonTextContent(existingResult) {
         if (!existingResult || !Array.isArray(existingResult.content)) {
             return [];
@@ -132,7 +144,10 @@ export function createToolResultNormalizers({ taskAwareTools, classifyRecoverabl
             ...(taskAwareTools.has(toolName) ? { execution: inferExecutionMetadata(toolName, basePayload) } : {}),
         };
         return {
-            content: extraContent,
+            content: [
+                { type: 'text', text: serializeSuccessEnvelope(envelope) },
+                ...extraContent,
+            ],
             structuredContent: envelope,
         };
     }

package/dist/helpers/workspace-project.js

@@ -48,6 +48,11 @@ export function normalizeFilesystemPath(input) {
     if (isWindowsStylePath(trimmed)) {
         return path.win32.normalize(trimmed).replaceAll('\\', '/').toLowerCase();
     }
+    // Canonicalize WSL-mounted Windows paths to the same normalized form as native Windows paths
+    // so registry entries like D:/Project/MyGame.uproject match /mnt/d/Project/MyGame.uproject.
+    if (isWslMountedWindowsPath(trimmed)) {
+        return toWindowsStylePath(trimmed).replaceAll('\\', '/').toLowerCase();
+    }
     return path.posix.normalize(trimmed);
 }
 export function filesystemPathsEqual(left, right) {

package/dist/project-controller.js

@@ -7,7 +7,14 @@ const DEFAULT_BUILD_TIMEOUT_MS = 30 * 60 * 1000;
 const DEFAULT_DISCONNECT_TIMEOUT_MS = 60 * 1000;
 const DEFAULT_RECONNECT_TIMEOUT_MS = 3 * 60 * 1000;
 const DEFAULT_POLL_INTERVAL_MS = 1_000;
-const DEFAULT_EDITOR_LAUNCH_ARGS = ['-RCWebControlEnable', '-RCWebInterfaceEnable'];
+const DEFAULT_EDITOR_LAUNCH_ARGS = ['-RCWebControlEnable', '-RCWebInterfaceEnable', '-WebControl.EnableServerOnStartup=1'];
+function hasCommandLineArg(args, arg) {
+    const normalizedTarget = arg.toLowerCase();
+    return args.some((candidate) => {
+        const normalizedCandidate = candidate.toLowerCase();
+        return normalizedCandidate === normalizedTarget || normalizedCandidate.startsWith(`${normalizedTarget}=`);
+    });
+}
 function defaultSleep(ms) {
     return new Promise((resolveSleep) => setTimeout(resolveSleep, ms));
 }
@@ -504,9 +511,13 @@ export class ProjectController {
         const hostExecutable = toHostFilesystemPath(executable, executionPlatform, this.platform);
         const requestedArgs = request.additionalArgs ?? [];
         const commandProjectPath = normalizeFilesystemPathForCommand(projectPath, executionPlatform);
+        const defaultArgs = DEFAULT_EDITOR_LAUNCH_ARGS.filter((arg) => {
+            const argName = arg.includes('=') ? arg.slice(0, arg.indexOf('=')) : arg;
+            return !hasCommandLineArg(requestedArgs, argName);
+        });
         const args = [
             commandProjectPath,
-            ...DEFAULT_EDITOR_LAUNCH_ARGS.filter((arg) => !requestedArgs.includes(arg)),
+            ...defaultArgs,
             ...requestedArgs,
         ];
         const invocation = resolveCommandInvocation(hostExecutable, args, executionPlatform, this.env);

package/dist/tools/project-control.js

@@ -47,6 +47,9 @@ export function registerProjectControlTools({ server, client, projectController,
         engineRoot: previousEditor?.engineRoot ?? fallback.engineRoot,
         target: previousEditor?.editorTarget ?? fallback.target,
     });
+    const matchesResolvedEditor = (entry, resolved) => (filesystemPathsEqual(entry.projectFilePath, resolved.projectPath)
+        && (!resolved.engineRoot || !entry.engineRoot || filesystemPathsEqual(entry.engineRoot, resolved.engineRoot))
+        && (!resolved.target || !entry.editorTarget || entry.editorTarget === resolved.target));
     const recoverEditorViaHostRelaunch = async (request) => {
         const recovery = {
             strategy: 'host_relaunch_after_failed_graceful_restart',
@@ -452,18 +455,51 @@ export function registerProjectControlTools({ server, client, projectController,
             if (!resolved.engineRoot || !resolved.projectPath) {
                 throw explainProjectResolutionFailure('launch_editor requires engine_root and project_path', resolved);
             }
+            const resolvedProjectPath = resolved.projectPath;
+            const resolvedEngineRoot = resolved.engineRoot;
+            const resolvedTarget = resolved.target;
+            if (activeEditorSession) {
+                const matchingEditors = (await activeEditorSession.listRunningEditors()).filter((entry) => matchesResolvedEditor(entry, {
+                    projectPath: resolvedProjectPath,
+                    engineRoot: resolvedEngineRoot,
+                    target: resolvedTarget,
+                }));
+                if (matchingEditors.length > 1) {
+                    throw new Error(`Multiple running editors already match "${resolvedProjectPath}". `
+                        + 'Call list_running_editors and select_editor instead of launch_editor.');
+                }
+                if (matchingEditors.length === 1) {
+                    try {
+                        const bound = await activeEditorSession.selectEditor({ instanceId: matchingEditors[0].instanceId });
+                        clearProjectAutomationContext();
+                        const activeEditor = toLabeledActiveEditor(bound);
+                        return jsonToolSuccess({
+                            success: true,
+                            operation: 'launch_editor',
+                            launched: false,
+                            reusedExistingEditor: true,
+                            message: 'Bound the existing matching editor instead of launching a new process.',
+                            inputResolution: buildInputResolution(resolved),
+                            activeEditor,
+                        });
+                    }
+                    catch {
+                        // Fall through to a real launch when the registry entry is stale or not yet responsive.
+                    }
+                }
+            }
             const launched = await projectController.launchEditor({
-                engineRoot: resolved.engineRoot,
-                projectPath: resolved.projectPath,
+                engineRoot: resolvedEngineRoot,
+                projectPath: resolvedProjectPath,
             });
             clearProjectAutomationContext();
             let activeEditor;
             if (activeEditorSession) {
                 const bound = await activeEditorSession.bindLaunchedEditor({
                     processId: launched.processId,
-                    projectPath: resolved.projectPath,
-                    engineRoot: resolved.engineRoot,
-                    target: resolved.target,
+                    projectPath: resolvedProjectPath,
+                    engineRoot: resolvedEngineRoot,
+                    target: resolvedTarget,
                     timeoutMs: reconnect_timeout_seconds * 1000,
                 });
                 activeEditor = toLabeledActiveEditor(bound);
@@ -1288,4 +1324,87 @@ export function registerProjectControlTools({ server, client, projectController,
             return jsonToolSuccess(failurePayload);
         }
     });
+    // ============================================================
+    // StateTree Debugger
+    // ============================================================
+    server.registerTool('start_statetree_debugger', {
+        title: 'Start StateTree Debugger',
+        description: 'Start recording StateTree debug traces. Requires PIE to be running. Optionally filter to a specific StateTree asset.',
+        inputSchema: {
+            asset_path: z.string().default('').describe('UE content path of the StateTree asset to filter on (e.g. /Game/AI/ST_Character). Empty = record all.'),
+        },
+        annotations: {
+            title: 'Start StateTree Debugger',
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: false,
+            openWorldHint: false,
+        },
+    }, async ({ asset_path }) => {
+        try {
+            const parsed = await callSubsystemJson('StartStateTreeDebugger', {
+                AssetPath: asset_path,
+            });
+            return jsonToolSuccess(parsed);
+        }
+        catch (error) {
+            return jsonToolError(error);
+        }
+    });
+    server.registerTool('stop_statetree_debugger', {
+        title: 'Stop StateTree Debugger',
+        description: 'Stop the active StateTree debugger session and discard trace data.',
+        inputSchema: {},
+        annotations: {
+            title: 'Stop StateTree Debugger',
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: false,
+            openWorldHint: false,
+        },
+    }, async () => {
+        try {
+            const parsed = await callSubsystemJson('StopStateTreeDebugger', {});
+            return jsonToolSuccess(parsed);
+        }
+        catch (error) {
+            return jsonToolError(error);
+        }
+    });
+    server.registerTool('read_statetree_debugger', {
+        title: 'Read StateTree Debugger',
+        description: 'Read current StateTree debugger data: instances, events, active states, transitions, conditions.',
+        inputSchema: {
+            instance_id: z.string().default('').describe('Filter to a specific instance ID (from a previous read). Empty = list all instances without events.'),
+            max_events: z.number().int().positive().default(500).describe('Maximum events to return per instance.'),
+            scrub_time: z.number().default(-1).describe('Set the scrub time before reading. -1 = use current position.'),
+        },
+        annotations: {
+            title: 'Read StateTree Debugger',
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: false,
+        },
+    }, async ({ instance_id, max_events, scrub_time }) => {
+        try {
+            const payload = {};
+            if (instance_id) {
+                payload.instanceId = instance_id;
+            }
+            if (max_events !== 500) {
+                payload.maxEvents = max_events;
+            }
+            if (scrub_time >= 0) {
+                payload.scrubTime = scrub_time;
+            }
+            const parsed = await callSubsystemJson('ReadStateTreeDebugger', {
+                PayloadJson: JSON.stringify(payload),
+            });
+            return jsonToolSuccess(parsed);
+        }
+        catch (error) {
+            return jsonToolError(error);
+        }
+    });
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "blueprint-extractor-mcp",
-  "version": "8.1.0",
+  "version": "8.2.0",
   "description": "MCP server for the Unreal Engine BlueprintExtractor plugin over Remote Control",
   "type": "module",
   "main": "dist/index.js",