blueprint-extractor-mcp 4.2.0 → 6.0.0

package/dist/automation-controller.js

@@ -120,6 +120,10 @@ export class AutomationController {
         if (!request.automationFilter) {
             throw new Error('run_automation_tests requires automation_filter');
         }
+        const safeFilterPattern = /^[A-Za-z0-9_.+* -]+$/u;
+        if (!safeFilterPattern.test(request.automationFilter)) {
+            throw new Error('automationFilter contains invalid characters: only alphanumeric, dots, underscores, plus, asterisk, hyphen, and spaces are allowed');
+        }
         const started = this.now();
         const filterSlug = sanitizeSegment(request.automationFilter);
         const runId = `${filterSlug}_${started.getTime()}_${randomUUID().slice(0, 8)}`;

package/dist/catalogs/example-catalog.js

@@ -560,8 +560,8 @@ export const exampleCatalog = {
                             }],
                         bindings: {
                             propertyBindings: [{
-                                    sourcePath: { segments: [{ name: 'SelectedGestureTag' }] },
-                                    targetPath: { segments: [{ name: 'MontageTag' }] },
+                                    sourcePath: 'SelectedGestureTag',
+                                    targetPath: 'MontageTag',
                                 }],
                         },
                     },

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

@@ -0,0 +1,24 @@
+/**
+ * CommandletAdapter spawns UnrealEditor-Cmd.exe with -run=blueprintextractor
+ * and communicates via stdin/stdout JSON-RPC.
+ */
+import type { ExecutionAdapter, ToolCapability } from '../execution-adapter.js';
+export interface CommandletAdapterOptions {
+    engineRoot: string;
+    projectPath: string;
+}
+export declare class CommandletAdapter implements ExecutionAdapter {
+    private options;
+    private process;
+    private requestId;
+    private pendingRequests;
+    private buffer;
+    constructor(options: CommandletAdapterOptions);
+    initialize(): Promise<void>;
+    execute(_subsystem: string, method: string, params: Record<string, unknown>): Promise<Record<string, unknown>>;
+    isAvailable(): Promise<boolean>;
+    getMode(): 'commandlet';
+    getCapabilities(): ReadonlySet<ToolCapability>;
+    shutdown(): Promise<void>;
+    private processBuffer;
+}

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

@@ -0,0 +1,124 @@
+/**
+ * CommandletAdapter spawns UnrealEditor-Cmd.exe with -run=blueprintextractor
+ * and communicates via stdin/stdout JSON-RPC.
+ */
+import { spawn } from 'child_process';
+import { COMMANDLET_CAPABILITIES } from '../execution-adapter.js';
+const STARTUP_TIMEOUT_MS = 30_000;
+const REQUEST_TIMEOUT_MS = 60_000;
+export class CommandletAdapter {
+    options;
+    process = null;
+    requestId = 0;
+    pendingRequests = new Map();
+    buffer = '';
+    constructor(options) {
+        this.options = options;
+    }
+    async initialize() {
+        if (this.process)
+            return;
+        const editorCmd = `${this.options.engineRoot}/Binaries/Win64/UnrealEditor-Cmd.exe`;
+        this.process = spawn(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'));
+            }
+            this.pendingRequests.clear();
+        });
+        // Wait for startup
+        await new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                reject(new Error(`Commandlet startup timed out after ${STARTUP_TIMEOUT_MS}ms`));
+            }, STARTUP_TIMEOUT_MS);
+            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);
+            });
+        });
+    }
+    async execute(_subsystem, method, params) {
+        if (!this.process?.stdin) {
+            throw new Error('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 ${REQUEST_TIMEOUT_MS}ms`));
+            }, REQUEST_TIMEOUT_MS);
+            this.pendingRequests.set(id, { resolve, reject, timer });
+            this.process.stdin.write(request + '\n');
+        });
+    }
+    async isAvailable() {
+        return this.process !== null && !this.process.killed;
+    }
+    getMode() {
+        return 'commandlet';
+    }
+    getCapabilities() {
+        return COMMANDLET_CAPABILITIES;
+    }
+    async shutdown() {
+        if (this.process) {
+            this.process.stdin?.end();
+            this.process.kill();
+            this.process = null;
+        }
+    }
+    processBuffer() {
+        const lines = this.buffer.split('\n');
+        this.buffer = lines.pop() ?? '';
+        for (const line of lines) {
+            const trimmed = line.trim();
+            if (!trimmed)
+                continue;
+            try {
+                const response = JSON.parse(trimmed);
+                if (response.id != null && this.pendingRequests.has(response.id)) {
+                    const pending = this.pendingRequests.get(response.id);
+                    this.pendingRequests.delete(response.id);
+                    clearTimeout(pending.timer);
+                    if (response.error) {
+                        pending.reject(new Error(typeof response.error === 'string'
+                            ? response.error
+                            : JSON.stringify(response.error)));
+                    }
+                    else {
+                        pending.resolve((typeof response.result === 'object' && response.result !== null)
+                            ? response.result
+                            : { result: response.result });
+                    }
+                }
+            }
+            catch {
+                // Non-JSON output — skip (may be engine log lines)
+            }
+        }
+    }
+}

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

@@ -0,0 +1,14 @@
+/**
+ * EditorAdapter wraps the existing UEClient with the ExecutionAdapter interface.
+ * This is a thin wrapper — all existing behavior is preserved.
+ */
+import type { UEClient } from '../../ue-client.js';
+import type { ExecutionAdapter, ToolCapability } from '../execution-adapter.js';
+export declare class EditorAdapter implements ExecutionAdapter {
+    private client;
+    constructor(client: UEClient);
+    execute(_subsystem: string, method: string, params: Record<string, unknown>): Promise<Record<string, unknown>>;
+    isAvailable(): Promise<boolean>;
+    getMode(): 'editor';
+    getCapabilities(): ReadonlySet<ToolCapability>;
+}

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

@@ -0,0 +1,24 @@
+/**
+ * EditorAdapter wraps the existing UEClient with the ExecutionAdapter interface.
+ * This is a thin wrapper — all existing behavior is preserved.
+ */
+import { ALL_CAPABILITIES } from '../execution-adapter.js';
+export class EditorAdapter {
+    client;
+    constructor(client) {
+        this.client = client;
+    }
+    async execute(_subsystem, method, params) {
+        const rawResult = await this.client.callSubsystem(method, params);
+        return JSON.parse(rawResult);
+    }
+    async isAvailable() {
+        return this.client.checkConnection();
+    }
+    getMode() {
+        return 'editor';
+    }
+    getCapabilities() {
+        return ALL_CAPABILITIES;
+    }
+}

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

@@ -0,0 +1,50 @@
+/**
+ * AdaptiveExecutor routes tool calls to the best available adapter.
+ * Falls back from editor to commandlet for compatible operations.
+ */
+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 EditorFallbackCaller = (method: string, params: Record<string, unknown>, options?: {
+    timeoutMs?: number;
+}) => Promise<Record<string, unknown>>;
+export declare class AdaptiveExecutor {
+    private editorAdapter;
+    private commandletAdapter;
+    private detector;
+    private toolModes;
+    /**
+     * Active tool name set by the tool registration wrapper before a handler runs.
+     * ASSUMPTION: The MCP SDK processes tool calls sequentially per transport
+     * connection (single Node.js event loop, SDK awaits each handler). If the SDK
+     * ever supports concurrent tool execution, this shared state must be replaced
+     * with per-request context (e.g., AsyncLocalStorage or passing toolName as a
+     * parameter to executeRouted).
+     */
+    private _activeToolName;
+    constructor(editorAdapter: ExecutionAdapter, commandletAdapter: ExecutionAdapter | null, detector: ExecutionModeDetector);
+    setToolMode(toolName: string, mode: ToolModeAnnotation): void;
+    getToolMode(toolName: string): ToolModeAnnotation;
+    getCurrentMode(): Promise<ExecutionMode>;
+    /** Set the active tool name before a handler runs. Cleared after handler completes. */
+    setActiveToolName(name: string | null): void;
+    getActiveToolName(): string | null;
+    /**
+     * Route a callSubsystemJson-shaped call through the executor.
+     * For editor mode, delegates to the provided editorFallback (the original
+     * callSubsystemJson with its error-checking layer intact).
+     * For commandlet mode, routes through the commandlet adapter.
+     * This allows transparent interception without changing tool call sites.
+     */
+    executeRouted(editorFallback: EditorFallbackCaller, method: string, params: Record<string, unknown>, options?: {
+        timeoutMs?: number;
+    }): Promise<Record<string, unknown>>;
+    execute(toolName: string, subsystem: string, method: string, params: Record<string, unknown>): Promise<Record<string, unknown>>;
+}
+export declare class ExecutorError extends Error {
+    code: string;
+    toolName: string;
+    currentMode: ExecutionMode;
+    requiredCapability: ToolCapability;
+    constructor(code: string, message: string, toolName: string, currentMode: ExecutionMode, requiredCapability: ToolCapability);
+}

package/dist/execution/adaptive-executor.js

@@ -0,0 +1,116 @@
+/**
+ * AdaptiveExecutor routes tool calls to the best available adapter.
+ * Falls back from editor to commandlet for compatible operations.
+ */
+export class AdaptiveExecutor {
+    editorAdapter;
+    commandletAdapter;
+    detector;
+    toolModes = new Map();
+    /**
+     * Active tool name set by the tool registration wrapper before a handler runs.
+     * ASSUMPTION: The MCP SDK processes tool calls sequentially per transport
+     * connection (single Node.js event loop, SDK awaits each handler). If the SDK
+     * ever supports concurrent tool execution, this shared state must be replaced
+     * with per-request context (e.g., AsyncLocalStorage or passing toolName as a
+     * parameter to executeRouted).
+     */
+    _activeToolName = null;
+    constructor(editorAdapter, commandletAdapter, detector) {
+        this.editorAdapter = editorAdapter;
+        this.commandletAdapter = commandletAdapter;
+        this.detector = detector;
+    }
+    setToolMode(toolName, mode) {
+        this.toolModes.set(toolName, mode);
+    }
+    getToolMode(toolName) {
+        return this.toolModes.get(toolName) ?? 'editor_only';
+    }
+    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;
+    }
+    getActiveToolName() {
+        return this._activeToolName;
+    }
+    /**
+     * Route a callSubsystemJson-shaped call through the executor.
+     * For editor mode, delegates to the provided editorFallback (the original
+     * callSubsystemJson with its error-checking layer intact).
+     * For commandlet mode, routes through the commandlet adapter.
+     * This allows transparent interception without changing tool call sites.
+     */
+    async executeRouted(editorFallback, method, params, options) {
+        const toolName = this._activeToolName;
+        const detection = await this.detector.detect();
+        // 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);
+        }
+        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') {
+                throw new ExecutorError('CAPABILITY_MISMATCH', `Tool '${toolName}' requires the Unreal Editor but only commandlet mode is available. ${detection.reason}`, toolName, detection.mode, requiredCapability);
+            }
+            const capabilities = this.commandletAdapter.getCapabilities();
+            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);
+        }
+        // No adapter available
+        throw new ExecutorError('MODE_UNAVAILABLE', `No execution mode available for tool '${toolName}'. ${detection.reason}`, toolName, detection.mode, requiredCapability);
+    }
+    async execute(toolName, subsystem, method, params) {
+        const detection = await this.detector.detect();
+        const toolMode = this.getToolMode(toolName);
+        // Determine required capability from tool mode
+        const requiredCapability = toolMode === 'read_only'
+            ? 'read'
+            : toolMode === 'both'
+                ? 'write_simple'
+                : 'write_complex';
+        // Try editor first
+        if (detection.mode === 'editor') {
+            return this.editorAdapter.execute(subsystem, method, params);
+        }
+        // Try commandlet for compatible tools
+        if (detection.mode === 'commandlet' && this.commandletAdapter) {
+            if (toolMode === 'editor_only') {
+                throw new ExecutorError('CAPABILITY_MISMATCH', `Tool '${toolName}' requires the Unreal Editor but only commandlet mode is available. ${detection.reason}`, toolName, detection.mode, requiredCapability);
+            }
+            const capabilities = this.commandletAdapter.getCapabilities();
+            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);
+        }
+        // No adapter available
+        throw new ExecutorError('MODE_UNAVAILABLE', `No execution mode available for tool '${toolName}'. ${detection.reason}`, toolName, detection.mode, requiredCapability);
+    }
+}
+export class ExecutorError extends Error {
+    code;
+    toolName;
+    currentMode;
+    requiredCapability;
+    constructor(code, message, toolName, currentMode, requiredCapability) {
+        super(message);
+        this.name = 'ExecutorError';
+        this.code = code;
+        this.toolName = toolName;
+        this.currentMode = currentMode;
+        this.requiredCapability = requiredCapability;
+    }
+}

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

@@ -0,0 +1,26 @@
+/**
+ * Core execution adapter interface for dual-mode architecture.
+ * Adapters abstract the underlying execution mechanism (editor or commandlet).
+ */
+export type ExecutionMode = 'editor' | 'commandlet' | 'unavailable';
+export type ToolCapability = 'read' | 'write_simple' | 'write_complex' | 'interactive';
+export interface ExecutionAdapter {
+    /** Execute a subsystem method with parameters */
+    execute(subsystem: string, method: string, params: Record<string, unknown>): Promise<Record<string, unknown>>;
+    /** Check if this adapter is currently available */
+    isAvailable(): Promise<boolean>;
+    /** Get the execution mode this adapter provides */
+    getMode(): ExecutionMode;
+    /** Get the capabilities this adapter supports */
+    getCapabilities(): ReadonlySet<ToolCapability>;
+    /** Optional initialization */
+    initialize?(): Promise<void>;
+    /** Optional shutdown */
+    shutdown?(): Promise<void>;
+}
+export interface ModeDetectionResult {
+    mode: ExecutionMode;
+    reason: string;
+}
+export declare const ALL_CAPABILITIES: ReadonlySet<ToolCapability>;
+export declare const COMMANDLET_CAPABILITIES: ReadonlySet<ToolCapability>;

package/dist/execution/execution-adapter.js

@@ -0,0 +1,10 @@
+/**
+ * Core execution adapter interface for dual-mode architecture.
+ * Adapters abstract the underlying execution mechanism (editor or commandlet).
+ */
+export const ALL_CAPABILITIES = new Set([
+    'read', 'write_simple', 'write_complex', 'interactive',
+]);
+export const COMMANDLET_CAPABILITIES = new Set([
+    'read', 'write_simple',
+]);

package/dist/execution/execution-mode-detector.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Detects the available execution mode by checking editor and commandlet availability.
+ * Caches the result for 5 seconds to avoid repeated probes.
+ */
+import type { ExecutionAdapter, ModeDetectionResult } from './execution-adapter.js';
+export declare class ExecutionModeDetector {
+    private editorAdapter;
+    private commandletAdapter;
+    private cachedResult;
+    private cachedAt;
+    private now;
+    constructor(editorAdapter: ExecutionAdapter, commandletAdapter?: ExecutionAdapter | null, now?: () => number);
+    detect(): Promise<ModeDetectionResult>;
+    invalidateCache(): void;
+    private cache;
+}

package/dist/execution/execution-mode-detector.js

@@ -0,0 +1,55 @@
+/**
+ * Detects the available execution mode by checking editor and commandlet availability.
+ * Caches the result for 5 seconds to avoid repeated probes.
+ */
+const CACHE_TTL_MS = 5_000;
+export class ExecutionModeDetector {
+    editorAdapter;
+    commandletAdapter;
+    cachedResult = null;
+    cachedAt = 0;
+    now;
+    constructor(editorAdapter, commandletAdapter = null, now = Date.now) {
+        this.editorAdapter = editorAdapter;
+        this.commandletAdapter = commandletAdapter;
+        this.now = now;
+    }
+    async detect() {
+        const currentTime = this.now();
+        if (this.cachedResult && (currentTime - this.cachedAt) < CACHE_TTL_MS) {
+            return this.cachedResult;
+        }
+        // Check editor first (preferred)
+        try {
+            const editorAvailable = await this.editorAdapter.isAvailable();
+            if (editorAvailable) {
+                return this.cache({ mode: 'editor', reason: 'Editor Remote Control API is available' });
+            }
+        }
+        catch {
+            // Editor not available
+        }
+        // Check commandlet fallback
+        if (this.commandletAdapter) {
+            try {
+                const cmdAvailable = await this.commandletAdapter.isAvailable();
+                if (cmdAvailable) {
+                    return this.cache({ mode: 'commandlet', reason: 'Commandlet process is running (editor unavailable)' });
+                }
+            }
+            catch {
+                // Commandlet not available
+            }
+        }
+        return this.cache({ mode: 'unavailable', reason: 'Neither editor nor commandlet is available' });
+    }
+    invalidateCache() {
+        this.cachedResult = null;
+        this.cachedAt = 0;
+    }
+    cache(result) {
+        this.cachedResult = result;
+        this.cachedAt = this.now();
+        return result;
+    }
+}

package/dist/execution/index.d.ts

@@ -0,0 +1,5 @@
+export { type ExecutionAdapter, type ExecutionMode, type ToolCapability, type ModeDetectionResult, ALL_CAPABILITIES, COMMANDLET_CAPABILITIES, } from './execution-adapter.js';
+export { EditorAdapter } from './adapters/editor-adapter.js';
+export { CommandletAdapter } from './adapters/commandlet-adapter.js';
+export { ExecutionModeDetector } from './execution-mode-detector.js';
+export { AdaptiveExecutor, ExecutorError } from './adaptive-executor.js';

package/dist/execution/index.js

@@ -0,0 +1,5 @@
+export { ALL_CAPABILITIES, COMMANDLET_CAPABILITIES, } from './execution-adapter.js';
+export { EditorAdapter } from './adapters/editor-adapter.js';
+export { CommandletAdapter } from './adapters/commandlet-adapter.js';
+export { ExecutionModeDetector } from './execution-mode-detector.js';
+export { AdaptiveExecutor, ExecutorError } from './adaptive-executor.js';

package/dist/helpers/blueprint-validation.d.ts

@@ -0,0 +1,17 @@
+type JsonSubsystemCaller = (method: string, params: Record<string, unknown>) => Promise<Record<string, unknown>>;
+export interface StructuredValidationError {
+    [key: string]: unknown;
+    code: string;
+    message: string;
+    recoverable: boolean;
+    next_steps: string[];
+}
+export type ValidationResult = {
+    valid: true;
+} | {
+    valid: false;
+    error: StructuredValidationError;
+};
+export declare function isInheritedComponent(componentName: string, blueprintData: Record<string, unknown>): boolean;
+export declare function validateInheritedComponents(assetPath: string, componentNames: string[], callSubsystemJson: JsonSubsystemCaller): Promise<ValidationResult>;
+export {};

package/dist/helpers/blueprint-validation.js

@@ -0,0 +1,54 @@
+export function isInheritedComponent(componentName, blueprintData) {
+    const components = Array.isArray(blueprintData.components)
+        ? blueprintData.components
+        : Array.isArray(blueprintData.Components)
+            ? blueprintData.Components
+            : [];
+    for (const comp of components) {
+        if (typeof comp !== 'object' || comp === null)
+            continue;
+        const c = comp;
+        const name = c.name ?? c.Name ?? c.component_name ?? c.ComponentName;
+        const inherited = c.inherited ?? c.bInherited ?? c.is_inherited;
+        if (name === componentName && inherited === true) {
+            return true;
+        }
+    }
+    return false;
+}
+export async function validateInheritedComponents(assetPath, componentNames, callSubsystemJson) {
+    if (componentNames.length === 0) {
+        return { valid: true };
+    }
+    let blueprintData;
+    try {
+        blueprintData = await callSubsystemJson('ExtractBlueprint', {
+            AssetPath: assetPath,
+            Scope: 'Components',
+            bIncludeClassDefaults: false,
+        });
+    }
+    catch {
+        // If extraction fails, allow the operation to proceed — the C++ side
+        // will provide its own error. Don't block on a pre-validation failure.
+        return { valid: true };
+    }
+    for (const componentName of componentNames) {
+        if (isInheritedComponent(componentName, blueprintData)) {
+            return {
+                valid: false,
+                error: {
+                    code: 'INHERITED_COMPONENT',
+                    message: `Component '${componentName}' in '${assetPath}' is inherited from a parent class and cannot be directly modified. Use the parent blueprint or UInheritableComponentHandler-compatible operations.`,
+                    recoverable: true,
+                    next_steps: [
+                        `Modify the component in the parent blueprint that owns '${componentName}'.`,
+                        'Use patch_component with override-aware parameters if the engine supports it.',
+                        'Extract the parent blueprint to identify the owning class.',
+                    ],
+                },
+            };
+        }
+    }
+    return { valid: true };
+}

package/dist/helpers/formatting.d.ts

@@ -1,6 +1,5 @@
 import type { ContentBlock } from '@modelcontextprotocol/sdk/types.js';
 export declare function isPlainObject(value: unknown): value is Record<string, unknown>;
-export declare function isRecord(value: unknown): value is Record<string, unknown>;
 export declare function coerceStringArray(value: unknown): string[];
 export declare function formatPromptValue(value: unknown): string | null;
 export declare function formatPromptList(label: string, value: unknown, fallback: string): string;

package/dist/helpers/formatting.js

@@ -1,9 +1,6 @@
 export function isPlainObject(value) {
     return typeof value === 'object' && value !== null && !Array.isArray(value);
 }
-export function isRecord(value) {
-    return typeof value === 'object' && value !== null && !Array.isArray(value);
-}
 export function coerceStringArray(value) {
     if (Array.isArray(value)) {
         return value.filter((entry) => typeof entry === 'string' && entry.trim().length > 0);
@@ -59,17 +56,17 @@ export function tryParseJsonText(text) {
     }
 }
 export function extractTextContent(result) {
-    if (!isRecord(result) || !Array.isArray(result.content)) {
+    if (!isPlainObject(result) || !Array.isArray(result.content)) {
         return undefined;
     }
-    const entry = result.content.find((candidate) => isRecord(candidate) && candidate.type === 'text');
-    return isRecord(entry) && typeof entry.text === 'string' ? entry.text : undefined;
+    const entry = result.content.find((candidate) => isPlainObject(candidate) && candidate.type === 'text');
+    return isPlainObject(entry) && typeof entry.text === 'string' ? entry.text : undefined;
 }
 export function extractToolPayload(result) {
-    if (isRecord(result) && 'structuredContent' in result) {
+    if (isPlainObject(result) && 'structuredContent' in result) {
         return result.structuredContent;
     }
-    if (isRecord(result) && Array.isArray(result.content)) {
+    if (isPlainObject(result) && Array.isArray(result.content)) {
         const text = extractTextContent(result);
         const parsed = tryParseJsonText(text);
         if (parsed !== undefined) {
@@ -82,7 +79,7 @@ export function extractToolPayload(result) {
     return result;
 }
 function isContentBlock(value) {
-    if (!isRecord(value) || typeof value.type !== 'string') {
+    if (!isPlainObject(value) || typeof value.type !== 'string') {
         return false;
     }
     switch (value.type) {
@@ -94,7 +91,7 @@ function isContentBlock(value) {
         case 'resource_link':
             return typeof value.uri === 'string' && typeof value.name === 'string';
         case 'resource':
-            return isRecord(value.resource)
+            return isPlainObject(value.resource)
                 && typeof value.resource.uri === 'string'
                 && typeof value.resource.mimeType === 'string'
                 && (typeof value.resource.text === 'string'
@@ -104,7 +101,7 @@ function isContentBlock(value) {
     }
 }
 export function extractExtraContent(result) {
-    if (!isRecord(result) || !Array.isArray(result.content)) {
+    if (!isPlainObject(result) || !Array.isArray(result.content)) {
         return [];
     }
     return result.content.filter((candidate) => (isContentBlock(candidate) && candidate.type !== 'text'));

package/dist/helpers/mutation-filter.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Filters internal fields from mutation results.
+ * Strips implementation details that waste context tokens.
+ */
+export declare function filterMutationResult(result: Record<string, unknown>): Record<string, unknown>;