blueprint-extractor-mcp 8.1.1 → 8.2.1

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/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

@@ -1324,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.1",
+  "version": "8.2.1",
   "description": "MCP server for the Unreal Engine BlueprintExtractor plugin over Remote Control",
   "type": "module",
   "main": "dist/index.js",