unreal-engine-mcp-server 0.5.4 → 0.5.5

package/src/automation/types.ts

@@ -1,108 +0,0 @@
-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;
-    maxQueuedRequests?: 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,34 +0,0 @@
-#!/usr/bin/env node
-// 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/class-aliases.ts

@@ -1,65 +0,0 @@
-/**
- * Shared configuration for Unreal Engine class names and aliases.
- * Centralizes class mappings to avoid duplication across handlers.
- */
-
-/**
- * User-friendly class name aliases to full Unreal class paths.
- * These allow users to specify simpler names like 'PointLight' instead of '/Script/Engine.PointLight'.
- */
-export const ACTOR_CLASS_ALIASES: Record<string, string> = {
-    // Special cases that need component addition
-    'SplineActor': '/Script/Engine.Actor',
-    'Spline': '/Script/Engine.Actor',
-
-    // Light actors
-    'PointLight': '/Script/Engine.PointLight',
-    'SpotLight': '/Script/Engine.SpotLight',
-    'DirectionalLight': '/Script/Engine.DirectionalLight',
-    'RectLight': '/Script/Engine.RectLight',
-
-    // Camera actors
-    'Camera': '/Script/Engine.CameraActor',
-    'CameraActor': '/Script/Engine.CameraActor',
-
-    // Mesh actors
-    'StaticMeshActor': '/Script/Engine.StaticMeshActor',
-    'SkeletalMeshActor': '/Script/Engine.SkeletalMeshActor',
-
-    // Gameplay actors
-    'PlayerStart': '/Script/Engine.PlayerStart',
-    'Pawn': '/Script/Engine.Pawn',
-    'Character': '/Script/Engine.Character',
-    'Actor': '/Script/Engine.Actor',
-
-    // Trigger volumes
-    'TriggerBox': '/Script/Engine.TriggerBox',
-    'TriggerSphere': '/Script/Engine.TriggerSphere',
-    'BlockingVolume': '/Script/Engine.BlockingVolume',
-};
-
-/**
- * Class aliases that require a component to be auto-added after spawning.
- */
-export const CLASSES_REQUIRING_COMPONENT: Record<string, string> = {
-    'SplineActor': 'SplineComponent',
-    'Spline': 'SplineComponent',
-};
-
-/**
- * Resolve a class name alias to its full Unreal class path.
- * @param classNameOrPath - The class name or alias to resolve
- * @returns The full class path, or the original if not an alias
- */
-export function resolveClassAlias(classNameOrPath: string): string {
-    return ACTOR_CLASS_ALIASES[classNameOrPath] || classNameOrPath;
-}
-
-/**
- * Check if a class alias requires an auto-added component.
- * @param className - The original class name or alias
- * @returns The component name to add, or undefined
- */
-export function getRequiredComponent(className: string): string | undefined {
-    return CLASSES_REQUIRING_COMPONENT[className];
-}

package/src/config.ts

@@ -1,73 +0,0 @@
-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

@@ -1,29 +0,0 @@
-// 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_MAX_QUEUED_REQUESTS = 100;
-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;
-
-// Command-specific timeouts
-export const CONSOLE_COMMAND_TIMEOUT_MS = 30000;
-export const ENGINE_QUERY_TIMEOUT_MS = 15000;
-export const CONNECTION_TIMEOUT_MS = 15000;
-
-// Message size limits
-export const MAX_WS_MESSAGE_SIZE_BYTES = 5 * 1024 * 1024;
-

package/src/graphql/loaders.ts

@@ -1,244 +0,0 @@
-/**
- * DataLoader instances for GraphQL N+1 query optimization
- * 
- * DataLoaders batch and cache requests within a single GraphQL request,
- * preventing the N+1 query problem when resolving nested fields.
- */
-
-import DataLoader from 'dataloader';
-import type { AutomationBridge } from '../automation/index.js';
-import { Logger } from '../utils/logger.js';
-
-const log = new Logger('GraphQL:Loaders');
-
-// ============================================================================
-// Types
-// ============================================================================
-
-export interface Actor {
-    name: string;
-    label?: string;
-    class?: string;
-    path?: string;
-    location?: { x: number; y: number; z: number };
-    rotation?: { pitch: number; yaw: number; roll: number };
-    scale?: { x: number; y: number; z: number };
-    tags?: string[];
-}
-
-export interface Asset {
-    name: string;
-    path: string;
-    class?: string;
-    packagePath?: string;
-    size?: number;
-}
-
-export interface Blueprint {
-    name: string;
-    path: string;
-    parentClass?: string;
-    variables?: Array<{ name: string; type: string; defaultValue?: unknown }>;
-    functions?: Array<{ name: string; parameters?: Array<{ name: string; type: string }> }>;
-    components?: Array<{ name: string; type: string }>;
-}
-
-// ============================================================================
-// Loader Factory
-// ============================================================================
-
-export interface GraphQLLoaders {
-    actorLoader: DataLoader<string, Actor | null>;
-    assetLoader: DataLoader<string, Asset | null>;
-    blueprintLoader: DataLoader<string, Blueprint | null>;
-    actorComponentsLoader: DataLoader<string, Array<{ name: string; type: string }> | null>;
-}
-
-/**
- * Creates DataLoader instances for a GraphQL request context.
- * 
- * Each GraphQL request should have its own set of loaders to ensure
- * proper request-scoped caching and batching.
- */
-export function createLoaders(automationBridge: AutomationBridge): GraphQLLoaders {
-    return {
-        /**
-         * Batches actor fetches by name
-         */
-        actorLoader: new DataLoader<string, Actor | null>(
-            async (names: readonly string[]) => {
-                log.debug(`Batching actor fetch for ${names.length} actors`);
-
-                try {
-                    // Use batch fetch if available, otherwise fall back to individual fetches
-                    const result = await automationBridge.sendAutomationRequest<{
-                        success: boolean;
-                        actors?: Actor[];
-                    }>('control_actor', {
-                        action: 'batch_get',
-                        actorNames: [...names]
-                    });
-
-                    if (result.success && result.actors) {
-                        // Map results back to input order
-                        return names.map(name =>
-                            result.actors?.find(a => a.name === name || a.label === name) ?? null
-                        );
-                    }
-                } catch {
-                    log.debug('Batch fetch not supported, falling back to individual fetches');
-                }
-
-                // Fallback: fetch individually
-                const results = await Promise.all(
-                    names.map(async (name) => {
-                        try {
-                            const result = await automationBridge.sendAutomationRequest<{
-                                success: boolean;
-                                actor?: Actor;
-                            }>('control_actor', {
-                                action: 'find_by_name',
-                                actorName: name
-                            });
-                            return result.success ? (result.actor ?? null) : null;
-                        } catch {
-                            return null;
-                        }
-                    })
-                );
-                return results;
-            },
-            {
-                cache: true,
-                maxBatchSize: 50
-            }
-        ),
-
-        /**
-         * Batches asset fetches by path
-         */
-        assetLoader: new DataLoader<string, Asset | null>(
-            async (paths: readonly string[]) => {
-                log.debug(`Batching asset fetch for ${paths.length} assets`);
-
-                try {
-                    const result = await automationBridge.sendAutomationRequest<{
-                        success: boolean;
-                        assets?: Asset[];
-                    }>('manage_asset', {
-                        action: 'batch_get',
-                        assetPaths: [...paths]
-                    });
-
-                    if (result.success && result.assets) {
-                        return paths.map(path =>
-                            result.assets?.find(a => a.path === path) ?? null
-                        );
-                    }
-                } catch {
-                    log.debug('Batch asset fetch not supported');
-                }
-
-                // Fallback: check existence individually
-                const results = await Promise.all(
-                    paths.map(async (path) => {
-                        try {
-                            const result = await automationBridge.sendAutomationRequest<{
-                                success: boolean;
-                                exists?: boolean;
-                                asset?: Asset;
-                            }>('manage_asset', {
-                                action: 'exists',
-                                assetPath: path
-                            });
-
-                            if (result.success && result.exists) {
-                                return result.asset ?? { name: path.split('/').pop() || '', path };
-                            }
-                            return null;
-                        } catch {
-                            return null;
-                        }
-                    })
-                );
-                return results;
-            },
-            {
-                cache: true,
-                maxBatchSize: 100
-            }
-        ),
-
-        /**
-         * Batches blueprint fetches by path
-         */
-        blueprintLoader: new DataLoader<string, Blueprint | null>(
-            async (paths: readonly string[]) => {
-                log.debug(`Batching blueprint fetch for ${paths.length} blueprints`);
-
-                const results = await Promise.all(
-                    paths.map(async (path) => {
-                        try {
-                            const result = await automationBridge.sendAutomationRequest<{
-                                success: boolean;
-                                blueprint?: Blueprint;
-                            }>('manage_blueprint', {
-                                action: 'get_blueprint',
-                                blueprintPath: path
-                            });
-                            return result.success ? (result.blueprint ?? null) : null;
-                        } catch {
-                            return null;
-                        }
-                    })
-                );
-                return results;
-            },
-            {
-                cache: true,
-                maxBatchSize: 20
-            }
-        ),
-
-        /**
-         * Batches actor component fetches
-         */
-        actorComponentsLoader: new DataLoader<string, Array<{ name: string; type: string }> | null>(
-            async (actorNames: readonly string[]) => {
-                log.debug(`Batching component fetch for ${actorNames.length} actors`);
-
-                const results = await Promise.all(
-                    actorNames.map(async (actorName) => {
-                        try {
-                            const result = await automationBridge.sendAutomationRequest<{
-                                success: boolean;
-                                components?: Array<{ name: string; type: string }>;
-                            }>('control_actor', {
-                                action: 'get_components',
-                                actorName
-                            });
-                            return result.success ? (result.components ?? null) : null;
-                        } catch {
-                            return null;
-                        }
-                    })
-                );
-                return results;
-            },
-            {
-                cache: true,
-                maxBatchSize: 30
-            }
-        )
-    };
-}
-
-/**
- * Clears all loader caches (useful between mutations)
- */
-export function clearLoaders(loaders: GraphQLLoaders): void {
-    loaders.actorLoader.clearAll();
-    loaders.assetLoader.clearAll();
-    loaders.blueprintLoader.clearAll();
-    loaders.actorComponentsLoader.clearAll();
-}