blueprint-extractor-mcp 8.0.0 → 8.1.0

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                109 tools                               BlueprintExtractor
+  Codex / OpenCode                112 tools                               BlueprintExtractor
   ...                             38 resources                            plugin
                                   4 resource templates
                                   12 prompts
@@ -86,6 +86,10 @@ codex mcp add --env UE_REMOTE_CONTROL_PORT=30010 \
 <tr><td><b>OpenCode</b></td></tr>
 <tr><td>
 
+```bash
+npm install --prefix ~/.config/opencode --save-exact blueprint-extractor-mcp@latest
+```
+
 ```jsonc
 // ~/.config/opencode/opencode.json
 {
@@ -93,7 +97,7 @@ codex mcp add --env UE_REMOTE_CONTROL_PORT=30010 \
   "mcp": {
     "blueprint-extractor": {
       "type": "local",
-      "command": ["npx", "-y", "blueprint-extractor-mcp@latest"],
+      "command": ["/absolute/path/to/.config/opencode/node_modules/.bin/blueprint-extractor-mcp"],
       "enabled": true,
       "environment": {
         "UE_REMOTE_CONTROL_PORT": "30010"
@@ -106,7 +110,7 @@ codex mcp add --env UE_REMOTE_CONTROL_PORT=30010 \
 </td></tr>
 </table>
 
-> On Windows, wrap `npx` with `cmd /c` if your shell requires it.
+> On Windows, point `command` at `C:\Users\you\.config\opencode\node_modules\.bin\blueprint-extractor-mcp.cmd`.
 
 <br>
 
@@ -127,7 +131,7 @@ Use `activate_tool_profile` to switch between the compact `default` surface and
 | `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 |
-| `project_control` | Editor-session binding, launch/wait, project automation context, PIE lifecycle control, host build/restart/sync, and `apply_window_ui_changes` |
+| `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 |

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/tool-help.js

@@ -158,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/prompts/prompt-catalog.d.ts

@@ -1,4 +1,4 @@
-import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { McpServer, RegisteredPrompt } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { z } from 'zod';
 export type PromptCatalogEntry = {
     title: string;
@@ -105,4 +105,4 @@ export declare const designSpecSchemaExample: {
     };
 };
 export declare const promptCatalog: Record<string, PromptCatalogEntry>;
-export declare function registerPromptCatalog(server: Pick<McpServer, 'registerPrompt'>): void;
+export declare function registerPromptCatalog(server: Pick<McpServer, 'registerPrompt'>): Map<string, RegisteredPrompt>;

package/dist/prompts/prompt-catalog.js

@@ -342,8 +342,9 @@ export const promptCatalog = {
     },
 };
 export function registerPromptCatalog(server) {
+    const registeredPrompts = new Map();
     for (const [name, prompt] of Object.entries(promptCatalog)) {
-        server.registerPrompt(name, {
+        const registeredPrompt = server.registerPrompt(name, {
             title: prompt.title,
             description: prompt.description,
             argsSchema: prompt.args,
@@ -357,5 +358,7 @@ export function registerPromptCatalog(server) {
                     },
                 }],
         }));
+        registeredPrompts.set(name, registeredPrompt);
     }
+    return registeredPrompts;
 }

package/dist/register-server-resources.d.ts

@@ -1,4 +1,4 @@
-import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { McpServer, type RegisteredPrompt } from '@modelcontextprotocol/sdk/server/mcp.js';
 import type { AutomationControllerLike } from './automation-controller.js';
 type JsonSubsystemCaller = (method: string, params: Record<string, unknown>) => Promise<Record<string, unknown>>;
 type RegisterServerResourcesOptions = {
@@ -6,5 +6,8 @@ type RegisterServerResourcesOptions = {
     automationController: AutomationControllerLike;
     callSubsystemJson: JsonSubsystemCaller;
 };
-export declare function registerServerResources({ server, automationController, callSubsystemJson, }: RegisterServerResourcesOptions): void;
+type RegisterServerResourcesResult = {
+    registeredPrompts: Map<string, RegisteredPrompt>;
+};
+export declare function registerServerResources({ server, automationController, callSubsystemJson, }: RegisterServerResourcesOptions): RegisterServerResourcesResult;
 export {};

package/dist/register-server-resources.js

@@ -8,5 +8,6 @@ export function registerServerResources({ server, automationController, callSubs
         automationController,
         callSubsystemJson,
     });
-    registerPromptCatalog(server);
+    const registeredPrompts = registerPromptCatalog(server);
+    return { registeredPrompts };
 }

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

@@ -221,6 +221,9 @@ export function registerStaticDocResources(server) {
         '',
         '- activate_tool_profile selects the compact default scoped surface or the expert flat surface.',
         '- get_project_automation_context returns the editor-derived engine root, project file path, editor target, and isPlayingInEditor state that project_control tools use as their first fallback.',
+        '- read_output_log returns buffered Output Log lines with text/category/verbosity/time filters.',
+        '- 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.',
         '- 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.',

package/dist/schemas/tool-inputs.d.ts

@@ -318,12 +318,12 @@ export declare const MaterialParameterSelectorSchema: z.ZodObject<{
     index: z.ZodOptional<z.ZodNumber>;
 }, "strip", z.ZodTypeAny, {
     name: string;
-    association?: "layer" | "GlobalParameter" | "LayerParameter" | "BlendParameter" | "global" | "blend" | undefined;
     index?: number | undefined;
+    association?: "layer" | "GlobalParameter" | "LayerParameter" | "BlendParameter" | "global" | "blend" | undefined;
 }, {
     name: string;
-    association?: "layer" | "GlobalParameter" | "LayerParameter" | "BlendParameter" | "global" | "blend" | undefined;
     index?: number | undefined;
+    association?: "layer" | "GlobalParameter" | "LayerParameter" | "BlendParameter" | "global" | "blend" | undefined;
 }>;
 export declare const MaterialColorValueSchema: z.ZodObject<{
     r: z.ZodNumber;
@@ -350,13 +350,13 @@ export declare const MaterialScalarParameterSchema: z.ZodObject<{
 }, "strip", z.ZodTypeAny, {
     name: string;
     value: number;
-    association?: "layer" | "GlobalParameter" | "LayerParameter" | "BlendParameter" | "global" | "blend" | undefined;
     index?: number | undefined;
+    association?: "layer" | "GlobalParameter" | "LayerParameter" | "BlendParameter" | "global" | "blend" | undefined;
 }, {
     name: string;
     value: number;
-    association?: "layer" | "GlobalParameter" | "LayerParameter" | "BlendParameter" | "global" | "blend" | undefined;
     index?: number | undefined;
+    association?: "layer" | "GlobalParameter" | "LayerParameter" | "BlendParameter" | "global" | "blend" | undefined;
 }>;
 export declare const MaterialVectorParameterSchema: z.ZodObject<{
     name: z.ZodString;
@@ -387,8 +387,8 @@ export declare const MaterialVectorParameterSchema: z.ZodObject<{
         b: number;
         a: number;
     };
-    association?: "layer" | "GlobalParameter" | "LayerParameter" | "BlendParameter" | "global" | "blend" | undefined;
     index?: number | undefined;
+    association?: "layer" | "GlobalParameter" | "LayerParameter" | "BlendParameter" | "global" | "blend" | undefined;
 }, {
     name: string;
     value: {
@@ -397,8 +397,8 @@ export declare const MaterialVectorParameterSchema: z.ZodObject<{
         b: number;
         a: number;
     };
-    association?: "layer" | "GlobalParameter" | "LayerParameter" | "BlendParameter" | "global" | "blend" | undefined;
     index?: number | undefined;
+    association?: "layer" | "GlobalParameter" | "LayerParameter" | "BlendParameter" | "global" | "blend" | undefined;
 }>;
 export declare const MaterialTextureParameterSchema: z.ZodObject<{
     name: z.ZodString;
@@ -409,13 +409,13 @@ export declare const MaterialTextureParameterSchema: z.ZodObject<{
 }, "strip", z.ZodTypeAny, {
     name: string;
     value: string | null;
-    association?: "layer" | "GlobalParameter" | "LayerParameter" | "BlendParameter" | "global" | "blend" | undefined;
     index?: number | undefined;
+    association?: "layer" | "GlobalParameter" | "LayerParameter" | "BlendParameter" | "global" | "blend" | undefined;
 }, {
     name: string;
     value: string | null;
-    association?: "layer" | "GlobalParameter" | "LayerParameter" | "BlendParameter" | "global" | "blend" | undefined;
     index?: number | undefined;
+    association?: "layer" | "GlobalParameter" | "LayerParameter" | "BlendParameter" | "global" | "blend" | undefined;
 }>;
 export declare const MaterialFontParameterSchema: z.ZodObject<{
     name: z.ZodString;
@@ -427,14 +427,14 @@ export declare const MaterialFontParameterSchema: z.ZodObject<{
 }, "strip", z.ZodTypeAny, {
     name: string;
     value: string | null;
-    association?: "layer" | "GlobalParameter" | "LayerParameter" | "BlendParameter" | "global" | "blend" | undefined;
     index?: number | undefined;
+    association?: "layer" | "GlobalParameter" | "LayerParameter" | "BlendParameter" | "global" | "blend" | undefined;
     fontPage?: number | undefined;
 }, {
     name: string;
     value: string | null;
-    association?: "layer" | "GlobalParameter" | "LayerParameter" | "BlendParameter" | "global" | "blend" | undefined;
     index?: number | undefined;
+    association?: "layer" | "GlobalParameter" | "LayerParameter" | "BlendParameter" | "global" | "blend" | undefined;
     fontPage?: number | undefined;
 }>;
 export declare const MaterialStaticSwitchParameterSchema: z.ZodObject<{
@@ -446,13 +446,13 @@ export declare const MaterialStaticSwitchParameterSchema: z.ZodObject<{
 }, "strip", z.ZodTypeAny, {
     name: string;
     value: boolean;
-    association?: "layer" | "GlobalParameter" | "LayerParameter" | "BlendParameter" | "global" | "blend" | undefined;
     index?: number | undefined;
+    association?: "layer" | "GlobalParameter" | "LayerParameter" | "BlendParameter" | "global" | "blend" | undefined;
 }, {
     name: string;
     value: boolean;
-    association?: "layer" | "GlobalParameter" | "LayerParameter" | "BlendParameter" | "global" | "blend" | undefined;
     index?: number | undefined;
+    association?: "layer" | "GlobalParameter" | "LayerParameter" | "BlendParameter" | "global" | "blend" | undefined;
 }>;
 export declare const MaterialLayerEntrySchema: z.ZodObject<{
     layerPath: z.ZodOptional<z.ZodNullable<z.ZodString>>;
@@ -1201,8 +1201,8 @@ export declare const ImportJobItemSchema: z.ZodObject<{
         severity: string;
         path?: string | undefined;
     }[];
-    dirtyPackages: string[];
     index: number;
+    dirtyPackages: string[];
     importedObjects: string[];
     url?: string | undefined;
     assetPath?: string | undefined;
@@ -1218,8 +1218,8 @@ export declare const ImportJobItemSchema: z.ZodObject<{
         severity: string;
         path?: string | undefined;
     }[];
-    dirtyPackages: string[];
     index: number;
+    dirtyPackages: string[];
     importedObjects: string[];
     url?: string | undefined;
     assetPath?: string | undefined;
@@ -1298,8 +1298,8 @@ export declare const ImportJobSchema: z.ZodObject<{
             severity: string;
             path?: string | undefined;
         }[];
-        dirtyPackages: string[];
         index: number;
+        dirtyPackages: string[];
         importedObjects: string[];
         url?: string | undefined;
         assetPath?: string | undefined;
@@ -1315,8 +1315,8 @@ export declare const ImportJobSchema: z.ZodObject<{
             severity: string;
             path?: string | undefined;
         }[];
-        dirtyPackages: string[];
         index: number;
+        dirtyPackages: string[];
         importedObjects: string[];
         url?: string | undefined;
         assetPath?: string | undefined;
@@ -1361,8 +1361,8 @@ export declare const ImportJobSchema: z.ZodObject<{
             severity: string;
             path?: string | undefined;
         }[];
-        dirtyPackages: string[];
         index: number;
+        dirtyPackages: string[];
         importedObjects: string[];
         url?: string | undefined;
         assetPath?: string | undefined;
@@ -1411,8 +1411,8 @@ export declare const ImportJobSchema: z.ZodObject<{
             severity: string;
             path?: string | undefined;
         }[];
-        dirtyPackages: string[];
         index: number;
+        dirtyPackages: string[];
         importedObjects: string[];
         url?: string | undefined;
         assetPath?: string | undefined;
@@ -1557,8 +1557,8 @@ export declare const ImportJobListSchema: z.ZodObject<{
                 severity: string;
                 path?: string | undefined;
             }[];
-            dirtyPackages: string[];
             index: number;
+            dirtyPackages: string[];
             importedObjects: string[];
             url?: string | undefined;
             assetPath?: string | undefined;
@@ -1574,8 +1574,8 @@ export declare const ImportJobListSchema: z.ZodObject<{
                 severity: string;
                 path?: string | undefined;
             }[];
-            dirtyPackages: string[];
             index: number;
+            dirtyPackages: string[];
             importedObjects: string[];
             url?: string | undefined;
             assetPath?: string | undefined;
@@ -1620,8 +1620,8 @@ export declare const ImportJobListSchema: z.ZodObject<{
                 severity: string;
                 path?: string | undefined;
             }[];
-            dirtyPackages: string[];
             index: number;
+            dirtyPackages: string[];
             importedObjects: string[];
             url?: string | undefined;
             assetPath?: string | undefined;
@@ -1670,8 +1670,8 @@ export declare const ImportJobListSchema: z.ZodObject<{
                 severity: string;
                 path?: string | undefined;
             }[];
-            dirtyPackages: string[];
             index: number;
+            dirtyPackages: string[];
             importedObjects: string[];
             url?: string | undefined;
             assetPath?: string | undefined;
@@ -1726,8 +1726,8 @@ export declare const ImportJobListSchema: z.ZodObject<{
                 severity: string;
                 path?: string | undefined;
             }[];
-            dirtyPackages: string[];
             index: number;
+            dirtyPackages: string[];
             importedObjects: string[];
             url?: string | undefined;
             assetPath?: string | undefined;
@@ -1799,8 +1799,8 @@ export declare const ImportJobListSchema: z.ZodObject<{
                 severity: string;
                 path?: string | undefined;
             }[];
-            dirtyPackages: string[];
             index: number;
+            dirtyPackages: string[];
             importedObjects: string[];
             url?: string | undefined;
             assetPath?: string | undefined;