unreal-engine-mcp-server 0.2.1

package/src/utils/errors.ts

@@ -0,0 +1,312 @@
+/**
+ * Enhanced error types for better error handling and recovery
+ */
+
+export enum ErrorCode {
+  // Connection errors
+  CONNECTION_FAILED = 'CONNECTION_FAILED',
+  CONNECTION_TIMEOUT = 'CONNECTION_TIMEOUT',
+  CONNECTION_REFUSED = 'CONNECTION_REFUSED',
+  
+  // API errors
+  API_ERROR = 'API_ERROR',
+  INVALID_RESPONSE = 'INVALID_RESPONSE',
+  RATE_LIMITED = 'RATE_LIMITED',
+  
+  // Validation errors
+  VALIDATION_ERROR = 'VALIDATION_ERROR',
+  INVALID_PARAMETERS = 'INVALID_PARAMETERS',
+  MISSING_REQUIRED_FIELD = 'MISSING_REQUIRED_FIELD',
+  
+  // Resource errors
+  RESOURCE_NOT_FOUND = 'RESOURCE_NOT_FOUND',
+  RESOURCE_LOCKED = 'RESOURCE_LOCKED',
+  RESOURCE_UNAVAILABLE = 'RESOURCE_UNAVAILABLE',
+  
+  // Permission errors
+  UNAUTHORIZED = 'UNAUTHORIZED',
+  FORBIDDEN = 'FORBIDDEN',
+  
+  // System errors
+  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 class AppError extends Error {
+  public readonly metadata: ErrorMetadata;
+
+  constructor(message: string, metadata: Partial<ErrorMetadata> = {}) {
+    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: string, metadata: Partial<ErrorMetadata> = {}) {
+    super(message, {
+      code: ErrorCode.CONNECTION_FAILED,
+      retriable: true,
+      statusCode: 503,
+      ...metadata
+    });
+  }
+}
+
+/**
+ * API-related errors
+ */
+export class ApiError extends AppError {
+  constructor(message: string, statusCode: number, metadata: Partial<ErrorMetadata> = {}) {
+    super(message, {
+      code: ErrorCode.API_ERROR,
+      statusCode,
+      retriable: statusCode >= 500 || statusCode === 429,
+      ...metadata
+    });
+  }
+}
+
+/**
+ * Validation errors
+ */
+export class ValidationError extends AppError {
+  constructor(message: string, metadata: Partial<ErrorMetadata> = {}) {
+    super(message, {
+      code: ErrorCode.VALIDATION_ERROR,
+      statusCode: 400,
+      retriable: false,
+      ...metadata
+    });
+  }
+}
+
+/**
+ * Resource errors
+ */
+export class ResourceError extends AppError {
+  constructor(message: string, code: ErrorCode, metadata: Partial<ErrorMetadata> = {}) {
+    super(message, {
+      code,
+      statusCode: code === ErrorCode.RESOURCE_NOT_FOUND ? 404 : 409,
+      retriable: code === ErrorCode.RESOURCE_LOCKED,
+      ...metadata
+    });
+  }
+}
+
+/**
+ * Circuit Breaker implementation for fault tolerance
+ */
+export 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 class CircuitBreaker {
+  private state: CircuitState = CircuitState.CLOSED;
+  private failures = 0;
+  private successCount = 0;
+  private lastFailureTime?: Date;
+  private readonly options: CircuitBreakerOptions;
+
+  constructor(options: Partial<CircuitBreakerOptions> = {}) {
+    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<T>(fn: () => Promise<T>): Promise<T> {
+    // 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;
+    }
+  }
+
+  private onSuccess(): void {
+    this.failures = 0;
+    if (this.state === CircuitState.HALF_OPEN) {
+      this.successCount++;
+      if (this.successCount >= 3) {
+        this.transitionTo(CircuitState.CLOSED);
+      }
+    }
+  }
+
+  private onFailure(): void {
+    this.failures++;
+    this.lastFailureTime = new Date();
+    this.successCount = 0;
+
+    if (this.failures >= this.options.threshold) {
+      this.transitionTo(CircuitState.OPEN);
+    }
+  }
+
+  private shouldAttemptReset(): boolean {
+    return (
+      this.lastFailureTime !== undefined &&
+      Date.now() - this.lastFailureTime.getTime() >= this.options.resetTimeout
+    );
+  }
+
+  private transitionTo(newState: CircuitState): void {
+    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(): CircuitState {
+    return this.state;
+  }
+
+  getMetrics() {
+    return {
+      state: this.state,
+      failures: this.failures,
+      successCount: this.successCount,
+      lastFailureTime: this.lastFailureTime
+    };
+  }
+}
+
+/**
+ * Error recovery strategies
+ */
+export class ErrorRecovery {
+  private static circuitBreakers = new Map<string, CircuitBreaker>();
+
+  /**
+   * Get or create circuit breaker for a service
+   */
+  static getCircuitBreaker(service: string, options?: Partial<CircuitBreakerOptions>): CircuitBreaker {
+    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<T>(
+    fn: () => Promise<T>,
+    options: {
+      service: string;
+      fallback?: () => T | Promise<T>;
+      onError?: (error: Error) => void;
+    }
+  ): Promise<T> {
+    const breaker = this.getCircuitBreaker(options.service);
+
+    try {
+      return await breaker.execute(fn);
+    } catch (error) {
+      if (options.onError) {
+        options.onError(error as Error);
+      }
+
+      // Try fallback if available
+      if (options.fallback) {
+        return await options.fallback();
+      }
+
+      throw error;
+    }
+  }
+
+  /**
+   * Check if error is retriable
+   */
+  static isRetriable(error: Error): boolean {
+    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')
+    );
+  }
+}

package/src/utils/http.ts

@@ -0,0 +1,184 @@
+import axios, { AxiosInstance, AxiosRequestConfig, AxiosError } 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
+});
+
+// Retry configuration interface
+interface RetryConfig {
+  maxRetries: number;
+  initialDelay: number;
+  maxDelay: number;
+  backoffMultiplier: number;
+  retryableStatuses: number[];
+  retryableErrors: string[];
+}
+
+const defaultRetryConfig: RetryConfig = {
+  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: number, config: RetryConfig): number {
+  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: string): AxiosInstance {
+  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 as any).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 as any).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<T = any>(
+  client: AxiosInstance,
+  config: AxiosRequestConfig,
+  retryConfig: Partial<RetryConfig> = {}
+): Promise<T> {
+  const retry = { ...defaultRetryConfig, ...retryConfig };
+  let lastError: Error | null = null;
+
+  for (let attempt = 1; attempt <= retry.maxRetries; attempt++) {
+    try {
+      const response = await client.request<T>(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 as Error;
+      const axiosError = error as AxiosError;
+      
+      // 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<T = any>(
+  client: AxiosInstance,
+  requests: AxiosRequestConfig[],
+  options: { concurrency?: number; throwOnError?: boolean } = {}
+): Promise<(T | Error)[]> {
+  const { concurrency = 5, throwOnError = false } = options;
+  const results: (T | Error)[] = [];
+  
+  // 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<T>(req)
+        .then(res => res.data)
+        .catch(err => throwOnError ? Promise.reject(err) : err)
+    );
+    
+    const batchResults = await Promise.all(batchPromises);
+    results.push(...batchResults);
+  }
+  
+  return results;
+}

package/src/utils/logger.ts

@@ -0,0 +1,30 @@
+export type LogLevel = 'debug' | 'info' | 'warn' | 'error';
+
+export class Logger {
+  private level: LogLevel;
+
+  constructor(private scope: string, level: LogLevel = 'info') {
+    const envLevel = (process.env.LOG_LEVEL || process.env.LOGLEVEL || level).toString().toLowerCase();
+    this.level = (['debug', 'info', 'warn', 'error'] as LogLevel[]).includes(envLevel as LogLevel)
+      ? (envLevel as LogLevel)
+      : 'info';
+  }
+
+  private shouldLog(level: LogLevel) {
+    const order: LogLevel[] = ['debug', 'info', 'warn', 'error'];
+    return order.indexOf(level) >= order.indexOf(this.level);
+  }
+
+  debug(...args: any[]) {
+    if (this.shouldLog('debug')) console.error(`[${this.scope}]`, ...args);
+  }
+  info(...args: any[]) {
+    if (this.shouldLog('info')) console.error(`[${this.scope}]`, ...args);
+  }
+  warn(...args: any[]) {
+    if (this.shouldLog('warn')) console.error(`[${this.scope}]`, ...args);
+  }
+  error(...args: any[]) {
+    if (this.shouldLog('error')) console.error(`[${this.scope}]`, ...args);
+  }
+}

package/src/utils/normalize.ts

@@ -0,0 +1,54 @@
+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 function toVec3Object(input: any): Vec3Obj | null {
+  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 as any).x ?? (input as any).X);
+      const y = Number((input as any).y ?? (input as any).Y);
+      const z = Number((input as any).z ?? (input as any).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: any): Vec3Array | null {
+  const obj = toVec3Object(input);
+  return obj ? [obj.x, obj.y, obj.z] : null;
+}
+
+export function toRotObject(input: any): Rot3Obj | null {
+  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 as any).pitch ?? (input as any).Pitch);
+      const yaw = Number((input as any).yaw ?? (input as any).Yaw);
+      const roll = Number((input as any).roll ?? (input as any).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: any): Rot3Array | null {
+  const obj = toRotObject(input);
+  return obj ? [obj.pitch, obj.yaw, obj.roll] : null;
+}