blueprint-extractor-mcp 7.0.8 → 8.0.1

package/README.md

@@ -23,7 +23,7 @@ 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 / OpenCode                106 tools                               BlueprintExtractor
+  Codex / OpenCode                112 tools                               BlueprintExtractor
   ...                             38 resources                            plugin
                                   4 resource templates
                                   12 prompts
@@ -112,22 +112,23 @@ codex mcp add --env UE_REMOTE_CONTROL_PORT=30010 \
 
 ## Tool Surface
 
-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`.
+Use `activate_tool_profile` to switch between the compact `default` surface and the full `expert` surface. The default profile keeps the context window lean and loads specialized families 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` |
+| **Core** *(always on in `default` profile)* | Search, extraction, `find_and_extract`, list/save/help, and the profile/scope switches such as `extract_asset`, `search_assets`, `save_assets`, `get_tool_help`, `activate_tool_profile`, 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_structure` | Recipe-first widget authoring, tree replacement, unified-diff patching, and focused structure edits without the deprecated widget aliases |
 | `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 |
+| `material_authoring` | `create_material_setup`, `modify_material`, `material_graph_operation`, compile, and material-instance edits |
+| `blueprint_authoring` | `scaffold_blueprint`, graph/member edits, Blueprint creation, 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 |
+| `project_control` | Editor-session binding, launch/wait, project automation context, Output Log and Message Log inspection, PIE lifecycle control, host build/restart/sync, and `apply_window_ui_changes` |
+| `automation_testing` | Host-side automation runs and automation-run polling |
 | `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 |

package/dist/execution/adaptive-executor.js

@@ -2,6 +2,15 @@
  * AdaptiveExecutor routes tool calls to the best available adapter.
  * Falls back from editor to commandlet for compatible operations.
  */
+const EDITOR_FALLBACK_ERROR_FRAGMENTS = [
+    'UE Editor not running or Remote Control not available',
+    'BlueprintExtractor subsystem not found',
+    'No active editor is selected for this MCP session',
+    'Multiple running editors match the workspace project',
+    'Active editor mismatch',
+    'previously selected active editor',
+    'The selected active editor is currently unavailable on its registered Remote Control endpoint.',
+];
 export class AdaptiveExecutor {
     editorAdapter;
     commandletAdapter;
@@ -47,10 +56,42 @@ export class AdaptiveExecutor {
     async executeRouted(editorFallback, method, params, options) {
         const toolName = this._activeToolName;
         const detection = await this.detector.detect();
+        const tryCommandletFallback = async (error, requiredCapability) => {
+            if (!toolName || !this.commandletAdapter || !shouldFallbackToCommandlet(error)) {
+                throw error;
+            }
+            const commandletCapabilities = this.commandletAdapter.getCapabilities();
+            if (!commandletCapabilities.has(requiredCapability) && requiredCapability !== 'write_simple') {
+                throw error;
+            }
+            const available = await this.commandletAdapter.isAvailable();
+            if (!available) {
+                throw error;
+            }
+            this.detector.invalidateCache();
+            return this.commandletAdapter.execute('BlueprintExtractor', method, params);
+        };
         // If no active tool context or editor mode, use the original path
         // (preserves callSubsystemJson error-checking layer)
         if (!toolName || detection.mode === 'editor') {
-            return editorFallback(method, params, options);
+            if (!toolName) {
+                return editorFallback(method, params, options);
+            }
+            const toolMode = this.getToolMode(toolName);
+            const requiredCapability = toolMode === 'read_only'
+                ? 'read'
+                : toolMode === 'both'
+                    ? 'write_simple'
+                    : 'write_complex';
+            try {
+                return await editorFallback(method, params, options);
+            }
+            catch (error) {
+                if (toolMode === 'editor_only') {
+                    throw error;
+                }
+                return tryCommandletFallback(error, requiredCapability);
+            }
         }
         const toolMode = this.getToolMode(toolName);
         const requiredCapability = toolMode === 'read_only'
@@ -100,6 +141,13 @@ export class AdaptiveExecutor {
         throw new ExecutorError('MODE_UNAVAILABLE', `No execution mode available for tool '${toolName}'. ${detection.reason}`, toolName, detection.mode, requiredCapability);
     }
 }
+function shouldFallbackToCommandlet(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    if (message.startsWith('Failed to call ')) {
+        return true;
+    }
+    return EDITOR_FALLBACK_ERROR_FRAGMENTS.some((fragment) => message.includes(fragment));
+}
 export class ExecutorError extends Error {
     code;
     toolName;

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

@@ -254,7 +254,7 @@ export const NEXT_STEP_HINTS_REGISTRY = new Map([
     ['extract_widget_blueprint', extractionHints('extract_widget_blueprint', {
             on_success: [
                 'Use patch_widget or replace_widget_tree to modify the widget.',
-                'Use compile_widget_blueprint to check for errors.',
+                'Use compile_widget to check for errors.',
                 'Use capture_widget_preview for visual verification.',
             ],
             scope_suggestion: 'widget_authoring',
@@ -276,25 +276,17 @@ export const NEXT_STEP_HINTS_REGISTRY = new Map([
     // =========================================================================
     // Widget structure tools
     // =========================================================================
-    ['create_widget_blueprint', creationHints('extract_widget_blueprint', 'build_widget_tree', {
+    ['create_widget_blueprint', creationHints('extract_widget_blueprint', 'replace_widget_tree', {
             on_success: [
-                'Use build_widget_tree to populate the widget tree.',
+                'Use replace_widget_tree to populate the widget tree.',
                 'Use extract_widget_blueprint to verify.',
                 'Use save_assets to persist.',
             ],
             scope_suggestion: 'widget_authoring',
         })],
-    ['build_widget_tree', modificationHints('extract_widget_blueprint', {
-            on_success: [
-                'Use compile_widget_blueprint to verify the tree compiles.',
-                'Use extract_widget_blueprint to inspect the result.',
-                'Use save_assets to persist.',
-            ],
-            scope_suggestion: 'widget_authoring',
-        })],
     ['replace_widget_tree', modificationHints('extract_widget_blueprint', {
             on_success: [
-                'Use compile_widget_blueprint to verify the new tree.',
+                'Use compile_widget to verify the new tree.',
                 'Use extract_widget_blueprint to inspect the result.',
                 'Use save_assets to persist.',
             ],
@@ -344,7 +336,7 @@ export const NEXT_STEP_HINTS_REGISTRY = new Map([
         })],
     ['replace_widget_class', modificationHints('extract_widget_blueprint', {
             on_success: [
-                'Use compile_widget_blueprint to verify the class change.',
+                'Use compile_widget to verify the class change.',
                 'Use extract_widget_blueprint to inspect the result.',
                 'Use save_assets to persist.',
             ],
@@ -352,7 +344,7 @@ export const NEXT_STEP_HINTS_REGISTRY = new Map([
         })],
     ['batch_widget_operations', modificationHints('extract_widget_blueprint', {
             on_success: [
-                'Use compile_widget_blueprint to verify the batch result.',
+                'Use compile_widget to verify the batch result.',
                 'Use extract_widget_blueprint to inspect changes.',
                 'Use save_assets to persist.',
             ],
@@ -370,36 +362,6 @@ export const NEXT_STEP_HINTS_REGISTRY = new Map([
             ],
             scope_suggestion: 'widget_authoring',
         }],
-    ['modify_widget_blueprint', modificationHints('extract_widget_blueprint', {
-            on_success: [
-                'Use operation-specific tools (patch_widget, replace_widget_tree, etc.) instead.',
-                'Use save_assets to persist changes.',
-            ],
-            on_error: [
-                'Use extract_widget_blueprint to inspect current state.',
-                'Consider using operation-specific tools for clearer errors.',
-            ],
-            scope_suggestion: 'widget_authoring',
-        })],
-    ['modify_widget', modificationHints('extract_widget_blueprint', {
-            on_success: [
-                'Use save_assets to persist changes.',
-                'Use extract_widget_blueprint to verify.',
-            ],
-            scope_suggestion: 'widget_authoring',
-        })],
-    ['compile_widget_blueprint', {
-            on_success: [
-                'Inspect compile.messages and diagnostics for warnings.',
-                'Re-extract the widget blueprint before applying the next patch.',
-                'Check BindWidget names/types if there are abstract class references.',
-            ],
-            on_error: [
-                'Use extract_widget_blueprint to inspect the current state.',
-                'Fix reported issues and recompile.',
-            ],
-            scope_suggestion: 'widget_authoring',
-        }],
     // =========================================================================
     // Widget verification tools
     // =========================================================================
@@ -464,7 +426,7 @@ export const NEXT_STEP_HINTS_REGISTRY = new Map([
     ['apply_commonui_button_style', {
             on_success: [
                 'Use extract_widget_blueprint to verify the style was applied.',
-                'Use compile_widget_blueprint to verify compilation.',
+                'Use compile_widget to verify compilation.',
                 'Use save_assets to persist.',
             ],
             on_error: [

package/dist/helpers/project-resolution.js

@@ -1,7 +1,7 @@
 import { access } from 'node:fs/promises';
 import { constants as fsConstants } from 'node:fs';
-import path, { resolve } from 'node:path';
-import { buildEngineAssociationCandidates, readProjectEngineAssociation } from './workspace-project.js';
+import path, { posix as posixPath, win32 as win32Path } from 'node:path';
+import { buildEngineAssociationCandidates, isWindowsStylePath, isWslMountedWindowsPath, readProjectEngineAssociation, toHostFilesystemPath, toWindowsStylePath, } from './workspace-project.js';
 export function rememberExternalBuild(result) {
     return {
         success: result.success === true,
@@ -32,6 +32,9 @@ export async function getProjectAutomationContext(deps) {
     return nextContext;
 }
 const cachedHeuristicEngineRoots = new Map();
+function getPathModule(platform) {
+    return platform === 'win32' ? win32Path : posixPath;
+}
 export function getHeuristicEngineCandidates(platform = process.platform) {
     if (platform === 'win32') {
         return [
@@ -74,10 +77,13 @@ function getEngineMarkers(platform) {
         'Engine/Build/BatchFiles/Build.sh',
     ];
 }
-async function accessFirstMatchingMarker(root, markers) {
+async function accessFirstMatchingMarker(root, markers, targetPlatform, hostPlatform) {
+    const pathModule = getPathModule(targetPlatform);
+    const normalizedRoot = targetPlatform === 'win32' ? toWindowsStylePath(root) : root;
     for (const marker of markers) {
         try {
-            await access(resolve(root, marker), fsConstants.F_OK);
+            const candidate = pathModule.resolve(normalizedRoot, marker);
+            await access(toHostFilesystemPath(candidate, targetPlatform, hostPlatform), fsConstants.F_OK);
             return true;
         }
         catch {
@@ -86,24 +92,24 @@ async function accessFirstMatchingMarker(root, markers) {
     }
     return false;
 }
-async function probeEngineRootHeuristic(platform) {
-    if (cachedHeuristicEngineRoots.has(platform)) {
-        return cachedHeuristicEngineRoots.get(platform) || undefined;
+async function probeEngineRootHeuristic(targetPlatform, hostPlatform) {
+    const cacheKey = `${hostPlatform}:${targetPlatform}`;
+    if (cachedHeuristicEngineRoots.has(cacheKey)) {
+        return cachedHeuristicEngineRoots.get(cacheKey) || undefined;
     }
-    for (const candidate of getHeuristicEngineCandidates(platform)) {
-        if (await accessFirstMatchingMarker(candidate, getEngineMarkers(platform))) {
-            cachedHeuristicEngineRoots.set(platform, candidate);
+    for (const candidate of getHeuristicEngineCandidates(targetPlatform)) {
+        if (await accessFirstMatchingMarker(candidate, getEngineMarkers(targetPlatform), targetPlatform, hostPlatform)) {
+            cachedHeuristicEngineRoots.set(cacheKey, candidate);
             return candidate;
         }
     }
-    cachedHeuristicEngineRoots.set(platform, '');
+    cachedHeuristicEngineRoots.set(cacheKey, '');
     return undefined;
 }
-async function probePreferredEngineRoot(candidates, platform) {
-    const markers = getEngineMarkers(platform);
+async function probePreferredEngineRoot(candidates, hostPlatform) {
     for (const candidate of candidates) {
-        if (await accessFirstMatchingMarker(candidate, markers)) {
-            return candidate;
+        if (await accessFirstMatchingMarker(candidate.path, getEngineMarkers(candidate.platform), candidate.platform, hostPlatform)) {
+            return candidate.path;
         }
     }
     return undefined;
@@ -133,7 +139,16 @@ 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, platform);
+    const windowsWorkspaceHint = [request.engine_root, request.project_path, projectPathFromWorkspace, projectPathFromEnv]
+        .filter((value) => typeof value === 'string' && value.length > 0)
+        .some((value) => isWindowsStylePath(value) || isWslMountedWindowsPath(value));
+    const heuristicPlatforms = windowsWorkspaceHint && platform !== 'win32'
+        ? ['win32', platform]
+        : [platform];
+    const associationCandidates = heuristicPlatforms.flatMap((candidatePlatform) => (buildEngineAssociationCandidates(engineAssociation, candidatePlatform).map((candidate) => ({
+        path: candidate,
+        platform: candidatePlatform,
+    }))));
     let engineRoot = firstDefinedString(request.engine_root, engineRootFromContext, engineRootFromEnv);
     let engineRootSource;
     if (request.engine_root) {
@@ -147,7 +162,15 @@ export async function resolveProjectInputs(request, deps) {
     }
     else {
         const preferredCandidate = await probePreferredEngineRoot(associationCandidates, platform);
-        const heuristicRoot = preferredCandidate ?? await probeEngineRootHeuristic(platform);
+        let heuristicRoot = preferredCandidate;
+        if (!heuristicRoot) {
+            for (const candidatePlatform of heuristicPlatforms) {
+                heuristicRoot = await probeEngineRootHeuristic(candidatePlatform, platform);
+                if (heuristicRoot) {
+                    break;
+                }
+            }
+        }
         if (heuristicRoot) {
             engineRoot = heuristicRoot;
             engineRootSource = 'filesystem_heuristic';

package/dist/helpers/tool-help.js

@@ -102,22 +102,6 @@ export function summarizeOutputSchema(schema) {
 }
 export function collectToolExampleFamilies(exampleCatalog, toolName) {
     const equivalentToolNames = new Set([toolName]);
-    if (toolName === 'modify_widget_blueprint') {
-        [
-            'patch_widget',
-            'patch_widget_class_defaults',
-            'insert_widget_child',
-            'remove_widget',
-            'move_widget',
-            'wrap_widget',
-            'replace_widget_class',
-            'replace_widget_tree',
-            'batch_widget_operations',
-        ].forEach((name) => equivalentToolNames.add(name));
-    }
-    if (toolName === 'compile_widget_blueprint') {
-        equivalentToolNames.add('compile_widget');
-    }
     return Object.entries(exampleCatalog)
         .flatMap(([family, entry]) => {
         const exampleTitles = entry.examples
@@ -143,7 +127,6 @@ export function collectRelatedResources(toolName) {
     if (toolName.startsWith('create_')
         || toolName.startsWith('modify_')
         || toolName.startsWith('apply_')
-        || toolName === 'build_widget_tree'
         || toolName === 'save_assets') {
         resources.add('blueprint://write-capabilities');
         resources.add('blueprint://authoring-conventions');
@@ -175,7 +158,10 @@ export function collectRelatedResources(toolName) {
         || toolName === 'sync_project_code'
         || toolName === 'start_pie'
         || toolName === 'stop_pie'
-        || toolName === 'relaunch_pie') {
+        || toolName === 'relaunch_pie'
+        || toolName === 'read_output_log'
+        || toolName === 'list_message_log_listings'
+        || toolName === 'read_message_log') {
         resources.add('blueprint://project-automation');
     }
     if (toolName === 'review_blueprint' || toolName === 'audit_project_assets') {

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

@@ -3,6 +3,10 @@ export type WorkspaceProjectResolution = {
     ambiguous: boolean;
     searchedFrom: string;
 };
+export declare function isWindowsStylePath(input: string): boolean;
+export declare function isWslMountedWindowsPath(input: string): boolean;
+export declare function toWindowsStylePath(input: string): string;
+export declare function toHostFilesystemPath(input: string, targetPlatform: NodeJS.Platform, hostPlatform?: NodeJS.Platform): string;
 export declare function normalizeFilesystemPath(input: string | undefined): string | undefined;
 export declare function filesystemPathsEqual(left: string | undefined, right: string | undefined): boolean;
 export declare function findNearestWorkspaceProject(startDir?: string): Promise<WorkspaceProjectResolution>;