unreal-engine-mcp-server 0.4.7 → 0.5.0

package/dist/utils/response-validator.js

@@ -1,6 +1,7 @@
 import Ajv from 'ajv';
 import { Logger } from './logger.js';
 import { cleanObject } from './safe-json.js';
+import { wasmIntegration } from '../wasm/index.js';
 const log = new Logger('ResponseValidator');
 function isRecord(value) {
     return !!value && typeof value === 'object' && !Array.isArray(value);
@@ -19,71 +20,106 @@ function buildSummaryText(toolName, payload) {
     if (!isRecord(payload)) {
         return `${toolName} responded`;
     }
+    const effectivePayload = { ...payload };
+    if (isRecord(effectivePayload.data)) {
+        Object.assign(effectivePayload, effectivePayload.data);
+    }
+    if (isRecord(effectivePayload.result)) {
+        Object.assign(effectivePayload, effectivePayload.result);
+    }
     const parts = [];
-    const message = typeof payload.message === 'string' ? normalizeText(payload.message) : '';
-    const error = typeof payload.error === 'string' ? normalizeText(payload.error) : '';
-    const success = typeof payload.success === 'boolean' ? (payload.success ? 'success' : 'failed') : '';
-    const path = typeof payload.path === 'string' ? payload.path : '';
-    const name = typeof payload.name === 'string' ? payload.name : '';
-    const warningCount = Array.isArray(payload.warnings) ? payload.warnings.length : 0;
-    if (message)
-        parts.push(message);
-    if (error && (!message || !message.includes(error)))
-        parts.push(`error: ${error}`);
-    if (success)
-        parts.push(success);
-    if (path)
-        parts.push(`path: ${path}`);
-    if (name)
-        parts.push(`name: ${name}`);
-    if (warningCount > 0)
-        parts.push(`warnings: ${warningCount}`);
-    const summary = isRecord(payload.summary) ? payload.summary : undefined;
-    if (summary) {
-        const summaryParts = [];
-        for (const [key, value] of Object.entries(summary)) {
-            if (typeof value === 'number' || typeof value === 'string') {
-                summaryParts.push(`${key}: ${value}`);
+    const listKeys = ['actors', 'levels', 'assets', 'folders', 'blueprints', 'components', 'pawnClasses', 'foliageTypes', 'nodes', 'tracks', 'bindings', 'keys'];
+    for (const key of listKeys) {
+        if (Array.isArray(effectivePayload[key])) {
+            const arr = effectivePayload[key];
+            const names = arr.map(i => isRecord(i) ? (i.name || i.path || i.id || i.assetName || i.objectPath || i.packageName || i.nodeName || '<?>') : String(i));
+            const count = arr.length;
+            const preview = names.slice(0, 100).join(', ');
+            const suffix = count > 100 ? `, ... (+${count - 100} more)` : '';
+            parts.push(`${key}: ${preview}${suffix} (Total: ${count})`);
+        }
+    }
+    if (typeof effectivePayload.actor === 'string' || isRecord(effectivePayload.actor)) {
+        const a = effectivePayload.actor;
+        const name = isRecord(a) ? (a.name || a.path) : a;
+        const loc = isRecord(effectivePayload.location) ? ` at [${effectivePayload.location.x},${effectivePayload.location.y},${effectivePayload.location.z}]` : '';
+        parts.push(`Actor: ${name}${loc}`);
+    }
+    if (typeof effectivePayload.asset === 'string' || isRecord(effectivePayload.asset)) {
+        const a = effectivePayload.asset;
+        const path = isRecord(a) ? (a.path || a.name) : a;
+        parts.push(`Asset: ${path}`);
+    }
+    if (typeof effectivePayload.blueprint === 'string' || isRecord(effectivePayload.blueprint)) {
+        const bp = effectivePayload.blueprint;
+        const name = isRecord(bp) ? (bp.name || bp.path || effectivePayload.blueprintPath) : bp;
+        parts.push(`Blueprint: ${name}`);
+    }
+    if (typeof effectivePayload.sequence === 'string' || isRecord(effectivePayload.sequence)) {
+        const seq = effectivePayload.sequence;
+        const name = isRecord(seq) ? (seq.name || seq.path) : seq;
+        parts.push(`Sequence: ${name}`);
+    }
+    const usefulKeys = [
+        'success', 'error', 'message', 'assets', 'folders', 'count', 'totalCount',
+        'saved', 'valid', 'issues', 'class', 'skeleton', 'parent',
+        'package', 'dependencies', 'graph', 'tags', 'metadata', 'properties'
+    ];
+    for (const key of usefulKeys) {
+        if (effectivePayload[key] !== undefined && effectivePayload[key] !== null) {
+            const val = effectivePayload[key];
+            if (typeof val === 'object') {
+                if (key === 'metadata' || key === 'properties' || key === 'tags') {
+                    const entries = Object.entries(val);
+                    const formatted = entries.map(([k, v]) => `${k}=${v}`);
+                    const limit = 50;
+                    parts.push(`${key}: { ${formatted.slice(0, limit).join(', ')}${formatted.length > limit ? '...' : ''} }`);
+                    continue;
+                }
+                continue;
+            }
+            const strVal = String(val);
+            if (strVal.length > 100)
+                continue;
+            if (!parts.some(p => p.includes(strVal))) {
+                parts.push(`${key}: ${strVal}`);
             }
-            if (summaryParts.length >= 3)
-                break;
         }
-        if (summaryParts.length) {
-            parts.push(`summary(${summaryParts.join(', ')})`);
+    }
+    const success = typeof payload.success === 'boolean' ? payload.success : undefined;
+    const message = typeof payload.message === 'string' ? normalizeText(payload.message) : '';
+    const error = typeof payload.error === 'string' ? normalizeText(payload.error) : '';
+    if (parts.length > 0) {
+        if (message && message.toLowerCase() !== 'success') {
+            parts.push(message);
         }
     }
-    if (parts.length === 0) {
-        const keys = Object.keys(payload).slice(0, 3);
-        if (keys.length) {
-            return `${toolName} responded (${keys.join(', ')})`;
+    else {
+        if (message)
+            parts.push(message);
+        if (error)
+            parts.push(`Error: ${error}`);
+        if (parts.length === 0 && success !== undefined) {
+            parts.push(success ? 'Success' : 'Failed');
         }
     }
-    return parts.length > 0
-        ? parts.join(' | ')
-        : `${toolName} responded`;
+    const warnings = Array.isArray(payload.warnings) ? payload.warnings : [];
+    if (warnings.length > 0) {
+        parts.push(`Warnings: ${warnings.length}`);
+    }
+    return parts.length > 0 ? parts.join(' | ') : `${toolName} responded`;
 }
-/**
- * Response Validator for MCP Tool Outputs
- * Validates tool responses against their defined output schemas
- */
 export class ResponseValidator {
-    // Keep ajv as any to avoid complex interop typing issues with Ajv's ESM/CJS dual export
-    // shape when using NodeNext module resolution.
     ajv;
     validators = new Map();
     constructor() {
-        // Cast Ajv to any for construction to avoid errors when TypeScript's NodeNext
-        // module resolution represents the import as a namespace object.
         const AjvCtor = Ajv?.default ?? Ajv;
         this.ajv = new AjvCtor({
             allErrors: true,
             verbose: true,
-            strict: false // Allow additional properties for flexibility
+            strict: true
         });
     }
-    /**
-     * Register a tool's output schema for validation
-     */
     registerSchema(toolName, outputSchema) {
         if (!outputSchema) {
             log.warn(`No output schema defined for tool: ${toolName}`);
@@ -92,35 +128,34 @@ export class ResponseValidator {
         try {
             const validator = this.ajv.compile(outputSchema);
             this.validators.set(toolName, validator);
-            // Demote per-tool schema registration to debug to reduce log noise
             log.debug(`Registered output schema for tool: ${toolName}`);
         }
         catch (_error) {
             log.error(`Failed to compile output schema for ${toolName}:`, _error);
         }
     }
-    /**
-     * Validate a tool's response against its schema
-     */
-    validateResponse(toolName, response) {
+    async validateResponse(toolName, response) {
         const validator = this.validators.get(toolName);
         if (!validator) {
             log.debug(`No validator found for tool: ${toolName}`);
-            return { valid: true }; // Pass through if no schema defined
+            return { valid: true };
         }
-        // Extract structured content from response
         let structuredContent = response;
-        // If response has MCP format with content array
         if (response.content && Array.isArray(response.content)) {
-            // Try to extract structured data from text content
             const textContent = response.content.find((c) => c.type === 'text');
             if (textContent?.text) {
-                try {
-                    // Check if text is JSON
-                    structuredContent = JSON.parse(textContent.text);
+                const rawText = String(textContent.text);
+                const trimmed = rawText.trim();
+                const looksLikeJson = trimmed.startsWith('{') || trimmed.startsWith('[');
+                if (looksLikeJson) {
+                    try {
+                        structuredContent = await wasmIntegration.parseProperties(rawText);
+                    }
+                    catch {
+                        structuredContent = response;
+                    }
                 }
-                catch {
-                    // Not JSON, use the full response
+                else {
                     structuredContent = response;
                 }
             }
@@ -140,16 +175,7 @@ export class ResponseValidator {
             structuredContent
         };
     }
-    /**
-     * Wrap a tool response with validation and MCP-compliant content shape.
-     *
-     * MCP tools/call responses must contain a `content` array. Many internal
-     * handlers return structured JSON objects (e.g., { success, message, ... }).
-     * This wrapper serializes such objects into a single text block while keeping
-     * existing `content` responses intact.
-     */
-    wrapResponse(toolName, response) {
-        // Ensure response is safe to serialize first
+    async wrapResponse(toolName, response) {
         try {
             if (response && typeof response === 'object') {
                 JSON.stringify(response);
@@ -159,16 +185,12 @@ export class ResponseValidator {
             log.error(`Response for ${toolName} contains circular references, cleaning...`);
             response = cleanObject(response);
         }
-        // If handler already returned MCP content, keep it as-is (still validate)
         const alreadyMcpShaped = response && typeof response === 'object' && Array.isArray(response.content);
-        // Choose the payload to validate: if already MCP-shaped, validate the
-        // structured content extracted from text; otherwise validate the object directly.
-        const validation = this.validateResponse(toolName, response);
+        const validation = await this.validateResponse(toolName, response);
         const structuredPayload = validation.structuredContent;
         if (!validation.valid) {
             log.warn(`Tool ${toolName} response validation failed:`, validation.errors);
         }
-        // If it's already MCP-shaped, return as-is (optionally append validation meta)
         if (alreadyMcpShaped) {
             if (structuredPayload !== undefined && response && typeof response === 'object' && response.structuredContent === undefined) {
                 try {
@@ -178,6 +200,14 @@ export class ResponseValidator {
                 }
                 catch { }
             }
+            try {
+                const sc = response.structuredContent || structuredPayload || {};
+                const hasExplicitFailure = (typeof sc.success === 'boolean' && sc.success === false) || (typeof sc.error === 'string' && sc.error.length > 0);
+                if (hasExplicitFailure && response.isError !== true) {
+                    response.isError = true;
+                }
+            }
+            catch { }
             if (!validation.valid) {
                 try {
                     response._validation = { valid: false, errors: validation.errors };
@@ -186,7 +216,6 @@ export class ResponseValidator {
             }
             return response;
         }
-        // Otherwise, wrap structured result into MCP content
         const summarySource = structuredPayload !== undefined ? structuredPayload : response;
         let text = buildSummaryText(toolName, summarySource);
         if (!text || !text.trim()) {
@@ -197,6 +226,15 @@ export class ResponseValidator {
                 { type: 'text', text }
             ]
         };
+        try {
+            if (structuredPayload && typeof structuredPayload.success === 'boolean') {
+                wrapped.success = Boolean(structuredPayload.success);
+            }
+            else if (response && typeof response.success === 'boolean') {
+                wrapped.success = Boolean(response.success);
+            }
+        }
+        catch { }
         if (structuredPayload !== undefined) {
             try {
                 wrapped.structuredContent = structuredPayload && typeof structuredPayload === 'object'
@@ -215,14 +253,26 @@ export class ResponseValidator {
                 wrapped.structuredContent = response;
             }
         }
+        try {
+            const sc = wrapped.structuredContent || {};
+            const hasExplicitFailure = (typeof sc.success === 'boolean' && sc.success === false) || (typeof sc.error === 'string' && sc.error.length > 0);
+            if (hasExplicitFailure) {
+                wrapped.isError = true;
+            }
+        }
+        catch { }
         if (!validation.valid) {
             wrapped._validation = { valid: false, errors: validation.errors };
         }
+        try {
+            const s = wrapped.success;
+            if (typeof s === 'boolean' && s === false) {
+                wrapped.isError = true;
+            }
+        }
+        catch { }
         return wrapped;
     }
-    /**
-     * Get validation statistics
-     */
     getStats() {
         return {
             totalSchemas: this.validators.size,
@@ -230,6 +280,5 @@ export class ResponseValidator {
         };
     }
 }
-// Singleton instance
 export const responseValidator = new ResponseValidator();
 //# sourceMappingURL=response-validator.js.map

package/dist/utils/result-helpers.d.ts

@@ -1,11 +1,10 @@
-import { StandardResultPayload } from './python-output.js';
 export interface InterpretedStandardResult {
     success: boolean;
     message: string;
     error?: string;
     warnings?: string[];
     details?: string[];
-    payload: StandardResultPayload & Record<string, unknown>;
+    payload: Record<string, unknown>;
     cleanText?: string;
     rawText: string;
     raw: unknown;
@@ -16,12 +15,12 @@ export declare function interpretStandardResult(response: unknown, defaults: {
 }): InterpretedStandardResult;
 export declare function cleanResultText(text: string | undefined, options?: {
     tag?: string;
-    fallback?: string;
+    defaultValue?: string;
 }): string | undefined;
-export declare function bestEffortInterpretedText(interpreted: Pick<InterpretedStandardResult, 'cleanText' | 'rawText'>, fallback?: string): string | undefined;
+export declare function bestEffortInterpretedText(interpreted: Pick<InterpretedStandardResult, 'cleanText' | 'rawText'>, defaultValue?: string): string | undefined;
 export declare function coerceString(value: unknown): string | undefined;
 export declare function coerceStringArray(value: unknown): string[] | undefined;
-export declare function coerceBoolean(value: unknown, fallback?: boolean): boolean | undefined;
+export declare function coerceBoolean(value: unknown, defaultValue?: boolean): boolean | undefined;
 export declare function coerceNumber(value: unknown): number | undefined;
 export declare function coerceVector3(value: unknown): [number, number, number] | undefined;
 //# sourceMappingURL=result-helpers.d.ts.map

package/dist/utils/result-helpers.js

@@ -1,10 +1,9 @@
-import { parseStandardResult, stripTaggedResultLines } from './python-output.js';
 export function interpretStandardResult(response, defaults) {
-    const parsed = parseStandardResult(response);
-    const payload = (parsed.data ?? {});
+    const payload = (response && typeof response === 'object' ? response : {});
     const success = payload.success === true;
-    const rawText = typeof parsed.text === 'string' ? parsed.text : String(parsed.text ?? '');
-    const cleanedText = cleanResultText(rawText, { fallback: undefined });
+    const rawText = typeof payload.message === 'string' ? payload.message :
+        typeof payload.output === 'string' ? payload.output :
+            String(payload.result ?? '');
     const messageFromPayload = typeof payload.message === 'string' ? payload.message.trim() : '';
     const errorFromPayload = typeof payload.error === 'string' ? payload.error.trim() : '';
     const message = messageFromPayload || (success ? defaults.successMessage : defaults.failureMessage);
@@ -16,32 +15,32 @@ export function interpretStandardResult(response, defaults) {
         warnings: coerceStringArray(payload.warnings),
         details: coerceStringArray(payload.details),
         payload,
-        cleanText: cleanedText,
+        cleanText: rawText || undefined,
         rawText,
-        raw: parsed.raw
+        raw: response
     };
 }
 export function cleanResultText(text, options = {}) {
-    const { tag = 'RESULT:', fallback } = options;
+    const { defaultValue } = options;
     if (!text) {
-        return fallback;
+        return defaultValue;
     }
-    const cleaned = stripTaggedResultLines(text, tag).trim();
+    const cleaned = text.trim();
     if (cleaned.length > 0) {
         return cleaned;
     }
-    return fallback;
+    return defaultValue;
 }
-export function bestEffortInterpretedText(interpreted, fallback) {
+export function bestEffortInterpretedText(interpreted, defaultValue) {
     const cleaned = interpreted.cleanText?.trim();
     if (cleaned) {
         return cleaned;
     }
     const raw = interpreted.rawText?.trim?.();
-    if (raw && !raw.startsWith('RESULT:')) {
+    if (raw) {
         return raw;
     }
-    return fallback;
+    return defaultValue;
 }
 export function coerceString(value) {
     if (typeof value === 'string') {
@@ -67,7 +66,7 @@ export function coerceStringArray(value) {
     }
     return items.length > 0 ? items : undefined;
 }
-export function coerceBoolean(value, fallback) {
+export function coerceBoolean(value, defaultValue) {
     if (typeof value === 'boolean') {
         return value;
     }
@@ -88,7 +87,7 @@ export function coerceBoolean(value, fallback) {
             return false;
         }
     }
-    return fallback;
+    return defaultValue;
 }
 export function coerceNumber(value) {
     if (typeof value === 'number' && Number.isFinite(value)) {

package/dist/utils/safe-json.js

@@ -1,12 +1,11 @@
-// Remove circular references and non-serializable properties from an object
+import { Logger } from './logger.js';
 export function cleanObject(obj, maxDepth = 10) {
     const seen = new WeakSet();
+    const logger = new Logger('safe-json');
     function clean(value, depth, path = 'root') {
-        // Prevent infinite recursion
         if (depth > maxDepth) {
             return '[Max depth reached]';
         }
-        // Handle primitives
         if (value === null || value === undefined) {
             return value;
         }
@@ -19,20 +18,16 @@ export function cleanObject(obj, maxDepth = 10) {
             }
             return value;
         }
-        // Check for circular reference
         if (seen.has(value)) {
             return '[Circular Reference]';
         }
         seen.add(value);
-        // Handle arrays
         if (Array.isArray(value)) {
             const result = value.map((item, index) => clean(item, depth + 1, `${path}[${index}]`));
-            seen.delete(value); // Remove from seen after processing
+            seen.delete(value);
             return result;
         }
-        // Handle objects
         const cleaned = {};
-        // Use Object.keys to avoid prototype properties
         const keys = Object.keys(value);
         for (const key of keys) {
             try {
@@ -42,11 +37,10 @@ export function cleanObject(obj, maxDepth = 10) {
                 }
             }
             catch (e) {
-                // Skip properties that throw errors when accessed
-                console.error(`Error cleaning property ${path}.${key}:`, e);
+                logger.error(`Error cleaning property ${path}.${key}`, e);
             }
         }
-        seen.delete(value); // Remove from seen after processing
+        seen.delete(value);
         return cleaned;
     }
     return clean(obj, 0);

package/dist/utils/unreal-command-queue.d.ts

@@ -0,0 +1,24 @@
+export interface CommandQueueItem<T = any> {
+    command: () => Promise<T>;
+    resolve: (value: T) => void;
+    reject: (reason?: any) => void;
+    priority: number;
+    retryCount?: number;
+}
+export declare class UnrealCommandQueue {
+    private log;
+    private queue;
+    private isProcessing;
+    private lastCommandTime;
+    private lastStatCommandTime;
+    private readonly MIN_COMMAND_DELAY;
+    private readonly MAX_COMMAND_DELAY;
+    private readonly STAT_COMMAND_DELAY;
+    constructor();
+    execute<T>(command: () => Promise<T>, priority?: number): Promise<T>;
+    private processQueue;
+    private calculateDelay;
+    private startProcessor;
+    private delay;
+}
+//# sourceMappingURL=unreal-command-queue.d.ts.map

package/dist/utils/unreal-command-queue.js

@@ -0,0 +1,120 @@
+import { Logger } from './logger.js';
+export class UnrealCommandQueue {
+    log = new Logger('UnrealCommandQueue');
+    queue = [];
+    isProcessing = false;
+    lastCommandTime = 0;
+    lastStatCommandTime = 0;
+    MIN_COMMAND_DELAY = 100;
+    MAX_COMMAND_DELAY = 500;
+    STAT_COMMAND_DELAY = 300;
+    constructor() {
+        this.startProcessor();
+    }
+    async execute(command, priority = 5) {
+        return new Promise((resolve, reject) => {
+            this.queue.push({
+                command,
+                resolve,
+                reject,
+                priority
+            });
+            this.queue.sort((a, b) => a.priority - b.priority);
+            if (!this.isProcessing) {
+                this.processQueue();
+            }
+        });
+    }
+    async processQueue() {
+        if (this.isProcessing || this.queue.length === 0) {
+            return;
+        }
+        this.isProcessing = true;
+        while (this.queue.length > 0) {
+            const item = this.queue.shift();
+            if (!item)
+                continue;
+            const timeSinceLastCommand = Date.now() - this.lastCommandTime;
+            const requiredDelay = this.calculateDelay(item.priority);
+            if (timeSinceLastCommand < requiredDelay) {
+                await this.delay(requiredDelay - timeSinceLastCommand);
+            }
+            try {
+                const result = await item.command();
+                item.resolve(result);
+            }
+            catch (error) {
+                const msgRaw = error?.message ?? String(error);
+                const msg = String(msgRaw).toLowerCase();
+                if (item.retryCount === undefined)
+                    item.retryCount = 0;
+                const isTransient = (msg.includes('timeout') ||
+                    msg.includes('timed out') ||
+                    msg.includes('connect') ||
+                    msg.includes('econnrefused') ||
+                    msg.includes('econnreset') ||
+                    msg.includes('broken pipe') ||
+                    msg.includes('automation bridge') ||
+                    msg.includes('not connected'));
+                const isDeterministicFailure = (msg.includes('command not executed') ||
+                    msg.includes('exec_failed') ||
+                    msg.includes('invalid command') ||
+                    msg.includes('invalid argument') ||
+                    msg.includes('unknown_plugin_action') ||
+                    msg.includes('unknown action'));
+                if (isTransient && item.retryCount < 3) {
+                    item.retryCount++;
+                    this.log.warn(`Command failed (transient), retrying (${item.retryCount}/3)`);
+                    this.queue.unshift({
+                        command: item.command,
+                        resolve: item.resolve,
+                        reject: item.reject,
+                        priority: Math.max(1, item.priority - 1),
+                        retryCount: item.retryCount
+                    });
+                    await this.delay(500);
+                }
+                else {
+                    if (isDeterministicFailure) {
+                        this.log.warn(`Command failed (non-retryable): ${msgRaw}`);
+                    }
+                    item.reject(error);
+                }
+            }
+            this.lastCommandTime = Date.now();
+        }
+        this.isProcessing = false;
+    }
+    calculateDelay(priority) {
+        if (priority <= 3) {
+            return this.MAX_COMMAND_DELAY;
+        }
+        else if (priority <= 6) {
+            return 200;
+        }
+        else if (priority === 8) {
+            const timeSinceLastStat = Date.now() - this.lastStatCommandTime;
+            if (timeSinceLastStat < this.STAT_COMMAND_DELAY) {
+                return this.STAT_COMMAND_DELAY;
+            }
+            this.lastStatCommandTime = Date.now();
+            return 150;
+        }
+        else {
+            const baseDelay = this.MIN_COMMAND_DELAY;
+            const jitter = Math.random() * 50;
+            return baseDelay + jitter;
+        }
+    }
+    startProcessor() {
+        setInterval(() => {
+            if (!this.isProcessing && this.queue.length > 0) {
+                this.processQueue();
+            }
+        }, 1000);
+    }
+    delay(ms) {
+        return new Promise(resolve => setTimeout(resolve, ms));
+    }
+}
+//# sourceMappingURL=unreal-command-queue.js.map