unreal-engine-mcp-server 0.4.0 → 0.4.4

package/dist/utils/elicitation.d.ts

@@ -0,0 +1,57 @@
+import type { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { Logger } from './logger.js';
+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 declare function createElicitationHelper(server: Server, log: Logger): {
+    supports: () => boolean;
+    elicit: (message: string, requestedSchema: ElicitSchema, opts?: ElicitOptions) => Promise<{
+        ok: boolean;
+        value?: any;
+        error?: string;
+    } | {
+        ok: boolean;
+        error: any;
+    }>;
+    getDefaultTimeoutMs: () => number;
+};
+//# sourceMappingURL=elicitation.d.ts.map

package/dist/utils/elicitation.js

@@ -0,0 +1,104 @@
+export function createElicitationHelper(server, log) {
+    // 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) {
+        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; // narrow for guards
+            if ('properties' in primitive || 'items' in primitive)
+                return false; // nested schemas unsupported
+            if (Array.isArray(primitive.enum)) {
+                const enumValues = primitive.enum;
+                const allStrings = enumValues.every((value) => typeof value === 'string');
+                if (!allStrings)
+                    return false;
+                return !('type' in primitive) || primitive.type === 'string';
+            }
+            if (primitive.type === 'string')
+                return true;
+            if (primitive.type === 'number' || primitive.type === 'integer')
+                return true;
+            if (primitive.type === 'boolean')
+                return true;
+            return false;
+        });
+    }
+    async function elicit(message, requestedSchema, opts = {}) {
+        if (!supported || !isSafeSchema(requestedSchema)) {
+            if (opts.fallback)
+                return opts.fallback();
+            return { ok: false, error: 'elicitation-unsupported' };
+        }
+        const params = { message, requestedSchema };
+        try {
+            const elicitMethod = server?.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 = 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) {
+            const msg = String(e?.message || e);
+            const code = e?.code ?? e?.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
+    };
+}
+//# sourceMappingURL=elicitation.js.map

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

@@ -11,15 +11,6 @@ export declare enum ErrorType {
     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
  */
@@ -28,14 +19,6 @@ 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
      */
@@ -46,21 +29,5 @@ export declare class ErrorHandler {
     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

@@ -13,21 +13,6 @@ export var ErrorType;
     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
  */
@@ -66,36 +51,15 @@ export class ErrorHandler {
             })
         };
     }
-    /**
-     * 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 explicitType = (error?.type || error?.errorType || '').toString().toUpperCase();
+        if (explicitType && Object.values(ErrorType).includes(explicitType)) {
+            return explicitType;
         }
-        const errorMessage = error.message?.toLowerCase() || String(error).toLowerCase();
+        const errorMessage = error?.message?.toLowerCase() || String(error).toLowerCase();
         // Connection errors
         if (errorMessage.includes('econnrefused') ||
             errorMessage.includes('timeout') ||
@@ -168,76 +132,5 @@ export class ErrorHandler {
         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/http.d.ts

@@ -1,26 +1,6 @@
-import { AxiosInstance, AxiosRequestConfig } from 'axios';
-interface RetryConfig {
-    maxRetries: number;
-    initialDelay: number;
-    maxDelay: number;
-    backoffMultiplier: number;
-    retryableStatuses: number[];
-    retryableErrors: string[];
-}
+import { AxiosInstance } from 'axios';
 /**
- * Enhanced HTTP client factory with connection pooling and retry logic
+ * Enhanced HTTP client factory with connection pooling and request timing
  */
 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

@@ -2,40 +2,24 @@ import axios 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
 });
 const log = new Logger('HTTP');
-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
+ * Enhanced HTTP client factory with connection pooling and request timing
  */
 export function createHttpClient(baseURL) {
     const client = axios.create({
@@ -85,53 +69,6 @@ export function createHttpClient(baseURL) {
     });
     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);
-            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(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;
-}
+// No retry helpers are exported; consolidated command flows rely on
+// Unreal's own retry/backoff semantics to avoid duplicate side effects.
 //# sourceMappingURL=http.js.map

package/dist/utils/normalize.d.ts

@@ -1,5 +1,3 @@
-export type Vec3Array = [number, number, number];
-export type Rot3Array = [number, number, number];
 export interface Vec3Obj {
     x: number;
     y: number;
@@ -10,8 +8,10 @@ export interface Rot3Obj {
     yaw: number;
     roll: number;
 }
+export type Vec3Tuple = [number, number, number];
+export type Rot3Tuple = [number, number, 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;
+export declare function toVec3Tuple(input: any): Vec3Tuple | null;
+export declare function toRotTuple(input: any): Rot3Tuple | null;
 //# sourceMappingURL=normalize.d.ts.map

package/dist/utils/normalize.js

@@ -18,10 +18,6 @@ export function toVec3Object(input) {
     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) {
@@ -42,8 +38,20 @@ export function toRotObject(input) {
     catch { }
     return null;
 }
-export function toRotArray(input) {
-    const obj = toRotObject(input);
-    return obj ? [obj.pitch, obj.yaw, obj.roll] : null;
+export function toVec3Tuple(input) {
+    const vec = toVec3Object(input);
+    if (!vec) {
+        return null;
+    }
+    const { x, y, z } = vec;
+    return [x, y, z];
+}
+export function toRotTuple(input) {
+    const rot = toRotObject(input);
+    if (!rot) {
+        return null;
+    }
+    const { pitch, yaw, roll } = rot;
+    return [pitch, yaw, roll];
 }
 //# sourceMappingURL=normalize.js.map

package/dist/utils/python-output.d.ts

@@ -0,0 +1,18 @@
+export interface PythonOutput {
+    raw: unknown;
+    text: string;
+}
+export interface TaggedJsonResult<T> extends PythonOutput {
+    data: T | null;
+}
+export interface StandardResultPayload {
+    success?: boolean;
+    message?: string;
+    error?: string;
+    [key: string]: unknown;
+}
+export declare function toPythonOutput(response: unknown): PythonOutput;
+export declare function parseStandardResult(response: unknown, tag?: string): TaggedJsonResult<StandardResultPayload>;
+export declare function stripTaggedResultLines(text: string, tag?: string): string;
+export declare function extractTaggedLine(output: string | PythonOutput, prefix: string): string | null;
+//# sourceMappingURL=python-output.d.ts.map