unreal-engine-mcp-server 0.4.6 → 0.5.0

package/dist/automation/index.js

@@ -0,0 +1,3 @@
+export { AutomationBridge } from './bridge.js';
+export * from './types.js';
+//# sourceMappingURL=index.js.map

package/dist/automation/message-handler.d.ts

@@ -0,0 +1,12 @@
+import { AutomationBridgeMessage } from './types.js';
+import { RequestTracker } from './request-tracker.js';
+export declare class MessageHandler {
+    private requestTracker;
+    private log;
+    constructor(requestTracker: RequestTracker);
+    handleMessage(message: AutomationBridgeMessage): void;
+    private handleAutomationResponse;
+    private handleAutomationEvent;
+    private enforceActionMatch;
+}
+//# sourceMappingURL=message-handler.d.ts.map

package/dist/automation/message-handler.js

@@ -0,0 +1,149 @@
+import { Logger } from '../utils/logger.js';
+function FStringSafe(val) {
+    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 {
+    requestTracker;
+    log = new Logger('MessageHandler');
+    constructor(requestTracker) {
+        this.requestTracker = requestTracker;
+    }
+    handleMessage(message) {
+        switch (message.type) {
+            case 'automation_response':
+                this.handleAutomationResponse(message);
+                break;
+            case 'bridge_ping':
+                break;
+            case 'bridge_pong':
+                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;
+        }
+    }
+    handleAutomationResponse(response) {
+        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;
+        }
+        const enforcedResponse = this.enforceActionMatch(response, pending.action);
+        if (pending.waitForEvent) {
+            if (!pending.initialResponse) {
+                pending.initialResponse = enforcedResponse;
+                if (enforcedResponse.success === false) {
+                    this.requestTracker.resolveRequest(requestId, enforcedResponse);
+                    return;
+                }
+                const result = enforcedResponse.result;
+                if (result && result.saved === true) {
+                    this.requestTracker.resolveRequest(requestId, enforcedResponse);
+                    return;
+                }
+                const eventTimeoutMs = pending.eventTimeoutMs || 30000;
+                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 {
+                this.requestTracker.resolveRequest(requestId, enforcedResponse);
+            }
+        }
+        else {
+            this.requestTracker.resolveRequest(requestId, enforcedResponse);
+        }
+    }
+    handleAutomationEvent(message) {
+        const evt = message;
+        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 = {
+                        type: 'automation_response',
+                        requestId: reqId,
+                        success: evtSuccess !== undefined ? evtSuccess : (baseSuccess !== undefined ? baseSuccess : undefined),
+                        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);
+    }
+    enforceActionMatch(response, expectedAction) {
+        try {
+            const expected = (expectedAction || '').toString().toLowerCase();
+            const echoed = (() => {
+                const r = response;
+                const candidate = (typeof r.action === 'string' && r.action) || (typeof r.result?.action === 'string' && r.result.action);
+                return candidate;
+            })();
+            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 = { ...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;
+                }
+            }
+        }
+        catch (e) {
+            this.log.debug('enforceActionMatch check skipped', e);
+        }
+        return response;
+    }
+}
+//# sourceMappingURL=message-handler.js.map

package/dist/automation/request-tracker.d.ts

@@ -0,0 +1,25 @@
+import { PendingRequest, AutomationBridgeResponseMessage } from './types.js';
+export declare class RequestTracker {
+    private maxPendingRequests;
+    private pendingRequests;
+    private coalescedRequests;
+    constructor(maxPendingRequests: number);
+    createRequest(action: string, payload: Record<string, unknown>, timeoutMs: number): {
+        requestId: string;
+        promise: Promise<AutomationBridgeResponseMessage>;
+    };
+    getPendingRequest(requestId: string): PendingRequest | undefined;
+    resolveRequest(requestId: string, response: AutomationBridgeResponseMessage): void;
+    rejectRequest(requestId: string, error: Error): void;
+    rejectAll(error: Error): void;
+    getPendingCount(): number;
+    getPendingDetails(): Array<{
+        requestId: string;
+        action: string;
+        ageMs: number;
+    }>;
+    getCoalescedRequest(key: string): Promise<AutomationBridgeResponseMessage> | undefined;
+    setCoalescedRequest(key: string, promise: Promise<AutomationBridgeResponseMessage>): void;
+    createCoalesceKey(action: string, payload: Record<string, unknown>): string;
+}
+//# sourceMappingURL=request-tracker.d.ts.map

package/dist/automation/request-tracker.js

@@ -0,0 +1,98 @@
+import { randomUUID, createHash } from 'node:crypto';
+const WAIT_FOR_EVENT_ACTIONS = new Set([]);
+export class RequestTracker {
+    maxPendingRequests;
+    pendingRequests = new Map();
+    coalescedRequests = new Map();
+    constructor(maxPendingRequests) {
+        this.maxPendingRequests = maxPendingRequests;
+    }
+    createRequest(action, payload, timeoutMs) {
+        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((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 };
+    }
+    getPendingRequest(requestId) {
+        return this.pendingRequests.get(requestId);
+    }
+    resolveRequest(requestId, response) {
+        const pending = this.pendingRequests.get(requestId);
+        if (pending) {
+            clearTimeout(pending.timeout);
+            if (pending.eventTimeout)
+                clearTimeout(pending.eventTimeout);
+            this.pendingRequests.delete(requestId);
+            pending.resolve(response);
+        }
+    }
+    rejectRequest(requestId, error) {
+        const pending = this.pendingRequests.get(requestId);
+        if (pending) {
+            clearTimeout(pending.timeout);
+            if (pending.eventTimeout)
+                clearTimeout(pending.eventTimeout);
+            this.pendingRequests.delete(requestId);
+            pending.reject(error);
+        }
+    }
+    rejectAll(error) {
+        for (const [, pending] of this.pendingRequests) {
+            clearTimeout(pending.timeout);
+            if (pending.eventTimeout)
+                clearTimeout(pending.eventTimeout);
+            pending.reject(error);
+        }
+        this.pendingRequests.clear();
+    }
+    getPendingCount() {
+        return this.pendingRequests.size;
+    }
+    getPendingDetails() {
+        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())
+        }));
+    }
+    getCoalescedRequest(key) {
+        return this.coalescedRequests.get(key);
+    }
+    setCoalescedRequest(key, promise) {
+        this.coalescedRequests.set(key, promise);
+        promise.finally(() => {
+            if (this.coalescedRequests.get(key) === promise) {
+                this.coalescedRequests.delete(key);
+            }
+        });
+    }
+    createCoalesceKey(action, payload) {
+        const readOnlyActions = ['list', 'get_', 'exists', 'search', 'find'];
+        if (!readOnlyActions.some(a => action.startsWith(a)))
+            return '';
+        const stablePayload = JSON.stringify(payload, Object.keys(payload).sort());
+        return `${action}:${createHash('md5').update(stablePayload).digest('hex')}`;
+    }
+}
+//# sourceMappingURL=request-tracker.js.map

package/dist/automation/types.d.ts

@@ -0,0 +1,130 @@
+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;
+};
+//# sourceMappingURL=types.d.ts.map

package/dist/automation/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/cli.js

@@ -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);
-});
+(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 (err && ((err.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);
+    }
+})();
+export {};
 //# sourceMappingURL=cli.js.map

package/dist/config.d.ts

@@ -0,0 +1,27 @@
+import { z } from 'zod';
+export declare const EnvSchema: z.ZodObject<{
+    NODE_ENV: z.ZodDefault<z.ZodEnum<{
+        development: "development";
+        production: "production";
+        test: "test";
+    }>>;
+    LOG_LEVEL: z.ZodDefault<z.ZodEnum<{
+        debug: "debug";
+        info: "info";
+        warn: "warn";
+        error: "error";
+    }>>;
+    MCP_ROUTE_STDOUT_LOGS: z.ZodPipe<z.ZodTransform<boolean, unknown>, z.ZodDefault<z.ZodBoolean>>;
+    UE_PROJECT_PATH: z.ZodOptional<z.ZodString>;
+    UE_EDITOR_EXE: z.ZodOptional<z.ZodString>;
+    UE_SCREENSHOT_DIR: z.ZodOptional<z.ZodString>;
+    MCP_AUTOMATION_PORT: z.ZodPipe<z.ZodTransform<number, unknown>, z.ZodDefault<z.ZodNumber>>;
+    MCP_AUTOMATION_HOST: z.ZodDefault<z.ZodString>;
+    MCP_AUTOMATION_CLIENT_MODE: z.ZodPipe<z.ZodTransform<boolean, unknown>, z.ZodDefault<z.ZodBoolean>>;
+    MCP_CONNECTION_TIMEOUT_MS: z.ZodPipe<z.ZodTransform<number, unknown>, z.ZodDefault<z.ZodNumber>>;
+    MCP_REQUEST_TIMEOUT_MS: z.ZodPipe<z.ZodTransform<number, unknown>, z.ZodDefault<z.ZodNumber>>;
+}, z.core.$strip>;
+export type Config = z.infer<typeof EnvSchema>;
+declare let config: Config;
+export { config };
+//# sourceMappingURL=config.d.ts.map

package/dist/config.js

@@ -0,0 +1,60 @@
+import { z } from 'zod';
+import { Logger } from './utils/logger.js';
+import dotenv from 'dotenv';
+const originalWrite = process.stdout.write;
+process.stdout.write = function () { return true; };
+try {
+    dotenv.config();
+}
+finally {
+    process.stdout.write = originalWrite;
+}
+const log = new Logger('Config');
+const stringToBoolean = (val) => {
+    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, defaultVal) => {
+    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({
+    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)),
+    UE_PROJECT_PATH: z.string().optional(),
+    UE_EDITOR_EXE: z.string().optional(),
+    UE_SCREENSHOT_DIR: z.string().optional(),
+    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)),
+    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)),
+});
+let 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.');
+        config = EnvSchema.parse({});
+    }
+    else {
+        throw error;
+    }
+}
+export { config };
+//# sourceMappingURL=config.js.map

package/dist/constants.d.ts

@@ -0,0 +1,12 @@
+export declare const DEFAULT_AUTOMATION_HOST = "127.0.0.1";
+export declare const DEFAULT_AUTOMATION_PORT = 8090;
+export declare const DEFAULT_AUTOMATION_PORTS: number[];
+export declare const DEFAULT_NEGOTIATED_PROTOCOLS: string[];
+export declare const DEFAULT_HEARTBEAT_INTERVAL_MS = 10000;
+export declare const DEFAULT_HANDSHAKE_TIMEOUT_MS = 5000;
+export declare const DEFAULT_MAX_PENDING_REQUESTS = 25;
+export declare const DEFAULT_TIME_OF_DAY = 9;
+export declare const DEFAULT_SUN_INTENSITY = 10000;
+export declare const DEFAULT_SKYLIGHT_INTENSITY = 1;
+export declare const DEFAULT_SCREENSHOT_RESOLUTION = "1920x1080";
+//# sourceMappingURL=constants.d.ts.map

package/dist/constants.js

@@ -0,0 +1,12 @@
+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';
+//# sourceMappingURL=constants.js.map