unreal-engine-mcp-server 0.4.3 → 0.4.5

package/src/unreal-bridge.ts

@@ -2,6 +2,7 @@ import WebSocket from 'ws';
 import { createHttpClient } from './utils/http.js';
 import { Logger } from './utils/logger.js';
 import { loadEnv } from './types/env.js';
+import { ErrorHandler } from './utils/error-handler.js';
 
 // RcMessage interface reserved for future WebSocket message handling
 // interface RcMessage {
@@ -44,6 +45,12 @@ export class UnrealBridge {
   private engineVersionCache?: { value: { version: string; major: number; minor: number; patch: number; isUE56OrAbove: boolean }; timestamp: number };
   private readonly ENGINE_VERSION_TTL_MS = 5 * 60 * 1000;
   
+  // WebSocket health monitoring (best practice from WebSocket optimization guides)
+  private lastPongReceived = 0;
+  private pingInterval?: NodeJS.Timeout;
+  private readonly PING_INTERVAL_MS = 30000; // 30 seconds
+  private readonly PONG_TIMEOUT_MS = 10000; // 10 seconds
+  
   // Command queue for throttling
   private commandQueue: CommandQueueItem[] = [];
   private isProcessing = false;
@@ -323,11 +330,12 @@ except Exception as e:
   get isConnected() { return this.connected; }
   
   /**
-   * Attempt to connect with retries
+   * Attempt to connect with exponential backoff retry strategy
+   * Uses optimized retry pattern from TypeScript best practices
    * @param maxAttempts Maximum number of connection attempts
    * @param timeoutMs Timeout for each connection attempt in milliseconds
-   * @param retryDelayMs Delay between retry attempts in milliseconds
-   * @returns Promise that resolves when connected or rejects after all attempts fail
+   * @param retryDelayMs Initial delay between retry attempts in milliseconds
+   * @returns Promise that resolves to true if connected, false otherwise
    */
   private connectPromise?: Promise<void>;
 
@@ -343,36 +351,25 @@ except Exception as e:
       return this.connected;
     }
 
-    this.connectPromise = (async () => {
-      for (let attempt = 1; attempt <= maxAttempts; attempt++) {
-        // Early exit if another concurrent attempt already connected
-        if (this.connected) {
-          this.log.debug('Already connected; skipping remaining retry attempts');
-          return;
-        }
-        try {
-          this.log.debug(`Connection attempt ${attempt}/${maxAttempts}`);
-          await this.connect(timeoutMs);
-          return; // Successfully connected
-        } catch (err: any) {
-          const msg = (err?.message || String(err));
-          this.log.debug(`Connection attempt ${attempt} failed: ${msg}`);
-          if (attempt < maxAttempts) {
-            this.log.debug(`Retrying in ${retryDelayMs}ms...`);
-            // Sleep, but allow early break if we became connected during the wait
-            const start = Date.now();
-            while (Date.now() - start < retryDelayMs) {
-              if (this.connected) return; // someone else connected
-              await new Promise(r => setTimeout(r, 50));
-            }
-          } else {
-            // Keep this at warn (not error) and avoid stack spam
-            this.log.warn(`All ${maxAttempts} connection attempts failed`);
-            return; // exit, connected remains false
-          }
+    // Use ErrorHandler's retryWithBackoff for consistent retry behavior
+    this.connectPromise = ErrorHandler.retryWithBackoff(
+      () => this.connect(timeoutMs),
+      {
+        maxRetries: maxAttempts - 1,
+        initialDelay: retryDelayMs,
+        maxDelay: 10000,
+        backoffMultiplier: 1.5,
+        shouldRetry: (error) => {
+          // Only retry on connection-related errors
+          const msg = (error as Error)?.message?.toLowerCase() || '';
+          return msg.includes('timeout') || msg.includes('connection') || msg.includes('econnrefused');
         }
       }
-    })();
+    ).then(() => {
+      // Success
+    }).catch((err) => {
+      this.log.warn(`Connection failed after ${maxAttempts} attempts:`, err.message);
+    });
 
     try {
       await this.connectPromise;

package/src/utils/error-handler.ts

@@ -162,4 +162,116 @@ export class ErrorHandler {
     } catch {}
     return false;
   }
-}
+
+  /**
+   * Retry an async operation with exponential backoff
+   * Best practice from TypeScript async programming patterns
+   * @param operation - Async operation to retry
+   * @param options - Retry configuration
+   * @returns Result of the operation
+   */
+  static async retryWithBackoff<T>(
+    operation: () => Promise<T>,
+    options: {
+      maxRetries?: number;
+      initialDelay?: number;
+      maxDelay?: number;
+      backoffMultiplier?: number;
+      shouldRetry?: (error: unknown) => boolean;
+    } = {}
+  ): Promise<T> {
+    const {
+      maxRetries = 3,
+      initialDelay = 100,
+      maxDelay = 10000,
+      backoffMultiplier = 2,
+      shouldRetry = (error) => this.isRetriable(error)
+    } = options;
+
+    let lastError: unknown;
+    let delay = initialDelay;
+
+    for (let attempt = 0; attempt <= maxRetries; attempt++) {
+      try {
+        return await operation();
+      } catch (error) {
+        lastError = error;
+
+        if (attempt === maxRetries || !shouldRetry(error)) {
+          throw error;
+        }
+
+        log.debug(`Retry attempt ${attempt + 1}/${maxRetries} after ${delay}ms`);
+        await new Promise(resolve => setTimeout(resolve, delay));
+
+        delay = Math.min(delay * backoffMultiplier, maxDelay);
+      }
+    }
+
+    throw lastError;
+  }
+
+  /**
+   * Add timeout to any promise
+   * @param promise - Promise to add timeout to
+   * @param timeoutMs - Timeout in milliseconds
+   * @param errorMessage - Custom error message for timeout
+   * @returns Promise that rejects on timeout
+   */
+  static async withTimeout<T>(
+    promise: Promise<T>,
+    timeoutMs: number,
+    errorMessage = 'Operation timed out'
+  ): Promise<T> {
+    let timeoutHandle: NodeJS.Timeout | undefined;
+
+    const timeoutPromise = new Promise<never>((_, reject) => {
+      timeoutHandle = setTimeout(() => {
+        reject(new Error(errorMessage));
+      }, timeoutMs);
+    });
+
+    try {
+      return await Promise.race([promise, timeoutPromise]);
+    } finally {
+      if (timeoutHandle !== undefined) {
+        clearTimeout(timeoutHandle);
+      }
+    }
+  }
+
+  /**
+   * Execute multiple operations with Promise.allSettled for better error handling
+   * Returns detailed results for each operation, including failures
+   * @param operations - Array of async operations to execute
+   * @returns Object with successful and failed operations separated
+   */
+  static async batchExecute<T>(
+    operations: Array<() => Promise<T>>
+  ): Promise<{
+    successful: Array<{ index: number; value: T }>;
+    failed: Array<{ index: number; reason: unknown }>;
+    successCount: number;
+    failureCount: number;
+  }> {
+    const results = await Promise.allSettled(operations.map(op => op()));
+
+    const successful: Array<{ index: number; value: T }> = [];
+    const failed: Array<{ index: number; reason: unknown }> = [];
+
+    results.forEach((result, index) => {
+      if (result.status === 'fulfilled') {
+        successful.push({ index, value: result.value });
+      } else {
+        failed.push({ index, reason: result.reason });
+      }
+    });
+
+    return {
+      successful,
+      failed,
+      successCount: successful.length,
+      failureCount: failed.length
+    };
+  }
+}

package/src/utils/http.ts

@@ -3,6 +3,60 @@ import http from 'http';
 import https from 'https';
 import { Logger } from './logger.js';
 
+/**
+ * Simple in-memory cache for HTTP responses
+ * Based on best practices from Axios optimization guides
+ */
+interface CacheEntry {
+  data: any;
+  timestamp: number;
+  ttl: number;
+}
+
+class SimpleCache {
+  private cache = new Map<string, CacheEntry>();
+  private readonly maxSize = 100;
+
+  set(key: string, data: any, ttl: number = 60000): void {
+    // Prevent unbounded growth
+    if (this.cache.size >= this.maxSize) {
+      const firstKey = this.cache.keys().next().value;
+      if (firstKey !== undefined) {
+        this.cache.delete(firstKey);
+      }
+    }
+    
+    this.cache.set(key, {
+      data,
+      timestamp: Date.now(),
+      ttl
+    });
+  }
+
+  get(key: string): any | null {
+    const entry = this.cache.get(key);
+    if (!entry) return null;
+
+    // Check if expired
+    if (Date.now() - entry.timestamp > entry.ttl) {
+      this.cache.delete(key);
+      return null;
+    }
+
+    return entry.data;
+  }
+
+  clear(): void {
+    this.cache.clear();
+  }
+
+  getStats(): { size: number; maxSize: number } {
+    return { size: this.cache.size, maxSize: this.maxSize };
+  }
+}
+
+const responseCache = new SimpleCache();
+
 // Enhanced connection pooling configuration to prevent socket failures
 const httpAgent = new http.Agent({
   keepAlive: true,
@@ -55,28 +109,73 @@ export function createHttpClient(baseURL: string): AxiosInstance {
     decompress: true
   });
 
-  // Add request interceptor for timing
+  // Request interceptor: timing, caching check, and logging
   client.interceptors.request.use(
     (config) => {
       // Add metadata for performance tracking
       (config as any).metadata = { startTime: Date.now() };
+      
+      // Check cache for GET requests
+      if (config.method?.toLowerCase() === 'get' && config.url) {
+        const cacheKey = `${config.url}:${JSON.stringify(config.params || {})}`;
+        const cached = responseCache.get(cacheKey);
+        if (cached) {
+          log.debug(`[HTTP Cache Hit] ${config.url}`);
+          // Return cached response
+          (config as any).cached = cached;
+        }
+      }
+      
       return config;
     },
     (error) => {
+      log.error('[HTTP Request Error]', error);
       return Promise.reject(error);
     }
   );
 
-  // Add response interceptor for timing and logging
+  // Response interceptor: timing, caching, and error handling
   client.interceptors.response.use(
     (response) => {
+      // Check if we used cached response
+      if ((response.config as any).cached) {
+        return Promise.resolve({
+          ...response,
+          data: (response.config as any).cached,
+          status: 200,
+          statusText: 'OK (Cached)',
+          headers: {},
+          config: response.config
+        });
+      }
+
+      // Performance tracking
       const duration = Date.now() - ((response.config as any).metadata?.startTime || 0);
       if (duration > 5000) {
-        log.warn(`[HTTP] Slow request: ${response.config.url} took ${duration}ms`);
+        log.warn(`[HTTP Slow] ${response.config.url} took ${duration}ms`);
+      } else if (duration > 1000) {
+        log.debug(`[HTTP] ${response.config.url} took ${duration}ms`);
       }
+
+      // Cache successful GET responses
+      if (response.config.method?.toLowerCase() === 'get' && 
+          response.status === 200 && 
+          response.config.url) {
+        const cacheKey = `${response.config.url}:${JSON.stringify(response.config.params || {})}`;
+        // Cache for 30 seconds by default
+        responseCache.set(cacheKey, response.data, 30000);
+      }
+
       return response;
     },
     (error) => {
+      // Enhanced error logging
+      const duration = Date.now() - ((error.config as any)?.metadata?.startTime || 0);
+      log.error(`[HTTP Error] ${error.config?.url} failed after ${duration}ms:`, {
+        status: error.response?.status,
+        message: error.message,
+        code: error.code
+      });
       return Promise.reject(error);
     }
   );

package/src/utils/response-validator.ts

@@ -9,11 +9,16 @@ const log = new Logger('ResponseValidator');
  * Validates tool responses against their defined output schemas
  */
 export class ResponseValidator {
-  private ajv: Ajv;
+  // 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();
 
   constructor() {
-    this.ajv = new Ajv({
+    // 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({
       allErrors: true,
       verbose: true,
       strict: false // Allow additional properties for flexibility

package/tsconfig.json

@@ -1,26 +1,49 @@
 {
   "compilerOptions": {
-    "target": "ES2022",
-    "module": "ES2022",
-    "moduleResolution": "Bundler",
+  "target": "ES2022",
+  "module": "NodeNext",
+  "moduleResolution": "NodeNext",
     "outDir": "dist",
     "rootDir": "src",
+    
+    // Strict Type Checking
     "strict": true,
+    "noImplicitAny": true,
+    "strictNullChecks": true,
+    "strictFunctionTypes": true,
+    "strictBindCallApply": true,
+    "strictPropertyInitialization": true,
+    "noImplicitThis": true,
+    "alwaysStrict": true,
+    
+    // Additional Checks
+    "noUnusedLocals": false,
+    "noUnusedParameters": false,
+    "noImplicitReturns": true,
+    "noFallthroughCasesInSwitch": true,
+    "allowUnreachableCode": false,
+    "noUncheckedIndexedAccess": false,
+    
+    // Module & Interop
     "esModuleInterop": true,
+    "allowSyntheticDefaultImports": true,
     "forceConsistentCasingInFileNames": true,
-    "skipLibCheck": true,
+    "resolveJsonModule": true,
+    
+    // Emit
     "declaration": true,
     "declarationMap": true,
     "sourceMap": true,
-    "resolveJsonModule": true,
-    "incremental": true,
-    "tsBuildInfoFile": ".tsbuildinfo",
-  "noUnusedLocals": false,
-  "noUnusedParameters": false,
-    "noImplicitReturns": true,
-    "noFallthroughCasesInSwitch": true,
-    "allowUnreachableCode": false,
-    "types": ["node"]
+    "removeComments": false,
+    "importHelpers": false,
+    "emitDeclarationOnly": false,
+    
+    // Performance
+    "skipLibCheck": true,
+  "incremental": false,
+    
+    "types": ["node"],
+    "noEmitOnError": false
   },
   "include": ["src/**/*"],
   "exclude": [