unreal-engine-mcp-server 0.4.6 → 0.5.0

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

@@ -0,0 +1,9 @@
+export declare class CommandValidator {
+    private static readonly DANGEROUS_COMMANDS;
+    private static readonly FORBIDDEN_TOKENS;
+    private static readonly INVALID_PATTERNS;
+    static validate(command: string): void;
+    static isLikelyInvalid(command: string): boolean;
+    static getPriority(command: string): number;
+}
+//# sourceMappingURL=command-validator.d.ts.map

package/dist/utils/command-validator.js

@@ -0,0 +1,67 @@
+export class CommandValidator {
+    static DANGEROUS_COMMANDS = [
+        'quit', 'exit', 'delete', 'destroy', 'kill', 'crash',
+        'viewmode visualizebuffer basecolor',
+        'viewmode visualizebuffer worldnormal',
+        'r.gpucrash',
+        'buildpaths',
+        'rebuildnavigation'
+    ];
+    static FORBIDDEN_TOKENS = [
+        'rm ', 'rm-', 'del ', 'format ', 'shutdown', 'reboot',
+        'rmdir', 'mklink', 'copy ', 'move ', 'start "', 'system(',
+        'import os', 'import subprocess', 'subprocess.', 'os.system',
+        'exec(', 'eval(', '__import__', 'import sys', 'import importlib',
+        'with open', 'open('
+    ];
+    static INVALID_PATTERNS = [
+        /^\d+$/,
+        /^invalid_command/i,
+        /^this_is_not_a_valid/i,
+    ];
+    static validate(command) {
+        if (!command || typeof command !== 'string') {
+            throw new Error('Invalid command: must be a non-empty string');
+        }
+        const cmdTrimmed = command.trim();
+        if (cmdTrimmed.length === 0) {
+            return;
+        }
+        if (cmdTrimmed.includes('\n') || cmdTrimmed.includes('\r')) {
+            throw new Error('Multi-line console commands are not allowed. Send one command per call.');
+        }
+        const cmdLower = cmdTrimmed.toLowerCase();
+        if (cmdLower === 'py' || cmdLower.startsWith('py ')) {
+            throw new Error('Python console commands are blocked from external calls for safety.');
+        }
+        if (this.DANGEROUS_COMMANDS.some(dangerous => cmdLower.includes(dangerous))) {
+            throw new Error(`Dangerous command blocked: ${command}`);
+        }
+        if (cmdLower.includes('&&') || cmdLower.includes('||')) {
+            throw new Error('Command chaining with && or || is blocked for safety.');
+        }
+        if (this.FORBIDDEN_TOKENS.some(token => cmdLower.includes(token))) {
+            throw new Error(`Command contains unsafe token and was blocked: ${command}`);
+        }
+    }
+    static isLikelyInvalid(command) {
+        const cmdTrimmed = command.trim();
+        return this.INVALID_PATTERNS.some(pattern => pattern.test(cmdTrimmed));
+    }
+    static getPriority(command) {
+        if (command.includes('BuildLighting') || command.includes('BuildPaths')) {
+            return 1;
+        }
+        else if (command.includes('summon') || command.includes('spawn')) {
+            return 5;
+        }
+        else if (command.startsWith('stat')) {
+            return 8;
+        }
+        else if (command.startsWith('show')) {
+            return 9;
+        }
+        return 7;
+    }
+}
+//# sourceMappingURL=command-validator.js.map

package/dist/utils/elicitation.d.ts

@@ -36,7 +36,7 @@ export interface ElicitSchema {
 }
 export interface ElicitOptions {
     timeoutMs?: number;
-    fallback?: () => Promise<{
+    alternate?: () => Promise<{
         ok: boolean;
         value?: any;
         error?: string;

package/dist/utils/elicitation.js

@@ -1,7 +1,5 @@
 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
+    let supported = true;
     const MIN_TIMEOUT_MS = 30_000;
     const MAX_TIMEOUT_MS = 10 * 60 * 1000;
     const DEFAULT_TIMEOUT_MS = 3 * 60 * 1000;
@@ -31,9 +29,9 @@ export function createElicitationHelper(server, log) {
         return propertyEntries.every(([, rawSchema]) => {
             if (!rawSchema || typeof rawSchema !== 'object')
                 return false;
-            const primitive = rawSchema; // narrow for guards
+            const primitive = rawSchema;
             if ('properties' in primitive || 'items' in primitive)
-                return false; // nested schemas unsupported
+                return false;
             if (Array.isArray(primitive.enum)) {
                 const enumValues = primitive.enum;
                 const allStrings = enumValues.every((value) => typeof value === 'string');
@@ -52,8 +50,8 @@ export function createElicitationHelper(server, log) {
     }
     async function elicit(message, requestedSchema, opts = {}) {
         if (!supported || !isSafeSchema(requestedSchema)) {
-            if (opts.fallback)
-                return opts.fallback();
+            if (opts.alternate)
+                return opts.alternate();
             return { ok: false, error: 'elicitation-unsupported' };
         }
         const params = { message, requestedSchema };
@@ -71,27 +69,26 @@ export function createElicitationHelper(server, log) {
             if (action === 'accept')
                 return { ok: true, value: content };
             if (action === 'decline' || action === 'cancel') {
-                if (opts.fallback)
-                    return opts.fallback();
+                if (opts.alternate)
+                    return opts.alternate();
                 return { ok: false, error: action };
             }
-            if (opts.fallback)
-                return opts.fallback();
+            if (opts.alternate)
+                return opts.alternate();
             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();
+            log.debug('Elicitation failed; using alternate handler', { error: msg, code });
+            if (opts.alternate)
+                return opts.alternate();
             return { ok: false, error: msg.includes('timeout') ? 'timeout' : 'rpc-failed' };
         }
     }

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

@@ -1,7 +1,4 @@
 import { BaseToolResponse } from '../types/tool-types.js';
-/**
- * Error types for categorization
- */
 export declare enum ErrorType {
     VALIDATION = "VALIDATION",
     CONNECTION = "CONNECTION",
@@ -11,63 +8,17 @@ export declare enum ErrorType {
     TIMEOUT = "TIMEOUT",
     UNKNOWN = "UNKNOWN"
 }
-/**
- * Consistent error handling for all tools
- */
 export declare class ErrorHandler {
-    /**
-     * Create a standardized error response
-     */
     static createErrorResponse(error: any, toolName: string, context?: 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;
-    /**
-     * Retry an async operation with exponential backoff
-     * Best practice from TypeScript async programming patterns
-     * @param operation - Async operation to retry
-     * @param options - Retry configuration
-     * @returns Result of the operation
-     */
-    static retryWithBackoff<T>(operation: () => Promise<T>, options?: {
+    static retryWithBackoff<T>(fn: () => Promise<T>, options?: {
         maxRetries?: number;
         initialDelay?: number;
         maxDelay?: number;
         backoffMultiplier?: number;
-        shouldRetry?: (error: unknown) => boolean;
+        shouldRetry?: (error: any) => boolean;
     }): Promise<T>;
-    /**
-     * Add timeout to any promise
-     * @param promise - Promise to add timeout to
-     * @param timeoutMs - Timeout in milliseconds
-     * @param errorMessage - Custom error message for timeout
-     * @returns Promise that rejects on timeout
-     */
-    static withTimeout<T>(promise: Promise<T>, timeoutMs: number, errorMessage?: string): Promise<T>;
-    /**
-     * Execute multiple operations with Promise.allSettled for better error handling
-     * Returns detailed results for each operation, including failures
-     * @param operations - Array of async operations to execute
-     * @returns Object with successful and failed operations separated
-     */
-    static batchExecute<T>(operations: Array<() => Promise<T>>): Promise<{
-        successful: Array<{
-            index: number;
-            value: T;
-        }>;
-        failed: Array<{
-            index: number;
-            reason: unknown;
-        }>;
-        successCount: number;
-        failureCount: number;
-    }>;
 }
 //# sourceMappingURL=error-handler.d.ts.map

package/dist/utils/error-handler.js

@@ -1,8 +1,5 @@
 import { Logger } from './logger.js';
 const log = new Logger('ErrorHandler');
-/**
- * Error types for categorization
- */
 export var ErrorType;
 (function (ErrorType) {
     ErrorType["VALIDATION"] = "VALIDATION";
@@ -13,13 +10,7 @@ export var ErrorType;
     ErrorType["TIMEOUT"] = "TIMEOUT";
     ErrorType["UNKNOWN"] = "UNKNOWN";
 })(ErrorType || (ErrorType = {}));
-/**
- * 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);
@@ -38,7 +29,6 @@ export class ErrorHandler {
             message: `Failed to execute ${toolName}: ${userMessage}`,
             retriable: retriable,
             scope: scope,
-            // Add debug info in development
             ...(process.env.NODE_ENV === 'development' && {
                 _debug: {
                     errorType,
@@ -51,57 +41,46 @@ export class ErrorHandler {
             })
         };
     }
-    /**
-     * Categorize error by type
-     */
     static categorizeError(error) {
         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();
-        // 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('connection failed') ||
             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.';
+                return 'Failed to connect to Unreal Engine. Please ensure the Automation Bridge plugin is active and the editor is running.';
             case ErrorType.VALIDATION:
                 return `Invalid input: ${originalMessage}`;
             case ErrorType.UNREAL_ENGINE:
@@ -116,7 +95,6 @@ export class ErrorHandler {
                 return originalMessage;
         }
     }
-    /** Determine if an error is likely retriable */
     static isRetriable(error) {
         try {
             const code = (error?.code || '').toString().toUpperCase();
@@ -132,80 +110,26 @@ export class ErrorHandler {
         catch { }
         return false;
     }
-    /**
-     * Retry an async operation with exponential backoff
-     * Best practice from TypeScript async programming patterns
-     * @param operation - Async operation to retry
-     * @param options - Retry configuration
-     * @returns Result of the operation
-     */
-    static async retryWithBackoff(operation, options = {}) {
-        const { maxRetries = 3, initialDelay = 100, maxDelay = 10000, backoffMultiplier = 2, shouldRetry = (error) => this.isRetriable(error) } = options;
-        let lastError;
+    static async retryWithBackoff(fn, options = {}) {
+        const maxRetries = options.maxRetries ?? 3;
+        const initialDelay = options.initialDelay ?? 1000;
+        const maxDelay = options.maxDelay ?? 10000;
+        const multiplier = options.backoffMultiplier ?? 2;
+        const shouldRetry = options.shouldRetry ?? ((err) => this.isRetriable(err));
         let delay = initialDelay;
         for (let attempt = 0; attempt <= maxRetries; attempt++) {
             try {
-                return await operation();
+                return await fn();
             }
             catch (error) {
-                lastError = error;
                 if (attempt === maxRetries || !shouldRetry(error)) {
                     throw error;
                 }
-                log.debug(`Retry attempt ${attempt + 1}/${maxRetries} after ${delay}ms`);
                 await new Promise(resolve => setTimeout(resolve, delay));
-                delay = Math.min(delay * backoffMultiplier, maxDelay);
+                delay = Math.min(delay * multiplier, maxDelay);
             }
         }
-        throw lastError;
-    }
-    /**
-     * Add timeout to any promise
-     * @param promise - Promise to add timeout to
-     * @param timeoutMs - Timeout in milliseconds
-     * @param errorMessage - Custom error message for timeout
-     * @returns Promise that rejects on timeout
-     */
-    static async withTimeout(promise, timeoutMs, errorMessage = 'Operation timed out') {
-        let timeoutHandle;
-        const timeoutPromise = new Promise((_, reject) => {
-            timeoutHandle = setTimeout(() => {
-                reject(new Error(errorMessage));
-            }, timeoutMs);
-        });
-        try {
-            return await Promise.race([promise, timeoutPromise]);
-        }
-        finally {
-            if (timeoutHandle !== undefined) {
-                clearTimeout(timeoutHandle);
-            }
-        }
-    }
-    /**
-     * Execute multiple operations with Promise.allSettled for better error handling
-     * Returns detailed results for each operation, including failures
-     * @param operations - Array of async operations to execute
-     * @returns Object with successful and failed operations separated
-     */
-    static async batchExecute(operations) {
-        const results = await Promise.allSettled(operations.map(op => op()));
-        const successful = [];
-        const failed = [];
-        results.forEach((result, index) => {
-            if (result.status === 'fulfilled') {
-                successful.push({ index, value: result.value });
-            }
-            else {
-                failed.push({ index, reason: result.reason });
-            }
-        });
-        return {
-            successful,
-            failed,
-            successCount: successful.length,
-            failureCount: failed.length
-        };
+        throw new Error('Max retries exceeded');
     }
 }
 //# sourceMappingURL=error-handler.js.map

package/dist/utils/ini-reader.d.ts

@@ -0,0 +1,3 @@
+export declare function readIniFile(filePath: string): Promise<Record<string, Record<string, string>>>;
+export declare function getProjectSetting(projectPath: string, category: string, sectionName: string, key?: string): Promise<any>;
+//# sourceMappingURL=ini-reader.d.ts.map

package/dist/utils/ini-reader.js

@@ -0,0 +1,69 @@
+import fs from 'fs/promises';
+import path from 'path';
+export async function readIniFile(filePath) {
+    try {
+        const content = await fs.readFile(filePath, 'utf-8');
+        const result = {};
+        let currentSection = '';
+        const lines = content.split(/\r?\n/);
+        for (const line of lines) {
+            const trimmed = line.trim();
+            if (!trimmed || trimmed.startsWith(';') || trimmed.startsWith('#')) {
+                continue;
+            }
+            if (trimmed.startsWith('[') && trimmed.endsWith(']')) {
+                currentSection = trimmed.substring(1, trimmed.length - 1);
+                result[currentSection] = {};
+            }
+            else if (currentSection) {
+                const parts = trimmed.split('=');
+                if (parts.length >= 2) {
+                    const key = parts[0].trim();
+                    const value = parts.slice(1).join('=').trim();
+                    result[currentSection][key] = value;
+                }
+            }
+        }
+        return result;
+    }
+    catch (error) {
+        throw new Error(`Failed to read INI file at ${filePath}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}
+export async function getProjectSetting(projectPath, category, sectionName, key) {
+    let dirPath = projectPath;
+    if (dirPath.toLowerCase().endsWith('.uproject')) {
+        dirPath = path.dirname(dirPath);
+    }
+    const cleanCategory = category.replace(/^Default/, '');
+    const candidates = [
+        path.join(dirPath, 'Config', `Default${cleanCategory}.ini`),
+        path.join(dirPath, 'Saved', 'Config', 'WindowsEditor', `${cleanCategory}.ini`),
+        path.join(dirPath, 'Saved', 'Config', 'Windows', `${cleanCategory}.ini`),
+        path.join(dirPath, 'Saved', 'Config', 'Mac', `${cleanCategory}.ini`),
+        path.join(dirPath, 'Saved', 'Config', 'Linux', `${cleanCategory}.ini`)
+    ];
+    for (const configPath of candidates) {
+        try {
+            const iniData = await readIniFile(configPath);
+            if (sectionName) {
+                const section = iniData[sectionName];
+                if (section) {
+                    if (key) {
+                        return section[key];
+                    }
+                    return section;
+                }
+            }
+            else {
+                if (Object.keys(iniData).length > 0) {
+                    return iniData;
+                }
+            }
+        }
+        catch (_e) {
+        }
+    }
+    return null;
+}
+//# sourceMappingURL=ini-reader.js.map

package/dist/utils/logger.js

@@ -13,16 +13,19 @@ export class Logger {
         return order.indexOf(level) >= order.indexOf(this.level);
     }
     debug(...args) {
-        if (this.shouldLog('debug'))
-            console.error(`[${this.scope}]`, ...args);
+        if (!this.shouldLog('debug'))
+            return;
+        console.error(`[${this.scope}]`, ...args);
     }
     info(...args) {
-        if (this.shouldLog('info'))
-            console.error(`[${this.scope}]`, ...args);
+        if (!this.shouldLog('info'))
+            return;
+        console.error(`[${this.scope}]`, ...args);
     }
     warn(...args) {
-        if (this.shouldLog('warn'))
-            console.error(`[${this.scope}]`, ...args);
+        if (!this.shouldLog('warn'))
+            return;
+        console.warn(`[${this.scope}]`, ...args);
     }
     error(...args) {
         if (this.shouldLog('error'))

package/dist/utils/normalize.d.ts

@@ -14,4 +14,7 @@ export declare function toVec3Object(input: any): Vec3Obj | null;
 export declare function toRotObject(input: any): Rot3Obj | null;
 export declare function toVec3Tuple(input: any): Vec3Tuple | null;
 export declare function toRotTuple(input: any): Rot3Tuple | null;
+export declare function toFiniteNumber(raw: unknown): number | undefined;
+export declare function normalizePartialVector(value: any, alternateKeys?: string[]): Record<string, number> | undefined;
+export declare function normalizeTransformInput(transform: any): Record<string, unknown> | undefined;
 //# sourceMappingURL=normalize.d.ts.map

package/dist/utils/normalize.js

@@ -54,4 +54,60 @@ export function toRotTuple(input) {
     const { pitch, yaw, roll } = rot;
     return [pitch, yaw, roll];
 }
+export function toFiniteNumber(raw) {
+    if (typeof raw === 'number' && Number.isFinite(raw))
+        return raw;
+    if (typeof raw === 'string') {
+        const trimmed = raw.trim();
+        if (trimmed.length === 0)
+            return undefined;
+        const parsed = Number(trimmed);
+        if (Number.isFinite(parsed))
+            return parsed;
+    }
+    return undefined;
+}
+export function normalizePartialVector(value, alternateKeys = ['x', 'y', 'z']) {
+    if (value === undefined || value === null)
+        return undefined;
+    const result = {};
+    const assignIfPresent = (component, raw) => {
+        const num = toFiniteNumber(raw);
+        if (num !== undefined)
+            result[component] = num;
+    };
+    if (Array.isArray(value)) {
+        if (value.length > 0)
+            assignIfPresent('x', value[0]);
+        if (value.length > 1)
+            assignIfPresent('y', value[1]);
+        if (value.length > 2)
+            assignIfPresent('z', value[2]);
+    }
+    else if (typeof value === 'object') {
+        const obj = value;
+        assignIfPresent('x', obj.x ?? obj[alternateKeys[0]]);
+        assignIfPresent('y', obj.y ?? obj[alternateKeys[1]]);
+        assignIfPresent('z', obj.z ?? obj[alternateKeys[2]]);
+    }
+    else {
+        assignIfPresent('x', value);
+    }
+    return Object.keys(result).length > 0 ? result : undefined;
+}
+export function normalizeTransformInput(transform) {
+    if (!transform || typeof transform !== 'object')
+        return undefined;
+    const result = {};
+    const location = normalizePartialVector(transform.location);
+    if (location)
+        result.location = location;
+    const rotation = normalizePartialVector(transform.rotation, ['pitch', 'yaw', 'roll']);
+    if (rotation)
+        result.rotation = rotation;
+    const scale = normalizePartialVector(transform.scale);
+    if (scale)
+        result.scale = scale;
+    return Object.keys(result).length > 0 ? result : undefined;
+}
 //# sourceMappingURL=normalize.js.map

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

@@ -0,0 +1,7 @@
+import { CallToolResult } from '@modelcontextprotocol/sdk/types.js';
+export declare class ResponseFactory {
+    static success(message: string, data?: unknown): CallToolResult;
+    static error(message: string, error?: unknown): CallToolResult;
+    static json(data: unknown): CallToolResult;
+}
+//# sourceMappingURL=response-factory.d.ts.map

package/dist/utils/response-factory.js

@@ -0,0 +1,33 @@
+export class ResponseFactory {
+    static success(message, data) {
+        const content = [{ type: 'text', text: message }];
+        if (data) {
+            content.push({
+                type: 'text',
+                text: JSON.stringify(data, null, 2)
+            });
+        }
+        return {
+            content,
+            isError: false
+        };
+    }
+    static error(message, error) {
+        const errorText = error instanceof Error ? error.message : String(error);
+        const fullMessage = error ? `${message}: ${errorText}` : message;
+        return {
+            content: [{ type: 'text', text: fullMessage }],
+            isError: true
+        };
+    }
+    static json(data) {
+        return {
+            content: [{
+                    type: 'text',
+                    text: JSON.stringify(data, null, 2)
+                }],
+            isError: false
+        };
+    }
+}
+//# sourceMappingURL=response-factory.js.map

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

@@ -1,35 +1,14 @@
-/**
- * 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): {
+    validateResponse(toolName: string, response: any): Promise<{
         valid: boolean;
         errors?: string[];
         structuredContent?: any;
-    };
-    /**
-     * Wrap a tool response with validation and MCP-compliant content shape.
-     *
-     * MCP tools/call responses must contain a `content` array. Many internal
-     * handlers return structured JSON objects (e.g., { success, message, ... }).
-     * This wrapper serializes such objects into a single text block while keeping
-     * existing `content` responses intact.
-     */
-    wrapResponse(toolName: string, response: any): any;
-    /**
-     * Get validation statistics
-     */
+    }>;
+    wrapResponse(toolName: string, response: any): Promise<any>;
     getStats(): {
         totalSchemas: number;
         tools: string[];