unreal-engine-mcp-server 0.2.1

package/dist/index.js

@@ -0,0 +1,484 @@
+import 'dotenv/config';
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { Logger } from './utils/logger.js';
+import { UnrealBridge } from './unreal-bridge.js';
+import { AssetResources } from './resources/assets.js';
+import { ActorResources } from './resources/actors.js';
+import { LevelResources } from './resources/levels.js';
+import { ActorTools } from './tools/actors.js';
+import { AssetTools } from './tools/assets.js';
+import { EditorTools } from './tools/editor.js';
+import { MaterialTools } from './tools/materials.js';
+import { AnimationTools } from './tools/animation.js';
+import { PhysicsTools } from './tools/physics.js';
+import { NiagaraTools } from './tools/niagara.js';
+import { BlueprintTools } from './tools/blueprint.js';
+import { LevelTools } from './tools/level.js';
+import { LightingTools } from './tools/lighting.js';
+import { LandscapeTools } from './tools/landscape.js';
+import { FoliageTools } from './tools/foliage.js';
+import { DebugVisualizationTools } from './tools/debug.js';
+import { PerformanceTools } from './tools/performance.js';
+import { AudioTools } from './tools/audio.js';
+import { UITools } from './tools/ui.js';
+import { RcTools } from './tools/rc.js';
+import { SequenceTools } from './tools/sequence.js';
+import { IntrospectionTools } from './tools/introspection.js';
+import { VisualTools } from './tools/visual.js';
+import { EngineTools } from './tools/engine.js';
+import { toolDefinitions } from './tools/tool-definitions.js';
+import { handleToolCall } from './tools/tool-handlers.js';
+import { consolidatedToolDefinitions } from './tools/consolidated-tool-definitions.js';
+import { handleConsolidatedToolCall } from './tools/consolidated-tool-handlers.js';
+import { prompts } from './prompts/index.js';
+import { CallToolRequestSchema, ListToolsRequestSchema, ListResourcesRequestSchema, ReadResourceRequestSchema, ListPromptsRequestSchema, GetPromptRequestSchema } from '@modelcontextprotocol/sdk/types.js';
+import { responseValidator } from './utils/response-validator.js';
+import { ErrorHandler } from './utils/error-handler.js';
+import { routeStdoutLogsToStderr } from './utils/stdio-redirect.js';
+import { cleanObject } from './utils/safe-json.js';
+const log = new Logger('UE-MCP');
+// Ensure stdout remains JSON-only for MCP by routing logs to stderr unless opted out.
+routeStdoutLogsToStderr();
+const metrics = {
+    totalRequests: 0,
+    successfulRequests: 0,
+    failedRequests: 0,
+    averageResponseTime: 0,
+    responseTimes: [],
+    connectionStatus: 'disconnected',
+    lastHealthCheck: new Date(),
+    uptime: Date.now(),
+    recentErrors: []
+};
+// Configuration
+const CONFIG = {
+    // Tool mode: true = consolidated (10 tools), false = individual (36+ tools)
+    USE_CONSOLIDATED_TOOLS: process.env.USE_CONSOLIDATED_TOOLS !== 'false',
+    // Connection retry settings
+    MAX_RETRY_ATTEMPTS: 3,
+    RETRY_DELAY_MS: 2000,
+    // Server info
+    SERVER_NAME: 'unreal-engine-mcp',
+    SERVER_VERSION: '0.2.1',
+    // Monitoring
+    HEALTH_CHECK_INTERVAL_MS: 30000 // 30 seconds
+};
+// Helper function to track performance
+function trackPerformance(startTime, success) {
+    const responseTime = Date.now() - startTime;
+    metrics.totalRequests++;
+    if (success) {
+        metrics.successfulRequests++;
+    }
+    else {
+        metrics.failedRequests++;
+    }
+    // Keep last 100 response times for average calculation
+    metrics.responseTimes.push(responseTime);
+    if (metrics.responseTimes.length > 100) {
+        metrics.responseTimes.shift();
+    }
+    // Calculate average
+    metrics.averageResponseTime = metrics.responseTimes.reduce((a, b) => a + b, 0) / metrics.responseTimes.length;
+}
+// Health check function
+async function performHealthCheck(bridge) {
+    try {
+        // Use a safe echo command that doesn't affect any settings
+        await bridge.executeConsoleCommand('echo MCP Server Health Check');
+        metrics.connectionStatus = 'connected';
+        metrics.lastHealthCheck = new Date();
+        return true;
+    }
+    catch (err1) {
+        // Fallback: minimal Python ping (if Python plugin is enabled)
+        try {
+            await bridge.executePython("import sys; sys.stdout.write('OK')");
+            metrics.connectionStatus = 'connected';
+            metrics.lastHealthCheck = new Date();
+            return true;
+        }
+        catch (err2) {
+            metrics.connectionStatus = 'error';
+            metrics.lastHealthCheck = new Date();
+            log.warn('Health check failed (console and python):', err1, err2);
+            return false;
+        }
+    }
+}
+export async function createServer() {
+    const bridge = new UnrealBridge();
+    // Initialize response validation with schemas
+    log.info('Initializing response validation...');
+    const toolDefs = CONFIG.USE_CONSOLIDATED_TOOLS ? consolidatedToolDefinitions : toolDefinitions;
+    toolDefs.forEach((tool) => {
+        if (tool.outputSchema) {
+            responseValidator.registerSchema(tool.name, tool.outputSchema);
+        }
+    });
+    log.info(`Registered ${responseValidator.getStats().totalSchemas} output schemas for validation`);
+    // Connect to UE5 Remote Control with retries and timeout
+    const connected = await bridge.tryConnect(CONFIG.MAX_RETRY_ATTEMPTS, 5000, // 5 second timeout per attempt
+    CONFIG.RETRY_DELAY_MS);
+    if (connected) {
+        metrics.connectionStatus = 'connected';
+        log.info('Successfully connected to Unreal Engine');
+    }
+    else {
+        log.warn('Could not connect to Unreal Engine after retries');
+        log.info('Server will start anyway - connection will be retried periodically');
+        log.info('Make sure Unreal Engine is running with Remote Control enabled');
+        metrics.connectionStatus = 'disconnected';
+        // Schedule automatic reconnection attempts
+        setInterval(async () => {
+            if (!bridge.isConnected) {
+                log.info('Attempting to reconnect to Unreal Engine...');
+                const reconnected = await bridge.tryConnect(1, 5000, 0); // Single attempt
+                if (reconnected) {
+                    log.info('Reconnected to Unreal Engine successfully');
+                    metrics.connectionStatus = 'connected';
+                }
+            }
+        }, 10000); // Try every 10 seconds
+    }
+    // Start periodic health checks
+    setInterval(() => {
+        performHealthCheck(bridge);
+    }, CONFIG.HEALTH_CHECK_INTERVAL_MS);
+    // Resources
+    const assetResources = new AssetResources(bridge);
+    const actorResources = new ActorResources(bridge);
+    const levelResources = new LevelResources(bridge);
+    // Tools
+    const actorTools = new ActorTools(bridge);
+    const assetTools = new AssetTools(bridge);
+    const editorTools = new EditorTools(bridge);
+    const materialTools = new MaterialTools(bridge);
+    const animationTools = new AnimationTools(bridge);
+    const physicsTools = new PhysicsTools(bridge);
+    const niagaraTools = new NiagaraTools(bridge);
+    const blueprintTools = new BlueprintTools(bridge);
+    const levelTools = new LevelTools(bridge);
+    const lightingTools = new LightingTools(bridge);
+    const landscapeTools = new LandscapeTools(bridge);
+    const foliageTools = new FoliageTools(bridge);
+    const debugTools = new DebugVisualizationTools(bridge);
+    const performanceTools = new PerformanceTools(bridge);
+    const audioTools = new AudioTools(bridge);
+    const uiTools = new UITools(bridge);
+    const rcTools = new RcTools(bridge);
+    const sequenceTools = new SequenceTools(bridge);
+    const introspectionTools = new IntrospectionTools(bridge);
+    const visualTools = new VisualTools(bridge);
+    const engineTools = new EngineTools(bridge);
+    const server = new Server({
+        name: CONFIG.SERVER_NAME,
+        version: CONFIG.SERVER_VERSION
+    }, {
+        capabilities: {
+            resources: {},
+            tools: {},
+            prompts: {},
+            logging: {}
+        }
+    });
+    // Handle resource listing
+    server.setRequestHandler(ListResourcesRequestSchema, async () => {
+        return {
+            resources: [
+                {
+                    uri: 'ue://assets',
+                    name: 'Project Assets',
+                    description: 'List all assets in the project',
+                    mimeType: 'application/json'
+                },
+                {
+                    uri: 'ue://actors',
+                    name: 'Level Actors',
+                    description: 'List all actors in the current level',
+                    mimeType: 'application/json'
+                },
+                {
+                    uri: 'ue://level',
+                    name: 'Current Level',
+                    description: 'Information about the current level',
+                    mimeType: 'application/json'
+                },
+                {
+                    uri: 'ue://exposed',
+                    name: 'Remote Control Exposed',
+                    description: 'List all exposed properties via Remote Control',
+                    mimeType: 'application/json'
+                },
+                {
+                    uri: 'ue://health',
+                    name: 'Health Status',
+                    description: 'Server health and performance metrics',
+                    mimeType: 'application/json'
+                },
+                {
+                    uri: 'ue://version',
+                    name: 'Engine Version',
+                    description: 'Unreal Engine version and compatibility info',
+                    mimeType: 'application/json'
+                }
+            ]
+        };
+    });
+    // Handle resource reading
+    server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
+        const uri = request.params.uri;
+        if (uri === 'ue://assets') {
+            const list = await assetResources.list('/Game', true);
+            return {
+                contents: [{
+                        uri,
+                        mimeType: 'application/json',
+                        text: JSON.stringify(list, null, 2)
+                    }]
+            };
+        }
+        if (uri === 'ue://actors') {
+            const list = await actorResources.listActors();
+            return {
+                contents: [{
+                        uri,
+                        mimeType: 'application/json',
+                        text: JSON.stringify(list, null, 2)
+                    }]
+            };
+        }
+        if (uri === 'ue://level') {
+            const level = await levelResources.getCurrentLevel();
+            return {
+                contents: [{
+                        uri,
+                        mimeType: 'application/json',
+                        text: JSON.stringify(level, null, 2)
+                    }]
+            };
+        }
+        if (uri === 'ue://exposed') {
+            try {
+                const exposed = await bridge.getExposed();
+                return {
+                    contents: [{
+                            uri,
+                            mimeType: 'application/json',
+                            text: JSON.stringify(exposed, null, 2)
+                        }]
+                };
+            }
+            catch {
+                return {
+                    contents: [{
+                            uri,
+                            mimeType: 'text/plain',
+                            text: 'Failed to get exposed properties. Ensure Remote Control is configured.'
+                        }]
+                };
+            }
+        }
+        if (uri === 'ue://health') {
+            const uptimeMs = Date.now() - metrics.uptime;
+            // Query engine version and feature flags (best-effort)
+            let versionInfo = {};
+            let featureFlags = {};
+            try {
+                versionInfo = await bridge.getEngineVersion();
+            }
+            catch { }
+            try {
+                featureFlags = await bridge.getFeatureFlags();
+            }
+            catch { }
+            const health = {
+                status: metrics.connectionStatus,
+                uptime: Math.floor(uptimeMs / 1000),
+                performance: {
+                    totalRequests: metrics.totalRequests,
+                    successfulRequests: metrics.successfulRequests,
+                    failedRequests: metrics.failedRequests,
+                    successRate: metrics.totalRequests > 0 ?
+                        (metrics.successfulRequests / metrics.totalRequests * 100).toFixed(2) + '%' : 'N/A',
+                    averageResponseTime: Math.round(metrics.averageResponseTime) + 'ms'
+                },
+                lastHealthCheck: metrics.lastHealthCheck.toISOString(),
+                unrealConnection: {
+                    status: bridge.isConnected ? 'connected' : 'disconnected',
+                    host: process.env.UE_HOST || 'localhost',
+                    httpPort: process.env.UE_RC_HTTP_PORT || 30010,
+                    wsPort: process.env.UE_RC_WS_PORT || 30020,
+                    engineVersion: versionInfo,
+                    features: {
+                        pythonEnabled: featureFlags.pythonEnabled === true,
+                        subsystems: featureFlags.subsystems || {},
+                        rcHttpReachable: bridge.isConnected
+                    }
+                },
+                recentErrors: metrics.recentErrors.slice(-5)
+            };
+            return {
+                contents: [{
+                        uri,
+                        mimeType: 'application/json',
+                        text: JSON.stringify(health, null, 2)
+                    }]
+            };
+        }
+        if (uri === 'ue://version') {
+            const info = await bridge.getEngineVersion();
+            return {
+                contents: [{
+                        uri,
+                        mimeType: 'application/json',
+                        text: JSON.stringify(info, null, 2)
+                    }]
+            };
+        }
+        throw new Error(`Unknown resource: ${uri}`);
+    });
+    // Handle tool listing - switch between consolidated (10) or individual (36) tools
+    server.setRequestHandler(ListToolsRequestSchema, async () => {
+        log.info(`Serving ${CONFIG.USE_CONSOLIDATED_TOOLS ? 'consolidated' : 'individual'} tools`);
+        return {
+            tools: CONFIG.USE_CONSOLIDATED_TOOLS ? consolidatedToolDefinitions : toolDefinitions
+        };
+    });
+    // Handle tool calls - switch between consolidated (10) or individual (36) tools
+    server.setRequestHandler(CallToolRequestSchema, async (request) => {
+        const { name, arguments: args } = request.params;
+        const startTime = Date.now();
+        // Create tools object for handler
+        const tools = {
+            actorTools,
+            assetTools,
+            materialTools,
+            editorTools,
+            animationTools,
+            physicsTools,
+            niagaraTools,
+            blueprintTools,
+            levelTools,
+            lightingTools,
+            landscapeTools,
+            foliageTools,
+            debugTools,
+            performanceTools,
+            audioTools,
+            uiTools,
+            rcTools,
+            sequenceTools,
+            introspectionTools,
+            visualTools,
+            engineTools,
+            bridge
+        };
+        // Use consolidated or individual handler based on configuration
+        try {
+            log.debug(`Executing tool: ${name}`);
+            let result;
+            if (CONFIG.USE_CONSOLIDATED_TOOLS) {
+                result = await handleConsolidatedToolCall(name, args, tools);
+            }
+            else {
+                result = await handleToolCall(name, args, tools);
+            }
+            log.debug(`Tool ${name} returned result`);
+            // Clean the result to remove circular references
+            result = cleanObject(result);
+            // Validate and enhance response
+            result = responseValidator.wrapResponse(name, result);
+            trackPerformance(startTime, true);
+            log.info(`Tool ${name} completed successfully in ${Date.now() - startTime}ms`);
+            // Log that we're returning the response
+            const responsePreview = JSON.stringify(result).substring(0, 100);
+            log.debug(`Returning response to MCP client: ${responsePreview}...`);
+            return result;
+        }
+        catch (error) {
+            trackPerformance(startTime, false);
+            // Use consistent error handling
+            const errorResponse = ErrorHandler.createErrorResponse(error, name, { ...args, scope: `tool-call/${name}` });
+            log.error(`Tool execution failed: ${name}`, errorResponse);
+            // Record error for health diagnostics
+            try {
+                metrics.recentErrors.push({
+                    time: new Date().toISOString(),
+                    scope: errorResponse.scope || `tool-call/${name}`,
+                    type: errorResponse._debug?.errorType || 'UNKNOWN',
+                    message: errorResponse.error || errorResponse.message || 'Unknown error',
+                    retriable: Boolean(errorResponse.retriable)
+                });
+                if (metrics.recentErrors.length > 20)
+                    metrics.recentErrors.splice(0, metrics.recentErrors.length - 20);
+            }
+            catch { }
+            return {
+                content: [{
+                        type: 'text',
+                        text: errorResponse.message || `Failed to execute ${name}`
+                    }],
+                ...errorResponse
+            };
+        }
+    });
+    // Handle prompt listing
+    server.setRequestHandler(ListPromptsRequestSchema, async () => {
+        return {
+            prompts: prompts.map(p => ({
+                name: p.name,
+                description: p.description,
+                arguments: Object.entries(p.arguments || {}).map(([name, schema]) => ({
+                    name,
+                    description: schema.description,
+                    required: schema.required || false
+                }))
+            }))
+        };
+    });
+    // Handle prompt retrieval
+    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}`);
+        }
+        // Return a template for the lighting setup
+        return {
+            messages: [
+                {
+                    role: 'user',
+                    content: {
+                        type: 'text',
+                        text: `Set up three-point lighting with ${request.params.arguments?.intensity || 'medium'} intensity`
+                    }
+                }
+            ]
+        };
+    });
+    return { server, bridge };
+}
+export async function startStdioServer() {
+    const { server } = await createServer();
+    const transport = new StdioServerTransport();
+    // Add debugging for transport messages
+    const originalWrite = process.stdout.write;
+    process.stdout.write = function (...args) {
+        const message = args[0];
+        if (typeof message === 'string' && message.includes('jsonrpc')) {
+            log.debug(`Sending to client: ${message.substring(0, 200)}...`);
+        }
+        return originalWrite.apply(process.stdout, args);
+    };
+    await server.connect(transport);
+    log.info('Unreal Engine MCP Server started on stdio');
+}
+// Start the server when run directly
+if (import.meta.url === `file://${process.argv[1].replace(/\\/g, '/')}`) {
+    startStdioServer().catch(error => {
+        console.error('Failed to start server:', error);
+        process.exit(1);
+    });
+}
+//# sourceMappingURL=index.js.map

package/dist/prompts/index.d.ts

@@ -0,0 +1,14 @@
+export interface PromptArgument {
+    type: string;
+    description?: string;
+    enum?: string[];
+    default?: any;
+    required?: boolean;
+}
+export interface Prompt {
+    name: string;
+    description: string;
+    arguments?: Record<string, PromptArgument>;
+}
+export declare const prompts: Prompt[];
+//# sourceMappingURL=index.d.ts.map

package/dist/prompts/index.js

@@ -0,0 +1,38 @@
+export const prompts = [
+    {
+        name: 'setup_three_point_lighting',
+        description: 'Set up a basic three-point lighting rig around the current camera focus',
+        arguments: {
+            intensity: {
+                type: 'string',
+                enum: ['low', 'medium', 'high'],
+                default: 'medium',
+                description: 'Light intensity level'
+            }
+        }
+    },
+    {
+        name: 'create_fps_controller',
+        description: 'Create a first-person shooter character controller',
+        arguments: {
+            spawnLocation: {
+                type: 'object',
+                description: 'Location to spawn the controller',
+                required: false
+            }
+        }
+    },
+    {
+        name: 'setup_post_processing',
+        description: 'Configure post-processing volume with cinematic settings',
+        arguments: {
+            style: {
+                type: 'string',
+                enum: ['cinematic', 'realistic', 'stylized', 'noir'],
+                default: 'cinematic',
+                description: 'Visual style preset'
+            }
+        }
+    }
+];
+//# sourceMappingURL=index.js.map

package/dist/python-utils.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Python Utilities for Modern Unreal Engine API
+ *
+ * This module provides Python code snippets that use the modern
+ * Unreal Engine Python API instead of deprecated functions.
+ */
+export declare class PythonUtils {
+    /**
+     * Get all actors in the level using modern API
+     * @returns Python code to get all level actors
+     */
+    static getAllLevelActors(): string;
+    /**
+     * Get selected actors using modern API
+     * @returns Python code to get selected actors
+     */
+    static getSelectedActors(): string;
+    /**
+     * Spawn actor from class using modern API
+     * @returns Python code to spawn actor
+     */
+    static spawnActorFromClass(): string;
+    /**
+     * Get a safe way to access actors
+     * @returns Python code with modern API
+     */
+    static getSafeActorAccess(): string;
+}
+//# sourceMappingURL=python-utils.d.ts.map

package/dist/python-utils.js

@@ -0,0 +1,54 @@
+/**
+ * Python Utilities for Modern Unreal Engine API
+ *
+ * This module provides Python code snippets that use the modern
+ * Unreal Engine Python API instead of deprecated functions.
+ */
+export class PythonUtils {
+    /**
+     * Get all actors in the level using modern API
+     * @returns Python code to get all level actors
+     */
+    static getAllLevelActors() {
+        return `
+# Use modern EditorActorSubsystem instead of deprecated EditorLevelLibrary
+editor_actor_subsystem = unreal.get_editor_subsystem(unreal.EditorActorSubsystem)
+actors = editor_actor_subsystem.get_all_level_actors()
+`.trim();
+    }
+    /**
+     * Get selected actors using modern API
+     * @returns Python code to get selected actors
+     */
+    static getSelectedActors() {
+        return `
+editor_actor_subsystem = unreal.get_editor_subsystem(unreal.EditorActorSubsystem)
+selected_actors = editor_actor_subsystem.get_selected_level_actors()
+`.trim();
+    }
+    /**
+     * Spawn actor from class using modern API
+     * @returns Python code to spawn actor
+     */
+    static spawnActorFromClass() {
+        return `
+editor_actor_subsystem = unreal.get_editor_subsystem(unreal.EditorActorSubsystem)
+# Use spawn_actor_from_class for spawning
+`.trim();
+    }
+    /**
+     * Get a safe way to access actors
+     * @returns Python code with modern API
+     */
+    static getSafeActorAccess() {
+        return `
+# Use modern API
+try:
+    editor_actor_subsystem = unreal.get_editor_subsystem(unreal.EditorActorSubsystem)
+    actors = editor_actor_subsystem.get_all_level_actors() if editor_actor_subsystem else []
+except:
+    actors = []
+`.trim();
+    }
+}
+//# sourceMappingURL=python-utils.js.map

package/dist/resources/actors.d.ts

@@ -0,0 +1,13 @@
+import { UnrealBridge } from '../unreal-bridge.js';
+export declare class ActorResources {
+    private bridge;
+    private cache;
+    private readonly CACHE_TTL_MS;
+    constructor(bridge: UnrealBridge);
+    private getFromCache;
+    private setCache;
+    listActors(): Promise<any>;
+    getActorByName(actorName: string): Promise<any>;
+    getActorTransform(actorPath: string): Promise<any>;
+}
+//# sourceMappingURL=actors.d.ts.map