unreal-engine-mcp-server 0.5.0 → 0.5.2

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.test.ts

@@ -0,0 +1,162 @@
+/**
+ * Unit tests for normalize utility functions
+ */
+import { describe, it, expect } from 'vitest';
+import {
+    toVec3Object,
+    toRotObject,
+    toVec3Tuple,
+    toRotTuple,
+    toFiniteNumber,
+    normalizePartialVector,
+    normalizeTransformInput
+} from './normalize.js';
+
+describe('toVec3Object', () => {
+    it('converts object input to Vector3', () => {
+        const result = toVec3Object({ x: 1, y: 2, z: 3 });
+        expect(result).toEqual({ x: 1, y: 2, z: 3 });
+    });
+
+    it('converts array input to Vector3', () => {
+        const result = toVec3Object([1, 2, 3]);
+        expect(result).toEqual({ x: 1, y: 2, z: 3 });
+    });
+
+    it('returns null for invalid input', () => {
+        expect(toVec3Object('invalid')).toBeNull();
+        expect(toVec3Object(null)).toBeNull();
+        expect(toVec3Object(undefined)).toBeNull();
+    });
+
+    it('returns null for incomplete object', () => {
+        expect(toVec3Object({ x: 1, y: 2 })).toBeNull();
+    });
+
+    it('handles zero values', () => {
+        const result = toVec3Object({ x: 0, y: 0, z: 0 });
+        expect(result).toEqual({ x: 0, y: 0, z: 0 });
+    });
+});
+
+describe('toRotObject', () => {
+    it('converts object input to Rotator', () => {
+        const result = toRotObject({ pitch: 10, yaw: 20, roll: 30 });
+        expect(result).toEqual({ pitch: 10, yaw: 20, roll: 30 });
+    });
+
+    it('converts array input to Rotator', () => {
+        const result = toRotObject([10, 20, 30]);
+        expect(result).toEqual({ pitch: 10, yaw: 20, roll: 30 });
+    });
+
+    it('returns null for invalid input', () => {
+        expect(toRotObject('invalid')).toBeNull();
+        expect(toRotObject(null)).toBeNull();
+    });
+});
+
+describe('toVec3Tuple', () => {
+    it('converts object to tuple', () => {
+        const result = toVec3Tuple({ x: 1, y: 2, z: 3 });
+        expect(result).toEqual([1, 2, 3]);
+    });
+
+    it('passes through valid array', () => {
+        const result = toVec3Tuple([1, 2, 3]);
+        expect(result).toEqual([1, 2, 3]);
+    });
+
+    it('returns null for invalid input', () => {
+        expect(toVec3Tuple([1, 2])).toBeNull();
+        expect(toVec3Tuple(null)).toBeNull();
+    });
+});
+
+describe('toRotTuple', () => {
+    it('converts object to tuple', () => {
+        const result = toRotTuple({ pitch: 10, yaw: 20, roll: 30 });
+        expect(result).toEqual([10, 20, 30]);
+    });
+
+    it('passes through valid array', () => {
+        const result = toRotTuple([10, 20, 30]);
+        expect(result).toEqual([10, 20, 30]);
+    });
+});
+
+describe('toFiniteNumber', () => {
+    it('accepts valid numbers', () => {
+        expect(toFiniteNumber(42)).toBe(42);
+        expect(toFiniteNumber(0)).toBe(0);
+        expect(toFiniteNumber(-5)).toBe(-5);
+        expect(toFiniteNumber(3.14)).toBe(3.14);
+    });
+
+    it('parses string numbers', () => {
+        expect(toFiniteNumber('42')).toBe(42);
+        expect(toFiniteNumber('3.14')).toBe(3.14);
+    });
+
+    it('returns undefined for invalid input', () => {
+        expect(toFiniteNumber('not a number')).toBeUndefined();
+        expect(toFiniteNumber(NaN)).toBeUndefined();
+        expect(toFiniteNumber(Infinity)).toBeUndefined();
+        expect(toFiniteNumber(null)).toBeUndefined();
+        expect(toFiniteNumber(undefined)).toBeUndefined();
+    });
+});
+
+describe('normalizePartialVector', () => {
+    it('normalizes complete vectors', () => {
+        const result = normalizePartialVector({ x: 1, y: 2, z: 3 });
+        expect(result).toEqual({ x: 1, y: 2, z: 3 });
+    });
+
+    it('handles partial vectors', () => {
+        const result = normalizePartialVector({ x: 1 });
+        expect(result).toBeDefined();
+        expect(result?.x).toBe(1);
+    });
+
+    it('uses alternate keys for reading input', () => {
+        const result = normalizePartialVector(
+            { pitch: 10, yaw: 20, roll: 30 },
+            ['pitch', 'yaw', 'roll']
+        );
+        // alternateKeys are used to READ from input, but output is still x/y/z
+        expect(result).toEqual({ x: 10, y: 20, z: 30 });
+    });
+
+    it('returns undefined for invalid input', () => {
+        expect(normalizePartialVector(null)).toBeUndefined();
+        expect(normalizePartialVector('string')).toBeUndefined();
+    });
+});
+
+describe('normalizeTransformInput', () => {
+    it('normalizes complete transform', () => {
+        const result = normalizeTransformInput({
+            location: { x: 0, y: 0, z: 100 },
+            rotation: { pitch: 0, yaw: 90, roll: 0 },
+            scale: { x: 1, y: 1, z: 1 }
+        });
+        expect(result).toBeDefined();
+        expect(result?.location).toBeDefined();
+        expect(result?.rotation).toBeDefined();
+        expect(result?.scale).toBeDefined();
+    });
+
+    it('handles partial transforms', () => {
+        const result = normalizeTransformInput({
+            location: { x: 100, y: 200, z: 300 }
+        });
+        expect(result).toBeDefined();
+        expect(result?.location).toBeDefined();
+    });
+
+    it('returns undefined for invalid input', () => {
+        expect(normalizeTransformInput(null)).toBeUndefined();
+        expect(normalizeTransformInput('invalid')).toBeUndefined();
+    });
+});

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;

package/src/utils/path-security.ts

@@ -0,0 +1,43 @@
+export function sanitizePath(path: string, allowedRoots: string[] = ['/Game', '/Engine']): string {
+    if (!path || typeof path !== 'string') {
+        throw new Error('Invalid path: must be a non-empty string');
+    }
+
+    const trimmed = path.trim();
+    if (trimmed.length === 0) {
+        throw new Error('Invalid path: cannot be empty');
+    }
+
+    // Normalize separators
+    const normalized = trimmed.replace(/\\/g, '/');
+
+    // Prevent directory traversal
+    if (normalized.includes('..')) {
+        throw new Error('Invalid path: directory traversal (..) is not allowed');
+    }
+
+    // Ensure path starts with a valid root
+    // We check case-insensitive for the root prefix to be user-friendly, 
+    // but Unreal paths are typically case-insensitive anyway.
+    const isAllowed = allowedRoots.some(root =>
+        normalized.toLowerCase() === root.toLowerCase() ||
+        normalized.toLowerCase().startsWith(`${root.toLowerCase()}/`)
+    );
+
+    if (!isAllowed) {
+        throw new Error(`Invalid path: must start with one of [${allowedRoots.join(', ')}]`);
+    }
+
+    // Basic character validation (Unreal strictness)
+    // Blocks: < > : " | ? * (Windows reserved) and control characters
+    // allowing spaces, dots, underscores, dashes, slashes
+    // Note: Unreal allows spaces in some contexts but it's often safer to restrict them if strict mode is desired.
+    // For now, we block the definitely invalid ones.
+    // eslint-disable-next-line no-control-regex
+    const invalidChars = /[<>:"|?*\x00-\x1f]/;
+    if (invalidChars.test(normalized)) {
+        throw new Error('Invalid path: contains illegal characters');
+    }
+
+    return normalized;
+}

package/src/utils/response-factory.ts

@@ -1,39 +1,44 @@
-import { CallToolResult } from '@modelcontextprotocol/sdk/types.js';
+import { StandardActionResponse } from '../types/tool-interfaces.js';
+import { cleanObject } from './safe-json.js';
 
 export class ResponseFactory {
-    static success(message: string, data?: unknown): CallToolResult {
-        const content: any[] = [{ type: 'text', text: message }];
-
-        if (data) {
-            content.push({
-                type: 'text',
-                text: JSON.stringify(data, null, 2)
-            });
-        }
-
+    /**
+     * Create a standard success response
+     */
+    static success(data: any, message: string = 'Operation successful'): StandardActionResponse {
         return {
-            content,
-            isError: false
+            success: true,
+            message,
+            data: cleanObject(data)
         };
     }
 
-    static error(message: string, error?: unknown): CallToolResult {
-        const errorText = error instanceof Error ? error.message : String(error);
-        const fullMessage = error ? `${message}: ${errorText}` : message;
+    /**
+     * Create a standard error response
+     * @param error The error object or message
+     * @param defaultMessage Fallback message if error is not an Error object
+     */
+    static error(error: any, defaultMessage: string = 'Operation failed'): StandardActionResponse {
+        const errorMessage = error instanceof Error ? error.message : String(error || defaultMessage);
+
+        // Log the full error for debugging (internal logs) but return a clean message to the client
+        console.error('[ResponseFactory] Error:', error);
 
         return {
-            content: [{ type: 'text', text: fullMessage }],
-            isError: true
+            success: false,
+            message: errorMessage,
+            data: null
         };
     }
 
-    static json(data: unknown): CallToolResult {
+    /**
+     * Create a validation error response
+     */
+    static validationError(message: string): StandardActionResponse {
         return {
-            content: [{
-                type: 'text',
-                text: JSON.stringify(data, null, 2)
-            }],
-            isError: false
+            success: false,
+            message: `Validation Error: ${message}`,
+            data: null
         };
     }
 }