unreal-engine-mcp-server 0.4.4 → 0.4.5

package/dist/unreal-bridge.js

@@ -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';
 export class UnrealBridge {
     ws;
     http = createHttpClient('');
@@ -15,6 +16,11 @@ export class UnrealBridge {
     autoReconnectEnabled = false; // disabled by default to prevent looping retries
     engineVersionCache;
     ENGINE_VERSION_TTL_MS = 5 * 60 * 1000;
+    // WebSocket health monitoring (best practice from WebSocket optimization guides)
+    lastPongReceived = 0;
+    pingInterval;
+    PING_INTERVAL_MS = 30000; // 30 seconds
+    PONG_TIMEOUT_MS = 10000; // 10 seconds
     // Command queue for throttling
     commandQueue = [];
     isProcessing = false;
@@ -289,11 +295,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
      */
     connectPromise;
     async tryConnect(maxAttempts = 3, timeoutMs = 5000, retryDelayMs = 2000) {
@@ -308,39 +315,22 @@ 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) {
-                    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?.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/dist/utils/error-handler.d.ts

@@ -29,5 +29,45 @@ export declare class ErrorHandler {
     private static getUserFriendlyMessage;
     /** Determine if an error is likely retriable */
     private static isRetriable;
+    /**
+     * 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 retryWithBackoff<T>(operation: () => Promise<T>, options?: {
+        maxRetries?: number;
+        initialDelay?: number;
+        maxDelay?: number;
+        backoffMultiplier?: number;
+        shouldRetry?: (error: unknown) => boolean;
+    }): Promise<T>;
+    /**
+     * 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 withTimeout<T>(promise: Promise<T>, timeoutMs: number, errorMessage?: string): Promise<T>;
+    /**
+     * 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 batchExecute<T>(operations: Array<() => Promise<T>>): Promise<{
+        successful: Array<{
+            index: number;
+            value: T;
+        }>;
+        failed: Array<{
+            index: number;
+            reason: unknown;
+        }>;
+        successCount: number;
+        failureCount: number;
+    }>;
 }
 //# sourceMappingURL=error-handler.d.ts.map

package/dist/utils/error-handler.js

@@ -132,5 +132,80 @@ 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(operation, options = {}) {
+        const { maxRetries = 3, initialDelay = 100, maxDelay = 10000, backoffMultiplier = 2, shouldRetry = (error) => this.isRetriable(error) } = options;
+        let lastError;
+        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(promise, timeoutMs, errorMessage = 'Operation timed out') {
+        let timeoutHandle;
+        const timeoutPromise = new Promise((_, 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(operations) {
+        const results = await Promise.allSettled(operations.map(op => op()));
+        const successful = [];
+        const failed = [];
+        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
+        };
+    }
 }
 //# sourceMappingURL=error-handler.js.map

package/dist/utils/http.js

@@ -2,6 +2,42 @@ import axios from 'axios';
 import http from 'http';
 import https from 'https';
 import { Logger } from './logger.js';
+class SimpleCache {
+    cache = new Map();
+    maxSize = 100;
+    set(key, data, ttl = 60000) {
+        // 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) {
+        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() {
+        this.cache.clear();
+    }
+    getStats() {
+        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,
@@ -49,22 +85,63 @@ export function createHttpClient(baseURL) {
         maxBodyLength: 50 * 1024 * 1024,
         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.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.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.cached) {
+            return Promise.resolve({
+                ...response,
+                data: response.config.cached,
+                status: 200,
+                statusText: 'OK (Cached)',
+                headers: {},
+                config: response.config
+            });
+        }
+        // Performance tracking
         const duration = Date.now() - (response.config.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?.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);
     });
     return client;

package/dist/utils/response-validator.js

@@ -7,10 +7,15 @@ const log = new Logger('ResponseValidator');
  * 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.
     ajv;
     validators = 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 = Ajv?.default ?? Ajv;
+        this.ajv = new AjvCtor({
             allErrors: true,
             verbose: true,
             strict: false // Allow additional properties for flexibility