blueprint-extractor-mcp 8.2.4 → 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/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/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/package.json

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