unreal-engine-mcp-server 0.5.1 → 0.5.2

package/src/unreal-bridge.ts

@@ -5,14 +5,59 @@ import { DEFAULT_AUTOMATION_HOST, DEFAULT_AUTOMATION_PORT } from './constants.js
 import { UnrealCommandQueue } from './utils/unreal-command-queue.js';
 import { CommandValidator } from './utils/command-validator.js';
 
+/** Connection event payload for automation bridge events */
+interface ConnectionEventInfo {
+  host?: string;
+  port?: number;
+  reason?: string;
+  error?: string;
+  [key: string]: unknown;
+}
+
+/** Result object from automation requests */
+interface AutomationResult {
+  value?: unknown;
+  propertyValue?: unknown;
+  message?: string;
+  warnings?: string[];
+  [key: string]: unknown;
+}
+
+/** Subsystems feature flags */
+interface SubsystemFlags {
+  unrealEditor?: boolean;
+  levelEditor?: boolean;
+  editorActor?: boolean;
+  [key: string]: unknown;
+}
+
+/** Engine version result */
+interface EngineVersionResult {
+  version?: string;
+  major?: number;
+  minor?: number;
+  patch?: number;
+  isUE56OrAbove?: boolean;
+  [key: string]: unknown;
+}
+
+/** Console command response */
+interface ConsoleCommandResponse {
+  success?: boolean;
+  message?: string;
+  error?: string;
+  transport?: string;
+  [key: string]: unknown;
+}
+
 export class UnrealBridge {
   private log = new Logger('UnrealBridge');
   private connected = false;
   private automationBridge?: AutomationBridge;
   private automationBridgeListeners?: {
-    connected: (info: any) => void;
-    disconnected: (info: any) => void;
-    handshakeFailed: (info: any) => void;
+    connected: (info: ConnectionEventInfo) => void;
+    disconnected: (info: ConnectionEventInfo) => void;
+    handshakeFailed: (info: ConnectionEventInfo) => void;
   };
 
   // Command queue for throttling
@@ -35,17 +80,17 @@ export class UnrealBridge {
       return;
     }
 
-    const onConnected = (info: any) => {
+    const onConnected = (info: ConnectionEventInfo) => {
       this.connected = true;
       this.log.debug('Automation bridge connected', info);
     };
 
-    const onDisconnected = (info: any) => {
+    const onDisconnected = (info: ConnectionEventInfo) => {
       this.connected = false;
       this.log.debug('Automation bridge disconnected', info);
     };
 
-    const onHandshakeFailed = (info: any) => {
+    const onHandshakeFailed = (info: ConnectionEventInfo) => {
       this.connected = false;
       this.log.warn('Automation bridge handshake failed', info);
     };
@@ -279,13 +324,13 @@ export class UnrealBridge {
       );
 
       const success = response.success !== false;
-      const rawResult =
+      const rawResult: AutomationResult | undefined =
         response.result && typeof response.result === 'object'
           ? { ...(response.result as Record<string, unknown>) }
-          : response.result;
+          : undefined;
       const value =
-        (rawResult as any)?.value ??
-        (rawResult as any)?.propertyValue ??
+        rawResult?.value ??
+        rawResult?.propertyValue ??
         (success ? rawResult : undefined);
 
       if (success) {
@@ -297,8 +342,8 @@ export class UnrealBridge {
           propertyValue: value,
           transport: 'automation_bridge',
           message: response.message,
-          warnings: Array.isArray((rawResult as any)?.warnings)
-            ? (rawResult as any).warnings
+          warnings: Array.isArray(rawResult?.warnings)
+            ? rawResult.warnings
             : undefined,
           raw: rawResult,
           bridge: {
@@ -389,10 +434,10 @@ export class UnrealBridge {
       );
 
       const success = response.success !== false;
-      const rawResult =
+      const rawResult: AutomationResult | undefined =
         response.result && typeof response.result === 'object'
           ? { ...(response.result as Record<string, unknown>) }
-          : response.result;
+          : undefined;
 
       if (success) {
         return {
@@ -401,7 +446,7 @@ export class UnrealBridge {
           propertyName,
           message:
             response.message ||
-            (typeof (rawResult as any)?.message === 'string' ? (rawResult as any).message : undefined),
+            (typeof rawResult?.message === 'string' ? rawResult.message : undefined),
           transport: 'automation_bridge',
           raw: rawResult,
           bridge: {
@@ -469,14 +514,14 @@ export class UnrealBridge {
         throw new Error('Automation bridge not connected');
       }
 
-      const pluginResp: any = await this.automationBridge.sendAutomationRequest(
+      const pluginResp: ConsoleCommandResponse = await this.automationBridge.sendAutomationRequest(
         'console_command',
         { command: cmdTrimmed },
         { timeoutMs: 30000 }
       );
 
       if (pluginResp && pluginResp.success) {
-        return { ...(pluginResp as any), transport: 'automation_bridge' };
+        return { ...pluginResp, transport: 'automation_bridge' };
       }
 
       const errMsg = pluginResp?.message || pluginResp?.error || 'Plugin execution failed';
@@ -553,14 +598,14 @@ export class UnrealBridge {
 
     const bridge = this.getAutomationBridge();
     try {
-      const resp: any = await bridge.sendAutomationRequest(
+      const resp = await bridge.sendAutomationRequest(
         'system_control',
         { action: 'get_engine_version' },
         { timeoutMs: 15000 }
       );
-      const raw = resp && typeof resp.result === 'object'
-        ? (resp.result as any)
-        : (resp?.result ?? resp ?? {});
+      const raw: EngineVersionResult = resp && typeof resp.result === 'object'
+        ? (resp.result as Record<string, unknown>)
+        : (resp?.result as Record<string, unknown>) ?? resp ?? {};
       const version = typeof raw.version === 'string' ? raw.version : 'unknown';
       const major = typeof raw.major === 'number' ? raw.major : 0;
       const minor = typeof raw.minor === 'number' ? raw.minor : 0;
@@ -596,16 +641,16 @@ export class UnrealBridge {
 
     const bridge = this.getAutomationBridge();
     try {
-      const resp: any = await bridge.sendAutomationRequest(
+      const resp = await bridge.sendAutomationRequest(
         'system_control',
         { action: 'get_feature_flags' },
         { timeoutMs: 15000 }
       );
       const raw = resp && typeof resp.result === 'object'
-        ? (resp.result as any)
-        : (resp?.result ?? resp ?? {});
-      const subs = raw && typeof raw.subsystems === 'object'
-        ? (raw.subsystems as any)
+        ? (resp.result as Record<string, unknown>)
+        : (resp?.result as Record<string, unknown>) ?? resp ?? {};
+      const subs: SubsystemFlags = raw && typeof raw.subsystems === 'object'
+        ? (raw.subsystems as SubsystemFlags)
         : {};
       return {
         subsystems: {

package/src/utils/command-validator.ts

@@ -1,28 +1,58 @@
+/**
+ * Validates console commands before execution to prevent dangerous operations.
+ * Blocks crash-inducing commands, shell injection, and Python execution.
+ */
 export class CommandValidator {
+    /**
+     * Commands that can crash the engine or cause severe instability.
+     * These are blocked unconditionally.
+     */
     private static readonly DANGEROUS_COMMANDS = [
-        'quit', 'exit', 'delete', 'destroy', 'kill', 'crash',
+        // Engine termination commands
+        'quit', 'exit', 'kill', 'crash',
+        // Crash-inducing commands
+        'r.gpucrash', 'r.crash', 'debug crash', 'forcecrash', 'debug break',
+        'assert false', 'check(false)',
+        // View buffer commands that can crash on some hardware
         'viewmode visualizebuffer basecolor',
         'viewmode visualizebuffer worldnormal',
-        'r.gpucrash',
-        'buildpaths', // Can cause access violation if nav system not initialized
-        'rebuildnavigation', // Can also crash without proper nav setup
-        'obj garbage', 'obj list', 'memreport' // Heavy debug commands that can stall
+        // Heavy operations that can cause access violations if systems not initialized
+        'buildpaths', 'rebuildnavigation',
+        // Heavy debug commands that can stall or crash
+        'obj garbage', 'obj list', 'memreport',
+        // Potentially destructive without proper setup
+        'delete', 'destroy'
     ];
 
+    /**
+     * Tokens that indicate shell injection or external system access attempts.
+     * Any command containing these is blocked.
+     */
     private static readonly FORBIDDEN_TOKENS = [
+        // Shell commands (Windows/Unix)
         'rm ', 'rm-', 'del ', 'format ', 'shutdown', 'reboot',
         'rmdir', 'mklink', 'copy ', 'move ', 'start "', 'system(',
+        // Python injection attempts
         'import os', 'import subprocess', 'subprocess.', 'os.system',
         'exec(', 'eval(', '__import__', 'import sys', 'import importlib',
         'with open', 'open(', 'write(', 'read('
     ];
 
+    /**
+     * Patterns that indicate obviously invalid commands.
+     * Used to warn about likely typos or invalid input.
+     */
     private static readonly INVALID_PATTERNS = [
         /^\d+$/,  // Just numbers
         /^invalid_command/i,
         /^this_is_not_a_valid/i,
     ];
 
+    /**
+     * Validates a console command for safety before execution.
+     * @param command - The console command string to validate
+     * @throws Error if the command is dangerous, contains forbidden tokens, or is invalid
+     */
     static validate(command: string): void {
         if (!command || typeof command !== 'string') {
             throw new Error('Invalid command: must be a non-empty string');
@@ -56,11 +86,22 @@ export class CommandValidator {
         }
     }
 
+    /**
+     * Check if a command looks like an obviously invalid or mistyped command.
+     * @param command - The command to check
+     * @returns true if the command matches known invalid patterns
+     */
     static isLikelyInvalid(command: string): boolean {
         const cmdTrimmed = command.trim();
         return this.INVALID_PATTERNS.some(pattern => pattern.test(cmdTrimmed));
     }
 
+    /**
+     * Get the priority level of a command for throttling purposes.
+     * Lower numbers indicate heavier operations that need more throttling.
+     * @param command - The command to evaluate
+     * @returns Priority level (1=heavy, 5=medium, 7=default, 8-9=light)
+     */
     static getPriority(command: string): number {
         if (command.includes('BuildLighting') || command.includes('BuildPaths')) {
             return 1; // Heavy operation

package/src/utils/error-handler.ts

@@ -16,61 +16,134 @@ export enum ErrorType {
   UNKNOWN = 'UNKNOWN'
 }
 
+/**
+ * Debug information attached to error responses in development mode
+ */
+interface ErrorResponseDebug {
+  errorType: ErrorType;
+  originalError: string;
+  stack?: string;
+  context?: Record<string, unknown>;
+  retriable: boolean;
+  scope: string;
+}
+
+/**
+ * Extended error response with optional debug info
+ */
+interface ErrorToolResponse extends BaseToolResponse {
+  _debug?: ErrorResponseDebug;
+}
+
+/**
+ * Represents any error object with common properties
+ */
+interface ErrorLike {
+  message?: string;
+  code?: string;
+  type?: string;
+  errorType?: string;
+  stack?: string;
+  response?: { status?: number };
+}
+
+/**
+ * Normalize any error type to ErrorLike interface
+ */
+function normalizeErrorToLike(error: unknown): ErrorLike {
+  if (error instanceof Error) {
+    return {
+      message: error.message,
+      stack: error.stack,
+      code: (error as NodeJS.ErrnoException).code
+    };
+  }
+  if (typeof error === 'object' && error !== null) {
+    const obj = error as Record<string, unknown>;
+    return {
+      message: typeof obj.message === 'string' ? obj.message : undefined,
+      code: typeof obj.code === 'string' ? obj.code : undefined,
+      type: typeof obj.type === 'string' ? obj.type : undefined,
+      errorType: typeof obj.errorType === 'string' ? obj.errorType : undefined,
+      stack: typeof obj.stack === 'string' ? obj.stack : undefined,
+      response: typeof obj.response === 'object' && obj.response !== null
+        ? {
+          status: typeof (obj.response as Record<string, unknown>).status === 'number'
+            ? (obj.response as Record<string, unknown>).status as number
+            : undefined
+        }
+        : undefined
+    };
+  }
+  return { message: String(error) };
+}
+
 /**
  * Consistent error handling for all tools
  */
 export class ErrorHandler {
   /**
    * Create a standardized error response
+   * @param error - The error object (can be Error, string, object with message, or unknown)
+   * @param toolName - Name of the tool that failed
+   * @param context - Optional additional context for debugging
    */
   static createErrorResponse(
-    error: any,
+    error: unknown,
     toolName: string,
-    context?: any
-  ): BaseToolResponse {
-    const errorType = this.categorizeError(error);
-    const userMessage = this.getUserFriendlyMessage(errorType, error);
-    const retriable = this.isRetriable(error);
-    const scope = context?.scope || `tool-call/${toolName}`;
-    
+    context?: Record<string, unknown>
+  ): ErrorToolResponse {
+    const errorObj = normalizeErrorToLike(error);
+    const errorType = this.categorizeError(errorObj);
+    const userMessage = this.getUserFriendlyMessage(errorType, errorObj);
+    const retriable = this.isRetriable(errorObj);
+    const scope = (context?.scope as string) || `tool-call/${toolName}`;
+    const errorMessage = errorObj.message || String(error);
+    const errorStack = errorObj.stack;
+
     log.error(`Tool ${toolName} failed:`, {
       type: errorType,
-      message: error.message || error,
+      message: errorMessage,
       retriable,
       scope,
       context
     });
 
-    return {
+    const response: ErrorToolResponse = {
       success: false,
       error: userMessage,
       message: `Failed to execute ${toolName}: ${userMessage}`,
-      retriable: retriable as any,
-      scope: scope as any,
-      // Add debug info in development
-      ...(process.env.NODE_ENV === 'development' && {
-        _debug: {
-          errorType,
-          originalError: error.message || String(error),
-          stack: error.stack,
-          context,
-          retriable,
-          scope
-        }
-      })
-    } as any;
+      retriable,
+      scope
+    };
+
+    // Add debug info in development
+    if (process.env.NODE_ENV === 'development') {
+      response._debug = {
+        errorType,
+        originalError: errorMessage,
+        stack: errorStack,
+        context,
+        retriable,
+        scope
+      };
+    }
+
+    return response;
   }
 
   /**
    * Categorize error by type
+   * @param error - The error to categorize
    */
-  private static categorizeError(error: any): ErrorType {
-    const explicitType = (error?.type || error?.errorType || '').toString().toUpperCase();
+  private static categorizeError(error: ErrorLike | Error | string): ErrorType {
+    const errorObj = typeof error === 'object' ? error as ErrorLike : null;
+    const explicitType = (errorObj?.type || errorObj?.errorType || '').toString().toUpperCase();
     if (explicitType && Object.values(ErrorType).includes(explicitType as ErrorType)) {
       return explicitType as ErrorType;
     }
 
-    const errorMessage = error?.message?.toLowerCase() || String(error).toLowerCase();
+    const errorMessage = (errorObj?.message || String(error)).toLowerCase();
 
     // Connection errors
     if (
@@ -122,49 +195,59 @@ export class ErrorHandler {
 
   /**
    * Get user-friendly error message
+   * @param type - The categorized error type
+   * @param error - The original error
    */
-  private static getUserFriendlyMessage(type: ErrorType, error: any): string {
-    const originalMessage = error.message || String(error);
+  private static getUserFriendlyMessage(type: ErrorType, error: ErrorLike | Error | string): string {
+    const originalMessage = (typeof error === 'object' && error !== null && 'message' in error)
+      ? (error as { message?: string }).message || String(error)
+      : String(error);
 
     switch (type) {
       case ErrorType.CONNECTION:
         return 'Failed to connect to Unreal Engine. Please ensure the Automation Bridge plugin is active and the editor is running.';
-      
+
       case ErrorType.VALIDATION:
         return `Invalid input: ${originalMessage}`;
-      
+
       case ErrorType.UNREAL_ENGINE:
         return `Unreal Engine error: ${originalMessage}`;
-      
+
       case ErrorType.PARAMETER:
         return `Invalid parameters: ${originalMessage}`;
-      
+
       case ErrorType.TIMEOUT:
         return 'Operation timed out. Unreal Engine may be busy or unresponsive.';
-      
+
       case ErrorType.EXECUTION:
         return `Execution failed: ${originalMessage}`;
-      
+
       default:
         return originalMessage;
     }
   }
 
-  /** Determine if an error is likely retriable */
-  private static isRetriable(error: any): boolean {
+  /**
+   * Determine if an error is likely retriable
+   * @param error - The error to check
+   */
+  private static isRetriable(error: ErrorLike | Error | string): boolean {
     try {
-      const code = (error?.code || '').toString().toUpperCase();
-      const msg = (error?.message || String(error) || '').toLowerCase();
-      const status = Number((error?.response?.status));
-      if (['ECONNRESET','ECONNREFUSED','ETIMEDOUT','EPIPE'].includes(code)) return true;
+      const errorObj = typeof error === 'object' ? error as ErrorLike : null;
+      const code = (errorObj?.code || '').toString().toUpperCase();
+      const msg = (errorObj?.message || String(error) || '').toLowerCase();
+      const status = Number(errorObj?.response?.status);
+      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 { }
     return false;
   }
 
   /**
    * Retry a function with exponential backoff
+   * @param fn - The async function to retry
+   * @param options - Retry configuration options
    */
   static async retryWithBackoff<T>(
     fn: () => Promise<T>,
@@ -173,14 +256,14 @@ export class ErrorHandler {
       initialDelay?: number;
       maxDelay?: number;
       backoffMultiplier?: number;
-      shouldRetry?: (error: any) => boolean;
+      shouldRetry?: (error: ErrorLike | Error | unknown) => boolean;
     } = {}
   ): Promise<T> {
     const maxRetries = options.maxRetries ?? 3;
     const initialDelay = options.initialDelay ?? 1000;
     const maxDelay = options.maxDelay ?? 10000;
     const multiplier = options.backoffMultiplier ?? 2;
-    const shouldRetry = options.shouldRetry ?? ((err) => this.isRetriable(err));
+    const shouldRetry = options.shouldRetry ?? ((err: unknown) => this.isRetriable(err as ErrorLike));
 
     let delay = initialDelay;
 
@@ -191,7 +274,7 @@ export class ErrorHandler {
         if (attempt === maxRetries || !shouldRetry(error)) {
           throw error;
         }
-        
+
         await new Promise(resolve => setTimeout(resolve, delay));
         delay = Math.min(delay * multiplier, maxDelay);
       }

package/src/utils/normalize.ts

@@ -4,47 +4,66 @@ export interface Rot3Obj { pitch: number; yaw: number; roll: number; }
 export type Vec3Tuple = [number, number, number];
 export type Rot3Tuple = [number, number, number];
 
-export function toVec3Object(input: any): Vec3Obj | null {
+/** Input that may represent a 3D vector */
+type VectorInput = Vec3Obj | Vec3Tuple | Record<string, unknown> | unknown[];
+
+/** Input that may represent a 3D rotation */
+type RotationInput = Rot3Obj | Rot3Tuple | Record<string, unknown> | unknown[];
+
+/**
+ * Convert various input formats to a Vec3 object
+ * @param input - Array, object with x/y/z or X/Y/Z properties
+ */
+export function toVec3Object(input: VectorInput | unknown): Vec3Obj | null {
   try {
     if (Array.isArray(input) && input.length === 3) {
       const [x, y, z] = input;
       if ([x, y, z].every(v => typeof v === 'number' && isFinite(v))) {
-        return { x, y, z };
+        return { x: x as number, y: y as number, z: z as number };
       }
     }
-    if (input && typeof input === 'object') {
-      const x = Number((input as any).x ?? (input as any).X);
-      const y = Number((input as any).y ?? (input as any).Y);
-      const z = Number((input as any).z ?? (input as any).Z);
+    if (input && typeof input === 'object' && !Array.isArray(input)) {
+      const obj = input as Record<string, unknown>;
+      const x = Number(obj.x ?? obj.X);
+      const y = Number(obj.y ?? obj.Y);
+      const z = Number(obj.z ?? obj.Z);
       if ([x, y, z].every(v => typeof v === 'number' && !isNaN(v) && isFinite(v))) {
         return { x, y, z };
       }
     }
-  } catch {}
+  } catch { }
   return null;
 }
 
-export function toRotObject(input: any): Rot3Obj | null {
+/**
+ * Convert various input formats to a Rotation object
+ * @param input - Array, object with pitch/yaw/roll or Pitch/Yaw/Roll properties
+ */
+export function toRotObject(input: RotationInput | unknown): Rot3Obj | null {
   try {
     if (Array.isArray(input) && input.length === 3) {
       const [pitch, yaw, roll] = input;
       if ([pitch, yaw, roll].every(v => typeof v === 'number' && isFinite(v))) {
-        return { pitch, yaw, roll };
+        return { pitch: pitch as number, yaw: yaw as number, roll: roll as number };
       }
     }
-    if (input && typeof input === 'object') {
-      const pitch = Number((input as any).pitch ?? (input as any).Pitch);
-      const yaw = Number((input as any).yaw ?? (input as any).Yaw);
-      const roll = Number((input as any).roll ?? (input as any).Roll);
+    if (input && typeof input === 'object' && !Array.isArray(input)) {
+      const obj = input as Record<string, unknown>;
+      const pitch = Number(obj.pitch ?? obj.Pitch);
+      const yaw = Number(obj.yaw ?? obj.Yaw);
+      const roll = Number(obj.roll ?? obj.Roll);
       if ([pitch, yaw, roll].every(v => typeof v === 'number' && !isNaN(v) && isFinite(v))) {
         return { pitch, yaw, roll };
       }
     }
-  } catch {}
+  } catch { }
   return null;
 }
 
-export function toVec3Tuple(input: any): Vec3Tuple | null {
+/**
+ * Convert vector input to a tuple format [x, y, z]
+ */
+export function toVec3Tuple(input: VectorInput | unknown): Vec3Tuple | null {
   const vec = toVec3Object(input);
   if (!vec) {
     return null;
@@ -53,7 +72,10 @@ export function toVec3Tuple(input: any): Vec3Tuple | null {
   return [x, y, z];
 }
 
-export function toRotTuple(input: any): Rot3Tuple | null {
+/**
+ * Convert rotation input to a tuple format [pitch, yaw, roll]
+ */
+export function toRotTuple(input: RotationInput | unknown): Rot3Tuple | null {
   const rot = toRotObject(input);
   if (!rot) {
     return null;