unreal-engine-mcp-server 0.4.7 → 0.5.1

package/src/automation/handshake.ts

@@ -0,0 +1,99 @@
+import { WebSocket } from 'ws';
+import { Logger } from '../utils/logger.js';
+import { AutomationBridgeMessage } from './types.js';
+import { EventEmitter } from 'node:events';
+
+export class HandshakeHandler extends EventEmitter {
+    private log = new Logger('HandshakeHandler');
+    private readonly DEFAULT_HANDSHAKE_TIMEOUT_MS = 5000;
+
+    constructor(
+        private capabilityToken?: string
+    ) {
+        super();
+    }
+
+    public initiateHandshake(socket: WebSocket, timeoutMs: number = this.DEFAULT_HANDSHAKE_TIMEOUT_MS): Promise<Record<string, unknown>> {
+        return new Promise((resolve, reject) => {
+            let handshakeComplete = false;
+
+            const timeout = setTimeout(() => {
+                if (!handshakeComplete) {
+                    this.log.warn('Automation bridge client handshake timed out');
+                    socket.close(4002, 'Handshake timeout');
+                    reject(new Error('Handshake timeout'));
+                }
+            }, timeoutMs);
+
+            const onMessage = (data: any) => {
+                let parsed: AutomationBridgeMessage;
+                const text = typeof data === 'string' ? data : data.toString('utf8');
+                try {
+                    parsed = JSON.parse(text) as AutomationBridgeMessage;
+                } catch (error) {
+                    this.log.error('Received non-JSON automation message during handshake', error);
+                    socket.close(4003, 'Invalid JSON payload');
+                    cleanup();
+                    reject(new Error('Invalid JSON payload'));
+                    return;
+                }
+
+                if (parsed.type === 'bridge_ack') {
+                    handshakeComplete = true;
+                    cleanup();
+                    const metadata = this.sanitizeHandshakeMetadata(parsed as Record<string, unknown>);
+                    resolve(metadata);
+                } else {
+                    this.log.warn(`Expected bridge_ack handshake, received ${parsed.type}`);
+                    socket.close(4004, 'Handshake expected bridge_ack');
+                    cleanup();
+                    reject(new Error(`Handshake expected bridge_ack, got ${parsed.type}`));
+                }
+            };
+
+            const onError = (error: Error) => {
+                cleanup();
+                reject(error);
+            };
+
+            const onClose = () => {
+                cleanup();
+                reject(new Error('Socket closed during handshake'));
+            };
+
+            const cleanup = () => {
+                clearTimeout(timeout);
+                socket.off('message', onMessage);
+                socket.off('error', onError);
+                socket.off('close', onClose);
+            };
+
+            socket.on('message', onMessage);
+            socket.on('error', onError);
+            socket.on('close', onClose);
+
+            // Send bridge_hello with a slight delay to ensure the server has registered its handlers
+            setTimeout(() => {
+                if (socket.readyState === WebSocket.OPEN) {
+                    const helloPayload: AutomationBridgeMessage = {
+                        type: 'bridge_hello',
+                        capabilityToken: this.capabilityToken || undefined
+                    };
+                    this.log.debug(`Sending bridge_hello (delayed): ${JSON.stringify(helloPayload)}`);
+                    socket.send(JSON.stringify(helloPayload));
+                } else {
+                    this.log.warn('Socket closed before bridge_hello could be sent');
+                }
+            }, 500);
+        });
+    }
+
+    private sanitizeHandshakeMetadata(payload: Record<string, unknown>): Record<string, unknown> {
+        const sanitized: Record<string, unknown> = { ...payload };
+        delete sanitized.type;
+        if ('capabilityToken' in sanitized) {
+            sanitized.capabilityToken = 'REDACTED';
+        }
+        return sanitized;
+    }
+}

package/src/automation/index.ts

@@ -0,0 +1,2 @@
+export { AutomationBridge } from './bridge.js';
+export * from './types.js';

package/src/automation/message-handler.ts

@@ -0,0 +1,167 @@
+import { Logger } from '../utils/logger.js';
+import { AutomationBridgeMessage, AutomationBridgeResponseMessage } from './types.js';
+import { RequestTracker } from './request-tracker.js';
+
+function FStringSafe(val: unknown): string {
+    try {
+        if (val === undefined || val === null) return '';
+        if (typeof val === 'string') return val;
+        return JSON.stringify(val);
+    } catch {
+        try { return String(val); } catch { return ''; }
+    }
+}
+
+export class MessageHandler {
+    private log = new Logger('MessageHandler');
+
+    constructor(
+        private requestTracker: RequestTracker
+    ) { }
+
+    public handleMessage(message: AutomationBridgeMessage): void {
+        switch (message.type) {
+            case 'automation_response':
+                this.handleAutomationResponse(message as AutomationBridgeResponseMessage);
+                break;
+            case 'bridge_ping':
+                // Handled by connection manager or ignored if client
+                break;
+            case 'bridge_pong':
+                // Handled by connection manager
+                break;
+            case 'bridge_goodbye':
+                this.log.info('Automation bridge client initiated shutdown.', message);
+                break;
+            case 'automation_event':
+                this.handleAutomationEvent(message);
+                break;
+            default:
+                this.log.debug('Received automation bridge message with no handler', message);
+                break;
+        }
+    }
+
+    private handleAutomationResponse(response: AutomationBridgeResponseMessage): void {
+        const requestId = response.requestId;
+        if (!requestId) {
+            this.log.warn('Received automation_response without requestId');
+            return;
+        }
+
+        const pending = this.requestTracker.getPendingRequest(requestId);
+        if (!pending) {
+            this.log.debug(`No pending automation request found for requestId=${requestId}`);
+            return;
+        }
+
+        // Enforce action match logic
+        const enforcedResponse = this.enforceActionMatch(response, pending.action);
+
+        if (pending.waitForEvent) {
+            if (!pending.initialResponse) {
+                // Store initial response and wait for event
+                pending.initialResponse = enforcedResponse;
+
+                // If the initial response indicates failure, resolve immediately
+                if (enforcedResponse.success === false) {
+                    this.requestTracker.resolveRequest(requestId, enforcedResponse);
+                    return;
+                }
+
+                // If the response indicates it's already saved/done, resolve immediately
+                const result = enforcedResponse.result as any;
+                if (result && result.saved === true) {
+                    this.requestTracker.resolveRequest(requestId, enforcedResponse);
+                    return;
+                }
+
+                // Set event timeout
+                const eventTimeoutMs = pending.eventTimeoutMs || 30000; // Default 30s for event
+                pending.eventTimeout = setTimeout(() => {
+                    this.requestTracker.rejectRequest(requestId, new Error(`Timed out waiting for completion event for ${pending.action}`));
+                }, eventTimeoutMs);
+
+                this.log.debug(`Received initial response for ${pending.action}, waiting for completion event...`);
+            } else {
+                // Second response, treat as completion
+                this.requestTracker.resolveRequest(requestId, enforcedResponse);
+            }
+        } else {
+            this.requestTracker.resolveRequest(requestId, enforcedResponse);
+        }
+    }
+
+    private handleAutomationEvent(message: AutomationBridgeMessage): void {
+        const evt: any = message as any;
+        const reqId = typeof evt.requestId === 'string' ? evt.requestId : undefined;
+
+        if (reqId) {
+            const pending = this.requestTracker.getPendingRequest(reqId);
+            if (pending) {
+                try {
+                    const baseSuccess = (pending.initialResponse && typeof pending.initialResponse.success === 'boolean') ? pending.initialResponse.success : undefined;
+                    const evtSuccess = (evt.result && typeof evt.result.success === 'boolean') ? !!evt.result.success : undefined;
+
+                    const synthetic: AutomationBridgeResponseMessage = {
+                        type: 'automation_response',
+                        requestId: reqId,
+                        success: evtSuccess !== undefined ? evtSuccess : (baseSuccess !== undefined ? baseSuccess : undefined as any),
+                        message: typeof evt.result?.message === 'string' ? evt.result.message : (typeof evt.message === 'string' ? evt.message : FStringSafe(evt.event)),
+                        error: typeof evt.result?.error === 'string' ? evt.result.error : undefined,
+                        result: evt.result ?? evt.payload ?? undefined
+                    };
+
+                    this.log.info(`automation_event resolved pending request ${reqId} (event=${String(evt.event || '')})`);
+                    this.requestTracker.resolveRequest(reqId, synthetic);
+                } catch (e) {
+                    this.log.warn(`Failed to resolve pending automation request from automation_event ${reqId}: ${String(e)}`);
+                }
+                return;
+            }
+        }
+
+        this.log.debug('Received automation_event (no pending request):', message);
+    }
+
+    private enforceActionMatch(response: AutomationBridgeResponseMessage, expectedAction: string): AutomationBridgeResponseMessage {
+        try {
+            const expected = (expectedAction || '').toString().toLowerCase();
+            const echoed: string | undefined = (() => {
+                const r: any = response as any;
+                const candidate = (typeof r.action === 'string' && r.action) || (typeof r.result?.action === 'string' && r.result.action);
+                return candidate as any;
+            })();
+
+            if (expected && echoed && typeof echoed === 'string') {
+                const got = echoed.toLowerCase();
+
+                const consolidatedToolActions = new Set([
+                    'animation_physics',
+                    'create_effect',
+                    'build_environment',
+                    'system_control',
+                    'manage_ui'
+                ]);
+
+                if (consolidatedToolActions.has(expected) && got !== expected) {
+                    return response;
+                }
+
+                const startsEitherWay = got.startsWith(expected) || expected.startsWith(got);
+
+                if (!startsEitherWay) {
+                    const mutated: any = { ...response };
+                    mutated.success = false;
+                    if (!mutated.error) mutated.error = 'ACTION_PREFIX_MISMATCH';
+                    const msgBase = typeof mutated.message === 'string' ? mutated.message + ' ' : '';
+                    mutated.message = `${msgBase}Response action mismatch (expected~='${expected}', got='${echoed}')`;
+                    return mutated as AutomationBridgeResponseMessage;
+                }
+            }
+        } catch (e) {
+            this.log.debug('enforceActionMatch check skipped', e as any);
+        }
+        return response;
+    }
+}

package/src/automation/request-tracker.ts

@@ -0,0 +1,123 @@
+import { PendingRequest, AutomationBridgeResponseMessage } from './types.js';
+import { randomUUID, createHash } from 'node:crypto';
+
+// Disabled: The two-phase event pattern was causing timeouts because C++ handlers
+// send a single response, not request+event. All actions now use simple request-response.
+const WAIT_FOR_EVENT_ACTIONS = new Set<string>([
+    // Empty - all actions use single response pattern
+]);
+
+export class RequestTracker {
+    private pendingRequests = new Map<string, PendingRequest>();
+    private coalescedRequests = new Map<string, Promise<AutomationBridgeResponseMessage>>();
+
+
+    constructor(
+        private maxPendingRequests: number
+    ) { }
+
+    public createRequest(
+        action: string,
+        payload: Record<string, unknown>,
+        timeoutMs: number
+    ): { requestId: string; promise: Promise<AutomationBridgeResponseMessage> } {
+        if (this.pendingRequests.size >= this.maxPendingRequests) {
+            throw new Error(`Max pending requests limit reached (${this.maxPendingRequests})`);
+        }
+
+        const requestId = randomUUID();
+        const waitForEvent = WAIT_FOR_EVENT_ACTIONS.has(action);
+
+        const promise = new Promise<AutomationBridgeResponseMessage>((resolve, reject) => {
+            const timeout = setTimeout(() => {
+                if (this.pendingRequests.has(requestId)) {
+                    this.pendingRequests.delete(requestId);
+                    reject(new Error(`Request ${requestId} timed out after ${timeoutMs}ms`));
+                }
+            }, timeoutMs);
+
+            this.pendingRequests.set(requestId, {
+                resolve,
+                reject,
+                timeout,
+                action,
+                payload,
+                requestedAt: new Date(),
+                waitForEvent,
+                eventTimeoutMs: timeoutMs
+            });
+        });
+
+        return { requestId, promise };
+    }
+
+    public getPendingRequest(requestId: string): PendingRequest | undefined {
+        return this.pendingRequests.get(requestId);
+    }
+
+    public resolveRequest(requestId: string, response: AutomationBridgeResponseMessage): void {
+        const pending = this.pendingRequests.get(requestId);
+        if (pending) {
+            clearTimeout(pending.timeout);
+            if (pending.eventTimeout) clearTimeout(pending.eventTimeout);
+            this.pendingRequests.delete(requestId);
+            pending.resolve(response);
+        }
+    }
+
+    public rejectRequest(requestId: string, error: Error): void {
+        const pending = this.pendingRequests.get(requestId);
+        if (pending) {
+            clearTimeout(pending.timeout);
+            if (pending.eventTimeout) clearTimeout(pending.eventTimeout);
+            this.pendingRequests.delete(requestId);
+            pending.reject(error);
+        }
+    }
+
+    public rejectAll(error: Error): void {
+        for (const [, pending] of this.pendingRequests) {
+            clearTimeout(pending.timeout);
+            if (pending.eventTimeout) clearTimeout(pending.eventTimeout);
+            pending.reject(error);
+        }
+        this.pendingRequests.clear();
+    }
+
+    public getPendingCount(): number {
+        return this.pendingRequests.size;
+    }
+
+    public getPendingDetails(): Array<{ requestId: string; action: string; ageMs: number }> {
+        const now = Date.now();
+        return Array.from(this.pendingRequests.entries()).map(([id, pending]) => ({
+            requestId: id,
+            action: pending.action,
+            ageMs: Math.max(0, now - pending.requestedAt.getTime())
+        }));
+    }
+
+    public getCoalescedRequest(key: string): Promise<AutomationBridgeResponseMessage> | undefined {
+        return this.coalescedRequests.get(key);
+    }
+
+    public setCoalescedRequest(key: string, promise: Promise<AutomationBridgeResponseMessage>): void {
+        this.coalescedRequests.set(key, promise);
+        // Remove from map when settled
+        promise.finally(() => {
+            if (this.coalescedRequests.get(key) === promise) {
+                this.coalescedRequests.delete(key);
+            }
+        });
+    }
+
+    public createCoalesceKey(action: string, payload: Record<string, unknown>): string {
+        // Only coalesce read-only operations
+        const readOnlyActions = ['list', 'get_', 'exists', 'search', 'find'];
+        if (!readOnlyActions.some(a => action.startsWith(a))) return '';
+
+        // Create a stable hash of the payload
+        const stablePayload = JSON.stringify(payload, Object.keys(payload).sort());
+        return `${action}:${createHash('md5').update(stablePayload).digest('hex')}`;
+    }
+}

package/src/automation/types.ts

@@ -0,0 +1,107 @@
+import { WebSocket } from 'ws';
+
+export interface AutomationBridgeOptions {
+    host?: string;
+    port?: number;
+    ports?: number[];
+    protocols?: string[];
+    capabilityToken?: string;
+    enabled?: boolean;
+    serverName?: string;
+    serverVersion?: string;
+    heartbeatIntervalMs?: number;
+    maxPendingRequests?: number;
+    maxConcurrentConnections?: number;
+    clientMode?: boolean;
+    clientHost?: string;
+    clientPort?: number;
+    serverLegacyEnabled?: boolean;
+}
+
+export interface AutomationBridgeMessage {
+    type: string;
+    [key: string]: unknown;
+}
+
+export interface AutomationBridgeResponseMessage extends AutomationBridgeMessage {
+    requestId: string;
+    success?: boolean;
+    message?: string;
+    error?: string;
+    result?: unknown;
+}
+
+export interface AutomationBridgeStatus {
+    enabled: boolean;
+    host: string;
+    port: number;
+    configuredPorts: number[];
+    listeningPorts: number[];
+    connected: boolean;
+    connectedAt: string | null;
+    activePort: number | null;
+    negotiatedProtocol: string | null;
+    supportedProtocols: string[];
+    supportedOpcodes: string[];
+    expectedResponseOpcodes: string[];
+    capabilityTokenRequired: boolean;
+    lastHandshakeAt: string | null;
+    lastHandshakeMetadata: Record<string, unknown> | null;
+    lastHandshakeAck: Record<string, unknown> | null;
+    lastHandshakeFailure: { reason: string; at: string } | null;
+    lastDisconnect: { code: number; reason: string; at: string } | null;
+    lastError: { message: string; at: string } | null;
+    lastMessageAt: string | null;
+    lastRequestSentAt: string | null;
+    pendingRequests: number;
+    pendingRequestDetails: Array<{ requestId: string; action: string; ageMs: number }>;
+    connections: Array<{
+        connectionId: string;
+        sessionId: string | null;
+        remoteAddress: string | null;
+        remotePort: number | null;
+        port: number;
+        connectedAt: string;
+        protocol: string | null;
+        readyState: number;
+        isPrimary: boolean;
+    }>;
+    webSocketListening: boolean;
+    serverLegacyEnabled: boolean;
+    serverName: string;
+    serverVersion: string;
+    maxConcurrentConnections: number;
+    maxPendingRequests: number;
+    heartbeatIntervalMs: number;
+}
+
+export interface PendingRequest {
+    resolve: (value: AutomationBridgeResponseMessage) => void;
+    reject: (reason: Error) => void;
+    timeout: NodeJS.Timeout;
+    action: string;
+    payload: Record<string, unknown>;
+    requestedAt: Date;
+    waitForEvent?: boolean;
+    eventTimeout?: NodeJS.Timeout | undefined;
+    eventTimeoutMs?: number | undefined;
+    initialResponse?: AutomationBridgeResponseMessage | undefined;
+}
+
+export interface SocketInfo {
+    connectionId: string;
+    port: number;
+    connectedAt: Date;
+    protocol?: string;
+    sessionId?: string;
+    remoteAddress?: string;
+    remotePort?: number;
+}
+
+export type AutomationBridgeEvents = {
+    connected: (info: { socket: WebSocket; metadata: Record<string, unknown>; port: number; protocol: string | null }) => void;
+    disconnected: (info: { code: number; reason: string; port: number; protocol: string | null }) => void;
+    message: (message: AutomationBridgeMessage) => void;
+    error: (error: Error & { port?: number }) => void;
+    handshakeFailed: (info: { reason: string; port: number }) => void;
+};

package/src/cli.ts

@@ -1,7 +1,34 @@
 #!/usr/bin/env node
-import { startStdioServer } from './index.js';
-
-startStdioServer().catch((err) => {
-  console.error('Failed to start server:', err);
-  process.exit(1);
-});
+// Dynamic import loader: prefer compiled JS when present (./index.js) but
+// gracefully fall back to TypeScript source (./index.ts) when running via
+// ts-node-esm or similar dev workflows where compiled JS isn't available.
+(async () => {
+  try {
+    const m = await import('./index.js');
+    if (m && typeof m.startStdioServer === 'function') {
+      await m.startStdioServer();
+    } else {
+      throw new Error('startStdioServer not exported from index.js');
+    }
+  } catch (err) {
+    // If index.js cannot be resolved, try importing the TypeScript source
+    // at runtime (useful when running via ts-node-esm). Cast the error to
+    // `any` when inspecting runtime-only properties like `code`.
+    if (err && (((err as any).code === 'ERR_MODULE_NOT_FOUND') || String(err).includes('Unable to resolve'))) {
+      try {
+          const tsModuleSpecifier = new URL('./index.ts', import.meta.url).href;
+          const m2 = await import(tsModuleSpecifier);
+          if (m2 && typeof m2.startStdioServer === 'function') {
+            await m2.startStdioServer();
+          } else {
+            throw new Error('startStdioServer not exported from index.ts');
+          }
+      } catch (err2) {
+        console.error('Failed to start server (fallback to TypeScript failed):', err2);
+        process.exit(1);
+      }
+    }
+    console.error('Failed to start server:', err);
+    process.exit(1);
+  }
+})();

package/src/config.ts

@@ -0,0 +1,73 @@
+import { z } from 'zod';
+import { Logger } from './utils/logger.js';
+import dotenv from 'dotenv';
+
+// Suppress dotenv output to avoid corrupting MCP stdout stream
+const originalWrite = process.stdout.write;
+process.stdout.write = function () { return true; } as any;
+try {
+  dotenv.config();
+} finally {
+  process.stdout.write = originalWrite;
+}
+
+const log = new Logger('Config');
+
+const stringToBoolean = (val: unknown) => {
+  if (typeof val === 'boolean') return val;
+  if (typeof val === 'string') {
+    const lower = val.toLowerCase().trim();
+    return lower === 'true' || lower === '1' || lower === 'on';
+  }
+  return false;
+};
+
+const stringToNumber = (val: unknown, defaultVal: number) => {
+  if (typeof val === 'number') return val;
+  if (typeof val === 'string') {
+    const parsed = parseInt(val, 10);
+    return isNaN(parsed) ? defaultVal : parsed;
+  }
+  return defaultVal;
+};
+
+export const EnvSchema = z.object({
+  // Server Settings
+  NODE_ENV: z.enum(['development', 'production', 'test']).default('development'),
+  LOG_LEVEL: z.enum(['debug', 'info', 'warn', 'error']).default('debug'),
+  MCP_ROUTE_STDOUT_LOGS: z.preprocess(stringToBoolean, z.boolean().default(true)),
+
+  // Unreal Settings
+  UE_PROJECT_PATH: z.string().optional(),
+  UE_EDITOR_EXE: z.string().optional(),
+
+
+  // Connection Settings
+  MCP_AUTOMATION_PORT: z.preprocess((v) => stringToNumber(v, 8091), z.number().default(8091)),
+  MCP_AUTOMATION_HOST: z.string().default('127.0.0.1'),
+  MCP_AUTOMATION_CLIENT_MODE: z.preprocess(stringToBoolean, z.boolean().default(false)),
+
+  // Timeouts
+  MCP_CONNECTION_TIMEOUT_MS: z.preprocess((v) => stringToNumber(v, 5000), z.number().default(5000)),
+  MCP_REQUEST_TIMEOUT_MS: z.preprocess((v) => stringToNumber(v, 30000), z.number().default(30000)),
+});
+
+export type Config = z.infer<typeof EnvSchema>;
+
+let config: Config;
+
+try {
+  config = EnvSchema.parse(process.env);
+  log.debug('Configuration loaded successfully');
+} catch (error) {
+  if (error instanceof z.ZodError) {
+    log.error('❌ Invalid configuration:', error.format());
+    log.warn('⚠️ Falling back to safe defaults.');
+    // Fallback to parsing an empty object to get all defaults
+    config = EnvSchema.parse({});
+  } else {
+    throw error;
+  }
+}
+
+export { config };

package/src/constants.ts

@@ -0,0 +1,19 @@
+// Shared runtime defaults and protocol constants
+export const DEFAULT_AUTOMATION_HOST = '127.0.0.1';
+export const DEFAULT_AUTOMATION_PORT = 8090;
+export const DEFAULT_AUTOMATION_PORTS = [8090, 8091];
+export const DEFAULT_NEGOTIATED_PROTOCOLS = ['mcp-automation'];
+export const DEFAULT_HEARTBEAT_INTERVAL_MS = 10000;
+export const DEFAULT_HANDSHAKE_TIMEOUT_MS = 5000;
+export const DEFAULT_MAX_PENDING_REQUESTS = 25;
+export const DEFAULT_TIME_OF_DAY = 9;
+export const DEFAULT_SUN_INTENSITY = 10000;
+export const DEFAULT_SKYLIGHT_INTENSITY = 1;
+
+export const DEFAULT_SCREENSHOT_RESOLUTION = '1920x1080';
+
+// Operation Timeouts
+export const DEFAULT_OPERATION_TIMEOUT_MS = 30000;
+export const DEFAULT_ASSET_OP_TIMEOUT_MS = 60000;
+export const EXTENDED_ASSET_OP_TIMEOUT_MS = 120000;
+export const LONG_RUNNING_OP_TIMEOUT_MS = 300000;