unreal-engine-mcp-server 0.5.2 → 0.5.4

package/src/types/handler-types.ts

@@ -0,0 +1,442 @@
+/**
+ * Shared type definitions for handler arguments and responses.
+ * Used across all *-handlers.ts files to replace 'any' types.
+ */
+
+// ============================================================================
+// Common Geometry Types
+// ============================================================================
+
+/** 3D Vector - used for locations, forces, scales */
+export interface Vector3 {
+    x: number;
+    y: number;
+    z: number;
+}
+
+/** Rotation in Unreal format (Pitch, Yaw, Roll in degrees) */
+export interface Rotator {
+    pitch: number;
+    yaw: number;
+    roll: number;
+}
+
+/** Transform combining location, rotation, and scale */
+export interface Transform {
+    location?: Vector3;
+    rotation?: Rotator;
+    scale?: Vector3;
+}
+
+// ============================================================================
+// Base Handler Types
+// ============================================================================
+
+/**
+ * Base interface for handler arguments.
+ * All handler args should extend this or use it directly for loose typing.
+ */
+export interface HandlerArgs {
+    action?: string;
+    subAction?: string;
+    [key: string]: unknown;
+}
+
+/**
+ * Standard response from automation bridge requests.
+ */
+export interface AutomationResponse {
+    success: boolean;
+    message?: string;
+    error?: string;
+    result?: unknown;
+    [key: string]: unknown;
+}
+
+/**
+ * Component information returned from getComponents.
+ */
+export interface ComponentInfo {
+    name: string;
+    class?: string;
+    objectPath?: string;
+    [key: string]: unknown;
+}
+
+// ============================================================================
+// Actor Types
+// ============================================================================
+
+export interface ActorArgs extends HandlerArgs {
+    actorName?: string;
+    name?: string;
+    classPath?: string;
+    class?: string;
+    type?: string;
+    location?: Vector3;
+    rotation?: Rotator;
+    scale?: Vector3;
+    meshPath?: string;
+    timeoutMs?: number;
+    force?: Vector3;
+    parentActor?: string;
+    childActor?: string;
+    tag?: string;
+    newName?: string;
+    offset?: Vector3;
+    visible?: boolean;
+    componentName?: string;
+    componentType?: string;
+    properties?: Record<string, unknown>;
+}
+
+// ============================================================================
+// Asset Types
+// ============================================================================
+
+export interface AssetArgs extends HandlerArgs {
+    assetPath?: string;
+    path?: string;
+    directory?: string;
+    directoryPath?: string;
+    sourcePath?: string;
+    destinationPath?: string;
+    newName?: string;
+    name?: string;
+    filter?: string;
+    recursive?: boolean;
+    overwrite?: boolean;
+    classNames?: string[];
+    packagePaths?: string[];
+    parentMaterial?: string;
+    parameters?: Record<string, unknown>;
+    assetPaths?: string[];
+    meshPath?: string;
+}
+
+// ============================================================================
+// Blueprint Types
+// ============================================================================
+
+export interface BlueprintArgs extends HandlerArgs {
+    blueprintPath?: string;
+    name?: string;
+    savePath?: string;
+    blueprintType?: string;
+    componentType?: string;
+    componentName?: string;
+    attachTo?: string;
+    variableName?: string;
+    eventType?: string;
+    customEventName?: string;
+    nodeType?: string;
+    graphName?: string;
+    x?: number;
+    y?: number;
+    memberName?: string;
+    nodeId?: string;
+    pinName?: string;
+    linkedTo?: string;
+    fromNodeId?: string;
+    fromPin?: string;
+    fromPinName?: string;
+    toNodeId?: string;
+    toPin?: string;
+    toPinName?: string;
+    propertyName?: string;
+    value?: unknown;
+    properties?: Record<string, unknown>;
+    compile?: boolean;
+    save?: boolean;
+    metadata?: Record<string, unknown>;
+}
+
+// ============================================================================
+// Editor Types
+// ============================================================================
+
+export interface EditorArgs extends HandlerArgs {
+    command?: string;
+    filename?: string;
+    resolution?: string;
+    location?: Vector3;
+    rotation?: Rotator;
+    fov?: number;
+    speed?: number;
+    viewMode?: string;
+    width?: number;
+    height?: number;
+    enabled?: boolean;
+    realtime?: boolean;
+    bookmarkName?: string;
+    assetPath?: string;
+    path?: string;
+    category?: string;
+    preferences?: Record<string, unknown>;
+    timeoutMs?: number;
+}
+
+// ============================================================================
+// Level Types
+// ============================================================================
+
+export interface LevelArgs extends HandlerArgs {
+    levelPath?: string;
+    levelName?: string;
+    levelPaths?: string[];
+    destinationPath?: string;
+    savePath?: string;
+    subLevelPath?: string;
+    parentLevel?: string;
+    parentPath?: string;
+    streamingMethod?: 'Blueprint' | 'AlwaysLoaded';
+    exportPath?: string;
+    packagePath?: string;
+    sourcePath?: string;
+    lightType?: 'Directional' | 'Point' | 'Spot' | 'Rect';
+    name?: string;
+    location?: Vector3;
+    rotation?: Rotator;
+    intensity?: number;
+    color?: number[];
+    quality?: string;
+    streaming?: boolean;
+    shouldBeLoaded?: boolean;
+    shouldBeVisible?: boolean;
+    dataLayerLabel?: string;
+    dataLayerName?: string;
+    dataLayerState?: string;
+    actorPath?: string;
+    min?: number[];
+    max?: number[];
+    origin?: number[];
+    extent?: number[];
+    metadata?: Record<string, unknown>;
+    timeoutMs?: number;
+}
+
+// ============================================================================
+// Sequence Types
+// ============================================================================
+
+export interface SequenceArgs extends HandlerArgs {
+    path?: string;
+    name?: string;
+    actorName?: string;
+    actorNames?: string[];
+    spawnable?: boolean;
+    trackName?: string;
+    trackType?: string;
+    property?: string;
+    frame?: number;
+    value?: unknown;
+    speed?: number;
+    lengthInFrames?: number;
+    start?: number;
+    end?: number;
+    startFrame?: number;
+    endFrame?: number;
+    assetPath?: string;
+    muted?: boolean;
+    solo?: boolean;
+    locked?: boolean;
+}
+
+// ============================================================================
+// Effect Types
+// ============================================================================
+
+export interface EffectArgs extends HandlerArgs {
+    location?: Vector3;
+    rotation?: Rotator;
+    scale?: number;
+    preset?: string;
+    systemPath?: string;
+    shape?: string;
+    size?: number;
+    color?: number[];
+    name?: string;
+    emitterName?: string;
+    modulePath?: string;
+    parameterName?: string;
+    parameterType?: string;
+    type?: string;
+    filter?: string;
+}
+
+// ============================================================================
+// Environment Types
+// ============================================================================
+
+export interface EnvironmentArgs extends HandlerArgs {
+    name?: string;
+    landscapeName?: string;
+    location?: Vector3;
+    scale?: Vector3;
+    componentCount?: { x: number; y: number };
+    sectionSize?: number;
+    sectionsPerComponent?: number;
+    materialPath?: string;
+    foliageType?: string;
+    foliageTypePath?: string;
+    meshPath?: string;
+    density?: number;
+    radius?: number;
+    minScale?: number;
+    maxScale?: number;
+    alignToNormal?: boolean;
+    randomYaw?: boolean;
+    cullDistance?: number;
+    transforms?: Transform[];
+    locations?: Vector3[];
+    bounds?: { min: Vector3; max: Vector3 };
+    seed?: number;
+    heightData?: number[];
+    layerName?: string;
+}
+
+// ============================================================================
+// Lighting Types
+// ============================================================================
+
+export interface LightingArgs extends HandlerArgs {
+    lightType?: 'Directional' | 'Point' | 'Spot' | 'Rect';
+    name?: string;
+    location?: Vector3;
+    rotation?: Rotator;
+    intensity?: number;
+    color?: number[];
+    temperature?: number;
+    radius?: number;
+    falloffExponent?: number;
+    innerCone?: number;
+    outerCone?: number;
+    castShadows?: boolean;
+    method?: 'Lightmass' | 'LumenGI' | 'ScreenSpace' | 'None';
+    bounces?: number;
+    quality?: string;
+    enabled?: boolean;
+    density?: number;
+    fogHeight?: number;
+    cubemapPath?: string;
+    sourceType?: 'CapturedScene' | 'SpecifiedCubemap';
+    recapture?: boolean;
+}
+
+// ============================================================================
+// Performance Types
+// ============================================================================
+
+export interface PerformanceArgs extends HandlerArgs {
+    type?: 'CPU' | 'GPU' | 'Memory' | 'RenderThread' | 'GameThread' | 'All';
+    category?: string;
+    duration?: number;
+    outputPath?: string;
+    level?: number;
+    scale?: number;
+    enabled?: boolean;
+    maxFPS?: number;
+    verbose?: boolean;
+    detailed?: boolean;
+}
+
+// ============================================================================
+// Inspect Types
+// ============================================================================
+
+export interface InspectArgs extends HandlerArgs {
+    objectPath?: string;
+    name?: string;
+    actorName?: string;
+    componentName?: string;
+    propertyName?: string;
+    propertyPath?: string;
+    value?: unknown;
+    className?: string;
+    classPath?: string;
+    filter?: string;
+    tag?: string;
+    snapshotName?: string;
+    destinationPath?: string;
+    outputPath?: string;
+    format?: string;
+}
+
+// ============================================================================
+// Graph Types (Blueprint, Material, Niagara, BehaviorTree)
+// ============================================================================
+
+export interface GraphArgs extends HandlerArgs {
+    assetPath?: string;
+    blueprintPath?: string;
+    systemPath?: string;
+    graphName?: string;
+    nodeType?: string;
+    nodeId?: string;
+    x?: number;
+    y?: number;
+    memberName?: string;
+    variableName?: string;
+    eventName?: string;
+    functionName?: string;
+    targetClass?: string;
+    memberClass?: string;
+    componentClass?: string;
+    pinName?: string;
+    linkedTo?: string;
+    fromNodeId?: string;
+    fromPinName?: string;
+    toNodeId?: string;
+    toPinName?: string;
+    parentNodeId?: string;
+    childNodeId?: string;
+    properties?: Record<string, unknown>;
+}
+
+// ============================================================================
+// System Types
+// ============================================================================
+
+export interface SystemArgs extends HandlerArgs {
+    command?: string;
+    category?: string;
+    profileType?: string;
+    level?: number;
+    key?: string;
+    value?: string;
+    section?: string;
+    configName?: string;
+    resolution?: string;
+    enabled?: boolean;
+    widgetPath?: string;
+    parentName?: string;
+    childClass?: string;
+    target?: string;
+    platform?: string;
+    configuration?: string;
+    arguments?: string;
+}
+
+// ============================================================================
+// Input Types
+// ============================================================================
+
+export interface InputArgs extends HandlerArgs {
+    name?: string;
+    path?: string;
+    actionPath?: string;
+    contextPath?: string;
+    key?: string;
+}
+
+// ============================================================================
+// Pipeline Types
+// ============================================================================
+
+export interface PipelineArgs extends HandlerArgs {
+    target?: string;
+    platform?: string;
+    configuration?: string;
+    arguments?: string;
+    projectPath?: string;
+}

package/src/unreal-bridge.ts

@@ -1,7 +1,7 @@
 import { Logger } from './utils/logger.js';
 import { ErrorHandler } from './utils/error-handler.js';
 import type { AutomationBridge } from './automation/index.js';
-import { DEFAULT_AUTOMATION_HOST, DEFAULT_AUTOMATION_PORT } from './constants.js';
+import { DEFAULT_AUTOMATION_HOST, DEFAULT_AUTOMATION_PORT, CONSOLE_COMMAND_TIMEOUT_MS, ENGINE_QUERY_TIMEOUT_MS } from './constants.js';
 import { UnrealCommandQueue } from './utils/unreal-command-queue.js';
 import { CommandValidator } from './utils/command-validator.js';
 
@@ -153,7 +153,9 @@ export class UnrealBridge {
     if (this.connectPromise) {
       try {
         await this.connectPromise;
-      } catch { }
+      } catch (err) {
+        this.log.debug('Existing connect promise rejected', err instanceof Error ? err.message : String(err));
+      }
       return this.connected;
     }
 
@@ -483,7 +485,7 @@ export class UnrealBridge {
   }
 
   // Execute a console command safely with validation and throttling
-  async executeConsoleCommand(command: string, _options: Record<string, never> = {}): Promise<any> {
+  async executeConsoleCommand(command: string): Promise<any> {
     const automationAvailable = Boolean(
       this.automationBridge && typeof this.automationBridge.sendAutomationRequest === 'function'
     );
@@ -517,7 +519,7 @@ export class UnrealBridge {
       const pluginResp: ConsoleCommandResponse = await this.automationBridge.sendAutomationRequest(
         'console_command',
         { command: cmdTrimmed },
-        { timeoutMs: 30000 }
+        { timeoutMs: CONSOLE_COMMAND_TIMEOUT_MS }
       );
 
       if (pluginResp && pluginResp.success) {
@@ -601,7 +603,7 @@ export class UnrealBridge {
       const resp = await bridge.sendAutomationRequest(
         'system_control',
         { action: 'get_engine_version' },
-        { timeoutMs: 15000 }
+        { timeoutMs: ENGINE_QUERY_TIMEOUT_MS }
       );
       const raw: EngineVersionResult = resp && typeof resp.result === 'object'
         ? (resp.result as Record<string, unknown>)
@@ -644,7 +646,7 @@ export class UnrealBridge {
       const resp = await bridge.sendAutomationRequest(
         'system_control',
         { action: 'get_feature_flags' },
-        { timeoutMs: 15000 }
+        { timeoutMs: ENGINE_QUERY_TIMEOUT_MS }
       );
       const raw = resp && typeof resp.result === 'object'
         ? (resp.result as Record<string, unknown>)

package/src/utils/command-validator.ts

@@ -48,6 +48,14 @@ export class CommandValidator {
         /^this_is_not_a_valid/i,
     ];
 
+    /**
+     * Pre-compiled patterns for dangerous commands using word boundaries.
+     * This prevents false positives like 'show exit menu' matching 'exit'.
+     */
+    private static readonly DANGEROUS_PATTERNS = CommandValidator.DANGEROUS_COMMANDS.map(
+        cmd => new RegExp(`(?:^|\\s)${cmd.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}(?:\\s|$)`, 'i')
+    );
+
     /**
      * Validates a console command for safety before execution.
      * @param command - The console command string to validate
@@ -73,7 +81,8 @@ export class CommandValidator {
             throw new Error('Python console commands are blocked from external calls for safety.');
         }
 
-        if (this.DANGEROUS_COMMANDS.some(dangerous => cmdLower.includes(dangerous))) {
+        // Use word-boundary matching to avoid false positives like 'show exit menu'
+        if (this.DANGEROUS_PATTERNS.some(pattern => pattern.test(cmdLower))) {
             throw new Error(`Dangerous command blocked: ${command}`);
         }
 
@@ -81,9 +90,22 @@ export class CommandValidator {
             throw new Error('Command chaining with && or || is blocked for safety.');
         }
 
+        // Block semicolon and pipe which can also be used for command chaining/injection
+        if (cmdTrimmed.includes(';')) {
+            throw new Error('Command chaining with ; (semicolon) is blocked for safety.');
+        }
+        if (cmdTrimmed.includes('|')) {
+            throw new Error('Command piping with | is blocked for safety.');
+        }
+
         if (this.FORBIDDEN_TOKENS.some(token => cmdLower.includes(token))) {
             throw new Error(`Command contains unsafe token and was blocked: ${command}`);
         }
+
+        // Block backticks which can be used for shell execution
+        if (cmdTrimmed.includes('`')) {
+            throw new Error('Backtick characters are blocked for safety.');
+        }
     }
 
     /**

package/src/utils/error-handler.ts

@@ -240,7 +240,10 @@ export class ErrorHandler {
       if (['ECONNRESET', 'ECONNREFUSED', 'ETIMEDOUT', 'EPIPE'].includes(code)) return true;
       if (/timeout|timed out|network|connection|closed|unavailable|busy|temporar/.test(msg)) return true;
       if (!isNaN(status) && (status === 429 || (status >= 500 && status < 600))) return true;
-    } catch { }
+    } catch (err) {
+      // Error checking retriability is uncommon; log at debug level
+      log.debug('isRetriable check failed', err instanceof Error ? err.message : String(err));
+    }
     return false;
   }
 

package/src/utils/response-validator.ts

@@ -1,4 +1,4 @@
-import Ajv from 'ajv';
+import Ajv, { ValidateFunction } from 'ajv';
 import { Logger } from './logger.js';
 import { cleanObject } from './safe-json.js';
 import { wasmIntegration } from '../wasm/index.js';
@@ -161,16 +161,14 @@ function buildSummaryText(toolName: string, payload: unknown): string {
  * 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.
-  private ajv: any;
-  private validators: Map<string, any> = new Map();
+  // Ajv instance - using Ajv.default for ESM/CJS interop
+  private ajv: Ajv.default;
+  private validators: Map<string, ValidateFunction> = 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: any = (Ajv as any)?.default ?? Ajv;
-    this.ajv = new AjvCtor({
+    // Ajv exports differ between ESM and CJS - handle both patterns
+    const AjvClass = (Ajv as unknown as { default: typeof Ajv.default }).default ?? Ajv.default;
+    this.ajv = new AjvClass({
       allErrors: true,
       verbose: true,
       strict: true // Enforce strict schema validation

package/src/utils/safe-json.ts

@@ -1,11 +1,18 @@
 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');
+// Module-level logger to avoid creating new instances on every call
+const log = new Logger('safe-json');
 
-  function clean(value: any, depth: number, path: string = 'root'): any {
+/**
+ * Remove circular references and non-serializable properties from an object.
+ * @param obj - The object to clean
+ * @param maxDepth - Maximum recursion depth (default: 10)
+ * @returns Cleaned object safe for JSON serialization
+ */
+export function cleanObject<T = unknown>(obj: T, maxDepth: number = 10): T {
+  const seen = new WeakSet<object>();
+
+  function clean(value: unknown, depth: number, path: string = 'root'): unknown {
     // Prevent infinite recursion
     if (depth > maxDepth) {
       return '[Max depth reached]';
@@ -26,7 +33,8 @@ export function cleanObject(obj: any, maxDepth: number = 10): any {
       return value;
     }
 
-    // Check for circular reference
+    // Check for circular reference - keep in set permanently for this call
+    // This prevents the same object from appearing in multiple branches
     if (seen.has(value)) {
       return '[Circular Reference]';
     }
@@ -35,31 +43,28 @@ export function cleanObject(obj: any, maxDepth: number = 10): any {
 
     // 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;
+      return value.map((item, index) => clean(item, depth + 1, `${path}[${index}]`));
     }
 
     // Handle objects
-    const cleaned: any = {};
+    const cleaned: Record<string, unknown> = {};
 
     // Use Object.keys to avoid prototype properties
-    const keys = Object.keys(value);
+    const keys = Object.keys(value as object);
     for (const key of keys) {
       try {
-        const cleanedValue = clean(value[key], depth + 1, `${path}.${key}`);
+        const cleanedValue = clean((value as Record<string, unknown>)[key], depth + 1, `${path}.${key}`);
         if (cleanedValue !== undefined) {
           cleaned[key] = cleanedValue;
         }
       } catch (e) {
         // Skip properties that throw errors when accessed
-        logger.error(`Error cleaning property ${path}.${key}`, e);
+        log.error(`Error cleaning property ${path}.${key}`, e);
       }
     }
 
-    seen.delete(value); // Remove from seen after processing
     return cleaned;
   }
 
-  return clean(obj, 0);
+  return clean(obj, 0) as T;
 }

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

@@ -140,11 +140,13 @@ export class UnrealCommandQueue {
   }
 
   private startProcessor(): void {
+    // Fallback processor - primary processing is triggered directly from execute()
+    // Reduced from 1000ms to 250ms for faster recovery if processor stalls
     this.processorInterval = setInterval(() => {
       if (!this.isProcessing && this.queue.length > 0) {
         this.processQueue();
       }
-    }, 1000);
+    }, 250);
   }
 
   /**

package/src/utils/validation.test.ts

@@ -59,9 +59,9 @@ describe('sanitizePath', () => {
     });
 
     it('sanitizes path segments with dots', () => {
-        const result = sanitizePath('/Game/../MyAsset');
-        // Each segment is sanitized, .. becomes a segment that gets sanitized
-        expect(result).toContain('/');
+        expect(() => sanitizePath('/Game/../MyAsset')).toThrow(
+            'Path traversal (..) is not allowed'
+        );
     });
 });