blueprint-extractor-mcp 6.0.7 → 6.1.0

package/README.md

@@ -23,9 +23,10 @@ Blueprint Extractor MCP is a [Model Context Protocol](https://modelcontextprotoc
  AI Assistant         stdio           MCP Server         HTTP :30010        Unreal Editor
  ─────────────  ◄────────────►  ─────────────────  ◄──────────────────►  ─────────────────
   Claude Code                     Node.js process                         Remote Control API
-  Codex                           95 tools                                BlueprintExtractor
-  ...                             4 resource templates                    plugin
-                                  8 prompts
+  Codex                           106 tools                               BlueprintExtractor
+  ...                             38 resources                            plugin
+                                  4 resource templates
+                                  12 prompts
 ```
 
 **What the assistant can do through this server:**
@@ -69,7 +70,7 @@ Connects to the editor at `127.0.0.1:30010` by default.
 ```bash
 claude mcp add -s user -t stdio blueprint-extractor \
   -e UE_REMOTE_CONTROL_PORT=30010 \
-  -- npx -y blueprint-extractor-mcp@6.0.6
+  -- npx -y blueprint-extractor-mcp@6.1.0
 ```
 
 </td></tr>
@@ -78,7 +79,7 @@ claude mcp add -s user -t stdio blueprint-extractor \
 
 ```bash
 codex mcp add --env UE_REMOTE_CONTROL_PORT=30010 \
-  blueprint-extractor -- npx -y blueprint-extractor-mcp@6.0.6
+  blueprint-extractor -- npx -y blueprint-extractor-mcp@6.1.0
 ```
 
 </td></tr>
@@ -90,20 +91,25 @@ codex mcp add --env UE_REMOTE_CONTROL_PORT=30010 \
 
 ## Tool Surface
 
-Only **~13 core tools** are visible by default to keep the context window lean. Specialized families are loaded on demand via `activate_workflow_scope`.
-
-| Scope | Tools | What It Unlocks |
-|:------|------:|:----------------|
-| **Core** *(always on)* | ~13 | `extract_asset` `search_assets` `save_assets` `get_tool_help` `find_and_extract` |
-| `widget_authoring` | 25 | Widget tree ops, compile, CommonUI button styles, widget animations, visual captures |
-| `material_authoring` | 5 | `create_material` `modify_material` `material_graph_operation` + instances |
-| `blueprint_authoring` | 4 | Blueprint members, graphs, `trigger_live_coding` |
-| `schema_ai_authoring` | 11 | Structs, enums, Blackboards, Behavior Trees, State Trees |
-| `animation_authoring` | 7 | Anim sequences, montages, blend spaces, widget motion |
-| `data_tables` | 7 | Data assets, data tables, curves, Enhanced Input actions & mappings |
-| `import` | 3 | `import_assets` with texture/mesh options, job polling |
-| `automation_testing` | 7 | `run_automation_tests`, run inspection, project automation context, PIE lifecycle control |
-| `verification` | 9 | Widget captures, editor/runtime screenshots, motion checkpoint bundles, reference comparisons |
+Only the compact core surface is visible by default to keep the context window lean. Specialized families are loaded on demand via `activate_workflow_scope`.
+
+| Scope | What It Unlocks |
+|:------|:----------------|
+| **Core** *(always on)* | Search, extraction, list/save/help, editor-session binding, and project-control entry points such as `extract_asset`, `search_assets`, `save_assets`, `get_tool_help`, and `activate_workflow_scope` |
+| `widget_authoring` | Parent scope that loads `widget_authoring_structure`, `widget_authoring_visual`, and `widget_verification` together |
+| `widget_authoring_structure` | Widget tree structure, hierarchy edits, wrapping, moving, replacement, and batch operations |
+| `widget_authoring_visual` | Widget compile flows, CommonUI styles, widget animations, and widget preview capture |
+| `widget_verification` | Widget capture, checkpoint bundles, capture listing, cleanup, and reference comparison |
+| `material_authoring` | Material creation, `material_graph_operation`, compile, and material-instance edits |
+| `blueprint_authoring` | Blueprint creation, member edits, graph edits, and Live Coding trigger |
+| `schema_ai_authoring` | Structs, enums, Blackboards, Behavior Trees, and State Trees |
+| `animation_authoring` | Anim sequences, montages, blend spaces, and widget motion authoring |
+| `data_tables` | Data assets, data tables, curves, Input Actions, and Input Mapping Contexts |
+| `import` | Async asset import and import-job polling |
+| `automation_testing` | Host-side automation runs, coarse project automation context, and PIE lifecycle control |
+| `analysis` | Deterministic Blueprint review and low-noise project asset audits |
+| `project_intelligence` | Bounded editor context, project indexing, freshness status, and snippet-first context search |
+| `verification` | Editor/runtime screenshots, capture comparison, motion verification, and artifact inspection |
 
 ### Contract Design
 
@@ -133,7 +139,9 @@ See [../docs/CURRENT_STATUS.md](../docs/CURRENT_STATUS.md) for the current valid
 | `UE_BUILD_PLATFORM` | &mdash; | e.g. `Win64` |
 | `UE_BUILD_CONFIGURATION` | &mdash; | e.g. `Development` |
 
-`get_project_automation_context` surfaces the editor-derived `engineRoot`, `projectFilePath`, `editorTarget`, and `isPlayingInEditor` state that project-control and verification flows use for fallback or guard logic.
+`get_project_automation_context` surfaces the coarse editor-derived `engineRoot`, `projectFilePath`, `editorTarget`, and `isPlayingInEditor` state that project-control and verification flows use for fallback or guard logic.
+
+`get_editor_context` is the separate read-only editor-state snapshot for selection, open asset editors, active level, and PIE summary. It stays session-bound and intentionally does not open assets, change focus, or switch viewports.
 
 <br>
 
@@ -162,6 +170,10 @@ blueprint://test-runs/{run_id}/{artifact}  Automation test artifacts
 | `plan_widget_motion_verification` | Keyframe-bundle verification planning |
 | `wire_hud_widget_classes` | Class-default wiring for HUD assets |
 | `debug_widget_compile_errors` | Diagnosing and recovering from compile failures |
+| `understand_blueprint_project` | Building a project-understanding pass over indexed assets, docs, prompts, and resources |
+| `review_blueprint_asset` | Running a deterministic read-only Blueprint review flow |
+| `snapshot_editor_context` | Inspecting bounded editor state without changing editor focus |
+| `audit_blueprint_project` | Running a low-noise project asset audit |
 
 <br>
 

package/dist/active-editor-session.d.ts

@@ -1,4 +1,5 @@
 import type { ActiveEditorState, EditorInstanceSnapshot } from './editor-instance-types.js';
+import type { EditorContextSnapshot } from './tool-context.js';
 type ActiveEditorSessionOptions = {
     cwd?: string;
     env?: NodeJS.ProcessEnv;
@@ -44,6 +45,7 @@ export declare class ActiveEditorSession {
     }): Promise<EditorInstanceSnapshot | undefined>;
     getBoundSnapshot(): EditorInstanceSnapshot | undefined;
     getWorkspaceProjectPath(): Promise<string | undefined>;
+    getEditorContext(): Promise<EditorContextSnapshot>;
     private ensureActiveEditor;
     private resolveCurrentEditorForConnection;
     private bindFromExplicitPins;

package/dist/active-editor-session.js

@@ -30,6 +30,12 @@ function buildActiveEditorDriftMessage(snapshot) {
         + `${snapshot.remoteControlHost}:${snapshot.remoteControlPort}. The session has been returned to an unbound state. `
         + 'Call list_running_editors and select_editor to continue.';
 }
+function toStringArray(value) {
+    if (!Array.isArray(value)) {
+        return [];
+    }
+    return value.filter((entry) => typeof entry === 'string' && entry.length > 0);
+}
 export class ActiveEditorSession {
     cwd;
     env;
@@ -222,6 +228,48 @@ export class ActiveEditorSession {
         const resolution = await this.workspaceProjectPromise;
         return resolution.projectPath;
     }
+    async getEditorContext() {
+        const raw = await this.callSubsystem('GetEditorContext', {});
+        const parsed = JSON.parse(raw);
+        if (typeof parsed.error === 'string' && parsed.error.length > 0) {
+            throw new Error(parsed.error);
+        }
+        const instanceId = typeof parsed.instanceId === 'string' ? parsed.instanceId : undefined;
+        const projectFilePath = typeof parsed.projectFilePath === 'string' ? parsed.projectFilePath : undefined;
+        if (!instanceId || !projectFilePath) {
+            throw new Error('GetEditorContext did not return instanceId and projectFilePath.');
+        }
+        const pieSummary = typeof parsed.pieSummary === 'object' && parsed.pieSummary !== null
+            ? parsed.pieSummary
+            : undefined;
+        return {
+            success: typeof parsed.success === 'boolean' ? parsed.success : true,
+            operation: typeof parsed.operation === 'string' ? parsed.operation : 'get_editor_context',
+            instanceId,
+            projectName: typeof parsed.projectName === 'string' ? parsed.projectName : undefined,
+            projectFilePath,
+            projectDir: typeof parsed.projectDir === 'string' ? parsed.projectDir : undefined,
+            engineRoot: typeof parsed.engineRoot === 'string' ? parsed.engineRoot : undefined,
+            editorTarget: typeof parsed.editorTarget === 'string' ? parsed.editorTarget : undefined,
+            remoteControlHost: typeof parsed.remoteControlHost === 'string' ? parsed.remoteControlHost : this.activeEditorSnapshot?.remoteControlHost ?? '127.0.0.1',
+            remoteControlPort: typeof parsed.remoteControlPort === 'number'
+                ? parsed.remoteControlPort
+                : this.activeEditorSnapshot?.remoteControlPort ?? 30010,
+            lastSeenAt: typeof parsed.lastSeenAt === 'string' ? parsed.lastSeenAt : undefined,
+            selectedAssetPaths: toStringArray(parsed.selectedAssetPaths),
+            selectedActorNames: toStringArray(parsed.selectedActorNames),
+            openAssetEditors: toStringArray(parsed.openAssetEditors),
+            activeLevel: typeof parsed.activeLevel === 'string' ? parsed.activeLevel : undefined,
+            pieSummary: pieSummary ? {
+                isPlayingInEditor: typeof pieSummary.isPlayingInEditor === 'boolean' ? pieSummary.isPlayingInEditor : undefined,
+                isSimulatingInEditor: typeof pieSummary.isSimulatingInEditor === 'boolean' ? pieSummary.isSimulatingInEditor : undefined,
+                worldName: typeof pieSummary.worldName === 'string' ? pieSummary.worldName : undefined,
+                worldPath: typeof pieSummary.worldPath === 'string' ? pieSummary.worldPath : undefined,
+            } : undefined,
+            partial: typeof parsed.partial === 'boolean' ? parsed.partial : undefined,
+            unsupportedSections: toStringArray(parsed.unsupportedSections),
+        };
+    }
     async ensureActiveEditor() {
         const validation = await this.validateActiveSelection();
         if (validation.healthy && this.activeEditorSnapshot) {

package/dist/catalogs/example-catalog.js

@@ -667,4 +667,48 @@ export const exampleCatalog = {
             },
         ],
     },
+    blueprint_review: {
+        summary: 'Run deterministic review first, then inspect the cited graph/variable evidence before planning any fix.',
+        recommended_flow: [
+            'review_blueprint',
+            'extract_blueprint',
+        ],
+        examples: [
+            {
+                title: 'review_gameplay_blueprint',
+                tool: 'review_blueprint',
+                arguments: {
+                    asset_path: '/Game/Blueprints/BP_PlayerCharacter',
+                },
+            },
+        ],
+    },
+    project_intelligence: {
+        summary: 'Warm the project index, search published context and asset metadata, snapshot bounded editor state when needed, then audit the relevant package scope.',
+        recommended_flow: [
+            'refresh_project_index',
+            'get_project_index_status',
+            'search_project_context',
+            'get_editor_context',
+            'audit_project_assets',
+        ],
+        examples: [
+            {
+                title: 'search_replication_context',
+                tool: 'search_project_context',
+                arguments: {
+                    query: 'replication authority review',
+                    page: 1,
+                    per_page: 5,
+                },
+            },
+            {
+                title: 'audit_ui_assets',
+                tool: 'audit_project_assets',
+                arguments: {
+                    package_path: '/Game/UI',
+                },
+            },
+        ],
+    },
 };

package/dist/execution/adapters/commandlet-adapter.d.ts

@@ -1,11 +1,16 @@
 /**
- * CommandletAdapter spawns UnrealEditor-Cmd.exe with -run=blueprintextractor
+ * CommandletAdapter spawns the platform-appropriate UnrealEditor-Cmd binary with -run=blueprintextractor
  * and communicates via stdin/stdout JSON-RPC.
  */
+import { spawn } from 'child_process';
 import type { ExecutionAdapter, ToolCapability } from '../execution-adapter.js';
 export interface CommandletAdapterOptions {
     engineRoot: string;
     projectPath: string;
+    platform?: NodeJS.Platform;
+    spawnProcess?: typeof spawn;
+    startupTimeoutMs?: number;
+    requestTimeoutMs?: number;
 }
 export declare class CommandletAdapter implements ExecutionAdapter {
     private options;
@@ -13,6 +18,10 @@ export declare class CommandletAdapter implements ExecutionAdapter {
     private requestId;
     private pendingRequests;
     private buffer;
+    private readonly spawnProcess;
+    private readonly platform;
+    private readonly startupTimeoutMs;
+    private readonly requestTimeoutMs;
     constructor(options: CommandletAdapterOptions);
     initialize(): Promise<void>;
     execute(_subsystem: string, method: string, params: Record<string, unknown>): Promise<Record<string, unknown>>;

package/dist/execution/adapters/commandlet-adapter.js

@@ -1,9 +1,10 @@
 /**
- * CommandletAdapter spawns UnrealEditor-Cmd.exe with -run=blueprintextractor
+ * CommandletAdapter spawns the platform-appropriate UnrealEditor-Cmd binary with -run=blueprintextractor
  * and communicates via stdin/stdout JSON-RPC.
  */
 import { spawn } from 'child_process';
 import { COMMANDLET_CAPABILITIES } from '../execution-adapter.js';
+import { resolveEditorExecutable } from '../../project-controller.js';
 const STARTUP_TIMEOUT_MS = 30_000;
 const REQUEST_TIMEOUT_MS = 60_000;
 export class CommandletAdapter {
@@ -12,14 +13,22 @@ export class CommandletAdapter {
     requestId = 0;
     pendingRequests = new Map();
     buffer = '';
+    spawnProcess;
+    platform;
+    startupTimeoutMs;
+    requestTimeoutMs;
     constructor(options) {
         this.options = options;
+        this.spawnProcess = options.spawnProcess ?? spawn;
+        this.platform = options.platform ?? process.platform;
+        this.startupTimeoutMs = options.startupTimeoutMs ?? STARTUP_TIMEOUT_MS;
+        this.requestTimeoutMs = options.requestTimeoutMs ?? REQUEST_TIMEOUT_MS;
     }
     async initialize() {
         if (this.process)
             return;
-        const editorCmd = `${this.options.engineRoot}/Binaries/Win64/UnrealEditor-Cmd.exe`;
-        this.process = spawn(editorCmd, [
+        const editorCmd = await resolveEditorExecutable(this.options.engineRoot, this.platform, 'commandlet');
+        this.process = this.spawnProcess(editorCmd, [
             this.options.projectPath,
             '-run=blueprintextractor',
             '-stdin',
@@ -45,8 +54,8 @@ export class CommandletAdapter {
         // Wait for startup
         await new Promise((resolve, reject) => {
             const timer = setTimeout(() => {
-                reject(new Error(`Commandlet startup timed out after ${STARTUP_TIMEOUT_MS}ms`));
-            }, STARTUP_TIMEOUT_MS);
+                reject(new Error(`Commandlet startup timed out after ${this.startupTimeoutMs}ms`));
+            }, this.startupTimeoutMs);
             const onData = () => {
                 clearTimeout(timer);
                 this.process?.stdout?.off('data', onData);
@@ -69,8 +78,8 @@ export class CommandletAdapter {
         return new Promise((resolve, reject) => {
             const timer = setTimeout(() => {
                 this.pendingRequests.delete(id);
-                reject(new Error(`Commandlet request timed out after ${REQUEST_TIMEOUT_MS}ms`));
-            }, REQUEST_TIMEOUT_MS);
+                reject(new Error(`Commandlet request timed out after ${this.requestTimeoutMs}ms`));
+            }, this.requestTimeoutMs);
             this.pendingRequests.set(id, { resolve, reject, timer });
             this.process.stdin.write(request + '\n');
         });

package/dist/helpers/next-step-hints.js

@@ -173,7 +173,7 @@ export const NEXT_STEP_HINTS_REGISTRY = new Map([
                 'Use get_tool_help for detailed usage of newly available tools.',
             ],
             on_error: [
-                'Check available scope names: widget_authoring, material_authoring, blueprint_authoring, schema_ai_authoring, animation_authoring, data_tables, import, automation_testing, verification.',
+                'Check available scope names: widget_authoring, material_authoring, blueprint_authoring, schema_ai_authoring, animation_authoring, data_tables, import, automation_testing, verification, analysis, project_intelligence.',
             ],
         }],
     ['find_and_extract', {

package/dist/helpers/project-resolution.d.ts

@@ -16,9 +16,11 @@ type ResolveProjectInputsDeps = {
     firstDefinedString(...values: Array<unknown>): string | undefined;
     env?: NodeJS.ProcessEnv;
     workspaceProjectPath?: string;
+    platform?: NodeJS.Platform;
 };
 export declare function rememberExternalBuild(result: CompileProjectCodeResult): Record<string, unknown>;
 export declare function getProjectAutomationContext(deps: GetProjectAutomationContextDeps): Promise<ProjectAutomationContext>;
+export declare function getHeuristicEngineCandidates(platform?: NodeJS.Platform): string[];
 export declare const HEURISTIC_ENGINE_CANDIDATES: string[];
 export declare function resolveProjectInputs(request: ProjectInputsRequest, deps: ResolveProjectInputsDeps): Promise<ResolvedProjectInputs>;
 export {};

package/dist/helpers/project-resolution.js

@@ -31,46 +31,85 @@ export async function getProjectAutomationContext(deps) {
     setCachedContext(nextContext);
     return nextContext;
 }
-let cachedHeuristicEngineRoot;
-export const HEURISTIC_ENGINE_CANDIDATES = [
-    'C:/Program Files/Epic Games/UE_5.7',
-    '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;
+const cachedHeuristicEngineRoots = new Map();
+export function getHeuristicEngineCandidates(platform = process.platform) {
+    if (platform === 'win32') {
+        return [
+            'C:/Program Files/Epic Games/UE_5.7',
+            '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',
+        ];
     }
-    for (const candidate of HEURISTIC_ENGINE_CANDIDATES) {
+    if (platform === 'darwin') {
+        return [
+            '/Users/Shared/Epic Games/UE_5.7',
+            '/Users/Shared/Epic Games/UE_5.6',
+            '/Users/Shared/Epic Games/UE_5.5',
+            '/Users/Shared/Epic Games/UE_5.4',
+            '/Users/Shared/Epic Games/UE_5.3',
+            '/Users/Shared/EpicGames/UE_5.7',
+            '/Users/Shared/EpicGames/UE_5.6',
+            '/Users/Shared/EpicGames/UE_5.5',
+            '/Users/Shared/EpicGames/UE_5.4',
+            '/Users/Shared/EpicGames/UE_5.3',
+        ];
+    }
+    return [];
+}
+export const HEURISTIC_ENGINE_CANDIDATES = getHeuristicEngineCandidates();
+function getEngineMarkers(platform) {
+    if (platform === 'win32') {
+        return ['Engine/Build/BatchFiles/Build.bat'];
+    }
+    if (platform === 'darwin') {
+        return [
+            'Engine/Build/BatchFiles/Mac/Build.sh',
+            'Engine/Build/BatchFiles/Build.sh',
+        ];
+    }
+    return [
+        'Engine/Build/BatchFiles/Linux/Build.sh',
+        'Engine/Build/BatchFiles/Build.sh',
+    ];
+}
+async function accessFirstMatchingMarker(root, markers) {
+    for (const marker of markers) {
         try {
-            await access(resolve(candidate, ENGINE_MARKER), fsConstants.F_OK);
-            cachedHeuristicEngineRoot = candidate;
-            return candidate;
+            await access(resolve(root, marker), fsConstants.F_OK);
+            return true;
         }
         catch {
-            // not found, try next
+            // try the next marker
+        }
+    }
+    return false;
+}
+async function probeEngineRootHeuristic(platform) {
+    if (cachedHeuristicEngineRoots.has(platform)) {
+        return cachedHeuristicEngineRoots.get(platform) || undefined;
+    }
+    for (const candidate of getHeuristicEngineCandidates(platform)) {
+        if (await accessFirstMatchingMarker(candidate, getEngineMarkers(platform))) {
+            cachedHeuristicEngineRoots.set(platform, candidate);
+            return candidate;
         }
     }
-    cachedHeuristicEngineRoot = '';
+    cachedHeuristicEngineRoots.set(platform, '');
     return undefined;
 }
-async function probePreferredEngineRoot(candidates) {
+async function probePreferredEngineRoot(candidates, platform) {
+    const markers = getEngineMarkers(platform);
     for (const candidate of candidates) {
-        try {
-            await access(resolve(candidate, ENGINE_MARKER), fsConstants.F_OK);
+        if (await accessFirstMatchingMarker(candidate, markers)) {
             return candidate;
         }
-        catch {
-            // try next candidate
-        }
     }
     return undefined;
 }
 export async function resolveProjectInputs(request, deps) {
-    const { getProjectAutomationContext, firstDefinedString, env = process.env, workspaceProjectPath, } = deps;
+    const { getProjectAutomationContext, firstDefinedString, env = process.env, workspaceProjectPath, platform = process.platform, } = deps;
     let context = null;
     let contextError;
     if (!request.engine_root || !request.project_path || !request.target) {
@@ -94,7 +133,7 @@ export async function resolveProjectInputs(request, deps) {
     const projectPath = firstDefinedString(request.project_path, projectPathFromContext, projectPathFromWorkspace, projectPathFromEnv);
     const target = firstDefinedString(request.target, targetFromContext, targetFromWorkspace, targetFromEnv);
     const engineAssociation = projectPath ? await readProjectEngineAssociation(projectPath) : undefined;
-    const associationCandidates = buildEngineAssociationCandidates(engineAssociation);
+    const associationCandidates = buildEngineAssociationCandidates(engineAssociation, platform);
     let engineRoot = firstDefinedString(request.engine_root, engineRootFromContext, engineRootFromEnv);
     let engineRootSource;
     if (request.engine_root) {
@@ -107,8 +146,8 @@ export async function resolveProjectInputs(request, deps) {
         engineRootSource = 'environment';
     }
     else {
-        const preferredCandidate = await probePreferredEngineRoot(associationCandidates);
-        const heuristicRoot = preferredCandidate ?? await probeEngineRootHeuristic();
+        const preferredCandidate = await probePreferredEngineRoot(associationCandidates, platform);
+        const heuristicRoot = preferredCandidate ?? await probeEngineRootHeuristic(platform);
         if (heuristicRoot) {
             engineRoot = heuristicRoot;
             engineRootSource = 'filesystem_heuristic';

package/dist/helpers/tool-help.js

@@ -178,6 +178,18 @@ export function collectRelatedResources(toolName) {
         || toolName === 'relaunch_pie') {
         resources.add('blueprint://project-automation');
     }
+    if (toolName === 'review_blueprint' || toolName === 'audit_project_assets') {
+        resources.add('blueprint://analysis-workflows');
+    }
+    if (toolName === 'refresh_project_index'
+        || toolName === 'get_project_index_status'
+        || toolName === 'search_project_context'
+        || toolName === 'get_editor_context') {
+        resources.add('blueprint://project-intelligence-workflows');
+    }
+    if (toolName === 'get_editor_context') {
+        resources.add('blueprint://project-automation');
+    }
     if (toolName.includes('animation')
         || toolName.includes('motion')
         || toolName === 'compare_motion_capture_bundle') {

package/dist/helpers/workspace-project.d.ts

@@ -7,4 +7,4 @@ export declare function normalizeFilesystemPath(input: string | undefined): stri
 export declare function filesystemPathsEqual(left: string | undefined, right: string | undefined): boolean;
 export declare function findNearestWorkspaceProject(startDir?: string): Promise<WorkspaceProjectResolution>;
 export declare function readProjectEngineAssociation(projectPath: string): Promise<string | undefined>;
-export declare function buildEngineAssociationCandidates(engineAssociation: string | undefined): string[];
+export declare function buildEngineAssociationCandidates(engineAssociation: string | undefined, platform?: NodeJS.Platform): string[];

package/dist/helpers/workspace-project.js

@@ -1,13 +1,22 @@
 import { readFile, readdir } from 'node:fs/promises';
 import path from 'node:path';
+const WINDOWS_DRIVE_PATH = /^[A-Za-z]:[\\/]/;
+const WINDOWS_UNC_PATH = /^(?:\\\\|\/\/)[^\\/]+[\\/][^\\/]+/;
+function isWindowsStylePath(input) {
+    return WINDOWS_DRIVE_PATH.test(input) || WINDOWS_UNC_PATH.test(input);
+}
 export function normalizeFilesystemPath(input) {
     if (!input) {
         return undefined;
     }
-    const normalized = path.normalize(input);
-    return process.platform === 'win32'
-        ? normalized.toLowerCase()
-        : normalized;
+    const trimmed = input.trim();
+    if (!trimmed) {
+        return undefined;
+    }
+    if (isWindowsStylePath(trimmed)) {
+        return path.win32.normalize(trimmed).replaceAll('\\', '/').toLowerCase();
+    }
+    return path.posix.normalize(trimmed);
 }
 export function filesystemPathsEqual(left, right) {
     const normalizedLeft = normalizeFilesystemPath(left);
@@ -58,7 +67,7 @@ export async function readProjectEngineAssociation(projectPath) {
         return undefined;
     }
 }
-export function buildEngineAssociationCandidates(engineAssociation) {
+export function buildEngineAssociationCandidates(engineAssociation, platform = process.platform) {
     if (!engineAssociation) {
         return [];
     }
@@ -67,11 +76,20 @@ export function buildEngineAssociationCandidates(engineAssociation) {
         return [];
     }
     const candidates = new Set();
+    const installRoots = platform === 'win32'
+        ? ['C:/Program Files/Epic Games']
+        : platform === 'darwin'
+            ? ['/Users/Shared/Epic Games', '/Users/Shared/EpicGames']
+            : [];
     if (/^\d+\.\d+$/.test(trimmed)) {
-        candidates.add(`C:/Program Files/Epic Games/UE_${trimmed}`);
+        for (const root of installRoots) {
+            candidates.add(`${root}/UE_${trimmed}`);
+        }
     }
     if (/^UE_\d+\.\d+$/.test(trimmed)) {
-        candidates.add(`C:/Program Files/Epic Games/${trimmed}`);
+        for (const root of installRoots) {
+            candidates.add(`${root}/${trimmed}`);
+        }
     }
     candidates.add(trimmed);
     return Array.from(candidates);

package/dist/project-controller.d.ts

@@ -122,6 +122,8 @@ export interface ProjectControllerLike {
     }): Promise<RestartReconnectResult>;
 }
 export declare function resolveCommandInvocation(executable: string, args: string[], platform: NodeJS.Platform, env?: NodeJS.ProcessEnv): CommandInvocation;
+export declare function getBuildScriptCandidates(engineRoot: string, platform: NodeJS.Platform): string[];
+export declare function resolveBuildScript(engineRoot: string, platform: NodeJS.Platform): Promise<string>;
 export declare function resolveEditorExecutable(engineRoot: string, platform: NodeJS.Platform, mode?: 'editor' | 'commandlet'): Promise<string>;
 export declare function classifyChangedPaths(changedPaths: string[], forceRebuild?: boolean): SyncStrategyPlan;
 /** Classify UBT build output into an error category. */

package/dist/project-controller.js

@@ -1,7 +1,7 @@
 import { execSync, spawn } from 'node:child_process';
 import { access, readdir, unlink } from 'node:fs/promises';
 import { constants as fsConstants } from 'node:fs';
-import { dirname, resolve } from 'node:path';
+import { dirname, resolve, win32 as win32Path } from 'node:path';
 const DEFAULT_BUILD_TIMEOUT_MS = 30 * 60 * 1000;
 const DEFAULT_DISCONNECT_TIMEOUT_MS = 60 * 1000;
 const DEFAULT_RECONNECT_TIMEOUT_MS = 3 * 60 * 1000;
@@ -42,6 +42,35 @@ export function resolveCommandInvocation(executable, args, platform, env = proce
         args: ['/d', '/s', '/c', commandLine],
     };
 }
+export function getBuildScriptCandidates(engineRoot, platform) {
+    if (platform === 'win32') {
+        return [
+            resolve(engineRoot, 'Engine', 'Build', 'BatchFiles', 'Build.bat'),
+        ];
+    }
+    if (platform === 'darwin') {
+        return [
+            resolve(engineRoot, 'Engine', 'Build', 'BatchFiles', 'Mac', 'Build.sh'),
+            resolve(engineRoot, 'Engine', 'Build', 'BatchFiles', 'Build.sh'),
+        ];
+    }
+    return [
+        resolve(engineRoot, 'Engine', 'Build', 'BatchFiles', 'Linux', 'Build.sh'),
+        resolve(engineRoot, 'Engine', 'Build', 'BatchFiles', 'Build.sh'),
+    ];
+}
+export async function resolveBuildScript(engineRoot, platform) {
+    for (const candidate of getBuildScriptCandidates(engineRoot, platform)) {
+        try {
+            await access(candidate, fsConstants.F_OK);
+            return candidate;
+        }
+        catch {
+            // Try the next platform-specific location.
+        }
+    }
+    throw new Error(`Unable to locate an Unreal build script under ${engineRoot} for platform ${platform}.`);
+}
 export async function resolveEditorExecutable(engineRoot, platform, mode = 'editor') {
     const executableName = mode === 'commandlet'
         ? (platform === 'win32' ? 'UnrealEditor-Cmd.exe' : 'UnrealEditor-Cmd')
@@ -135,6 +164,9 @@ function fileName(path) {
     const lastSlash = normalized.lastIndexOf('/');
     return lastSlash >= 0 ? normalized.slice(lastSlash + 1) : normalized;
 }
+function normalizeFilesystemPathForCommand(path, platform) {
+    return platform === 'win32' ? win32Path.normalize(path) : path;
+}
 export function classifyChangedPaths(changedPaths, forceRebuild = false) {
     const reasons = new Set();
     if (forceRebuild) {
@@ -325,10 +357,8 @@ export class ProjectController {
         if (!target) {
             throw new Error('compile_project_code requires target or UE_PROJECT_TARGET/UE_EDITOR_TARGET');
         }
-        const buildScript = this.platform === 'win32'
-            ? resolve(engineRoot, 'Engine', 'Build', 'BatchFiles', 'Build.bat')
-            : resolve(engineRoot, 'Engine', 'Build', 'BatchFiles', 'Build.sh');
-        await access(buildScript, fsConstants.F_OK);
+        const buildScript = await resolveBuildScript(engineRoot, this.platform);
+        const commandProjectPath = normalizeFilesystemPathForCommand(projectPath, this.platform);
         let uhtCacheFilesDeleted;
         if (request.clearUhtCache) {
             uhtCacheFilesDeleted = await clearUhtCacheFiles(dirname(projectPath));
@@ -337,7 +367,7 @@ export class ProjectController {
             target,
             platform,
             configuration,
-            `-Project=${projectPath}`,
+            `-Project=${commandProjectPath}`,
             '-WaitMutex',
             '-NoHotReloadFromIDE',
         ];