unreal-engine-mcp-server 0.2.1

package/dist/utils/cache-manager.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Cache Manager for API responses
+ * Implements LRU cache with TTL support for optimizing repeated API calls
+ */
+interface CacheOptions {
+    maxSize?: number;
+    defaultTTL?: number;
+    enableMetrics?: boolean;
+}
+interface CacheMetrics {
+    hits: number;
+    misses: number;
+    evictions: number;
+    size: number;
+}
+export declare class CacheManager<T = any> {
+    private cache;
+    private readonly maxSize;
+    private readonly defaultTTL;
+    private readonly enableMetrics;
+    private metrics;
+    constructor(options?: CacheOptions);
+    /**
+     * Get item from cache
+     */
+    get(key: string): T | null;
+    /**
+     * Set item in cache
+     */
+    set(key: string, data: T): void;
+    /**
+     * Check if key exists and is valid
+     */
+    has(key: string): boolean;
+    /**
+     * Clear specific key or all cache
+     */
+    clear(key?: string): void;
+    /**
+     * Get cache metrics
+     */
+    getMetrics(): CacheMetrics;
+    /**
+     * Get cache hit rate
+     */
+    getHitRate(): number;
+    /**
+     * Wrap async function with cache
+     */
+    wrap<R = T>(key: string, fn: () => Promise<R>): Promise<R>;
+    /**
+     * Batch get multiple keys
+     */
+    getBatch(keys: string[]): Map<string, T | null>;
+    /**
+     * Invalidate cache entries by pattern
+     */
+    invalidatePattern(pattern: RegExp): number;
+}
+export declare const assetCache: CacheManager<any>;
+export declare const engineCache: CacheManager<any>;
+export declare const commandCache: CacheManager<any>;
+export {};
+//# sourceMappingURL=cache-manager.d.ts.map

package/dist/utils/cache-manager.js

@@ -0,0 +1,176 @@
+/**
+ * Cache Manager for API responses
+ * Implements LRU cache with TTL support for optimizing repeated API calls
+ */
+export class CacheManager {
+    cache;
+    maxSize;
+    defaultTTL;
+    enableMetrics;
+    metrics;
+    constructor(options = {}) {
+        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) {
+        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, data) {
+        // 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 = {
+            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) {
+        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) {
+        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() {
+        return { ...this.metrics };
+    }
+    /**
+     * Get cache hit rate
+     */
+    getHitRate() {
+        const total = this.metrics.hits + this.metrics.misses;
+        return total > 0 ? this.metrics.hits / total : 0;
+    }
+    /**
+     * Wrap async function with cache
+     */
+    async wrap(key, fn) {
+        // Check cache first
+        const cached = this.get(key);
+        if (cached !== null) {
+            return cached;
+        }
+        // Execute function and cache result
+        const result = await fn();
+        this.set(key, result);
+        return result;
+    }
+    /**
+     * Batch get multiple keys
+     */
+    getBatch(keys) {
+        const results = new Map();
+        for (const key of keys) {
+            results.set(key, this.get(key));
+        }
+        return results;
+    }
+    /**
+     * Invalidate cache entries by pattern
+     */
+    invalidatePattern(pattern) {
+        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
+});
+//# sourceMappingURL=cache-manager.js.map

package/dist/utils/error-handler.d.ts

@@ -0,0 +1,66 @@
+import { BaseToolResponse } from '../types/tool-types.js';
+/**
+ * Error types for categorization
+ */
+export declare 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 declare class ToolError extends Error {
+    type: ErrorType;
+    toolName: string;
+    originalError?: any | undefined;
+    constructor(type: ErrorType, toolName: string, message: string, originalError?: any | undefined);
+}
+/**
+ * Consistent error handling for all tools
+ */
+export declare class ErrorHandler {
+    /**
+     * Create a standardized error response
+     */
+    static createErrorResponse(error: any, toolName: string, context?: any): BaseToolResponse;
+    /**
+     * Create a standardized warning response
+     */
+    static createWarningResponse(message: string, result: any, toolName: string): BaseToolResponse;
+    /**
+     * Create a standardized success response
+     */
+    static createSuccessResponse(message: string, data?: any): BaseToolResponse;
+    /**
+     * Categorize error by type
+     */
+    private static categorizeError;
+    /**
+     * Get user-friendly error message
+     */
+    private static getUserFriendlyMessage;
+    /** Determine if an error is likely retriable */
+    private static isRetriable;
+    /**
+     * Wrap async function with error handling
+     */
+    static wrapAsync<T extends BaseToolResponse>(toolName: string, fn: () => Promise<T>, context?: any): Promise<T>;
+    /**
+     * Validate required parameters
+     */
+    static validateParams(params: any, required: string[], toolName: string): void;
+    /**
+     * Handle Unreal Engine specific errors
+     */
+    static handleUnrealError(error: any, operation: string): string;
+    /**
+     * Create operation result with consistent structure
+     */
+    static createResult<T extends BaseToolResponse>(success: boolean, message: string, data?: Partial<T>): T;
+}
+//# sourceMappingURL=error-handler.d.ts.map

package/dist/utils/error-handler.js

@@ -0,0 +1,243 @@
+import { Logger } from './logger.js';
+const log = new Logger('ErrorHandler');
+/**
+ * Error types for categorization
+ */
+export var ErrorType;
+(function (ErrorType) {
+    ErrorType["VALIDATION"] = "VALIDATION";
+    ErrorType["CONNECTION"] = "CONNECTION";
+    ErrorType["UNREAL_ENGINE"] = "UNREAL_ENGINE";
+    ErrorType["PARAMETER"] = "PARAMETER";
+    ErrorType["EXECUTION"] = "EXECUTION";
+    ErrorType["TIMEOUT"] = "TIMEOUT";
+    ErrorType["UNKNOWN"] = "UNKNOWN";
+})(ErrorType || (ErrorType = {}));
+/**
+ * Custom error class for MCP tools
+ */
+export class ToolError extends Error {
+    type;
+    toolName;
+    originalError;
+    constructor(type, toolName, message, originalError) {
+        super(message);
+        this.type = type;
+        this.toolName = toolName;
+        this.originalError = originalError;
+        this.name = 'ToolError';
+    }
+}
+/**
+ * Consistent error handling for all tools
+ */
+export class ErrorHandler {
+    /**
+     * Create a standardized error response
+     */
+    static createErrorResponse(error, toolName, context) {
+        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,
+            scope: scope,
+            // Add debug info in development
+            ...(process.env.NODE_ENV === 'development' && {
+                _debug: {
+                    errorType,
+                    originalError: error.message || String(error),
+                    stack: error.stack,
+                    context,
+                    retriable,
+                    scope
+                }
+            })
+        };
+    }
+    /**
+     * Create a standardized warning response
+     */
+    static createWarningResponse(message, result, toolName) {
+        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, data = {}) {
+        return {
+            success: true,
+            message,
+            ...data
+        };
+    }
+    /**
+     * Categorize error by type
+     */
+    static categorizeError(error) {
+        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
+     */
+    static getUserFriendlyMessage(type, error) {
+        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 */
+    static isRetriable(error) {
+        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(toolName, fn, context) {
+        try {
+            const result = await fn();
+            // Ensure result has success field
+            if (typeof result === 'object' && result !== null) {
+                if (!('success' in result)) {
+                    result.success = true;
+                }
+            }
+            return result;
+        }
+        catch (error) {
+            return this.createErrorResponse(error, toolName, context);
+        }
+    }
+    /**
+     * Validate required parameters
+     */
+    static validateParams(params, required, toolName) {
+        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, operation) {
+        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(success, message, data) {
+        const result = {
+            success,
+            message,
+            ...(data || {})
+        };
+        if (!success && !result.error) {
+            result.error = message;
+        }
+        return result;
+    }
+}
+//# sourceMappingURL=error-handler.js.map

package/dist/utils/errors.d.ts

@@ -0,0 +1,133 @@
+/**
+ * Enhanced error types for better error handling and recovery
+ */
+export declare enum ErrorCode {
+    CONNECTION_FAILED = "CONNECTION_FAILED",
+    CONNECTION_TIMEOUT = "CONNECTION_TIMEOUT",
+    CONNECTION_REFUSED = "CONNECTION_REFUSED",
+    API_ERROR = "API_ERROR",
+    INVALID_RESPONSE = "INVALID_RESPONSE",
+    RATE_LIMITED = "RATE_LIMITED",
+    VALIDATION_ERROR = "VALIDATION_ERROR",
+    INVALID_PARAMETERS = "INVALID_PARAMETERS",
+    MISSING_REQUIRED_FIELD = "MISSING_REQUIRED_FIELD",
+    RESOURCE_NOT_FOUND = "RESOURCE_NOT_FOUND",
+    RESOURCE_LOCKED = "RESOURCE_LOCKED",
+    RESOURCE_UNAVAILABLE = "RESOURCE_UNAVAILABLE",
+    UNAUTHORIZED = "UNAUTHORIZED",
+    FORBIDDEN = "FORBIDDEN",
+    INTERNAL_ERROR = "INTERNAL_ERROR",
+    CIRCUIT_BREAKER_OPEN = "CIRCUIT_BREAKER_OPEN",
+    SERVICE_UNAVAILABLE = "SERVICE_UNAVAILABLE"
+}
+export interface ErrorMetadata {
+    code: ErrorCode;
+    statusCode?: number;
+    retriable: boolean;
+    context?: Record<string, any>;
+    timestamp: Date;
+    correlationId?: string;
+}
+/**
+ * Base application error with metadata
+ */
+export declare class AppError extends Error {
+    readonly metadata: ErrorMetadata;
+    constructor(message: string, metadata?: Partial<ErrorMetadata>);
+    toJSON(): {
+        stack: string | undefined;
+        code: ErrorCode;
+        statusCode?: number;
+        retriable: boolean;
+        context?: Record<string, any>;
+        timestamp: Date;
+        correlationId?: string;
+        name: string;
+        message: string;
+    };
+}
+/**
+ * Connection-related errors
+ */
+export declare class ConnectionError extends AppError {
+    constructor(message: string, metadata?: Partial<ErrorMetadata>);
+}
+/**
+ * API-related errors
+ */
+export declare class ApiError extends AppError {
+    constructor(message: string, statusCode: number, metadata?: Partial<ErrorMetadata>);
+}
+/**
+ * Validation errors
+ */
+export declare class ValidationError extends AppError {
+    constructor(message: string, metadata?: Partial<ErrorMetadata>);
+}
+/**
+ * Resource errors
+ */
+export declare class ResourceError extends AppError {
+    constructor(message: string, code: ErrorCode, metadata?: Partial<ErrorMetadata>);
+}
+/**
+ * Circuit Breaker implementation for fault tolerance
+ */
+export declare enum CircuitState {
+    CLOSED = "CLOSED",
+    OPEN = "OPEN",
+    HALF_OPEN = "HALF_OPEN"
+}
+interface CircuitBreakerOptions {
+    threshold: number;
+    timeout: number;
+    resetTimeout: number;
+    onStateChange?: (oldState: CircuitState, newState: CircuitState) => void;
+}
+export declare class CircuitBreaker {
+    private state;
+    private failures;
+    private successCount;
+    private lastFailureTime?;
+    private readonly options;
+    constructor(options?: Partial<CircuitBreakerOptions>);
+    /**
+     * Execute function with circuit breaker protection
+     */
+    execute<T>(fn: () => Promise<T>): Promise<T>;
+    private onSuccess;
+    private onFailure;
+    private shouldAttemptReset;
+    private transitionTo;
+    getState(): CircuitState;
+    getMetrics(): {
+        state: CircuitState;
+        failures: number;
+        successCount: number;
+        lastFailureTime: Date | undefined;
+    };
+}
+/**
+ * Error recovery strategies
+ */
+export declare class ErrorRecovery {
+    private static circuitBreakers;
+    /**
+     * Get or create circuit breaker for a service
+     */
+    static getCircuitBreaker(service: string, options?: Partial<CircuitBreakerOptions>): CircuitBreaker;
+    /**
+     * Wrap function with error recovery
+     */
+    static withRecovery<T>(fn: () => Promise<T>, options: {
+        service: string;
+        fallback?: () => T | Promise<T>;
+        onError?: (error: Error) => void;
+    }): Promise<T>;
+    /**
+     * Check if error is retriable
+     */
+    static isRetriable(error: Error): boolean;
+}
+export {};
+//# sourceMappingURL=errors.d.ts.map