unreal-engine-mcp-server 0.5.0 → 0.5.2

package/src/utils/response-validator.ts

@@ -27,114 +27,130 @@ function buildSummaryText(toolName: string, payload: unknown): string {
     return `${toolName} responded`;
   }
 
-  // 1. Check for specific "data" or "result" wrapper
+  // Recursively flatten data/result wrappers into effective payload
   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[] = [];
+  const flattenWrappers = (obj: Record<string, any>, depth = 0): void => {
+    if (depth > 5) return; // Prevent infinite loops
+    if (isRecord(obj.data)) {
+      Object.assign(obj, obj.data);
+      delete obj.data;
+      flattenWrappers(obj, depth + 1);
+    }
+    if (isRecord(obj.result)) {
+      Object.assign(obj, obj.result);
+      delete obj.result;
+      flattenWrappers(obj, depth + 1);
+    }
+  };
+  flattenWrappers(effectivePayload);
 
-  // 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})`);
+  const parts: string[] = [];
+  const addedKeys = new Set<string>();
+
+  // Keys to skip (internal/redundant)
+  const skipKeys = new Set(['requestId', 'type', 'data', 'result', 'warnings']);
+
+  // Helper to format a value for display
+  const formatValue = (val: unknown): string => {
+    if (val === null || val === undefined) return '';
+    if (typeof val === 'string') return val.length > 150 ? val.slice(0, 150) + '...' : val;
+    if (typeof val === 'number' || typeof val === 'boolean') return String(val);
+
+    // Handle arrays - show items with names/paths
+    if (Array.isArray(val)) {
+      if (val.length === 0) return '[] (0)';
+      const items = val.slice(0, 30).map(v => {
+        if (isRecord(v)) {
+          // Try common identifier fields
+          return v.name || v.path || v.id || v.nodeId || v.nodeName || v.className ||
+            v.displayName || v.type || v.assetPath || v.objectPath ||
+            JSON.stringify(v).slice(0, 50);
+        }
+        return String(v);
+      });
+      const suffix = val.length > 30 ? `, ... (+${val.length - 30} more)` : '';
+      return `[${items.join(', ')}${suffix}] (${val.length})`;
     }
-  }
 
-  // 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}`);
-  }
+    // Handle transform-like objects (location/rotation/scale)
+    if (isRecord(val)) {
+      const keys = Object.keys(val);
+      // Check if it looks like a 3D vector/transform
+      if (keys.some(k => ['x', 'y', 'z', 'pitch', 'yaw', 'roll'].includes(k))) {
+        const x = val.x ?? val.pitch ?? 0;
+        const y = val.y ?? val.yaw ?? 0;
+        const z = val.z ?? val.roll ?? 0;
+        return `[${x}, ${y}, ${z}]`;
+      }
+      // Generic object - show key=value pairs
+      const entries = Object.entries(val).slice(0, 8);
+      const formatted = entries.map(([k, v]) => {
+        const vStr = typeof v === 'object' ? JSON.stringify(v).slice(0, 40) : String(v);
+        return `${k}=${vStr}`;
+      });
+      return `{ ${formatted.join(', ')}${keys.length > 8 ? ' ...' : ''} }`;
+    }
 
-  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}`);
+    return String(val);
+  };
+
+  // Process all keys in priority order
+  // 1. First add 'success' and 'error' at the start
+  for (const key of ['success', 'error']) {
+    if (effectivePayload[key] !== undefined && !addedKeys.has(key)) {
+      const formatted = formatValue(effectivePayload[key]);
+      if (formatted) {
+        parts.push(`${key}: ${formatted}`);
+        addedKeys.add(key);
+      }
+    }
   }
 
-  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}`);
-  }
+  // 2. Then add ALL other keys dynamically
+  let hasArrays = false;
+  for (const [key, val] of Object.entries(effectivePayload)) {
+    if (addedKeys.has(key)) continue;
+    if (skipKeys.has(key)) continue;
+    if (val === undefined || val === null) continue;
+    if (typeof val === 'string' && val.trim() === '') continue;
 
-  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}`);
-  }
+    // Skip 'message' for now - handle later to avoid duplication
+    if (key === 'message') continue;
 
-  // 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;
-      }
+    // Track if we have arrays (to skip duplicate count/totalCount later)
+    if (Array.isArray(val) && val.length > 0) hasArrays = true;
 
-      const strVal = String(val);
-      // Avoid traversing huge strings
-      if (strVal.length > 100) continue;
+    // Skip count/totalCount if we already have arrays showing counts
+    if ((key === 'count' || key === 'totalCount') && hasArrays) continue;
 
-      if (!parts.some(p => p.includes(strVal))) {
-        parts.push(`${key}: ${strVal}`);
-      }
+    const formatted = formatValue(val);
+    if (formatted) {
+      parts.push(`${key}: ${formatted}`);
+      addedKeys.add(key);
     }
   }
 
-  // 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) : '';
+  // 3. Handle message last - but skip if it duplicates existing info
+  const message = typeof effectivePayload.message === 'string' ? normalizeText(effectivePayload.message) : '';
+  if (message && message.toLowerCase() !== 'success') {
+    // Skip if message duplicates count info
+    const isDuplicateInfo = /^(found|listed|retrieved|got|loaded|created|deleted|saved|spawned)\s+\d+/i.test(message) ||
+      /Folders:\s*\[/.test(message) ||
+      /\d+\s+(assets?|folders?|items?|actors?|components?)\s+(and|in|at)/i.test(message);
 
-  if (parts.length > 0) {
-    if (message && message.toLowerCase() !== 'success') {
+    // Also skip if message content is already represented in parts
+    const messageInParts = parts.some(p => p.toLowerCase().includes(message.toLowerCase().slice(0, 30)));
+
+    if (!isDuplicateInfo && !messageInParts) {
       parts.push(message);
     }
-  } 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');
-    }
   }
 
-  // 6. Warnings
-  const warnings = Array.isArray(payload.warnings) ? payload.warnings : [];
+  // 4. Warnings at end
+  const warnings = Array.isArray(effectivePayload.warnings) ? effectivePayload.warnings : [];
   if (warnings.length > 0) {
-    parts.push(`Warnings: ${warnings.length}`);
+    parts.push(`Warnings: ${warnings.map((w: any) => typeof w === 'string' ? w : JSON.stringify(w)).join('; ')}`);
   }
 
   return parts.length > 0 ? parts.join(' | ') : `${toolName} responded`;

package/src/utils/safe-json.test.ts

@@ -0,0 +1,90 @@
+/**
+ * Unit tests for safe-json utility
+ */
+import { describe, it, expect } from 'vitest';
+import { cleanObject } from './safe-json.js';
+
+describe('cleanObject', () => {
+    it('removes undefined values', () => {
+        const input = { a: 1, b: undefined, c: 3 };
+        const result = cleanObject(input);
+        expect(result).toEqual({ a: 1, c: 3 });
+        expect('b' in result).toBe(false);
+    });
+
+    it('preserves null values (only removes undefined)', () => {
+        const input = { a: 1, b: null, c: 3 };
+        const result = cleanObject(input);
+        // cleanObject preserves null, only removes undefined
+        expect(result).toEqual({ a: 1, b: null, c: 3 });
+    });
+
+    it('handles nested objects', () => {
+        const input = { a: 1, nested: { b: 2, c: undefined } };
+        const result = cleanObject(input);
+        expect(result.nested).toEqual({ b: 2 });
+    });
+
+    it('handles arrays with undefined (preserves null)', () => {
+        const input = { arr: [1, undefined, 3, null] };
+        const result = cleanObject(input);
+        // Arrays preserve their structure, undefined becomes undefined in array
+        expect(result.arr).toEqual([1, undefined, 3, null]);
+    });
+
+    it('preserves falsy values that are not null/undefined', () => {
+        const input = { a: 0, b: '', c: false };
+        const result = cleanObject(input);
+        expect(result).toEqual({ a: 0, b: '', c: false });
+    });
+
+    it('handles empty objects', () => {
+        expect(cleanObject({})).toEqual({});
+    });
+
+    it('handles primitive inputs', () => {
+        expect(cleanObject('string')).toBe('string');
+        expect(cleanObject(42)).toBe(42);
+        expect(cleanObject(true)).toBe(true);
+    });
+
+    it('respects max depth limit', () => {
+        // Create deeply nested object
+        let deep: any = { value: 'deep' };
+        for (let i = 0; i < 15; i++) {
+            deep = { nested: deep };
+        }
+
+        // Should not throw when hitting depth limit
+        expect(() => cleanObject(deep, 10)).not.toThrow();
+    });
+
+    it('handles circular reference prevention at max depth', () => {
+        const obj: any = { a: 1 };
+        obj.self = obj; // circular reference
+
+        // Should not throw - depth limiting should prevent infinite recursion
+        expect(() => cleanObject(obj, 5)).not.toThrow();
+    });
+
+    it('handles Date objects (converts to empty object)', () => {
+        const date = new Date('2024-01-01');
+        const input = { created: date };
+        const result = cleanObject(input);
+        // Date objects are processed as objects using Object.keys, which returns []
+        expect(result.created).toEqual({});
+    });
+
+    it('handles empty arrays', () => {
+        const input = { arr: [] };
+        const result = cleanObject(input);
+        expect(result.arr).toEqual([]);
+    });
+
+    it('handles NaN values', () => {
+        const input = { a: 1, b: NaN };
+        const result = cleanObject(input);
+        // NaN handling depends on implementation
+        expect(result.a).toBe(1);
+    });
+});

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

@@ -14,6 +14,7 @@ export class UnrealCommandQueue {
   private isProcessing = false;
   private lastCommandTime = 0;
   private lastStatCommandTime = 0;
+  private processorInterval?: ReturnType<typeof setInterval>;
 
   // Config
   private readonly MIN_COMMAND_DELAY = 100;
@@ -139,13 +140,24 @@ export class UnrealCommandQueue {
   }
 
   private startProcessor(): void {
-    setInterval(() => {
+    this.processorInterval = setInterval(() => {
       if (!this.isProcessing && this.queue.length > 0) {
         this.processQueue();
       }
     }, 1000);
   }
 
+  /**
+   * Stop the command queue processor and clean up the interval.
+   * Should be called during shutdown to allow clean process exit.
+   */
+  stopProcessor(): void {
+    if (this.processorInterval) {
+      clearInterval(this.processorInterval);
+      this.processorInterval = undefined;
+    }
+  }
+
   private delay(ms: number): Promise<void> {
     return new Promise(resolve => setTimeout(resolve, ms));
   }

package/src/utils/validation.test.ts

@@ -0,0 +1,184 @@
+/**
+ * Unit tests for validation utility functions
+ */
+import { describe, it, expect } from 'vitest';
+import {
+    sanitizeAssetName,
+    sanitizePath,
+    validatePathLength,
+    validateAssetParams,
+    validateNumber,
+    ensureVector3,
+    ensureRotation
+} from './validation.js';
+
+describe('sanitizeAssetName', () => {
+    it('removes invalid characters', () => {
+        // ! is replaced with _, then trailing _ is stripped
+        expect(sanitizeAssetName('My Asset!')).toBe('My_Asset');
+    });
+
+    it('removes leading/trailing whitespace', () => {
+        expect(sanitizeAssetName('  MyAsset  ')).toBe('MyAsset');
+    });
+
+    it('preserves valid names', () => {
+        expect(sanitizeAssetName('ValidName_123')).toBe('ValidName_123');
+    });
+
+    it('replaces spaces with underscores', () => {
+        expect(sanitizeAssetName('My Cool Asset')).toBe('My_Cool_Asset');
+    });
+
+    it('handles empty strings', () => {
+        const result = sanitizeAssetName('');
+        expect(result.length).toBeGreaterThan(0);
+    });
+
+    it('removes consecutive underscores', () => {
+        const result = sanitizeAssetName('My__Asset');
+        expect(result).not.toContain('__');
+    });
+});
+
+describe('sanitizePath', () => {
+    it('normalizes forward slashes', () => {
+        const result = sanitizePath('/Game/MyAsset');
+        expect(result).toContain('/');
+        expect(result).not.toContain('\\\\');
+    });
+
+    it('removes double slashes', () => {
+        const result = sanitizePath('/Game//MyAsset');
+        expect(result).not.toContain('//');
+    });
+
+    it('handles backslashes', () => {
+        const result = sanitizePath('\\Game\\MyAsset');
+        expect(result).toContain('/');
+    });
+
+    it('sanitizes path segments with dots', () => {
+        const result = sanitizePath('/Game/../MyAsset');
+        // Each segment is sanitized, .. becomes a segment that gets sanitized
+        expect(result).toContain('/');
+    });
+});
+
+describe('validatePathLength', () => {
+    it('accepts valid short paths', () => {
+        const result = validatePathLength('/Game/MyAsset');
+        expect(result.valid).toBe(true);
+    });
+
+    it('accepts empty paths (length 0 < 260)', () => {
+        const result = validatePathLength('');
+        // Empty string has length 0, which is < 260, so it's valid
+        expect(result.valid).toBe(true);
+    });
+
+    it('rejects excessively long paths', () => {
+        const longPath = '/Game/' + 'a'.repeat(300);
+        const result = validatePathLength(longPath);
+        expect(result.valid).toBe(false);
+        expect(result.error).toBeDefined();
+    });
+});
+
+describe('validateAssetParams', () => {
+    it('validates correct create params', () => {
+        const result = validateAssetParams({
+            action: 'create',
+            name: 'MyAsset',
+            path: '/Game/Assets'
+        });
+        expect(result.valid).toBe(true);
+    });
+
+    it('handles names that need sanitization', () => {
+        const result = validateAssetParams({
+            name: '',
+            savePath: '/Game'
+        });
+        // Empty name gets sanitized to 'Asset', so this should be valid
+        expect(result.valid).toBe(true);
+    });
+
+    it('validates path params', () => {
+        const result = validateAssetParams({
+            name: 'Target',
+            savePath: '/Game/Source'
+        });
+        expect(result.valid).toBe(true);
+    });
+});
+
+describe('validateNumber', () => {
+    it('accepts valid finite numbers', () => {
+        expect(() => validateNumber(42, 'test')).not.toThrow();
+    });
+
+    it('rejects NaN', () => {
+        expect(() => validateNumber(NaN, 'test')).toThrow('expected a finite number');
+    });
+
+    it('rejects Infinity', () => {
+        expect(() => validateNumber(Infinity, 'test')).toThrow();
+    });
+
+    it('respects minimum constraint', () => {
+        expect(() => validateNumber(5, 'test', { min: 10 })).toThrow('must be >=');
+    });
+
+    it('respects maximum constraint', () => {
+        expect(() => validateNumber(15, 'test', { max: 10 })).toThrow('must be <=');
+    });
+
+    it('allows zero by default', () => {
+        expect(() => validateNumber(0, 'test')).not.toThrow();
+    });
+
+    it('rejects zero when allowZero is false', () => {
+        expect(() => validateNumber(0, 'test', { allowZero: false })).toThrow('zero is not allowed');
+    });
+});
+
+describe('ensureVector3', () => {
+    it('accepts object format with x, y, z', () => {
+        const result = ensureVector3({ x: 1, y: 2, z: 3 }, 'location');
+        expect(result).toEqual([1, 2, 3]);
+    });
+
+    it('accepts array format', () => {
+        const result = ensureVector3([1, 2, 3], 'location');
+        expect(result).toEqual([1, 2, 3]);
+    });
+
+    it('throws on invalid object', () => {
+        expect(() => ensureVector3({ x: 1 }, 'location')).toThrow();
+    });
+
+    it('throws on wrong array length', () => {
+        expect(() => ensureVector3([1, 2], 'location')).toThrow();
+    });
+
+    it('throws on non-number values', () => {
+        expect(() => ensureVector3({ x: 'a', y: 2, z: 3 }, 'location')).toThrow();
+    });
+});
+
+describe('ensureRotation', () => {
+    it('accepts object format with pitch, yaw, roll', () => {
+        const result = ensureRotation({ pitch: 0, yaw: 90, roll: 0 }, 'rotation');
+        expect(result).toEqual([0, 90, 0]);
+    });
+
+    it('accepts array format', () => {
+        const result = ensureRotation([0, 90, 0], 'rotation');
+        expect(result).toEqual([0, 90, 0]);
+    });
+
+    it('throws on invalid input', () => {
+        expect(() => ensureRotation('invalid', 'rotation')).toThrow();
+    });
+});