unreal-engine-mcp-server 0.4.6 → 0.5.0

package/src/utils/response-validator.ts

@@ -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');
 
@@ -26,45 +27,117 @@ function buildSummaryText(toolName: string, payload: unknown): string {
     return `${toolName} responded`;
   }
 
+  // 1. Check for specific "data" or "result" wrapper
+  const effectivePayload: Record<string, any> = { ...(payload as object) };
+  if (isRecord(effectivePayload.data)) {
+    Object.assign(effectivePayload, effectivePayload.data);
+  }
+  if (isRecord(effectivePayload.result)) {
+    Object.assign(effectivePayload, effectivePayload.result);
+  }
+
   const parts: string[] = [];
+
+  // 2. Identify "List" responses (Arrays) - Prioritize showing content
+  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] as any[];
+      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(', '); // Show up to 100
+      const suffix = count > 100 ? `, ... (+${count - 100} more)` : '';
+      parts.push(`${key}: ${preview}${suffix} (Total: ${count})`);
+    }
+  }
+
+  // 3. Identify "Entity" operations (Single significant object)
+  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}`);
+  }
+
+  // 4. Generic Key-Value Summary (Contextual)
+  // Added: sequencePath, graphName, nodeName, variableName, memberName, scriptName, etc.
+  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];
+      // Special handling for objects like metadata
+      if (typeof val === 'object') {
+        if (key === 'metadata' || key === 'properties' || key === 'tags') {
+          const entries = Object.entries(val as object);
+          // Format as "Key=Value", skip generic types if possible, or just show raw
+          const formatted = entries.map(([k, v]) => `${k}=${v}`);
+          const limit = 50; // Show more items as requested
+          parts.push(`${key}: { ${formatted.slice(0, limit).join(', ')}${formatted.length > limit ? '...' : ''} }`);
+          continue;
+        }
+        // Try to find a name if it's an object
+        // Skip complex objects unless handled above
+        continue;
+      }
+
+      const strVal = String(val);
+      // Avoid traversing huge strings
+      if (strVal.length > 100) continue;
+
+      if (!parts.some(p => p.includes(strVal))) {
+        parts.push(`${key}: ${strVal}`);
+      }
+    }
+  }
+
+  // 5. Add standard status messages LAST
+  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) : '';
-  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: string[] = [];
-    for (const [key, value] of Object.entries(summary)) {
-      if (typeof value === 'number' || typeof value === 'string') {
-        summaryParts.push(`${key}: ${value}`);
-      }
-      if (summaryParts.length >= 3) break;
+
+  if (parts.length > 0) {
+    if (message && message.toLowerCase() !== 'success') {
+      parts.push(message);
     }
-    if (summaryParts.length) {
-      parts.push(`summary(${summaryParts.join(', ')})`);
+  } else {
+    // No data parts, rely on message/error
+    if (message) parts.push(message);
+    if (error) parts.push(`Error: ${error}`);
+    if (parts.length === 0 && success !== undefined) {
+      parts.push(success ? 'Success' : 'Failed');
     }
   }
 
-  if (parts.length === 0) {
-    const keys = Object.keys(payload).slice(0, 3);
-    if (keys.length) {
-      return `${toolName} responded (${keys.join(', ')})`;
-    }
+  // 6. Warnings
+  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`;
+  return parts.length > 0 ? parts.join(' | ') : `${toolName} responded`;
 }
 
 /**
@@ -84,7 +157,7 @@ export class ResponseValidator {
     this.ajv = new AjvCtor({
       allErrors: true,
       verbose: true,
-      strict: false // Allow additional properties for flexibility
+      strict: true // Enforce strict schema validation
     });
   }
 
@@ -110,13 +183,13 @@ export class ResponseValidator {
   /**
    * Validate a tool's response against its schema
    */
-  validateResponse(toolName: string, response: any): { 
-    valid: boolean; 
+  async validateResponse(toolName: string, response: any): Promise<{
+    valid: boolean;
     errors?: string[];
     structuredContent?: any;
-  } {
+  }> {
     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
@@ -124,41 +197,52 @@ export class ResponseValidator {
 
     // 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: any) => c.type === 'text');
       if (textContent?.text) {
-        try {
-          // Check if text is JSON
-          structuredContent = JSON.parse(textContent.text);
-        } catch {
-          // Not JSON, use the full response
+        const rawText = String(textContent.text);
+        const trimmed = rawText.trim();
+        const looksLikeJson = trimmed.startsWith('{') || trimmed.startsWith('[');
+
+        if (looksLikeJson) {
+          try {
+            // Check if text is JSON - use WASM for high-performance parsing (5-8x faster)
+            structuredContent = await wasmIntegration.parseProperties(rawText);
+          } catch {
+            // If JSON parsing fails, fall back to using the full response without
+            // emitting noisy parse errors for plain-text messages.
+            structuredContent = response;
+          }
+        } else {
+          // Plain-text summary or error message; keep the original structured
+          // response object instead of attempting JSON parsing.
           structuredContent = response;
         }
       }
     }
 
     const valid = validator(structuredContent);
-    
+
     if (!valid) {
-      const errors = validator.errors?.map((err: any) => 
+      const errors = validator.errors?.map((err: any) =>
         `${err.instancePath || 'root'}: ${err.message}`
       );
-      
+
       log.warn(`Response validation failed for ${toolName}:`, errors);
-      
-      return { 
-        valid: false, 
+
+      return {
+        valid: false,
         errors,
-        structuredContent 
+        structuredContent
       };
     }
 
-    return { 
+    return {
       valid: true,
-      structuredContent 
+      structuredContent
     };
   }
 
@@ -170,7 +254,7 @@ export class ResponseValidator {
    * This wrapper serializes such objects into a single text block while keeping
    * existing `content` responses intact.
    */
-  wrapResponse(toolName: string, response: any): any {
+  async wrapResponse(toolName: string, response: any): Promise<any> {
     // Ensure response is safe to serialize first
     try {
       if (response && typeof response === 'object') {
@@ -186,7 +270,7 @@ export class ResponseValidator {
 
     // 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) {
@@ -195,17 +279,25 @@ export class ResponseValidator {
 
     // 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) {
+      if (structuredPayload !== undefined && response && typeof response === 'object' && (response as any).structuredContent === undefined) {
         try {
           (response as any).structuredContent = structuredPayload && typeof structuredPayload === 'object'
             ? cleanObject(structuredPayload)
             : structuredPayload;
-        } catch {}
+        } catch { }
       }
+      // Promote failure semantics to top-level isError when obvious
+      try {
+        const sc: any = (response as any).structuredContent || structuredPayload || {};
+        const hasExplicitFailure = (typeof sc.success === 'boolean' && sc.success === false) || (typeof sc.error === 'string' && sc.error.length > 0);
+        if (hasExplicitFailure && (response as any).isError !== true) {
+          (response as any).isError = true;
+        }
+      } catch { }
       if (!validation.valid) {
         try {
           (response as any)._validation = { valid: false, errors: validation.errors };
-        } catch {}
+        } catch { }
       }
       return response;
     }
@@ -223,6 +315,16 @@ export class ResponseValidator {
       ]
     } as any;
 
+    // Surface a top-level success flag when available so clients and test
+    // harnesses do not have to infer success from the absence of isError.
+    try {
+      if (structuredPayload && typeof (structuredPayload as any).success === 'boolean') {
+        (wrapped as any).success = Boolean((structuredPayload as any).success);
+      } else if (response && typeof (response as any).success === 'boolean') {
+        (wrapped as any).success = Boolean((response as any).success);
+      }
+    } catch { }
+
     if (structuredPayload !== undefined) {
       try {
         wrapped.structuredContent = structuredPayload && typeof structuredPayload === 'object'
@@ -239,10 +341,28 @@ export class ResponseValidator {
       }
     }
 
+    // Promote failure semantics to top-level isError when obvious
+    try {
+      const sc: any = 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 };
     }
 
+    // Mark explicit error when success is false to avoid false positives in
+    // clients that check only for the absence of isError.
+    try {
+      const s = (wrapped as any).success;
+      if (typeof s === 'boolean' && s === false) {
+        (wrapped as any).isError = true;
+      }
+    } catch { }
+
     return wrapped;
   }
 
@@ -258,4 +378,4 @@ export class ResponseValidator {
 }
 
 // Singleton instance
-export const responseValidator = new ResponseValidator();
+export const responseValidator = new ResponseValidator();

package/src/utils/result-helpers.ts

@@ -1,26 +1,27 @@
-import { parseStandardResult, StandardResultPayload, stripTaggedResultLines } from './python-output.js';
-
+// Generic result interpretation for automation bridge responses
 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;
 }
 
+/** Interprets automation bridge responses into a standard format */
 export function interpretStandardResult(
   response: unknown,
   defaults: { successMessage: string; failureMessage: string }
 ): InterpretedStandardResult {
-  const parsed = parseStandardResult(response);
-  const payload = (parsed.data ?? {}) as StandardResultPayload & Record<string, unknown>;
+  // Handle automation bridge response format
+  const payload = (response && typeof response === 'object' ? response : {}) as Record<string, unknown>;
   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() : '';
@@ -35,32 +36,33 @@ export function interpretStandardResult(
     warnings: coerceStringArray(payload.warnings),
     details: coerceStringArray(payload.details),
     payload,
-    cleanText: cleanedText,
+    cleanText: rawText || undefined,
     rawText,
-    raw: parsed.raw
+    raw: response
   };
 }
 
+/** Cleans result text by removing tags */
 export function cleanResultText(
   text: string | undefined,
-  options: { tag?: string; fallback?: string } = {}
+  options: { tag?: string; defaultValue?: string } = {}
 ): string | undefined {
-  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: Pick<InterpretedStandardResult, 'cleanText' | 'rawText'>,
-  fallback?: string
+  defaultValue?: string
 ): string | undefined {
   const cleaned = interpreted.cleanText?.trim();
   if (cleaned) {
@@ -68,11 +70,11 @@ export function bestEffortInterpretedText(
   }
 
   const raw = interpreted.rawText?.trim?.();
-  if (raw && !raw.startsWith('RESULT:')) {
+  if (raw) {
     return raw;
   }
 
-  return fallback;
+  return defaultValue;
 }
 
 export function coerceString(value: unknown): string | undefined {
@@ -103,7 +105,7 @@ export function coerceStringArray(value: unknown): string[] | undefined {
   return items.length > 0 ? items : undefined;
 }
 
-export function coerceBoolean(value: unknown, fallback?: boolean): boolean | undefined {
+export function coerceBoolean(value: unknown, defaultValue?: boolean): boolean | undefined {
   if (typeof value === 'boolean') {
     return value;
   }
@@ -127,7 +129,7 @@ export function coerceBoolean(value: unknown, fallback?: boolean): boolean | und
     }
   }
 
-  return fallback;
+  return defaultValue;
 }
 
 export function coerceNumber(value: unknown): number | undefined {

package/src/utils/safe-json.ts

@@ -1,18 +1,21 @@
+import { Logger } from './logger.js';
+
 // Remove circular references and non-serializable properties from an object
 export function cleanObject(obj: any, maxDepth: number = 10): any {
   const seen = new WeakSet();
-  
+  const logger = new Logger('safe-json');
+
   function clean(value: any, depth: number, path: string = 'root'): any {
     // Prevent infinite recursion
     if (depth > maxDepth) {
       return '[Max depth reached]';
     }
-    
+
     // Handle primitives
     if (value === null || value === undefined) {
       return value;
     }
-    
+
     if (typeof value !== 'object') {
       if (typeof value === 'function' || typeof value === 'symbol') {
         return undefined;
@@ -22,24 +25,24 @@ export function cleanObject(obj: any, maxDepth: number = 10): any {
       }
       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
       return result;
     }
-    
+
     // Handle objects
     const cleaned: any = {};
-    
+
     // Use Object.keys to avoid prototype properties
     const keys = Object.keys(value);
     for (const key of keys) {
@@ -50,13 +53,13 @@ export function cleanObject(obj: any, maxDepth: number = 10): any {
         }
       } 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
     return cleaned;
   }
-  
+
   return clean(obj, 0);
 }

package/src/utils/unreal-command-queue.ts

@@ -0,0 +1,152 @@
+import { Logger } from './logger.js';
+
+export interface CommandQueueItem<T = any> {
+  command: () => Promise<T>;
+  resolve: (value: T) => void;
+  reject: (reason?: any) => void;
+  priority: number;
+  retryCount?: number;
+}
+
+export class UnrealCommandQueue {
+  private log = new Logger('UnrealCommandQueue');
+  private queue: CommandQueueItem[] = [];
+  private isProcessing = false;
+  private lastCommandTime = 0;
+  private lastStatCommandTime = 0;
+
+  // Config
+  private readonly MIN_COMMAND_DELAY = 100;
+  private readonly MAX_COMMAND_DELAY = 500;
+  private readonly STAT_COMMAND_DELAY = 300;
+
+  constructor() {
+    this.startProcessor();
+  }
+
+  /**
+   * Execute a command with priority-based throttling
+   */
+  async execute<T>(command: () => Promise<T>, priority: number = 5): Promise<T> {
+    return new Promise((resolve, reject) => {
+      this.queue.push({
+        command,
+        resolve,
+        reject,
+        priority
+      });
+
+      // Sort by priority (lower number = higher priority)
+      this.queue.sort((a, b) => a.priority - b.priority);
+
+      // Process queue if not already processing
+      if (!this.isProcessing) {
+        this.processQueue();
+      }
+    });
+  }
+
+  private async processQueue(): Promise<void> {
+    if (this.isProcessing || this.queue.length === 0) {
+      return;
+    }
+
+    this.isProcessing = true;
+
+    while (this.queue.length > 0) {
+      const item = this.queue.shift();
+      if (!item) continue;
+
+      // Calculate delay based on time since last command
+      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: any) {
+        // Enhanced retry policy
+        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;
+  }
+
+  private calculateDelay(priority: number): number {
+    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;
+    }
+  }
+
+  private startProcessor(): void {
+    setInterval(() => {
+      if (!this.isProcessing && this.queue.length > 0) {
+        this.processQueue();
+      }
+    }, 1000);
+  }
+
+  private delay(ms: number): Promise<void> {
+    return new Promise(resolve => setTimeout(resolve, ms));
+  }
+}