unreal-engine-mcp-server 0.4.0 → 0.4.3

package/src/utils/elicitation.ts

@@ -0,0 +1,129 @@
+import type { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { Logger } from './logger.js';
+
+// Minimal helper to opportunistically use MCP Elicitation when available.
+// Safe across clients: validates schema shape, handles timeouts and -32601 fallbacks.
+export type PrimitiveSchema =
+  | { type: 'string'; title?: string; description?: string; minLength?: number; maxLength?: number; pattern?: string; format?: 'email'|'uri'|'date'|'date-time'; default?: string }
+  | { type: 'number'|'integer'; title?: string; description?: string; minimum?: number; maximum?: number; default?: number }
+  | { type: 'boolean'; title?: string; description?: string; default?: boolean }
+  | { type: 'string'; enum: string[]; enumNames?: string[]; title?: string; description?: string; default?: string };
+
+export interface ElicitSchema {
+  type: 'object';
+  properties: Record<string, PrimitiveSchema>;
+  required?: string[];
+}
+
+export interface ElicitOptions {
+  timeoutMs?: number;
+  fallback?: () => Promise<{ ok: boolean; value?: any; error?: string }>;
+}
+
+export function createElicitationHelper(server: Server, log: Logger) {
+  // We do not require explicit capability detection: we optimistically try once
+  // and disable on a Method-not-found (-32601) error for the session.
+  let supported = true; // optimistic; will be set false on first failure
+
+  const MIN_TIMEOUT_MS = 30_000;
+  const MAX_TIMEOUT_MS = 10 * 60 * 1000;
+  const DEFAULT_TIMEOUT_MS = 3 * 60 * 1000;
+
+  const timeoutEnvRaw = process.env.MCP_ELICITATION_TIMEOUT_MS ?? process.env.ELICITATION_TIMEOUT_MS ?? '';
+  const parsedEnvTimeout = Number.parseInt(timeoutEnvRaw, 10);
+  const defaultTimeoutMs = Number.isFinite(parsedEnvTimeout) && parsedEnvTimeout > 0
+    ? Math.min(Math.max(parsedEnvTimeout, MIN_TIMEOUT_MS), MAX_TIMEOUT_MS)
+    : DEFAULT_TIMEOUT_MS;
+
+  if (timeoutEnvRaw) {
+    log.debug('Configured elicitation timeout override detected', {
+      defaultTimeoutMs,
+      fromEnv: timeoutEnvRaw
+    });
+  }
+
+  function isSafeSchema(schema: ElicitSchema): boolean {
+    if (!schema || schema.type !== 'object' || typeof schema.properties !== 'object') return false;
+
+    const propertyEntries = Object.entries(schema.properties ?? {});
+    const propertyKeys = propertyEntries.map(([key]) => key);
+
+    if (schema.required) {
+      if (!Array.isArray(schema.required)) return false;
+      const invalidRequired = schema.required.some((key) => typeof key !== 'string' || !propertyKeys.includes(key));
+      if (invalidRequired) return false;
+    }
+
+    return propertyEntries.every(([, rawSchema]) => {
+      if (!rawSchema || typeof rawSchema !== 'object') return false;
+      const primitive = rawSchema as PrimitiveSchema & { properties?: unknown; items?: unknown }; // narrow for guards
+
+      if ('properties' in primitive || 'items' in primitive) return false; // nested schemas unsupported
+
+      if (Array.isArray((primitive as any).enum)) {
+        const enumValues = (primitive as any).enum;
+        const allStrings = enumValues.every((value: unknown) => typeof value === 'string');
+        if (!allStrings) return false;
+        return !('type' in primitive) || (primitive as any).type === 'string';
+      }
+
+      if ((primitive as any).type === 'string') return true;
+      if ((primitive as any).type === 'number' || (primitive as any).type === 'integer') return true;
+      if ((primitive as any).type === 'boolean') return true;
+
+      return false;
+    });
+  }
+
+  async function elicit(message: string, requestedSchema: ElicitSchema, opts: ElicitOptions = {}) {
+    if (!supported || !isSafeSchema(requestedSchema)) {
+      if (opts.fallback) return opts.fallback();
+      return { ok: false, error: 'elicitation-unsupported' };
+    }
+
+    const params = { message, requestedSchema } as any;
+
+    try {
+      const elicitMethod = (server as any)?.elicitInput;
+      if (typeof elicitMethod !== 'function') {
+        supported = false;
+        throw new Error('elicitInput-not-available');
+      }
+
+      const requestedTimeout = opts.timeoutMs;
+      const timeoutMs = Math.max(MIN_TIMEOUT_MS, requestedTimeout ?? defaultTimeoutMs);
+      const res: any = await elicitMethod.call(server, params, { timeout: timeoutMs });
+      const action = res?.action;
+      const content = res?.content;
+
+      if (action === 'accept') return { ok: true, value: content };
+      if (action === 'decline' || action === 'cancel') {
+        if (opts.fallback) return opts.fallback();
+        return { ok: false, error: action };
+      }
+      if (opts.fallback) return opts.fallback();
+      return { ok: false, error: 'unexpected-response' };
+    } catch (e: any) {
+      const msg = String(e?.message || e);
+      const code = (e as any)?.code ?? (e as any)?.error?.code;
+      // If client doesn't support it, don’t try again this session
+      if (
+        msg.includes('Method not found') ||
+        msg.includes('elicitInput-not-available') ||
+        msg.includes('request-not-available') ||
+        String(code) === '-32601'
+      ) {
+        supported = false;
+      }
+      log.debug('Elicitation failed; falling back', { error: msg, code });
+      if (opts.fallback) return opts.fallback();
+      return { ok: false, error: msg.includes('timeout') ? 'timeout' : 'rpc-failed' };
+    }
+  }
+
+  return {
+    supports: () => supported,
+    elicit,
+    getDefaultTimeoutMs: () => defaultTimeoutMs
+  };
+}

package/src/utils/error-handler.ts

@@ -16,21 +16,6 @@ export enum ErrorType {
   UNKNOWN = 'UNKNOWN'
 }
 
-/**
- * Custom error class for MCP tools
- */
-export class ToolError extends Error {
-  constructor(
-    public type: ErrorType,
-    public toolName: string,
-    message: string,
-    public originalError?: any
-  ) {
-    super(message);
-    this.name = 'ToolError';
-  }
-}
-
 /**
  * Consistent error handling for all tools
  */
@@ -76,47 +61,16 @@ export class ErrorHandler {
     } as any;
   }
 
-  /**
-   * Create a standardized warning response
-   */
-  static createWarningResponse(
-    message: string,
-    result: any,
-    toolName: string
-  ): BaseToolResponse {
-    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: string,
-    data: any = {}
-  ): BaseToolResponse {
-    return {
-      success: true,
-      message,
-      ...data
-    };
-  }
-
   /**
    * Categorize error by type
    */
   private static categorizeError(error: any): ErrorType {
-    if (error instanceof ToolError) {
-      return error.type;
+    const explicitType = (error?.type || error?.errorType || '').toString().toUpperCase();
+    if (explicitType && Object.values(ErrorType).includes(explicitType as ErrorType)) {
+      return explicitType as ErrorType;
     }
 
-    const errorMessage = error.message?.toLowerCase() || String(error).toLowerCase();
+    const errorMessage = error?.message?.toLowerCase() || String(error).toLowerCase();
 
     // Connection errors
     if (
@@ -208,113 +162,4 @@ export class ErrorHandler {
     } catch {}
     return false;
   }
-
-  /**
-   * Wrap async function with error handling
-   */
-  static async wrapAsync<T extends BaseToolResponse>(
-    toolName: string,
-    fn: () => Promise<T>,
-    context?: any
-  ): Promise<T> {
-    try {
-      const result = await fn();
-      
-      // Ensure result has success field
-      if (typeof result === 'object' && result !== null) {
-        if (!('success' in result)) {
-          (result as any).success = true;
-        }
-      }
-      
-      return result;
-    } catch (error) {
-      return this.createErrorResponse(error, toolName, context) as T;
-    }
-  }
-
-  /**
-   * Validate required parameters
-   */
-  static validateParams(
-    params: any,
-    required: string[],
-    toolName: string
-  ): void {
-    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: any, operation: string): string {
-    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<T extends BaseToolResponse>(
-    success: boolean,
-    message: string,
-    data?: Partial<T>
-  ): T {
-    const result: BaseToolResponse = {
-      success,
-      message,
-      ...(data || {})
-    };
-
-    if (!success && !result.error) {
-      result.error = message;
-    }
-
-    return result as T;
-  }
 }

package/src/utils/http.ts

@@ -1,65 +1,34 @@
-import axios, { AxiosInstance, AxiosRequestConfig, AxiosError } from 'axios';
+import axios, { AxiosInstance } from 'axios';
 import http from 'http';
 import https from 'https';
 import { Logger } from './logger.js';
 
-// Connection pooling configuration for better performance
+// Enhanced connection pooling configuration to prevent socket failures
 const httpAgent = new http.Agent({
   keepAlive: true,
-  keepAliveMsecs: 30000,
-  maxSockets: 10,
-  maxFreeSockets: 5,
-  timeout: 30000
+  keepAliveMsecs: 60000, // Increased keep-alive time
+  maxSockets: 20, // Increased socket pool
+  maxFreeSockets: 10, // More free sockets
+  timeout: 60000, // Longer timeout
 });
 
 const httpsAgent = new https.Agent({
   keepAlive: true,
-  keepAliveMsecs: 30000,
-  maxSockets: 10,
-  maxFreeSockets: 5,
-  timeout: 30000
+  keepAliveMsecs: 60000, // Increased keep-alive time
+  maxSockets: 20, // Increased socket pool
+  maxFreeSockets: 10, // More free sockets
+  timeout: 60000, // Longer timeout
 });
 
-// Retry configuration interface
-interface RetryConfig {
-  maxRetries: number;
-  initialDelay: number;
-  maxDelay: number;
-  backoffMultiplier: number;
-  retryableStatuses: number[];
-  retryableErrors: string[];
-}
-
 const log = new Logger('HTTP');
 
-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
+ * Enhanced HTTP client factory with connection pooling and request timing
  */
 export function createHttpClient(baseURL: string): AxiosInstance {
   const client = axios.create({
     baseURL,
-    headers: { 
+    headers: {
       'Content-Type': 'application/json',
       'Accept': 'application/json'
     },
@@ -71,7 +40,7 @@ export function createHttpClient(baseURL: string): AxiosInstance {
       // 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);
@@ -102,7 +71,7 @@ export function createHttpClient(baseURL: string): AxiosInstance {
   client.interceptors.response.use(
     (response) => {
       const duration = Date.now() - ((response.config as any).metadata?.startTime || 0);
-if (duration > 5000) {
+      if (duration > 5000) {
         log.warn(`[HTTP] Slow request: ${response.config.url} took ${duration}ms`);
       }
       return response;
@@ -115,73 +84,5 @@ if (duration > 5000) {
   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);
-      log.debug(`[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;
-}
+// No retry helpers are exported; consolidated command flows rely on
+// Unreal's own retry/backoff semantics to avoid duplicate side effects.

package/src/utils/normalize.ts

@@ -1,8 +1,9 @@
-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 type Vec3Tuple = [number, number, number];
+export type Rot3Tuple = [number, number, number];
+
 export function toVec3Object(input: any): Vec3Obj | null {
   try {
     if (Array.isArray(input) && input.length === 3) {
@@ -23,11 +24,6 @@ export function toVec3Object(input: any): Vec3Obj | null {
   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) {
@@ -48,7 +44,21 @@ export function toRotObject(input: any): Rot3Obj | null {
   return null;
 }
 
-export function toRotArray(input: any): Rot3Array | null {
-  const obj = toRotObject(input);
-  return obj ? [obj.pitch, obj.yaw, obj.roll] : null;
+export function toVec3Tuple(input: any): Vec3Tuple | null {
+  const vec = toVec3Object(input);
+  if (!vec) {
+    return null;
+  }
+  const { x, y, z } = vec;
+  return [x, y, z];
 }
+
+export function toRotTuple(input: any): Rot3Tuple | null {
+  const rot = toRotObject(input);
+  if (!rot) {
+    return null;
+  }
+  const { pitch, yaw, roll } = rot;
+  return [pitch, yaw, roll];
+}
+