blueprint-extractor-mcp 8.2.3 → 8.2.5

package/README.md

@@ -19,6 +19,8 @@
 
 Blueprint Extractor MCP is a [Model Context Protocol](https://modelcontextprotocol.io) server that bridges AI coding assistants (Claude Code, Codex, OpenCode, etc.) to a running Unreal Editor instance via the Remote Control HTTP API.
 
+For compatible tools, the server can also execute through a commandlet lane when no reachable editor session is available. When an editor is already running, editor execution stays preferred for editor-only flows and for save paths that need to avoid package-lock contention.
+
 ```
  AI Assistant         stdio           MCP Server         HTTP :30010        Unreal Editor
  ─────────────  ◄────────────►  ─────────────────  ◄──────────────────►  ─────────────────
@@ -116,11 +118,11 @@ npm install --prefix ~/.config/opencode --save-exact blueprint-extractor-mcp@lat
 
 ## Tool Surface
 
-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`.
+Use `activate_tool_profile` to switch between the compact `default` surface and the full `expert` surface. The default profile keeps the context window lean with a retrieval-first core and loads specialized families on demand via `activate_workflow_scope`.
 
 | Scope | What It Unlocks |
 |:------|:----------------|
-| **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` |
+| **Core** *(always on in `default` profile)* | Retrieval-first discovery and persistence: `search_assets`, `find_and_extract`, `extract_blueprint`, `extract_asset`, `check_asset_exists`, `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` | 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 |
@@ -146,6 +148,7 @@ The tool contract is optimized for model reliability:
 - **`structuredContent`** carries the canonical success and error payload for MCP clients that consume structured results directly
 - **Structured error envelopes** with diagnostic codes and recovery hints
 - **Explicit-save semantics** — nothing persists until `save_assets` is called
+- **Dual execution lanes** — compatible tools can fall back to commandlet execution when no editor is reachable, while `save_assets` prefers a running editor and can reroute there on file-lock contention
 - **Next-step hints** guiding the assistant toward the logical follow-up action
 
 See [../docs/CURRENT_STATUS.md](../docs/CURRENT_STATUS.md) for the current validation snapshot, normative docs, and the one-shot stabilization ledger.

package/dist/active-editor-session.js

@@ -80,7 +80,7 @@ export class ActiveEditorSession {
         return this.getClient(rebound).checkConnection();
     }
     async editorModeAvailable() {
-        return true;
+        return this.checkConnection();
     }
     async listRunningEditors() {
         const result = await listRegisteredEditors();

package/dist/execution/adaptive-executor.js

@@ -11,6 +11,17 @@ const EDITOR_FALLBACK_ERROR_FRAGMENTS = [
     'previously selected active editor',
     'The selected active editor is currently unavailable on its registered Remote Control endpoint.',
 ];
+const COMMANDLET_LOCK_ERROR_FRAGMENTS = [
+    'locked by another process',
+    'locked file',
+    'cannot access the file',
+    'asset lock conflict',
+    'save_failed',
+    'Failed to save one or more packages',
+];
+const EDITOR_PREFERRED_WHILE_RUNNING_TOOLS = new Set([
+    'save_assets',
+]);
 export class AdaptiveExecutor {
     editorAdapter;
     commandletAdapter;
@@ -56,7 +67,16 @@ 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) {
+            return editorFallback(method, params, options);
+        }
+        const toolMode = this.getToolMode(toolName);
+        const requiredCapability = toolMode === 'read_only'
+            ? 'read'
+            : toolMode === 'both'
+                ? 'write_simple'
+                : 'write_complex';
+        const tryCommandletFallback = async (error) => {
             if (!toolName || !this.commandletAdapter || !shouldFallbackToCommandlet(error)) {
                 throw error;
             }
@@ -71,18 +91,9 @@ export class AdaptiveExecutor {
             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') {
-            if (!toolName) {
-                return editorFallback(method, params, options);
-            }
-            const toolMode = this.getToolMode(toolName);
-            const requiredCapability = toolMode === 'read_only'
-                ? 'read'
-                : toolMode === 'both'
-                    ? 'write_simple'
-                    : 'write_complex';
+        // Editor mode keeps the existing direct path, with commandlet fallback for
+        // compatible tools when the editor call fails.
+        if (detection.mode === 'editor') {
             try {
                 return await editorFallback(method, params, options);
             }
@@ -90,15 +101,9 @@ export class AdaptiveExecutor {
                 if (toolMode === 'editor_only') {
                     throw error;
                 }
-                return tryCommandletFallback(error, requiredCapability);
+                return tryCommandletFallback(error);
             }
         }
-        const toolMode = this.getToolMode(toolName);
-        const requiredCapability = toolMode === 'read_only'
-            ? 'read'
-            : toolMode === 'both'
-                ? 'write_simple'
-                : 'write_complex';
         // Try commandlet for compatible tools
         if (detection.mode === 'commandlet' && this.commandletAdapter) {
             if (toolMode === 'editor_only') {
@@ -108,7 +113,36 @@ export class AdaptiveExecutor {
             if (!capabilities.has(requiredCapability) && requiredCapability !== 'write_simple') {
                 throw new ExecutorError('CAPABILITY_MISMATCH', `Tool '${toolName}' requires '${requiredCapability}' capability which commandlet mode does not support.`, toolName, detection.mode, requiredCapability);
             }
-            return this.commandletAdapter.execute('BlueprintExtractor', method, params);
+            if (shouldPreferEditorWhileRunning(toolName)) {
+                try {
+                    const editorAvailable = await this.editorAdapter.isAvailable();
+                    if (editorAvailable) {
+                        this.detector.invalidateCache();
+                        return await editorFallback(method, params, options);
+                    }
+                }
+                catch {
+                    // Fall back to the commandlet path below.
+                }
+            }
+            try {
+                return await this.commandletAdapter.execute('BlueprintExtractor', method, params);
+            }
+            catch (error) {
+                if (toolMode !== 'read_only' && shouldFallbackToEditorOnLock(error)) {
+                    try {
+                        const editorAvailable = await this.editorAdapter.isAvailable();
+                        if (editorAvailable) {
+                            this.detector.invalidateCache();
+                            return await editorFallback(method, params, options);
+                        }
+                    }
+                    catch {
+                        // If the editor is not actually reachable, preserve the commandlet error.
+                    }
+                }
+                throw error;
+            }
         }
         // No adapter available
         throw new ExecutorError('MODE_UNAVAILABLE', `No execution mode available for tool '${toolName}'. ${detection.reason}`, toolName, detection.mode, requiredCapability);
@@ -122,7 +156,6 @@ export class AdaptiveExecutor {
             : toolMode === 'both'
                 ? 'write_simple'
                 : 'write_complex';
-        // Try editor first
         if (detection.mode === 'editor') {
             return this.editorAdapter.execute(subsystem, method, params);
         }
@@ -135,7 +168,36 @@ export class AdaptiveExecutor {
             if (!capabilities.has(requiredCapability) && requiredCapability !== 'write_simple') {
                 throw new ExecutorError('CAPABILITY_MISMATCH', `Tool '${toolName}' requires '${requiredCapability}' capability which commandlet mode does not support.`, toolName, detection.mode, requiredCapability);
             }
-            return this.commandletAdapter.execute(subsystem, method, params);
+            if (shouldPreferEditorWhileRunning(toolName)) {
+                try {
+                    const editorAvailable = await this.editorAdapter.isAvailable();
+                    if (editorAvailable) {
+                        this.detector.invalidateCache();
+                        return await this.editorAdapter.execute(subsystem, method, params);
+                    }
+                }
+                catch {
+                    // Keep the commandlet path below.
+                }
+            }
+            try {
+                return await this.commandletAdapter.execute(subsystem, method, params);
+            }
+            catch (error) {
+                if (toolMode !== 'read_only' && shouldFallbackToEditorOnLock(error)) {
+                    try {
+                        const editorAvailable = await this.editorAdapter.isAvailable();
+                        if (editorAvailable) {
+                            this.detector.invalidateCache();
+                            return await this.editorAdapter.execute(subsystem, method, params);
+                        }
+                    }
+                    catch {
+                        // Preserve the original commandlet failure below.
+                    }
+                }
+                throw error;
+            }
         }
         // No adapter available
         throw new ExecutorError('MODE_UNAVAILABLE', `No execution mode available for tool '${toolName}'. ${detection.reason}`, toolName, detection.mode, requiredCapability);
@@ -148,6 +210,13 @@ function shouldFallbackToCommandlet(error) {
     }
     return EDITOR_FALLBACK_ERROR_FRAGMENTS.some((fragment) => message.includes(fragment));
 }
+function shouldFallbackToEditorOnLock(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return COMMANDLET_LOCK_ERROR_FRAGMENTS.some((fragment) => message.includes(fragment));
+}
+function shouldPreferEditorWhileRunning(toolName) {
+    return EDITOR_PREFERRED_WHILE_RUNNING_TOOLS.has(toolName);
+}
 export class ExecutorError extends Error {
     code;
     toolName;

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, { posix as posixPath, win32 as win32Path } from 'node:path';
-import { buildEngineAssociationCandidates, isWindowsStylePath, isWslMountedWindowsPath, readProjectEngineAssociation, toHostFilesystemPath, toWindowsStylePath, } from './workspace-project.js';
+import { buildEngineAssociationCandidates, filesystemPathsEqual, isWindowsStylePath, isWslMountedWindowsPath, readProjectEngineAssociation, toHostFilesystemPath, toWindowsStylePath, } from './workspace-project.js';
 export function rememberExternalBuild(result) {
     return {
         success: result.success === true,
@@ -114,6 +114,32 @@ async function probePreferredEngineRoot(candidates, hostPlatform) {
     }
     return undefined;
 }
+function hasConcreteAssociationCandidate(candidates) {
+    return candidates.some((candidate) => (isWindowsStylePath(candidate.path)
+        || isWslMountedWindowsPath(candidate.path)
+        || candidate.path.startsWith('/')));
+}
+function matchesAssociationCandidate(engineRoot, candidates) {
+    if (!engineRoot) {
+        return false;
+    }
+    return candidates.some((candidate) => filesystemPathsEqual(engineRoot, candidate.path));
+}
+function buildEngineRootConflict(engineAssociation, candidates, implicitRoots) {
+    if (!engineAssociation || implicitRoots.length === 0) {
+        return undefined;
+    }
+    const roots = implicitRoots.map(({ source, path }) => `${source}:${path}`).join(', ');
+    const concreteCandidates = candidates
+        .map((candidate) => candidate.path)
+        .filter((candidate, index, all) => all.indexOf(candidate) === index)
+        .filter((candidate) => (isWindowsStylePath(candidate)
+        || isWslMountedWindowsPath(candidate)
+        || candidate.startsWith('/')));
+    return concreteCandidates.length > 0
+        ? `project EngineAssociation "${engineAssociation}" conflicts with implicit engine roots (${roots}); expected one of ${concreteCandidates.join(' | ')}`
+        : `project EngineAssociation "${engineAssociation}" conflicts with implicit engine roots (${roots})`;
+}
 export async function resolveProjectInputs(request, deps) {
     const { getProjectAutomationContext, firstDefinedString, env = process.env, workspaceProjectPath, platform = process.platform, } = deps;
     let context = null;
@@ -149,11 +175,45 @@ export async function resolveProjectInputs(request, deps) {
         path: candidate,
         platform: candidatePlatform,
     }))));
+    const associationIsConcrete = hasConcreteAssociationCandidate(associationCandidates);
+    const matchingContextEngineRoot = associationIsConcrete && matchesAssociationCandidate(engineRootFromContext, associationCandidates)
+        ? engineRootFromContext
+        : undefined;
+    const matchingEnvEngineRoot = associationIsConcrete && matchesAssociationCandidate(engineRootFromEnv, associationCandidates)
+        ? engineRootFromEnv
+        : undefined;
+    const conflictingImplicitRoots = associationIsConcrete
+        ? [
+            ...(engineRootFromContext && !matchingContextEngineRoot ? [{ source: 'editor_context', path: engineRootFromContext }] : []),
+            ...(engineRootFromEnv && !matchingEnvEngineRoot ? [{ source: 'environment', path: engineRootFromEnv }] : []),
+        ]
+        : [];
     let engineRoot = firstDefinedString(request.engine_root, engineRootFromContext, engineRootFromEnv);
     let engineRootSource;
+    let engineRootConflict;
     if (request.engine_root) {
         engineRootSource = 'explicit';
     }
+    else if (associationIsConcrete) {
+        const preferredCandidate = await probePreferredEngineRoot(associationCandidates, platform);
+        if (matchingContextEngineRoot) {
+            engineRoot = matchingContextEngineRoot;
+            engineRootSource = 'editor_context';
+        }
+        else if (matchingEnvEngineRoot) {
+            engineRoot = matchingEnvEngineRoot;
+            engineRootSource = 'environment';
+        }
+        else if (preferredCandidate) {
+            engineRoot = preferredCandidate;
+            engineRootSource = 'project_association';
+        }
+        else {
+            engineRoot = undefined;
+            engineRootSource = 'missing';
+            engineRootConflict = buildEngineRootConflict(engineAssociation, associationCandidates, conflictingImplicitRoots);
+        }
+    }
     else if (engineRootFromContext) {
         engineRootSource = 'editor_context';
     }
@@ -161,8 +221,7 @@ export async function resolveProjectInputs(request, deps) {
         engineRootSource = 'environment';
     }
     else {
-        const preferredCandidate = await probePreferredEngineRoot(associationCandidates, platform);
-        let heuristicRoot = preferredCandidate;
+        let heuristicRoot;
         if (!heuristicRoot) {
             for (const candidatePlatform of heuristicPlatforms) {
                 heuristicRoot = await probeEngineRootHeuristic(candidatePlatform, platform);
@@ -185,6 +244,8 @@ export async function resolveProjectInputs(request, deps) {
         target,
         context,
         contextError,
+        projectEngineAssociation: engineAssociation,
+        engineRootConflict,
         sources: {
             engineRoot: engineRootSource,
             projectPath: request.project_path ? 'explicit' : projectPathFromContext ? 'editor_context' : projectPathFromWorkspace ? 'workspace' : projectPathFromEnv ? 'environment' : 'missing',

package/dist/helpers/project-utils.js

@@ -10,11 +10,17 @@ export function buildProjectResolutionDiagnostics(resolved) {
         `project_path=${resolved.sources.projectPath}`,
         `target=${resolved.sources.target}`,
     ];
+    if (resolved.projectEngineAssociation) {
+        diagnostics.push(`project_engine_association=${resolved.projectEngineAssociation}`);
+    }
+    if (resolved.engineRootConflict) {
+        diagnostics.push(`engine_root_conflict=${resolved.engineRootConflict}`);
+    }
     if (resolved.contextError) {
         diagnostics.push(`editor_context_error=${resolved.contextError}`);
     }
     return diagnostics;
 }
 export function explainProjectResolutionFailure(prefix, resolved) {
-    return new Error(`${prefix}; attempted explicit args -> editor context -> environment (${buildProjectResolutionDiagnostics(resolved).join(', ')})`);
+    return new Error(`${prefix}; attempted explicit args -> project association -> editor context -> environment (${buildProjectResolutionDiagnostics(resolved).join(', ')})`);
 }

package/dist/resources/static-doc-resources.js

@@ -225,7 +225,7 @@ export function registerStaticDocResources(server) {
         '- list_message_log_listings probes known built-in and caller-supplied Message Log listing names and reports which ones are currently registered.',
         '- read_message_log reads one registered Message Log listing with severity, token, text, and paging filters.',
         '- compile_project_code runs an external UBT build from the MCP host.',
-        '- compile_project_code and sync_project_code resolve engine_root, project_path, and target in this order: explicit args -> editor context -> environment.',
+        '- compile_project_code and sync_project_code resolve project inputs by preferring explicit args, then honoring a concrete .uproject EngineAssociation before falling back to editor context and environment defaults.',
         '- trigger_live_coding requests an editor-side Live Coding compile and is only supported on Windows-focused setups. changed_paths remains an accepted compatibility input but the current editor-side trigger ignores it. When Live Coding reports NoChanges or another fallback state, the result includes fallbackRecommended, reason, and the last external build context when available.',
         '- restart_editor requests an editor restart, then waits for Remote Control to disconnect and reconnect. When save_dirty_assets is true, all dirty packages are saved before the restart to prevent modal save dialogs.',
         '- wait_for_editor polls Remote Control once per second and returns a normalized readiness result that callers can use after restart windows or transient disconnects.',

package/dist/server-config.js

@@ -5,8 +5,9 @@ export const serverInstructions = [
     'Blueprint Extractor MCP uses a v2 public contract with tool profiles, workflow-scoped tool surfaces, snake_case arguments, prompt workflows, and structured JSON results.',
     // Tool discovery
     'Use activate_tool_profile with profile: "default" for the compact scoped surface or profile: "expert" for the full flat tool list. Clients with tool-list change support start in default; fallback clients start in expert.',
-    'A compact core tool set is visible in the default profile. Use activate_workflow_scope to load specialized tool families: widget_authoring (or sub-scopes: widget_authoring_structure, widget_authoring_visual, widget_verification), material_authoring, blueprint_authoring, schema_ai_authoring, animation_authoring, data_tables, import, project_control, automation_testing, verification, analysis, and project_intelligence.',
-    'Use find_and_extract for search+extract in one call from the default core surface. Use search_assets when you only need to locate assets.',
+    'A compact retrieval-first core tool set is visible in the default profile: search_assets, find_and_extract, extract_blueprint, extract_asset, check_asset_exists, save_assets, get_tool_help, and the profile/scope switches.',
+    'Use activate_workflow_scope to load specialized tool families: widget_authoring (or sub-scopes: widget_authoring_structure, widget_authoring_visual, widget_verification), material_authoring, blueprint_authoring, schema_ai_authoring, animation_authoring, data_tables, import, project_control, automation_testing, verification, analysis, and project_intelligence.',
+    'Prefer find_and_extract for search plus routed extraction from the default core surface. Use search_assets when you only need to locate assets.',
     'Call get_tool_help before the first use of a complex or polymorphic tool when you need operation-specific payload guidance. Use activate_workflow_scope explicitly when the tool family is not in the current profile.',
     // Deferred tool directory (tools available via activate_workflow_scope)
     'Deferred tool families — widget_authoring_structure: recipe-first widget authoring, tree replacement, diff/patch DSLs, and focused structural edits. widget_authoring_visual: CommonUI styles, widget animations, compile_widget, extraction, and preview capture. widget_verification: captures and comparisons. widget_authoring: activates all three widget sub-scopes. material_authoring: create_material_setup, modify_material DSL/batch authoring, material_graph_operation, and material instances. blueprint_authoring: scaffold_blueprint, modify_blueprint_graphs DSL authoring, member edits, and Live Coding trigger. schema_ai_authoring: structs, enums, blackboards, behavior trees, state trees. animation_authoring: anim sequences, montages, blend spaces, widget animations. data_tables: data assets, input actions, tables, curves. import: import_assets, job tracking. project_control: editor-session binding, launch/wait, project automation context, Output Log and Message Log inspection, PIE lifecycle control, host build/restart/sync flows, and apply_window_ui_changes. automation_testing: run/get/list automation tests. verification: widget captures, editor screenshots, runtime screenshots, and comparisons. analysis: deterministic Blueprint review and asset audits. project_intelligence: editor context, project indexing, and metadata-first context search.',

package/dist/tool-context.d.ts

@@ -47,13 +47,15 @@ export type EditorContextSnapshot = {
     partial?: boolean;
     unsupportedSections?: string[];
 };
-export type ProjectInputSource = 'explicit' | 'editor_context' | 'workspace' | 'environment' | 'filesystem_heuristic' | 'missing';
+export type ProjectInputSource = 'explicit' | 'editor_context' | 'workspace' | 'environment' | 'project_association' | 'filesystem_heuristic' | 'missing';
 export type ResolvedProjectInputs = {
     engineRoot?: string;
     projectPath?: string;
     target?: string;
     context: ProjectAutomationContext | null;
     contextError?: string;
+    projectEngineAssociation?: string;
+    engineRootConflict?: string;
     sources: {
         engineRoot: ProjectInputSource;
         projectPath: ProjectInputSource;

package/dist/tool-surface-manager.d.ts

@@ -8,6 +8,10 @@ export interface WorkflowScope {
     description: string;
 }
 export declare const WORKFLOW_SCOPE_IDS: readonly WorkflowScopeId[];
+/**
+ * Keep the always-visible default surface small so weaker models can route
+ * through search, routed extraction, and explicit help before expanding.
+ */
 export declare const CORE_TOOLS: ReadonlySet<string>;
 export declare class ToolSurfaceManager {
     private registeredToolMap;

package/dist/tool-surface-manager.js

@@ -15,14 +15,15 @@ export const WORKFLOW_SCOPE_IDS = [
     'analysis',
     'project_intelligence',
 ];
+/**
+ * Keep the always-visible default surface small so weaker models can route
+ * through search, routed extraction, and explicit help before expanding.
+ */
 export const CORE_TOOLS = new Set([
     'search_assets',
     'find_and_extract',
     'extract_blueprint',
     'extract_asset',
-    'extract_material',
-    'extract_cascade',
-    'list_assets',
     'check_asset_exists',
     'save_assets',
     'get_tool_help',

package/package.json

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