unreal-engine-mcp-server 0.4.7 → 0.5.0

package/dist/server-setup.js

@@ -0,0 +1,111 @@
+import { ListPromptsRequestSchema, GetPromptRequestSchema } from '@modelcontextprotocol/sdk/types.js';
+import { prompts } from './prompts/index.js';
+import { AssetResources } from './resources/assets.js';
+import { ActorResources } from './resources/actors.js';
+import { LevelResources } from './resources/levels.js';
+import { ResourceRegistry } from './server/resource-registry.js';
+import { ToolRegistry } from './server/tool-registry.js';
+import fs from 'fs';
+export class ServerSetup {
+    server;
+    bridge;
+    automationBridge;
+    logger;
+    healthMonitor;
+    assetResources;
+    actorResources;
+    levelResources;
+    constructor(server, bridge, automationBridge, logger, healthMonitor) {
+        this.server = server;
+        this.bridge = bridge;
+        this.automationBridge = automationBridge;
+        this.logger = logger;
+        this.healthMonitor = healthMonitor;
+        this.assetResources = new AssetResources(bridge);
+        this.actorResources = new ActorResources(bridge);
+        this.levelResources = new LevelResources(bridge);
+    }
+    async setup() {
+        this.validateEnvironment();
+        const ensureConnected = this.ensureConnectedOnDemand.bind(this);
+        const resourceRegistry = new ResourceRegistry(this.server, this.bridge, this.automationBridge, this.assetResources, this.actorResources, this.levelResources, this.healthMonitor, ensureConnected);
+        resourceRegistry.register();
+        const toolRegistry = new ToolRegistry(this.server, this.bridge, this.automationBridge, this.logger, this.healthMonitor, this.assetResources, this.actorResources, this.levelResources, ensureConnected);
+        toolRegistry.register();
+        this.registerPrompts();
+    }
+    validateEnvironment() {
+        const projectPath = process.env.UE_PROJECT_PATH;
+        if (projectPath) {
+            if (!fs.existsSync(projectPath)) {
+                this.logger.warn(`UE_PROJECT_PATH is set to '${projectPath}' but the path does not exist.`);
+            }
+            else {
+                this.logger.info(`UE_PROJECT_PATH validated: ${projectPath}`);
+            }
+        }
+        else {
+            this.logger.info('UE_PROJECT_PATH is not set. Offline project settings fallback will be disabled.');
+        }
+        const enginePath = process.env.UE_ENGINE_PATH || process.env.UNREAL_ENGINE_PATH;
+        if (enginePath) {
+            if (!fs.existsSync(enginePath)) {
+                this.logger.warn(`UE_ENGINE_PATH is set to '${enginePath}' but the path does not exist.`);
+            }
+            else {
+                this.logger.info(`UE_ENGINE_PATH validated: ${enginePath}`);
+            }
+        }
+    }
+    async ensureConnectedOnDemand() {
+        if (this.bridge.isConnected)
+            return true;
+        const ok = await this.bridge.tryConnect(3, 5000, 1000);
+        if (ok) {
+            this.healthMonitor.metrics.connectionStatus = 'connected';
+            this.healthMonitor.startHealthChecks(this.bridge);
+        }
+        else {
+            this.healthMonitor.metrics.connectionStatus = 'disconnected';
+        }
+        return ok;
+    }
+    registerPrompts() {
+        this.server.setRequestHandler(ListPromptsRequestSchema, async () => {
+            return {
+                prompts: prompts.map(p => ({
+                    name: p.name,
+                    description: p.description,
+                    arguments: Object.entries(p.arguments || {}).map(([name, schema]) => {
+                        const meta = {};
+                        if (schema.type)
+                            meta.type = schema.type;
+                        if (schema.enum)
+                            meta.enum = schema.enum;
+                        if (schema.default !== undefined)
+                            meta.default = schema.default;
+                        return {
+                            name,
+                            description: schema.description,
+                            required: schema.required ?? false,
+                            ...(Object.keys(meta).length ? { _meta: meta } : {})
+                        };
+                    })
+                }))
+            };
+        });
+        this.server.setRequestHandler(GetPromptRequestSchema, async (request) => {
+            const prompt = prompts.find(p => p.name === request.params.name);
+            if (!prompt) {
+                throw new Error(`Unknown prompt: ${request.params.name}`);
+            }
+            const args = (request.params.arguments || {});
+            const messages = prompt.build(args);
+            return {
+                description: prompt.description,
+                messages
+            };
+        });
+    }
+}
+//# sourceMappingURL=server-setup.js.map

package/dist/services/health-monitor.d.ts

@@ -0,0 +1,34 @@
+import { UnrealBridge } from '../unreal-bridge.js';
+import { Logger } from '../utils/logger.js';
+export interface PerformanceMetrics {
+    totalRequests: number;
+    successfulRequests: number;
+    failedRequests: number;
+    averageResponseTime: number;
+    responseTimes: number[];
+    connectionStatus: 'connected' | 'disconnected' | 'error';
+    lastHealthCheck: Date;
+    uptime: number;
+    recentErrors: Array<{
+        time: string;
+        scope: string;
+        type: string;
+        message: string;
+        retriable: boolean;
+    }>;
+}
+export declare class HealthMonitor {
+    private logger;
+    metrics: PerformanceMetrics;
+    private healthCheckTimer;
+    private lastHealthSuccessAt;
+    private readonly HEALTH_CHECK_INTERVAL_MS;
+    constructor(logger: Logger);
+    trackPerformance(startTime: number, success: boolean): void;
+    recordError(errorResponse: any): void;
+    performHealthCheck(bridge: UnrealBridge): Promise<boolean>;
+    startHealthChecks(bridge: UnrealBridge): void;
+    stopHealthChecks(): void;
+    setLastHealthSuccessAt(time: number): void;
+}
+//# sourceMappingURL=health-monitor.d.ts.map

package/dist/services/health-monitor.js

@@ -0,0 +1,105 @@
+export class HealthMonitor {
+    logger;
+    metrics;
+    healthCheckTimer;
+    lastHealthSuccessAt = 0;
+    HEALTH_CHECK_INTERVAL_MS = 30000;
+    constructor(logger) {
+        this.logger = logger;
+        this.metrics = {
+            totalRequests: 0,
+            successfulRequests: 0,
+            failedRequests: 0,
+            averageResponseTime: 0,
+            responseTimes: [],
+            connectionStatus: 'disconnected',
+            lastHealthCheck: new Date(),
+            uptime: Date.now(),
+            recentErrors: []
+        };
+    }
+    trackPerformance(startTime, success) {
+        const responseTime = Date.now() - startTime;
+        this.metrics.totalRequests++;
+        if (success) {
+            this.metrics.successfulRequests++;
+        }
+        else {
+            this.metrics.failedRequests++;
+        }
+        this.metrics.responseTimes.push(responseTime);
+        if (this.metrics.responseTimes.length > 100) {
+            this.metrics.responseTimes.shift();
+        }
+        this.metrics.averageResponseTime = this.metrics.responseTimes.reduce((a, b) => a + b, 0) / this.metrics.responseTimes.length;
+    }
+    recordError(errorResponse) {
+        try {
+            this.metrics.recentErrors.push({
+                time: new Date().toISOString(),
+                scope: errorResponse.scope || 'unknown',
+                type: errorResponse._debug?.errorType || 'UNKNOWN',
+                message: errorResponse.error || errorResponse.message || 'Unknown error',
+                retriable: Boolean(errorResponse.retriable)
+            });
+            if (this.metrics.recentErrors.length > 20)
+                this.metrics.recentErrors.splice(0, this.metrics.recentErrors.length - 20);
+        }
+        catch { }
+    }
+    async performHealthCheck(bridge) {
+        if (!bridge.isConnected) {
+            return false;
+        }
+        try {
+            await bridge.executeConsoleCommand('stat none');
+            this.metrics.connectionStatus = 'connected';
+            this.metrics.lastHealthCheck = new Date();
+            this.lastHealthSuccessAt = Date.now();
+            return true;
+        }
+        catch (err1) {
+            this.metrics.connectionStatus = 'error';
+            this.metrics.lastHealthCheck = new Date();
+            this.logger.debug('Health check failed (console):', err1);
+            return false;
+        }
+    }
+    startHealthChecks(bridge) {
+        if (this.healthCheckTimer)
+            return;
+        this.lastHealthSuccessAt = Date.now();
+        this.healthCheckTimer = setInterval(async () => {
+            if (!bridge.isConnected) {
+                const FIVE_MIN_MS = 5 * 60 * 1000;
+                if (!this.lastHealthSuccessAt || Date.now() - this.lastHealthSuccessAt > FIVE_MIN_MS) {
+                    if (this.healthCheckTimer) {
+                        clearInterval(this.healthCheckTimer);
+                        this.healthCheckTimer = undefined;
+                    }
+                    this.logger.info('Health checks paused after 5 minutes without a successful response');
+                }
+                return;
+            }
+            await this.performHealthCheck(bridge);
+            const FIVE_MIN_MS = 5 * 60 * 1000;
+            if (!this.lastHealthSuccessAt || Date.now() - this.lastHealthSuccessAt > FIVE_MIN_MS) {
+                if (this.healthCheckTimer) {
+                    clearInterval(this.healthCheckTimer);
+                    this.healthCheckTimer = undefined;
+                    this.logger.info('Health checks paused after 5 minutes without a successful response');
+                }
+            }
+        }, this.HEALTH_CHECK_INTERVAL_MS);
+    }
+    stopHealthChecks() {
+        if (this.healthCheckTimer) {
+            clearInterval(this.healthCheckTimer);
+            this.healthCheckTimer = undefined;
+        }
+    }
+    setLastHealthSuccessAt(time) {
+        this.lastHealthSuccessAt = time;
+    }
+}
+//# sourceMappingURL=health-monitor.js.map

package/dist/services/metrics-server.d.ts

@@ -0,0 +1,11 @@
+import { HealthMonitor } from './health-monitor.js';
+import { AutomationBridge } from '../automation/index.js';
+import { Logger } from '../utils/logger.js';
+interface MetricsServerOptions {
+    healthMonitor: HealthMonitor;
+    automationBridge: AutomationBridge;
+    logger: Logger;
+}
+export declare function startMetricsServer(options: MetricsServerOptions): void;
+export {};
+//# sourceMappingURL=metrics-server.d.ts.map

package/dist/services/metrics-server.js

@@ -0,0 +1,105 @@
+import http from 'http';
+import { wasmIntegration } from '../wasm/index.js';
+import { DEFAULT_AUTOMATION_HOST } from '../constants.js';
+function formatPrometheusMetrics(options) {
+    const { healthMonitor, automationBridge } = options;
+    const m = healthMonitor.metrics;
+    const status = automationBridge.getStatus();
+    const wasmMetrics = wasmIntegration.getMetrics();
+    const wasmStatus = wasmIntegration.getStatus();
+    const lines = [];
+    lines.push('# HELP unreal_mcp_requests_total Total number of tool requests seen by the MCP server.');
+    lines.push('# TYPE unreal_mcp_requests_total counter');
+    lines.push(`unreal_mcp_requests_total ${m.totalRequests}`);
+    lines.push('# HELP unreal_mcp_requests_success_total Total number of successful tool requests.');
+    lines.push('# TYPE unreal_mcp_requests_success_total counter');
+    lines.push(`unreal_mcp_requests_success_total ${m.successfulRequests}`);
+    lines.push('# HELP unreal_mcp_requests_failed_total Total number of failed tool requests.');
+    lines.push('# TYPE unreal_mcp_requests_failed_total counter');
+    lines.push(`unreal_mcp_requests_failed_total ${m.failedRequests}`);
+    lines.push('# HELP unreal_mcp_average_response_time_ms Average response time of recent tool requests (ms).');
+    lines.push('# TYPE unreal_mcp_average_response_time_ms gauge');
+    lines.push(`unreal_mcp_average_response_time_ms ${Number.isFinite(m.averageResponseTime) ? m.averageResponseTime.toFixed(2) : '0'}`);
+    lines.push('# HELP unreal_mcp_unreal_connected Whether the Unreal automation bridge is currently connected (1) or not (0).');
+    lines.push('# TYPE unreal_mcp_unreal_connected gauge');
+    lines.push(`unreal_mcp_unreal_connected ${status.connected ? 1 : 0}`);
+    lines.push('# HELP unreal_mcp_automation_pending_requests Number of pending automation bridge requests.');
+    lines.push('# TYPE unreal_mcp_automation_pending_requests gauge');
+    lines.push(`unreal_mcp_automation_pending_requests ${status.pendingRequests}`);
+    lines.push('# HELP unreal_mcp_automation_max_pending_requests Configured maximum number of pending automation bridge requests.');
+    lines.push('# TYPE unreal_mcp_automation_max_pending_requests gauge');
+    lines.push(`unreal_mcp_automation_max_pending_requests ${status.maxPendingRequests}`);
+    lines.push('# HELP unreal_mcp_automation_max_concurrent_connections Configured maximum concurrent automation bridge connections.');
+    lines.push('# TYPE unreal_mcp_automation_max_concurrent_connections gauge');
+    lines.push(`unreal_mcp_automation_max_concurrent_connections ${status.maxConcurrentConnections}`);
+    lines.push('# HELP unreal_mcp_wasm_enabled Whether the optional WebAssembly integration is enabled (1) or not (0).');
+    lines.push('# TYPE unreal_mcp_wasm_enabled gauge');
+    lines.push(`unreal_mcp_wasm_enabled ${wasmStatus.enabled ? 1 : 0}`);
+    lines.push('# HELP unreal_mcp_wasm_ready Whether the WebAssembly module has been initialized successfully (1) or not (0).');
+    lines.push('# TYPE unreal_mcp_wasm_ready gauge');
+    lines.push(`unreal_mcp_wasm_ready ${wasmStatus.ready ? 1 : 0}`);
+    lines.push('# HELP unreal_mcp_wasm_operations_total Total number of WASM-related operations recorded by the integration layer.');
+    lines.push('# TYPE unreal_mcp_wasm_operations_total counter');
+    lines.push(`unreal_mcp_wasm_operations_total ${wasmMetrics.totalOperations}`);
+    lines.push('# HELP unreal_mcp_wasm_operations_wasm_total Number of operations that used the WebAssembly implementation.');
+    lines.push('# TYPE unreal_mcp_wasm_operations_wasm_total counter');
+    lines.push(`unreal_mcp_wasm_operations_wasm_total ${wasmMetrics.wasmOperations}`);
+    lines.push('# HELP unreal_mcp_wasm_operations_ts_total Number of operations that used the TypeScript fallback implementation.');
+    lines.push('# TYPE unreal_mcp_wasm_operations_ts_total counter');
+    lines.push(`unreal_mcp_wasm_operations_ts_total ${wasmMetrics.tsOperations}`);
+    const uptimeSeconds = Math.floor((Date.now() - m.uptime) / 1000);
+    lines.push('# HELP unreal_mcp_uptime_seconds MCP server uptime in seconds (since HealthMonitor was created).');
+    lines.push('# TYPE unreal_mcp_uptime_seconds gauge');
+    lines.push(`unreal_mcp_uptime_seconds ${uptimeSeconds}`);
+    return lines.join('\n') + '\n';
+}
+export function startMetricsServer(options) {
+    const { logger } = options;
+    const portEnv = process.env.MCP_METRICS_PORT || process.env.PROMETHEUS_PORT;
+    const port = portEnv ? Number(portEnv) : 0;
+    if (!port || !Number.isFinite(port) || port <= 0) {
+        logger.debug('Metrics server disabled (set MCP_METRICS_PORT to enable Prometheus /metrics endpoint).');
+        return;
+    }
+    try {
+        const server = http.createServer((req, res) => {
+            if (!req.url) {
+                res.statusCode = 400;
+                res.end('Bad Request');
+                return;
+            }
+            if (req.method !== 'GET') {
+                res.statusCode = 405;
+                res.setHeader('Allow', 'GET');
+                res.end('Method Not Allowed');
+                return;
+            }
+            if (!req.url.startsWith('/metrics')) {
+                res.statusCode = 404;
+                res.end('Not Found');
+                return;
+            }
+            try {
+                const body = formatPrometheusMetrics(options);
+                res.statusCode = 200;
+                res.setHeader('Content-Type', 'text/plain; version=0.0.4; charset=utf-8');
+                res.end(body);
+            }
+            catch (err) {
+                logger.warn('Failed to render /metrics payload', err);
+                res.statusCode = 500;
+                res.end('Internal Server Error');
+            }
+        });
+        server.listen(port, () => {
+            logger.info(`Prometheus metrics server listening on http://${DEFAULT_AUTOMATION_HOST}:${port}/metrics`);
+        });
+        server.on('error', (err) => {
+            logger.warn('Metrics server error', err);
+        });
+    }
+    catch (err) {
+        logger.warn('Failed to start metrics server', err);
+    }
+}
+//# sourceMappingURL=metrics-server.js.map

package/dist/tools/actors.d.ts

@@ -1,6 +1,7 @@
 import { UnrealBridge } from '../unreal-bridge.js';
-export declare class ActorTools {
-    private bridge;
+import { BaseTool } from './base-tool.js';
+import { IActorTools, StandardActionResponse } from '../types/tool-interfaces.js';
+export declare class ActorTools extends BaseTool implements IActorTools {
     constructor(bridge: UnrealBridge);
     spawn(params: {
         classPath: string;
@@ -15,9 +16,38 @@ export declare class ActorTools {
             roll: number;
         };
         actorName?: string;
-    }): Promise<Record<string, unknown>>;
-    spawnViaConsole(params: {
-        classPath: string;
+        meshPath?: string;
+        timeoutMs?: number;
+    }): Promise<StandardActionResponse<any>>;
+    delete(params: {
+        actorName?: string;
+        actorNames?: string[];
+    }): Promise<any>;
+    applyForce(params: {
+        actorName: string;
+        force: {
+            x: number;
+            y: number;
+            z: number;
+        };
+    }): Promise<any>;
+    private resolveActorClass;
+    spawnBlueprint(params: {
+        blueprintPath: string;
+        actorName?: string;
+        location?: {
+            x: number;
+            y: number;
+            z: number;
+        };
+        rotation?: {
+            pitch: number;
+            yaw: number;
+            roll: number;
+        };
+    }): Promise<any>;
+    setTransform(params: {
+        actorName: string;
         location?: {
             x: number;
             y: number;
@@ -28,13 +58,121 @@ export declare class ActorTools {
             yaw: number;
             roll: number;
         };
+        scale?: {
+            x: number;
+            y: number;
+            z: number;
+        };
+    }): Promise<any>;
+    getTransform(actorName: string): Promise<any>;
+    setVisibility(params: {
+        actorName: string;
+        visible: boolean;
+    }): Promise<any>;
+    addComponent(params: {
+        actorName: string;
+        componentType: string;
+        componentName?: string;
+        properties?: Record<string, unknown>;
+    }): Promise<any>;
+    setComponentProperties(params: {
+        actorName: string;
+        componentName: string;
+        properties: Record<string, unknown>;
+    }): Promise<any>;
+    getComponents(actorName: string): Promise<{
+        success: boolean;
+        error: any;
+        message?: undefined;
+        components?: undefined;
+        count?: undefined;
+    } | {
+        success: boolean;
+        message: string;
+        components: any;
+        count: any;
+        error?: undefined;
+    }>;
+    duplicate(params: {
+        actorName: string;
+        newName?: string;
+        offset?: {
+            x: number;
+            y: number;
+            z: number;
+        };
+    }): Promise<any>;
+    addTag(params: {
+        actorName: string;
+        tag: string;
+    }): Promise<any>;
+    removeTag(params: {
+        actorName: string;
+        tag: string;
+    }): Promise<any>;
+    findByTag(params: {
+        tag: string;
+        matchType?: string;
+    }): Promise<any>;
+    findByName(name: string): Promise<any>;
+    detach(actorName: string): Promise<any>;
+    attach(params: {
+        childActor: string;
+        parentActor: string;
+    }): Promise<any>;
+    deleteByTag(tag: string): Promise<any>;
+    setBlueprintVariables(params: {
+        actorName: string;
+        variables: Record<string, unknown>;
+    }): Promise<any>;
+    createSnapshot(params: {
+        actorName: string;
+        snapshotName: string;
+    }): Promise<any>;
+    restoreSnapshot(params: {
+        actorName: string;
+        snapshotName: string;
+    }): Promise<any>;
+    exportActor(params: {
+        actorName: string;
+        destinationPath?: string;
+    }): Promise<any>;
+    getBoundingBox(actorName: string): Promise<{
+        success: boolean;
+        error: any;
+        message?: undefined;
+        boundingBox?: undefined;
+    } | {
+        success: boolean;
+        message: string;
+        boundingBox: any;
+        error?: undefined;
+    }>;
+    getMetadata(actorName: string): Promise<{
+        success: boolean;
+        error: any;
+        message?: undefined;
+        metadata?: undefined;
+    } | {
+        success: boolean;
+        message: string;
+        metadata: any;
+        error?: undefined;
+    }>;
+    listActors(params?: {
+        filter?: string;
     }): Promise<{
+        success: boolean;
+        error: any;
+        message?: undefined;
+        actors?: undefined;
+        count?: undefined;
+    } | {
         success: boolean;
         message: string;
-        note: string;
+        actors: any[];
+        count: number;
+        error?: undefined;
     }>;
-    private getPythonSpawnHelper;
-    private resolveActorClass;
-    private getConsoleClassName;
 }
 //# sourceMappingURL=actors.d.ts.map