blueprint-extractor-mcp 8.2.6 → 8.2.7

package/README.md

@@ -2,7 +2,7 @@
   <h1 align="center">Blueprint Extractor MCP</h1>
   <p align="center">
     Give AI assistants full read/write access to Unreal Engine projects<br>
-    through a live editor connection.
+    through a live editor or headless commandlet lane.
   </p>
 </p>
 
@@ -17,7 +17,10 @@
 
 ## Overview
 
-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.
+Blueprint Extractor MCP is a [Model Context Protocol](https://modelcontextprotocol.io) server that bridges AI coding assistants (Claude Code, Codex, OpenCode, etc.) to Unreal Engine through two execution lanes:
+
+- **Editor lane** via the Remote Control HTTP API for editor-bound and interactive workflows
+- **Commandlet lane** for headless-safe extraction and authoring when no reachable editor session is available
 
 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.
 
@@ -49,11 +52,13 @@ For compatible tools, the server can also execute through a commandlet lane when
 
 ### Prerequisites
 
-You need three things running:
+You need these prerequisites:
 
 1. **Node.js 18+**
-2. **Unreal Editor** with the **Remote Control API** plugin enabled
-3. **[BlueprintExtractor](https://github.com/SunGrow/ue-blueprint-extractor)** plugin installed in your project
+2. **[BlueprintExtractor](https://github.com/SunGrow/ue-blueprint-extractor)** plugin installed in your project
+3. One execution lane configured:
+   - **Editor lane**: Unreal Editor running with the **Remote Control API** plugin enabled
+   - **Commandlet lane**: resolvable `UE_ENGINE_ROOT` and `UE_PROJECT_PATH` so headless-safe tools can launch `UnrealEditor-Cmd`
 
 ### Run
 
@@ -63,6 +68,8 @@ npx blueprint-extractor-mcp
 
 Connects to the editor at `127.0.0.1:30010` by default.
 
+For headless-safe tools, also set `UE_ENGINE_ROOT` and `UE_PROJECT_PATH` so the MCP server can resolve the commandlet lane when no editor is reachable.
+
 ### Add to Your AI Client
 
 <table>
@@ -84,6 +91,15 @@ codex mcp add --env UE_REMOTE_CONTROL_PORT=30010 \
   blueprint-extractor -- npx -y blueprint-extractor-mcp@latest
 ```
 
+```bash
+# Optional for headless-safe tools when no editor is running
+codex mcp add \
+  --env UE_REMOTE_CONTROL_PORT=30010 \
+  --env UE_ENGINE_ROOT="C:\\Program Files\\Epic Games\\UE_5.7" \
+  --env UE_PROJECT_PATH="D:\\Development\\V2\\CyberVolleyball6vs6.uproject" \
+  blueprint-extractor -- npx -y blueprint-extractor-mcp@latest
+```
+
 </td></tr>
 <tr><td><b>OpenCode</b></td></tr>
 <tr><td>
@@ -168,6 +184,8 @@ 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_tool_help` now reports execution compatibility per tool, including whether the tool is editor-only or headless-safe.
+
 `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.

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

@@ -13,11 +13,16 @@ export interface CommandletAdapterOptions {
     requestTimeoutMs?: number;
 }
 export declare class CommandletAdapter implements ExecutionAdapter {
+    private static readonly MAX_LOG_TAIL_LINES;
     private options;
     private process;
     private requestId;
     private pendingRequests;
-    private buffer;
+    private stdoutBuffer;
+    private stderrBuffer;
+    private recentLogs;
+    private startupPromise;
+    private startupState;
     private readonly spawnProcess;
     private readonly platform;
     private readonly startupTimeoutMs;
@@ -29,5 +34,12 @@ export declare class CommandletAdapter implements ExecutionAdapter {
     getMode(): 'commandlet';
     getCapabilities(): ReadonlySet<ToolCapability>;
     shutdown(): Promise<void>;
-    private processBuffer;
+    private spawnAndWaitForReady;
+    private processStdoutBuffer;
+    private processStderrBuffer;
+    private appendLogLine;
+    private withRecentLogs;
+    private resolveStartup;
+    private rejectStartup;
+    private handleProcessTermination;
 }

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

@@ -8,11 +8,16 @@ import { resolveEditorExecutable } from '../../project-controller.js';
 const STARTUP_TIMEOUT_MS = 30_000;
 const REQUEST_TIMEOUT_MS = 60_000;
 export class CommandletAdapter {
+    static MAX_LOG_TAIL_LINES = 100;
     options;
     process = null;
     requestId = 0;
     pendingRequests = new Map();
-    buffer = '';
+    stdoutBuffer = '';
+    stderrBuffer = '';
+    recentLogs = [];
+    startupPromise = null;
+    startupState = null;
     spawnProcess;
     platform;
     startupTimeoutMs;
@@ -25,60 +30,37 @@ export class CommandletAdapter {
         this.requestTimeoutMs = options.requestTimeoutMs ?? REQUEST_TIMEOUT_MS;
     }
     async initialize() {
-        if (this.process)
-            return;
-        const editorCmd = await resolveEditorExecutable(this.options.engineRoot, this.platform, 'commandlet');
-        this.process = this.spawnProcess(editorCmd, [
-            this.options.projectPath,
-            '-run=blueprintextractor',
-            '-stdin',
-            '-unattended',
-            '-nosplash',
-            '-nullrhi',
-        ], {
-            stdio: ['pipe', 'pipe', 'pipe'],
-        });
-        this.process.stdout?.on('data', (data) => {
-            this.buffer += data.toString();
-            this.processBuffer();
-        });
-        this.process.on('exit', () => {
-            this.process = null;
-            // Reject all pending requests
-            for (const [, pending] of this.pendingRequests) {
-                clearTimeout(pending.timer);
-                pending.reject(new Error('Commandlet process exited'));
+        if (this.process && !this.process.killed) {
+            if (this.startupPromise) {
+                await this.startupPromise;
             }
-            this.pendingRequests.clear();
-        });
-        // Wait for startup
-        await new Promise((resolve, reject) => {
-            const timer = setTimeout(() => {
-                reject(new Error(`Commandlet startup timed out after ${this.startupTimeoutMs}ms`));
-            }, this.startupTimeoutMs);
-            const onData = () => {
-                clearTimeout(timer);
-                this.process?.stdout?.off('data', onData);
-                resolve();
-            };
-            // Resolve on first stdout output (indicating process is ready)
-            this.process?.stdout?.on('data', onData);
-            this.process?.on('error', (err) => {
-                clearTimeout(timer);
-                reject(err);
-            });
-        });
+            return;
+        }
+        if (this.startupPromise) {
+            await this.startupPromise;
+            return;
+        }
+        this.startupPromise = this.spawnAndWaitForReady();
+        try {
+            await this.startupPromise;
+        }
+        finally {
+            this.startupPromise = null;
+        }
     }
     async execute(_subsystem, method, params) {
-        if (!this.process?.stdin) {
-            throw new Error('Commandlet process not running. Call initialize() first.');
+        if (!this.process?.stdin || this.process.killed) {
+            await this.initialize();
+        }
+        if (!this.process?.stdin || this.process.killed) {
+            throw new Error(this.withRecentLogs('Commandlet process not running. Call initialize() first.'));
         }
         const id = ++this.requestId;
         const request = JSON.stringify({ jsonrpc: '2.0', id, method, params });
         return new Promise((resolve, reject) => {
             const timer = setTimeout(() => {
                 this.pendingRequests.delete(id);
-                reject(new Error(`Commandlet request timed out after ${this.requestTimeoutMs}ms`));
+                reject(new Error(this.withRecentLogs(`Commandlet request timed out after ${this.requestTimeoutMs}ms`)));
             }, this.requestTimeoutMs);
             this.pendingRequests.set(id, { resolve, reject, timer });
             this.process.stdin.write(request + '\n');
@@ -94,21 +76,80 @@ export class CommandletAdapter {
         return COMMANDLET_CAPABILITIES;
     }
     async shutdown() {
-        if (this.process) {
-            this.process.stdin?.end();
-            this.process.kill();
-            this.process = null;
+        if (!this.process) {
+            return;
+        }
+        this.process.stdin?.end();
+        this.process.kill();
+        this.process = null;
+    }
+    async spawnAndWaitForReady() {
+        this.stdoutBuffer = '';
+        this.stderrBuffer = '';
+        this.recentLogs = [];
+        const editorCmd = await resolveEditorExecutable(this.options.engineRoot, this.platform, 'commandlet');
+        const startupWaiter = new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                reject(new Error(this.withRecentLogs(`Commandlet startup timed out after ${this.startupTimeoutMs}ms`)));
+            }, this.startupTimeoutMs);
+            this.startupState = { resolve, reject, timer };
+        });
+        try {
+            this.process = this.spawnProcess(editorCmd, [
+                this.options.projectPath,
+                '-run=blueprintextractor',
+                '-stdin',
+                '-unattended',
+                '-nosplash',
+                '-nullrhi',
+            ], {
+                stdio: ['pipe', 'pipe', 'pipe'],
+            });
+            this.process.stdout?.on('data', (data) => {
+                this.stdoutBuffer += data.toString();
+                this.processStdoutBuffer();
+            });
+            this.process.stderr?.on('data', (data) => {
+                this.stderrBuffer += data.toString();
+                this.processStderrBuffer();
+            });
+            this.process.on('exit', (code, signal) => {
+                const suffix = code != null
+                    ? ` with code ${code}`
+                    : signal
+                        ? ` with signal ${signal}`
+                        : '';
+                this.handleProcessTermination(`Commandlet process exited${suffix}`);
+            });
+            this.process.on('error', (error) => {
+                const message = error instanceof Error ? error.message : String(error);
+                this.handleProcessTermination(`Commandlet process error: ${message}`);
+            });
+        }
+        catch (error) {
+            const startupError = error instanceof Error ? error : new Error(String(error));
+            this.rejectStartup(startupError);
+            throw startupError;
         }
+        await startupWaiter;
     }
-    processBuffer() {
-        const lines = this.buffer.split('\n');
-        this.buffer = lines.pop() ?? '';
+    processStdoutBuffer() {
+        const lines = this.stdoutBuffer.split('\n');
+        this.stdoutBuffer = lines.pop() ?? '';
         for (const line of lines) {
             const trimmed = line.trim();
             if (!trimmed)
                 continue;
             try {
                 const response = JSON.parse(trimmed);
+                if (response.jsonrpc === '2.0'
+                    && response.id === 0
+                    && typeof response.result === 'object'
+                    && response.result !== null
+                    && response.result.ready === true) {
+                    this.resolveStartup();
+                    continue;
+                }
                 if (response.id != null && this.pendingRequests.has(response.id)) {
                     const pending = this.pendingRequests.get(response.id);
                     this.pendingRequests.delete(response.id);
@@ -123,11 +164,61 @@ export class CommandletAdapter {
                             ? response.result
                             : { result: response.result });
                     }
+                    continue;
                 }
             }
             catch {
-                // Non-JSON output — skip (may be engine log lines)
+                this.appendLogLine(trimmed);
+            }
+        }
+    }
+    processStderrBuffer() {
+        const lines = this.stderrBuffer.split('\n');
+        this.stderrBuffer = lines.pop() ?? '';
+        for (const line of lines) {
+            const trimmed = line.trim();
+            if (!trimmed) {
+                continue;
             }
+            this.appendLogLine(trimmed);
+        }
+    }
+    appendLogLine(line) {
+        this.recentLogs.push(line);
+        if (this.recentLogs.length > CommandletAdapter.MAX_LOG_TAIL_LINES) {
+            this.recentLogs.splice(0, this.recentLogs.length - CommandletAdapter.MAX_LOG_TAIL_LINES);
+        }
+    }
+    withRecentLogs(message) {
+        if (this.recentLogs.length === 0) {
+            return message;
+        }
+        return `${message}\nRecent commandlet logs:\n${this.recentLogs.join('\n')}`;
+    }
+    resolveStartup() {
+        if (!this.startupState) {
+            return;
+        }
+        clearTimeout(this.startupState.timer);
+        this.startupState.resolve();
+        this.startupState = null;
+    }
+    rejectStartup(error) {
+        if (!this.startupState) {
+            return;
+        }
+        clearTimeout(this.startupState.timer);
+        this.startupState.reject(error);
+        this.startupState = null;
+    }
+    handleProcessTermination(baseMessage) {
+        const error = new Error(this.withRecentLogs(baseMessage));
+        this.rejectStartup(error);
+        this.process = null;
+        for (const [, pending] of this.pendingRequests) {
+            clearTimeout(pending.timer);
+            pending.reject(error);
         }
+        this.pendingRequests.clear();
     }
 }

package/dist/execution/adaptive-executor.d.ts

@@ -5,6 +5,7 @@
 import type { ExecutionAdapter, ToolCapability, ExecutionMode } from './execution-adapter.js';
 import { ExecutionModeDetector } from './execution-mode-detector.js';
 export type ToolModeAnnotation = 'both' | 'editor_only' | 'read_only';
+export type ExecutionLane = 'editor' | 'commandlet';
 export type EditorFallbackCaller = (method: string, params: Record<string, unknown>, options?: {
     timeoutMs?: number;
 }) => Promise<Record<string, unknown>>;
@@ -22,13 +23,21 @@ export declare class AdaptiveExecutor {
      * parameter to executeRouted).
      */
     private _activeToolName;
+    private _activeToolExecutionMetadata;
     constructor(editorAdapter: ExecutionAdapter, commandletAdapter: ExecutionAdapter | null, detector: ExecutionModeDetector);
     setToolMode(toolName: string, mode: ToolModeAnnotation): void;
     getToolMode(toolName: string): ToolModeAnnotation;
+    getSupportedExecutionModes(toolName: string): ExecutionLane[];
     getCurrentMode(): Promise<ExecutionMode>;
     /** Set the active tool name before a handler runs. Cleared after handler completes. */
     setActiveToolName(name: string | null): void;
     getActiveToolName(): string | null;
+    getActiveToolExecutionMetadata(): {
+        runtime_mode?: ExecutionLane;
+        supported_modes: ExecutionLane[];
+        fallback_used?: boolean;
+    } | null;
+    private recordToolExecution;
     /**
      * Route a callSubsystemJson-shaped call through the executor.
      * For editor mode, delegates to the provided editorFallback (the original

package/dist/execution/adaptive-executor.js

@@ -36,6 +36,7 @@ export class AdaptiveExecutor {
      * parameter to executeRouted).
      */
     _activeToolName = null;
+    _activeToolExecutionMetadata = null;
     constructor(editorAdapter, commandletAdapter, detector) {
         this.editorAdapter = editorAdapter;
         this.commandletAdapter = commandletAdapter;
@@ -47,16 +48,47 @@ export class AdaptiveExecutor {
     getToolMode(toolName) {
         return this.toolModes.get(toolName) ?? 'editor_only';
     }
+    getSupportedExecutionModes(toolName) {
+        return this.getToolMode(toolName) === 'editor_only'
+            ? ['editor']
+            : ['editor', 'commandlet'];
+    }
     getCurrentMode() {
         return this.detector.detect().then((r) => r.mode);
     }
     /** Set the active tool name before a handler runs. Cleared after handler completes. */
     setActiveToolName(name) {
         this._activeToolName = name;
+        this._activeToolExecutionMetadata = name
+            ? { supportedModes: this.getSupportedExecutionModes(name) }
+            : null;
     }
     getActiveToolName() {
         return this._activeToolName;
     }
+    getActiveToolExecutionMetadata() {
+        if (!this._activeToolExecutionMetadata) {
+            return null;
+        }
+        return {
+            runtime_mode: this._activeToolExecutionMetadata.mode,
+            supported_modes: [...this._activeToolExecutionMetadata.supportedModes],
+            ...(typeof this._activeToolExecutionMetadata.fallbackUsed === 'boolean'
+                ? { fallback_used: this._activeToolExecutionMetadata.fallbackUsed }
+                : {}),
+        };
+    }
+    recordToolExecution(toolName, mode, fallbackUsed) {
+        if (this._activeToolName !== toolName) {
+            return;
+        }
+        const current = this._activeToolExecutionMetadata ?? {
+            supportedModes: this.getSupportedExecutionModes(toolName),
+        };
+        current.mode = mode;
+        current.fallbackUsed = current.fallbackUsed === true ? true : fallbackUsed;
+        this._activeToolExecutionMetadata = current;
+    }
     /**
      * Route a callSubsystemJson-shaped call through the executor.
      * For editor mode, delegates to the provided editorFallback (the original
@@ -89,15 +121,26 @@ export class AdaptiveExecutor {
                 throw error;
             }
             this.detector.invalidateCache();
-            return this.commandletAdapter.execute('BlueprintExtractor', method, params);
+            try {
+                const result = await this.commandletAdapter.execute('BlueprintExtractor', method, params);
+                this.recordToolExecution(toolName, 'commandlet', true);
+                return result;
+            }
+            catch (fallbackError) {
+                this.recordToolExecution(toolName, 'commandlet', true);
+                throw fallbackError;
+            }
         };
         // 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);
+                const result = await editorFallback(method, params, options);
+                this.recordToolExecution(toolName, 'editor', false);
+                return result;
             }
             catch (error) {
+                this.recordToolExecution(toolName, 'editor', false);
                 if (toolMode === 'editor_only') {
                     throw error;
                 }
@@ -118,7 +161,9 @@ export class AdaptiveExecutor {
                     const editorAvailable = await this.editorAdapter.isAvailable();
                     if (editorAvailable) {
                         this.detector.invalidateCache();
-                        return await editorFallback(method, params, options);
+                        const result = await editorFallback(method, params, options);
+                        this.recordToolExecution(toolName, 'editor', true);
+                        return result;
                     }
                 }
                 catch {
@@ -126,15 +171,20 @@ export class AdaptiveExecutor {
                 }
             }
             try {
-                return await this.commandletAdapter.execute('BlueprintExtractor', method, params);
+                const result = await this.commandletAdapter.execute('BlueprintExtractor', method, params);
+                this.recordToolExecution(toolName, 'commandlet', false);
+                return result;
             }
             catch (error) {
+                this.recordToolExecution(toolName, 'commandlet', false);
                 if (toolMode !== 'read_only' && shouldFallbackToEditorOnLock(error)) {
                     try {
                         const editorAvailable = await this.editorAdapter.isAvailable();
                         if (editorAvailable) {
                             this.detector.invalidateCache();
-                            return await editorFallback(method, params, options);
+                            const result = await editorFallback(method, params, options);
+                            this.recordToolExecution(toolName, 'editor', true);
+                            return result;
                         }
                     }
                     catch {
@@ -157,7 +207,15 @@ export class AdaptiveExecutor {
                 ? 'write_simple'
                 : 'write_complex';
         if (detection.mode === 'editor') {
-            return this.editorAdapter.execute(subsystem, method, params);
+            try {
+                const result = await this.editorAdapter.execute(subsystem, method, params);
+                this.recordToolExecution(toolName, 'editor', false);
+                return result;
+            }
+            catch (error) {
+                this.recordToolExecution(toolName, 'editor', false);
+                throw error;
+            }
         }
         // Try commandlet for compatible tools
         if (detection.mode === 'commandlet' && this.commandletAdapter) {
@@ -173,7 +231,9 @@ export class AdaptiveExecutor {
                     const editorAvailable = await this.editorAdapter.isAvailable();
                     if (editorAvailable) {
                         this.detector.invalidateCache();
-                        return await this.editorAdapter.execute(subsystem, method, params);
+                        const result = await this.editorAdapter.execute(subsystem, method, params);
+                        this.recordToolExecution(toolName, 'editor', true);
+                        return result;
                     }
                 }
                 catch {
@@ -181,15 +241,20 @@ export class AdaptiveExecutor {
                 }
             }
             try {
-                return await this.commandletAdapter.execute(subsystem, method, params);
+                const result = await this.commandletAdapter.execute(subsystem, method, params);
+                this.recordToolExecution(toolName, 'commandlet', false);
+                return result;
             }
             catch (error) {
+                this.recordToolExecution(toolName, 'commandlet', false);
                 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);
+                            const result = await this.editorAdapter.execute(subsystem, method, params);
+                            this.recordToolExecution(toolName, 'editor', true);
+                            return result;
                         }
                     }
                     catch {

package/dist/helpers/composite-patterns.d.ts

@@ -24,6 +24,9 @@ export interface CompositeToolResult {
         task_support: 'optional' | 'required' | 'forbidden';
         status?: string;
         progress_message?: string;
+        runtime_mode?: 'editor' | 'commandlet';
+        supported_modes?: Array<'editor' | 'commandlet'>;
+        fallback_used?: boolean;
     };
 }
 type Result<T, E> = {