unreal-engine-mcp-server 0.2.1

package/dist/utils/errors.js

@@ -0,0 +1,256 @@
+/**
+ * Enhanced error types for better error handling and recovery
+ */
+export var ErrorCode;
+(function (ErrorCode) {
+    // Connection errors
+    ErrorCode["CONNECTION_FAILED"] = "CONNECTION_FAILED";
+    ErrorCode["CONNECTION_TIMEOUT"] = "CONNECTION_TIMEOUT";
+    ErrorCode["CONNECTION_REFUSED"] = "CONNECTION_REFUSED";
+    // API errors
+    ErrorCode["API_ERROR"] = "API_ERROR";
+    ErrorCode["INVALID_RESPONSE"] = "INVALID_RESPONSE";
+    ErrorCode["RATE_LIMITED"] = "RATE_LIMITED";
+    // Validation errors
+    ErrorCode["VALIDATION_ERROR"] = "VALIDATION_ERROR";
+    ErrorCode["INVALID_PARAMETERS"] = "INVALID_PARAMETERS";
+    ErrorCode["MISSING_REQUIRED_FIELD"] = "MISSING_REQUIRED_FIELD";
+    // Resource errors
+    ErrorCode["RESOURCE_NOT_FOUND"] = "RESOURCE_NOT_FOUND";
+    ErrorCode["RESOURCE_LOCKED"] = "RESOURCE_LOCKED";
+    ErrorCode["RESOURCE_UNAVAILABLE"] = "RESOURCE_UNAVAILABLE";
+    // Permission errors
+    ErrorCode["UNAUTHORIZED"] = "UNAUTHORIZED";
+    ErrorCode["FORBIDDEN"] = "FORBIDDEN";
+    // System errors
+    ErrorCode["INTERNAL_ERROR"] = "INTERNAL_ERROR";
+    ErrorCode["CIRCUIT_BREAKER_OPEN"] = "CIRCUIT_BREAKER_OPEN";
+    ErrorCode["SERVICE_UNAVAILABLE"] = "SERVICE_UNAVAILABLE";
+})(ErrorCode || (ErrorCode = {}));
+/**
+ * Base application error with metadata
+ */
+export class AppError extends Error {
+    metadata;
+    constructor(message, metadata = {}) {
+        super(message);
+        this.name = this.constructor.name;
+        this.metadata = {
+            code: metadata.code || ErrorCode.INTERNAL_ERROR,
+            retriable: metadata.retriable || false,
+            timestamp: new Date(),
+            ...metadata
+        };
+        Error.captureStackTrace(this, this.constructor);
+    }
+    toJSON() {
+        return {
+            name: this.name,
+            message: this.message,
+            ...this.metadata,
+            stack: this.stack
+        };
+    }
+}
+/**
+ * Connection-related errors
+ */
+export class ConnectionError extends AppError {
+    constructor(message, metadata = {}) {
+        super(message, {
+            code: ErrorCode.CONNECTION_FAILED,
+            retriable: true,
+            statusCode: 503,
+            ...metadata
+        });
+    }
+}
+/**
+ * API-related errors
+ */
+export class ApiError extends AppError {
+    constructor(message, statusCode, metadata = {}) {
+        super(message, {
+            code: ErrorCode.API_ERROR,
+            statusCode,
+            retriable: statusCode >= 500 || statusCode === 429,
+            ...metadata
+        });
+    }
+}
+/**
+ * Validation errors
+ */
+export class ValidationError extends AppError {
+    constructor(message, metadata = {}) {
+        super(message, {
+            code: ErrorCode.VALIDATION_ERROR,
+            statusCode: 400,
+            retriable: false,
+            ...metadata
+        });
+    }
+}
+/**
+ * Resource errors
+ */
+export class ResourceError extends AppError {
+    constructor(message, code, metadata = {}) {
+        super(message, {
+            code,
+            statusCode: code === ErrorCode.RESOURCE_NOT_FOUND ? 404 : 409,
+            retriable: code === ErrorCode.RESOURCE_LOCKED,
+            ...metadata
+        });
+    }
+}
+/**
+ * Circuit Breaker implementation for fault tolerance
+ */
+export var CircuitState;
+(function (CircuitState) {
+    CircuitState["CLOSED"] = "CLOSED";
+    CircuitState["OPEN"] = "OPEN";
+    CircuitState["HALF_OPEN"] = "HALF_OPEN";
+})(CircuitState || (CircuitState = {}));
+export class CircuitBreaker {
+    state = CircuitState.CLOSED;
+    failures = 0;
+    successCount = 0;
+    lastFailureTime;
+    options;
+    constructor(options = {}) {
+        this.options = {
+            threshold: options.threshold || 5,
+            timeout: options.timeout || 60000, // 1 minute
+            resetTimeout: options.resetTimeout || 30000, // 30 seconds
+            onStateChange: options.onStateChange
+        };
+    }
+    /**
+     * Execute function with circuit breaker protection
+     */
+    async execute(fn) {
+        // Check circuit state
+        if (this.state === CircuitState.OPEN) {
+            if (this.shouldAttemptReset()) {
+                this.transitionTo(CircuitState.HALF_OPEN);
+            }
+            else {
+                throw new AppError('Circuit breaker is open', {
+                    code: ErrorCode.CIRCUIT_BREAKER_OPEN,
+                    retriable: true,
+                    context: {
+                        failures: this.failures,
+                        lastFailure: this.lastFailureTime
+                    }
+                });
+            }
+        }
+        try {
+            const result = await fn();
+            this.onSuccess();
+            return result;
+        }
+        catch (error) {
+            this.onFailure();
+            throw error;
+        }
+    }
+    onSuccess() {
+        this.failures = 0;
+        if (this.state === CircuitState.HALF_OPEN) {
+            this.successCount++;
+            if (this.successCount >= 3) {
+                this.transitionTo(CircuitState.CLOSED);
+            }
+        }
+    }
+    onFailure() {
+        this.failures++;
+        this.lastFailureTime = new Date();
+        this.successCount = 0;
+        if (this.failures >= this.options.threshold) {
+            this.transitionTo(CircuitState.OPEN);
+        }
+    }
+    shouldAttemptReset() {
+        return (this.lastFailureTime !== undefined &&
+            Date.now() - this.lastFailureTime.getTime() >= this.options.resetTimeout);
+    }
+    transitionTo(newState) {
+        const oldState = this.state;
+        this.state = newState;
+        if (newState === CircuitState.CLOSED) {
+            this.failures = 0;
+            this.successCount = 0;
+        }
+        if (this.options.onStateChange && oldState !== newState) {
+            this.options.onStateChange(oldState, newState);
+        }
+    }
+    getState() {
+        return this.state;
+    }
+    getMetrics() {
+        return {
+            state: this.state,
+            failures: this.failures,
+            successCount: this.successCount,
+            lastFailureTime: this.lastFailureTime
+        };
+    }
+}
+/**
+ * Error recovery strategies
+ */
+export class ErrorRecovery {
+    static circuitBreakers = new Map();
+    /**
+     * Get or create circuit breaker for a service
+     */
+    static getCircuitBreaker(service, options) {
+        if (!this.circuitBreakers.has(service)) {
+            this.circuitBreakers.set(service, new CircuitBreaker(options));
+        }
+        const breaker = this.circuitBreakers.get(service);
+        if (!breaker) {
+            throw new Error(`Circuit breaker for service ${service} could not be created`);
+        }
+        return breaker;
+    }
+    /**
+     * Wrap function with error recovery
+     */
+    static async withRecovery(fn, options) {
+        const breaker = this.getCircuitBreaker(options.service);
+        try {
+            return await breaker.execute(fn);
+        }
+        catch (error) {
+            if (options.onError) {
+                options.onError(error);
+            }
+            // Try fallback if available
+            if (options.fallback) {
+                return await options.fallback();
+            }
+            throw error;
+        }
+    }
+    /**
+     * Check if error is retriable
+     */
+    static isRetriable(error) {
+        if (error instanceof AppError) {
+            return error.metadata.retriable;
+        }
+        // Check for network errors
+        const message = error.message.toLowerCase();
+        return (message.includes('timeout') ||
+            message.includes('network') ||
+            message.includes('econnrefused') ||
+            message.includes('econnreset'));
+    }
+}
+//# sourceMappingURL=errors.js.map

package/dist/utils/http.d.ts

@@ -0,0 +1,26 @@
+import { AxiosInstance, AxiosRequestConfig } from 'axios';
+interface RetryConfig {
+    maxRetries: number;
+    initialDelay: number;
+    maxDelay: number;
+    backoffMultiplier: number;
+    retryableStatuses: number[];
+    retryableErrors: string[];
+}
+/**
+ * Enhanced HTTP client factory with connection pooling and retry logic
+ */
+export declare function createHttpClient(baseURL: string): AxiosInstance;
+/**
+ * Execute request with retry logic for resilience
+ */
+export declare function requestWithRetry<T = any>(client: AxiosInstance, config: AxiosRequestConfig, retryConfig?: Partial<RetryConfig>): Promise<T>;
+/**
+ * Batch multiple requests for efficiency
+ */
+export declare function batchRequests<T = any>(client: AxiosInstance, requests: AxiosRequestConfig[], options?: {
+    concurrency?: number;
+    throwOnError?: boolean;
+}): Promise<(T | Error)[]>;
+export {};
+//# sourceMappingURL=http.d.ts.map

package/dist/utils/http.js

@@ -0,0 +1,135 @@
+import axios from 'axios';
+import http from 'http';
+import https from 'https';
+// Connection pooling configuration for better performance
+const httpAgent = new http.Agent({
+    keepAlive: true,
+    keepAliveMsecs: 30000,
+    maxSockets: 10,
+    maxFreeSockets: 5,
+    timeout: 30000
+});
+const httpsAgent = new https.Agent({
+    keepAlive: true,
+    keepAliveMsecs: 30000,
+    maxSockets: 10,
+    maxFreeSockets: 5,
+    timeout: 30000
+});
+const defaultRetryConfig = {
+    maxRetries: 3,
+    initialDelay: 1000,
+    maxDelay: 10000,
+    backoffMultiplier: 2,
+    retryableStatuses: [408, 429, 500, 502, 503, 504],
+    retryableErrors: ['ECONNABORTED', 'ETIMEDOUT', 'ECONNRESET', 'ENOTFOUND']
+};
+/**
+ * Calculate exponential backoff delay with jitter
+ */
+function calculateBackoff(attempt, config) {
+    const delay = Math.min(config.initialDelay * Math.pow(config.backoffMultiplier, attempt - 1), config.maxDelay);
+    // Add jitter to prevent thundering herd
+    return delay + Math.random() * 1000;
+}
+/**
+ * Enhanced HTTP client factory with connection pooling and retry logic
+ */
+export function createHttpClient(baseURL) {
+    const client = axios.create({
+        baseURL,
+        headers: {
+            'Content-Type': 'application/json',
+            'Accept': 'application/json'
+        },
+        timeout: 15000,
+        httpAgent,
+        httpsAgent,
+        // Ensure proper handling of request body transformation
+        transformRequest: [(data, headers) => {
+                // Remove Content-Length if it's set incorrectly
+                delete headers['Content-Length'];
+                delete headers['content-length'];
+                // Properly stringify JSON data
+                if (data && typeof data === 'object') {
+                    const jsonStr = JSON.stringify(data);
+                    // Let axios set Content-Length automatically
+                    return jsonStr;
+                }
+                return data;
+            }],
+        // Optimize response handling
+        maxContentLength: 50 * 1024 * 1024, // 50MB
+        maxBodyLength: 50 * 1024 * 1024,
+        decompress: true
+    });
+    // Add request interceptor for timing
+    client.interceptors.request.use((config) => {
+        // Add metadata for performance tracking
+        config.metadata = { startTime: Date.now() };
+        return config;
+    }, (error) => {
+        return Promise.reject(error);
+    });
+    // Add response interceptor for timing and logging
+    client.interceptors.response.use((response) => {
+        const duration = Date.now() - (response.config.metadata?.startTime || 0);
+        if (duration > 5000) {
+            console.warn(`[HTTP] Slow request: ${response.config.url} took ${duration}ms`);
+        }
+        return response;
+    }, (error) => {
+        return Promise.reject(error);
+    });
+    return client;
+}
+/**
+ * Execute request with retry logic for resilience
+ */
+export async function requestWithRetry(client, config, retryConfig = {}) {
+    const retry = { ...defaultRetryConfig, ...retryConfig };
+    let lastError = null;
+    for (let attempt = 1; attempt <= retry.maxRetries; attempt++) {
+        try {
+            const response = await client.request(config);
+            // Check if we should retry based on status
+            if (retry.retryableStatuses.includes(response.status)) {
+                throw new Error(`Retryable status: ${response.status}`);
+            }
+            return response.data;
+        }
+        catch (error) {
+            lastError = error;
+            const axiosError = error;
+            // Check if error is retryable
+            const isRetryable = retry.retryableErrors.includes(axiosError.code || '') ||
+                (axiosError.response && retry.retryableStatuses.includes(axiosError.response.status));
+            if (!isRetryable || attempt === retry.maxRetries) {
+                throw error;
+            }
+            // Calculate delay and wait
+            const delay = calculateBackoff(attempt, retry);
+            console.error(`[HTTP] Retry attempt ${attempt}/${retry.maxRetries} after ${Math.round(delay)}ms`);
+            await new Promise(resolve => setTimeout(resolve, delay));
+        }
+    }
+    throw lastError || new Error('Request failed after retries');
+}
+/**
+ * Batch multiple requests for efficiency
+ */
+export async function batchRequests(client, requests, options = {}) {
+    const { concurrency = 5, throwOnError = false } = options;
+    const results = [];
+    // Process requests in batches
+    for (let i = 0; i < requests.length; i += concurrency) {
+        const batch = requests.slice(i, i + concurrency);
+        const batchPromises = batch.map(req => client.request(req)
+            .then(res => res.data)
+            .catch(err => throwOnError ? Promise.reject(err) : err));
+        const batchResults = await Promise.all(batchPromises);
+        results.push(...batchResults);
+    }
+    return results;
+}
+//# sourceMappingURL=http.js.map

package/dist/utils/logger.d.ts

@@ -0,0 +1,12 @@
+export type LogLevel = 'debug' | 'info' | 'warn' | 'error';
+export declare class Logger {
+    private scope;
+    private level;
+    constructor(scope: string, level?: LogLevel);
+    private shouldLog;
+    debug(...args: any[]): void;
+    info(...args: any[]): void;
+    warn(...args: any[]): void;
+    error(...args: any[]): void;
+}
+//# sourceMappingURL=logger.d.ts.map

package/dist/utils/logger.js

@@ -0,0 +1,32 @@
+export class Logger {
+    scope;
+    level;
+    constructor(scope, level = 'info') {
+        this.scope = scope;
+        const envLevel = (process.env.LOG_LEVEL || process.env.LOGLEVEL || level).toString().toLowerCase();
+        this.level = ['debug', 'info', 'warn', 'error'].includes(envLevel)
+            ? envLevel
+            : 'info';
+    }
+    shouldLog(level) {
+        const order = ['debug', 'info', 'warn', 'error'];
+        return order.indexOf(level) >= order.indexOf(this.level);
+    }
+    debug(...args) {
+        if (this.shouldLog('debug'))
+            console.error(`[${this.scope}]`, ...args);
+    }
+    info(...args) {
+        if (this.shouldLog('info'))
+            console.error(`[${this.scope}]`, ...args);
+    }
+    warn(...args) {
+        if (this.shouldLog('warn'))
+            console.error(`[${this.scope}]`, ...args);
+    }
+    error(...args) {
+        if (this.shouldLog('error'))
+            console.error(`[${this.scope}]`, ...args);
+    }
+}
+//# sourceMappingURL=logger.js.map

package/dist/utils/normalize.d.ts

@@ -0,0 +1,17 @@
+export type Vec3Array = [number, number, number];
+export type Rot3Array = [number, number, number];
+export interface Vec3Obj {
+    x: number;
+    y: number;
+    z: number;
+}
+export interface Rot3Obj {
+    pitch: number;
+    yaw: number;
+    roll: number;
+}
+export declare function toVec3Object(input: any): Vec3Obj | null;
+export declare function toVec3Array(input: any): Vec3Array | null;
+export declare function toRotObject(input: any): Rot3Obj | null;
+export declare function toRotArray(input: any): Rot3Array | null;
+//# sourceMappingURL=normalize.d.ts.map

package/dist/utils/normalize.js

@@ -0,0 +1,49 @@
+export function toVec3Object(input) {
+    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 };
+            }
+        }
+        if (input && typeof input === 'object') {
+            const x = Number(input.x ?? input.X);
+            const y = Number(input.y ?? input.Y);
+            const z = Number(input.z ?? input.Z);
+            if ([x, y, z].every(v => typeof v === 'number' && !isNaN(v) && isFinite(v))) {
+                return { x, y, z };
+            }
+        }
+    }
+    catch { }
+    return null;
+}
+export function toVec3Array(input) {
+    const obj = toVec3Object(input);
+    return obj ? [obj.x, obj.y, obj.z] : null;
+}
+export function toRotObject(input) {
+    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 };
+            }
+        }
+        if (input && typeof input === 'object') {
+            const pitch = Number(input.pitch ?? input.Pitch);
+            const yaw = Number(input.yaw ?? input.Yaw);
+            const roll = Number(input.roll ?? input.Roll);
+            if ([pitch, yaw, roll].every(v => typeof v === 'number' && !isNaN(v) && isFinite(v))) {
+                return { pitch, yaw, roll };
+            }
+        }
+    }
+    catch { }
+    return null;
+}
+export function toRotArray(input) {
+    const obj = toRotObject(input);
+    return obj ? [obj.pitch, obj.yaw, obj.roll] : null;
+}
+//# sourceMappingURL=normalize.js.map

package/dist/utils/response-validator.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Response Validator for MCP Tool Outputs
+ * Validates tool responses against their defined output schemas
+ */
+export declare class ResponseValidator {
+    private ajv;
+    private validators;
+    constructor();
+    /**
+     * Register a tool's output schema for validation
+     */
+    registerSchema(toolName: string, outputSchema: any): void;
+    /**
+     * Validate a tool's response against its schema
+     */
+    validateResponse(toolName: string, response: any): {
+        valid: boolean;
+        errors?: string[];
+        structuredContent?: any;
+    };
+    /**
+     * Wrap a tool response with validation
+     */
+    wrapResponse(toolName: string, response: any): any;
+    /**
+     * Get validation statistics
+     */
+    getStats(): {
+        totalSchemas: number;
+        tools: string[];
+    };
+}
+export declare const responseValidator: ResponseValidator;
+//# sourceMappingURL=response-validator.d.ts.map

package/dist/utils/response-validator.js

@@ -0,0 +1,121 @@
+import Ajv from 'ajv';
+import { Logger } from './logger.js';
+import { cleanObject } from './safe-json.js';
+const log = new Logger('ResponseValidator');
+/**
+ * Response Validator for MCP Tool Outputs
+ * Validates tool responses against their defined output schemas
+ */
+export class ResponseValidator {
+    ajv;
+    validators = new Map();
+    constructor() {
+        this.ajv = new Ajv({
+            allErrors: true,
+            verbose: true,
+            strict: false // Allow additional properties for flexibility
+        });
+    }
+    /**
+     * Register a tool's output schema for validation
+     */
+    registerSchema(toolName, outputSchema) {
+        if (!outputSchema) {
+            log.warn(`No output schema defined for tool: ${toolName}`);
+            return;
+        }
+        try {
+            const validator = this.ajv.compile(outputSchema);
+            this.validators.set(toolName, validator);
+            log.info(`Registered output schema for tool: ${toolName}`);
+        }
+        catch (error) {
+            log.error(`Failed to compile output schema for ${toolName}:`, error);
+        }
+    }
+    /**
+     * Validate a tool's response against its schema
+     */
+    validateResponse(toolName, response) {
+        const validator = this.validators.get(toolName);
+        if (!validator) {
+            log.debug(`No validator found for tool: ${toolName}`);
+            return { valid: true }; // Pass through if no schema defined
+        }
+        // Extract structured content from response
+        let structuredContent = response;
+        // If response has MCP format with content array
+        if (response.content && Array.isArray(response.content)) {
+            // Try to extract structured data from text content
+            const textContent = response.content.find((c) => c.type === 'text');
+            if (textContent?.text) {
+                try {
+                    // Check if text is JSON
+                    structuredContent = JSON.parse(textContent.text);
+                }
+                catch {
+                    // Not JSON, use the full response
+                    structuredContent = response;
+                }
+            }
+        }
+        const valid = validator(structuredContent);
+        if (!valid) {
+            const errors = validator.errors?.map((err) => `${err.instancePath || 'root'}: ${err.message}`);
+            log.warn(`Response validation failed for ${toolName}:`, errors);
+            return {
+                valid: false,
+                errors,
+                structuredContent
+            };
+        }
+        return {
+            valid: true,
+            structuredContent
+        };
+    }
+    /**
+     * Wrap a tool response with validation
+     */
+    wrapResponse(toolName, response) {
+        // Ensure response is safe to serialize first
+        try {
+            // The response should already be cleaned, but double-check
+            if (response && typeof response === 'object') {
+                // Make sure we can serialize it
+                JSON.stringify(response);
+            }
+        }
+        catch (error) {
+            log.error(`Response for ${toolName} contains circular references, cleaning...`);
+            response = cleanObject(response);
+        }
+        const validation = this.validateResponse(toolName, response);
+        // Add validation metadata
+        if (!validation.valid) {
+            log.warn(`Tool ${toolName} response validation failed:`, validation.errors);
+            // Add warning to response but don't fail
+            if (response && typeof response === 'object') {
+                response._validation = {
+                    valid: false,
+                    errors: validation.errors
+                };
+            }
+        }
+        // Don't add structuredContent to the response - it's for internal validation only
+        // Adding it can cause circular references
+        return response;
+    }
+    /**
+     * Get validation statistics
+     */
+    getStats() {
+        return {
+            totalSchemas: this.validators.size,
+            tools: Array.from(this.validators.keys())
+        };
+    }
+}
+// Singleton instance
+export const responseValidator = new ResponseValidator();
+//# sourceMappingURL=response-validator.js.map

package/dist/utils/safe-json.d.ts

@@ -0,0 +1,4 @@
+export declare function safeStringify(obj: any, space?: number): string;
+export declare function sanitizeResponse(response: any): any;
+export declare function cleanObject(obj: any, maxDepth?: number): any;
+//# sourceMappingURL=safe-json.d.ts.map