unreal-engine-mcp-server 0.2.1

package/src/utils/cache-manager.ts

@@ -0,0 +1,213 @@
+/**
+ * Cache Manager for API responses
+ * Implements LRU cache with TTL support for optimizing repeated API calls
+ */
+
+interface CacheEntry<T> {
+  data: T;
+  timestamp: number;
+  hits: number;
+}
+
+interface CacheOptions {
+  maxSize?: number;
+  defaultTTL?: number; // in milliseconds
+  enableMetrics?: boolean;
+}
+
+interface CacheMetrics {
+  hits: number;
+  misses: number;
+  evictions: number;
+  size: number;
+}
+
+export class CacheManager<T = any> {
+  private cache: Map<string, CacheEntry<T>>;
+  private readonly maxSize: number;
+  private readonly defaultTTL: number;
+  private readonly enableMetrics: boolean;
+  private metrics: CacheMetrics;
+
+  constructor(options: CacheOptions = {}) {
+    this.cache = new Map();
+    this.maxSize = options.maxSize || 100;
+    this.defaultTTL = options.defaultTTL || 60000; // 1 minute default
+    this.enableMetrics = options.enableMetrics || false;
+    this.metrics = {
+      hits: 0,
+      misses: 0,
+      evictions: 0,
+      size: 0
+    };
+  }
+
+  /**
+   * Get item from cache
+   */
+  get(key: string): T | null {
+    const entry = this.cache.get(key);
+    
+    if (!entry) {
+      if (this.enableMetrics) this.metrics.misses++;
+      return null;
+    }
+
+    // Check if expired
+    if (Date.now() - entry.timestamp > this.defaultTTL) {
+      this.cache.delete(key);
+      if (this.enableMetrics) {
+        this.metrics.misses++;
+        this.metrics.size--;
+      }
+      return null;
+    }
+
+    // Update hit count and move to end (LRU)
+    entry.hits++;
+    this.cache.delete(key);
+    this.cache.set(key, entry);
+    
+    if (this.enableMetrics) this.metrics.hits++;
+    return entry.data;
+  }
+
+  /**
+   * Set item in cache
+   */
+  set(key: string, data: T): void {
+    // Evict oldest if at max size
+    if (this.cache.size >= this.maxSize && !this.cache.has(key)) {
+      const firstKey = this.cache.keys().next().value;
+      if (firstKey) {
+        this.cache.delete(firstKey);
+        if (this.enableMetrics) {
+          this.metrics.evictions++;
+          this.metrics.size--;
+        }
+      }
+    }
+
+    const entry: CacheEntry<T> = {
+      data,
+      timestamp: Date.now(),
+      hits: 0
+    };
+
+    this.cache.set(key, entry);
+    if (this.enableMetrics) this.metrics.size = this.cache.size;
+  }
+
+  /**
+   * Check if key exists and is valid
+   */
+  has(key: string): boolean {
+    const entry = this.cache.get(key);
+    if (!entry) return false;
+    
+    // Check expiration
+    if (Date.now() - entry.timestamp > this.defaultTTL) {
+      this.cache.delete(key);
+      if (this.enableMetrics) this.metrics.size--;
+      return false;
+    }
+    
+    return true;
+  }
+
+  /**
+   * Clear specific key or all cache
+   */
+  clear(key?: string): void {
+    if (key) {
+      this.cache.delete(key);
+      if (this.enableMetrics) this.metrics.size = this.cache.size;
+    } else {
+      this.cache.clear();
+      if (this.enableMetrics) {
+        this.metrics.size = 0;
+      }
+    }
+  }
+
+  /**
+   * Get cache metrics
+   */
+  getMetrics(): CacheMetrics {
+    return { ...this.metrics };
+  }
+
+  /**
+   * Get cache hit rate
+   */
+  getHitRate(): number {
+    const total = this.metrics.hits + this.metrics.misses;
+    return total > 0 ? this.metrics.hits / total : 0;
+  }
+
+  /**
+   * Wrap async function with cache
+   */
+  async wrap<R = T>(
+    key: string,
+    fn: () => Promise<R>
+  ): Promise<R> {
+    // Check cache first
+    const cached = this.get(key) as R | null;
+    if (cached !== null) {
+      return cached;
+    }
+
+    // Execute function and cache result
+    const result = await fn();
+    this.set(key, result as any);
+    return result;
+  }
+
+  /**
+   * Batch get multiple keys
+   */
+  getBatch(keys: string[]): Map<string, T | null> {
+    const results = new Map<string, T | null>();
+    for (const key of keys) {
+      results.set(key, this.get(key));
+    }
+    return results;
+  }
+
+  /**
+   * Invalidate cache entries by pattern
+   */
+  invalidatePattern(pattern: RegExp): number {
+    let count = 0;
+    for (const key of this.cache.keys()) {
+      if (pattern.test(key)) {
+        this.cache.delete(key);
+        count++;
+      }
+    }
+    if (this.enableMetrics) {
+      this.metrics.size = this.cache.size;
+    }
+    return count;
+  }
+}
+
+// Global cache instances for different purposes
+export const assetCache = new CacheManager({
+  maxSize: 500,
+  defaultTTL: 300000, // 5 minutes for assets
+  enableMetrics: true
+});
+
+export const engineCache = new CacheManager({
+  maxSize: 50,
+  defaultTTL: 600000, // 10 minutes for engine info
+  enableMetrics: true
+});
+
+export const commandCache = new CacheManager({
+  maxSize: 100,
+  defaultTTL: 30000, // 30 seconds for commands
+  enableMetrics: true
+});

package/src/utils/error-handler.ts

@@ -0,0 +1,320 @@
+import { Logger } from './logger.js';
+import { BaseToolResponse } from '../types/tool-types.js';
+
+const log = new Logger('ErrorHandler');
+
+/**
+ * Error types for categorization
+ */
+export enum ErrorType {
+  VALIDATION = 'VALIDATION',
+  CONNECTION = 'CONNECTION',
+  UNREAL_ENGINE = 'UNREAL_ENGINE',
+  PARAMETER = 'PARAMETER',
+  EXECUTION = 'EXECUTION',
+  TIMEOUT = 'TIMEOUT',
+  UNKNOWN = 'UNKNOWN'
+}
+
+/**
+ * Custom error class for MCP tools
+ */
+export class ToolError extends Error {
+  constructor(
+    public type: ErrorType,
+    public toolName: string,
+    message: string,
+    public originalError?: any
+  ) {
+    super(message);
+    this.name = 'ToolError';
+  }
+}
+
+/**
+ * Consistent error handling for all tools
+ */
+export class ErrorHandler {
+  /**
+   * Create a standardized error response
+   */
+  static createErrorResponse(
+    error: any,
+    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}`;
+    
+    log.error(`Tool ${toolName} failed:`, {
+      type: errorType,
+      message: error.message || error,
+      retriable,
+      scope,
+      context
+    });
+
+    return {
+      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;
+  }
+
+  /**
+   * Create a standardized warning response
+   */
+  static createWarningResponse(
+    message: string,
+    result: any,
+    toolName: string
+  ): BaseToolResponse {
+    log.warn(`Tool ${toolName} warning: ${message}`);
+    
+    return {
+      success: true,
+      warning: message,
+      message: `${toolName} completed with warnings`,
+      ...result
+    };
+  }
+
+  /**
+   * Create a standardized success response
+   */
+  static createSuccessResponse(
+    message: string,
+    data: any = {}
+  ): BaseToolResponse {
+    return {
+      success: true,
+      message,
+      ...data
+    };
+  }
+
+  /**
+   * Categorize error by type
+   */
+  private static categorizeError(error: any): ErrorType {
+    if (error instanceof ToolError) {
+      return error.type;
+    }
+
+    const errorMessage = error.message?.toLowerCase() || String(error).toLowerCase();
+
+    // Connection errors
+    if (
+      errorMessage.includes('econnrefused') ||
+      errorMessage.includes('timeout') ||
+      errorMessage.includes('connection') ||
+      errorMessage.includes('network')
+    ) {
+      return ErrorType.CONNECTION;
+    }
+
+    // Validation errors
+    if (
+      errorMessage.includes('invalid') ||
+      errorMessage.includes('required') ||
+      errorMessage.includes('must be') ||
+      errorMessage.includes('validation')
+    ) {
+      return ErrorType.VALIDATION;
+    }
+
+    // Unreal Engine specific errors
+    if (
+      errorMessage.includes('unreal') ||
+      errorMessage.includes('remote control') ||
+      errorMessage.includes('blueprint') ||
+      errorMessage.includes('actor') ||
+      errorMessage.includes('asset')
+    ) {
+      return ErrorType.UNREAL_ENGINE;
+    }
+
+    // Parameter errors
+    if (
+      errorMessage.includes('parameter') ||
+      errorMessage.includes('argument') ||
+      errorMessage.includes('missing')
+    ) {
+      return ErrorType.PARAMETER;
+    }
+
+    // Timeout errors
+    if (errorMessage.includes('timeout')) {
+      return ErrorType.TIMEOUT;
+    }
+
+    return ErrorType.UNKNOWN;
+  }
+
+  /**
+   * Get user-friendly error message
+   */
+  private static getUserFriendlyMessage(type: ErrorType, error: any): string {
+    const originalMessage = error.message || String(error);
+
+    switch (type) {
+      case ErrorType.CONNECTION:
+        return 'Failed to connect to Unreal Engine. Please ensure Remote Control is enabled and the engine 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 {
+    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;
+      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 {}
+    return false;
+  }
+
+  /**
+   * Wrap async function with error handling
+   */
+  static async wrapAsync<T extends BaseToolResponse>(
+    toolName: string,
+    fn: () => Promise<T>,
+    context?: any
+  ): Promise<T> {
+    try {
+      const result = await fn();
+      
+      // Ensure result has success field
+      if (typeof result === 'object' && result !== null) {
+        if (!('success' in result)) {
+          (result as any).success = true;
+        }
+      }
+      
+      return result;
+    } catch (error) {
+      return this.createErrorResponse(error, toolName, context) as T;
+    }
+  }
+
+  /**
+   * Validate required parameters
+   */
+  static validateParams(
+    params: any,
+    required: string[],
+    toolName: string
+  ): void {
+    if (!params || typeof params !== 'object') {
+      throw new ToolError(
+        ErrorType.PARAMETER,
+        toolName,
+        'Invalid parameters: expected object'
+      );
+    }
+
+    for (const field of required) {
+      if (!(field in params) || params[field] === undefined || params[field] === null) {
+        throw new ToolError(
+          ErrorType.PARAMETER,
+          toolName,
+          `Missing required parameter: ${field}`
+        );
+      }
+
+      // Additional validation for common types
+      if (field.includes('Path') || field.includes('Name')) {
+        if (typeof params[field] !== 'string' || params[field].trim() === '') {
+          throw new ToolError(
+            ErrorType.PARAMETER,
+            toolName,
+            `Invalid ${field}: must be a non-empty string`
+          );
+        }
+      }
+    }
+  }
+
+  /**
+   * Handle Unreal Engine specific errors
+   */
+  static handleUnrealError(error: any, operation: string): string {
+    const errorStr = String(error.message || error).toLowerCase();
+
+    // Common Unreal errors
+    if (errorStr.includes('worldcontext')) {
+      return `${operation} completed (WorldContext warnings are normal)`;
+    }
+    
+    if (errorStr.includes('does not exist')) {
+      return `Asset or object not found for ${operation}`;
+    }
+    
+    if (errorStr.includes('access denied') || errorStr.includes('read-only')) {
+      return `Permission denied for ${operation}. Check file permissions.`;
+    }
+    
+    if (errorStr.includes('already exists')) {
+      return `Object already exists for ${operation}`;
+    }
+
+    return `Unreal Engine error during ${operation}: ${error.message || error}`;
+  }
+
+  /**
+   * Create operation result with consistent structure
+   */
+  static createResult<T extends BaseToolResponse>(
+    success: boolean,
+    message: string,
+    data?: Partial<T>
+  ): T {
+    const result: BaseToolResponse = {
+      success,
+      message,
+      ...(data || {})
+    };
+
+    if (!success && !result.error) {
+      result.error = message;
+    }
+
+    return result as T;
+  }
+}