unreal-engine-mcp-server 0.3.0 → 0.4.0

package/.env.production

@@ -10,11 +10,16 @@ UE_RC_WS_PORT=30020
 USE_CONSOLIDATED_TOOLS=true
 
 # Logging Level
+# Available levels (from quietest to most verbose):
+# - error  : only errors
+# - warn   : warnings and errors
+# - info   : info, warnings, errors (default)
+# - debug  : full debug, very verbose
 LOG_LEVEL=info
 
 # Server Settings
 SERVER_NAME=unreal-engine-mcp
-SERVER_VERSION=0.3.0
+SERVER_VERSION=0.4.0
 
 # Connection Settings
 MAX_RETRY_ATTEMPTS=3

package/Dockerfile

@@ -1,5 +1,5 @@
 # Multi-stage build for efficient image size
-FROM node:20-alpine AS builder
+FROM node:22-alpine AS builder
 
 # Set working directory
 WORKDIR /app
@@ -18,37 +18,20 @@ COPY src ./src
 RUN npm run build
 
 # Production stage
-FROM node:20-alpine
+FROM cgr.dev/chainguard/node:latest
 
-# Install dumb-init for proper signal handling
-RUN apk add --no-cache dumb-init
+ENV NODE_ENV=production
 
-# Create non-root user
-RUN addgroup -g 1001 -S nodejs && \
-    adduser -S nodejs -u 1001
-
-# Set working directory
+# Chainguard node runs as nonroot by default (user: node)
 WORKDIR /app
 
-# Copy package files
-COPY package*.json ./
-
-# Install production dependencies only (skip prepare script)
-RUN npm ci --only=production --ignore-scripts && \
-    npm cache clean --force
+# Copy only package manifests and install production deps in a clean layer
+COPY --chown=node:node package*.json ./
+RUN npm ci --omit=dev --ignore-scripts && npm cache clean --force
 
 # Copy built application from builder stage
-COPY --from=builder /app/dist ./dist
-
-# Change ownership to nodejs user
-RUN chown -R nodejs:nodejs /app
-
-# Switch to non-root user
-USER nodejs
-
-# MCP servers use stdio, no port exposure needed
-# Use dumb-init to handle signals properly
-ENTRYPOINT ["dumb-init", "--"]
+COPY --chown=node:node --from=builder /app/dist ./dist
 
-# Run the MCP server
-CMD ["node", "dist/cli.js"]
+# No shell, no init needed; run as provided nonroot user
+ENTRYPOINT ["/usr/bin/node"]
+CMD ["dist/cli.js"]

package/README.md

@@ -114,7 +114,7 @@ Then enable Python execution in: Edit > Project Settings > Plugins > Remote Cont
 }
 ```
 
-## Available Tools (13 Consolidated)
+## Available Tools (13)
 
 | Tool | Description |
 |------|-------------|
@@ -161,7 +161,6 @@ Blueprints, Materials, Textures, Static/Skeletal Meshes, Levels, Sounds, Particl
 UE_HOST=127.0.0.1              # Unreal Engine host
 UE_RC_HTTP_PORT=30010          # Remote Control HTTP port
 UE_RC_WS_PORT=30020            # Remote Control WebSocket port
-USE_CONSOLIDATED_TOOLS=true    # Use 13 consolidated tools (false = 37 individual)
 LOG_LEVEL=info                 # debug | info | warn | error
 ```
 

package/dist/index.js

@@ -17,6 +17,7 @@ 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 { BuildEnvironmentAdvanced } from './tools/build_environment_advanced.js';
 import { FoliageTools } from './tools/foliage.js';
 import { DebugVisualizationTools } from './tools/debug.js';
 import { PerformanceTools } from './tools/performance.js';
@@ -27,8 +28,6 @@ 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';
@@ -51,16 +50,18 @@ const metrics = {
     uptime: Date.now(),
     recentErrors: []
 };
+// Health check timer and last success tracking (stop pings after inactivity)
+let healthCheckTimer;
+let lastHealthSuccessAt = 0;
 // Configuration
 const CONFIG = {
-    // Tool mode: true = consolidated (13 tools), false = individual (36+ tools)
-    USE_CONSOLIDATED_TOOLS: process.env.USE_CONSOLIDATED_TOOLS !== 'false',
+    // Tooling: use consolidated tools only (13 tools)
     // Connection retry settings
     MAX_RETRY_ATTEMPTS: 3,
     RETRY_DELAY_MS: 2000,
     // Server info
     SERVER_NAME: 'unreal-engine-mcp',
-    SERVER_VERSION: '0.3.0',
+    SERVER_VERSION: '0.4.0',
     // Monitoring
     HEALTH_CHECK_INTERVAL_MS: 30000 // 30 seconds
 };
@@ -84,11 +85,16 @@ function trackPerformance(startTime, success) {
 }
 // Health check function
 async function performHealthCheck(bridge) {
+    // If not connected, do not attempt any ping (stay quiet)
+    if (!bridge.isConnected) {
+        return false;
+    }
     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();
+        lastHealthSuccessAt = Date.now();
         return true;
     }
     catch (err1) {
@@ -97,55 +103,80 @@ async function performHealthCheck(bridge) {
             await bridge.executePython("import sys; sys.stdout.write('OK')");
             metrics.connectionStatus = 'connected';
             metrics.lastHealthCheck = new Date();
+            lastHealthSuccessAt = Date.now();
             return true;
         }
         catch (err2) {
             metrics.connectionStatus = 'error';
             metrics.lastHealthCheck = new Date();
-            log.warn('Health check failed (console and python):', err1, err2);
+            // Avoid noisy warnings when engine may be shutting down; log at debug
+            log.debug('Health check failed (console and python):', err1, err2);
             return false;
         }
     }
 }
 export async function createServer() {
     const bridge = new UnrealBridge();
+    // Disable auto-reconnect loops; connect only on-demand
+    bridge.setAutoReconnectEnabled(false);
     // Initialize response validation with schemas
-    log.info('Initializing response validation...');
-    const toolDefs = CONFIG.USE_CONSOLIDATED_TOOLS ? consolidatedToolDefinitions : toolDefinitions;
+    log.debug('Initializing response validation...');
+    const toolDefs = consolidatedToolDefinitions;
     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 () => {
+    // Summary at debug level to avoid repeated noisy blocks in some shells
+    log.debug(`Registered ${responseValidator.getStats().totalSchemas} output schemas for validation`);
+    // Do NOT connect to Unreal at startup; connect on demand
+    log.debug('Server starting without connecting to Unreal Engine');
+    metrics.connectionStatus = 'disconnected';
+    // Health checks manager (only active when connected)
+    const startHealthChecks = () => {
+        if (healthCheckTimer)
+            return;
+        lastHealthSuccessAt = Date.now();
+        healthCheckTimer = setInterval(async () => {
+            // Only attempt health pings while connected; stay silent otherwise
             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';
+                // Optionally pause fully after 5 minutes of no success
+                const FIVE_MIN_MS = 5 * 60 * 1000;
+                if (!lastHealthSuccessAt || Date.now() - lastHealthSuccessAt > FIVE_MIN_MS) {
+                    if (healthCheckTimer) {
+                        clearInterval(healthCheckTimer);
+                        healthCheckTimer = undefined;
+                    }
+                    log.info('Health checks paused after 5 minutes without a successful response');
                 }
+                return;
             }
-        }, 10000); // Try every 10 seconds
-    }
-    // Start periodic health checks
-    setInterval(() => {
-        performHealthCheck(bridge);
-    }, CONFIG.HEALTH_CHECK_INTERVAL_MS);
+            await performHealthCheck(bridge);
+            // Stop sending echoes if we haven't had a successful response in > 5 minutes
+            const FIVE_MIN_MS = 5 * 60 * 1000;
+            if (!lastHealthSuccessAt || Date.now() - lastHealthSuccessAt > FIVE_MIN_MS) {
+                if (healthCheckTimer) {
+                    clearInterval(healthCheckTimer);
+                    healthCheckTimer = undefined;
+                    log.info('Health checks paused after 5 minutes without a successful response');
+                }
+            }
+        }, CONFIG.HEALTH_CHECK_INTERVAL_MS);
+    };
+    // On-demand connection helper
+    const ensureConnectedOnDemand = async () => {
+        if (bridge.isConnected)
+            return true;
+        const ok = await bridge.tryConnect(3, 5000, 1000);
+        if (ok) {
+            metrics.connectionStatus = 'connected';
+            startHealthChecks();
+        }
+        else {
+            metrics.connectionStatus = 'disconnected';
+        }
+        return ok;
+    };
     // Resources
     const assetResources = new AssetResources(bridge);
     const actorResources = new ActorResources(bridge);
@@ -163,6 +194,7 @@ export async function createServer() {
     const lightingTools = new LightingTools(bridge);
     const landscapeTools = new LandscapeTools(bridge);
     const foliageTools = new FoliageTools(bridge);
+    const buildEnvAdvanced = new BuildEnvironmentAdvanced(bridge);
     const debugTools = new DebugVisualizationTools(bridge);
     const performanceTools = new PerformanceTools(bridge);
     const audioTools = new AudioTools(bridge);
@@ -230,6 +262,10 @@ export async function createServer() {
     server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
         const uri = request.params.uri;
         if (uri === 'ue://assets') {
+            const ok = await ensureConnectedOnDemand();
+            if (!ok) {
+                return { contents: [{ uri, mimeType: 'text/plain', text: 'Unreal Engine not connected (after 3 attempts).' }] };
+            }
             const list = await assetResources.list('/Game', true);
             return {
                 contents: [{
@@ -240,6 +276,10 @@ export async function createServer() {
             };
         }
         if (uri === 'ue://actors') {
+            const ok = await ensureConnectedOnDemand();
+            if (!ok) {
+                return { contents: [{ uri, mimeType: 'text/plain', text: 'Unreal Engine not connected (after 3 attempts).' }] };
+            }
             const list = await actorResources.listActors();
             return {
                 contents: [{
@@ -250,6 +290,10 @@ export async function createServer() {
             };
         }
         if (uri === 'ue://level') {
+            const ok = await ensureConnectedOnDemand();
+            if (!ok) {
+                return { contents: [{ uri, mimeType: 'text/plain', text: 'Unreal Engine not connected (after 3 attempts).' }] };
+            }
             const level = await levelResources.getCurrentLevel();
             return {
                 contents: [{
@@ -260,6 +304,10 @@ export async function createServer() {
             };
         }
         if (uri === 'ue://exposed') {
+            const ok = await ensureConnectedOnDemand();
+            if (!ok) {
+                return { contents: [{ uri, mimeType: 'text/plain', text: 'Unreal Engine not connected (after 3 attempts).' }] };
+            }
             try {
                 const exposed = await bridge.getExposed();
                 return {
@@ -282,17 +330,19 @@ export async function createServer() {
         }
         if (uri === 'ue://health') {
             const uptimeMs = Date.now() - metrics.uptime;
-            // Query engine version and feature flags (best-effort)
+            // Query engine version and feature flags only when connected
             let versionInfo = {};
             let featureFlags = {};
-            try {
-                versionInfo = await bridge.getEngineVersion();
-            }
-            catch { }
-            try {
-                featureFlags = await bridge.getFeatureFlags();
+            if (bridge.isConnected) {
+                try {
+                    versionInfo = await bridge.getEngineVersion();
+                }
+                catch { }
+                try {
+                    featureFlags = await bridge.getFeatureFlags();
+                }
+                catch { }
             }
-            catch { }
             const health = {
                 status: metrics.connectionStatus,
                 uptime: Math.floor(uptimeMs / 1000),
@@ -328,6 +378,10 @@ export async function createServer() {
             };
         }
         if (uri === 'ue://version') {
+            const ok = await ensureConnectedOnDemand();
+            if (!ok) {
+                return { contents: [{ uri, mimeType: 'text/plain', text: 'Unreal Engine not connected (after 3 attempts).' }] };
+            }
             const info = await bridge.getEngineVersion();
             return {
                 contents: [{
@@ -339,17 +393,30 @@ export async function createServer() {
         }
         throw new Error(`Unknown resource: ${uri}`);
     });
-    // Handle tool listing - switch between consolidated (13) or individual (36) tools
+    // Handle tool listing - consolidated tools only
     server.setRequestHandler(ListToolsRequestSchema, async () => {
-        log.info(`Serving ${CONFIG.USE_CONSOLIDATED_TOOLS ? 'consolidated' : 'individual'} tools`);
+        log.info('Serving consolidated tools');
         return {
-            tools: CONFIG.USE_CONSOLIDATED_TOOLS ? consolidatedToolDefinitions : toolDefinitions
+            tools: consolidatedToolDefinitions
         };
     });
-    // Handle tool calls - switch between consolidated (13) or individual (36) tools
+    // Handle tool calls - consolidated tools only (13)
     server.setRequestHandler(CallToolRequestSchema, async (request) => {
         const { name, arguments: args } = request.params;
         const startTime = Date.now();
+        // Ensure connection only when needed, with 3 attempts
+        const connected = await ensureConnectedOnDemand();
+        if (!connected) {
+            const notConnected = {
+                content: [{ type: 'text', text: 'Unreal Engine is not connected (after 3 attempts). Please open UE and try again.' }],
+                success: false,
+                error: 'UE_NOT_CONNECTED',
+                retriable: false,
+                scope: `tool-call/${name}`
+            };
+            trackPerformance(startTime, false);
+            return notConnected;
+        }
         // Create tools object for handler
         const tools = {
             actorTools,
@@ -364,6 +431,7 @@ export async function createServer() {
             lightingTools,
             landscapeTools,
             foliageTools,
+            buildEnvAdvanced,
             debugTools,
             performanceTools,
             audioTools,
@@ -373,18 +441,16 @@ export async function createServer() {
             introspectionTools,
             visualTools,
             engineTools,
+            // Resources for listing and info
+            assetResources,
+            actorResources,
+            levelResources,
             bridge
         };
-        // Use consolidated or individual handler based on configuration
+        // Execute consolidated tool handler
         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);
-            }
+            let result = await handleConsolidatedToolCall(name, args, tools);
             log.debug(`Tool ${name} returned result`);
             // Clean the result to remove circular references
             result = cleanObject(result);

package/dist/resources/actors.js

@@ -25,25 +25,83 @@ export class ActorResources {
         // Use Python to get actors via EditorActorSubsystem
         try {
             const pythonCode = `
-import unreal
+import unreal, json
 actor_subsystem = unreal.get_editor_subsystem(unreal.EditorActorSubsystem)
-actors = actor_subsystem.get_all_level_actors()
+actors = actor_subsystem.get_all_level_actors() if actor_subsystem else []
 actor_list = []
 for actor in actors:
-    if actor:
-        actor_list.append({
-            'name': actor.get_name(),
-            'class': actor.get_class().get_name(),
-            'path': actor.get_path_name()
-        })
-print(f"Found {len(actor_list)} actors")
+    try:
+        if actor:
+            actor_list.append({
+                'name': actor.get_name(),
+                'class': actor.get_class().get_name(),
+                'path': actor.get_path_name()
+            })
+    except Exception:
+        pass
+print('RESULT:' + json.dumps({'success': True, 'count': len(actor_list), 'actors': actor_list}))
       `.trim();
-            const result = await this.bridge.executePython(pythonCode);
-            this.setCache('listActors', result);
-            return result;
+            const resp = await this.bridge.executePythonWithResult(pythonCode);
+            if (resp && typeof resp === 'object' && resp.success === true && Array.isArray(resp.actors)) {
+                this.setCache('listActors', resp);
+                return resp;
+            }
+            // Fallback manual extraction with bracket matching
+            const raw = await this.bridge.executePython(pythonCode);
+            let output = '';
+            if (raw?.LogOutput && Array.isArray(raw.LogOutput))
+                output = raw.LogOutput.map((l) => l.Output || '').join('');
+            else if (typeof raw === 'string')
+                output = raw;
+            else
+                output = JSON.stringify(raw);
+            const marker = 'RESULT:';
+            const idx = output.lastIndexOf(marker);
+            if (idx !== -1) {
+                let i = idx + marker.length;
+                while (i < output.length && output[i] !== '{')
+                    i++;
+                if (i < output.length) {
+                    let depth = 0, inStr = false, esc = false, j = i;
+                    for (; j < output.length; j++) {
+                        const ch = output[j];
+                        if (esc) {
+                            esc = false;
+                            continue;
+                        }
+                        if (ch === '\\') {
+                            esc = true;
+                            continue;
+                        }
+                        if (ch === '"') {
+                            inStr = !inStr;
+                            continue;
+                        }
+                        if (!inStr) {
+                            if (ch === '{')
+                                depth++;
+                            else if (ch === '}') {
+                                depth--;
+                                if (depth === 0) {
+                                    j++;
+                                    break;
+                                }
+                            }
+                        }
+                    }
+                    const jsonStr = output.slice(i, j);
+                    try {
+                        const parsed = JSON.parse(jsonStr);
+                        this.setCache('listActors', parsed);
+                        return parsed;
+                    }
+                    catch { }
+                }
+            }
+            return { success: false, error: 'Failed to parse actors list' };
         }
         catch (err) {
-            return { error: `Failed to list actors: ${err}` };
+            return { success: false, error: `Failed to list actors: ${err}` };
         }
     }
     async getActorByName(actorName) {

package/dist/resources/assets.d.ts

@@ -5,6 +5,7 @@ export declare class AssetResources {
     private cache;
     private get ttlMs();
     private makeKey;
+    private normalizeDir;
     list(dir?: string, _recursive?: boolean, limit?: number): Promise<any>;
     /**
      * List assets with pagination support
@@ -14,8 +15,8 @@ export declare class AssetResources {
      */
     listPaged(dir?: string, page?: number, pageSize?: number, recursive?: boolean): Promise<any>;
     /**
-     * Directory-based listing for paths with too many assets
-     * Shows only immediate children (folders and files) to avoid timeouts
+     * Directory-based listing of immediate children using AssetRegistry.
+     * Returns both subfolders and assets at the given path.
      */
     private listDirectoryOnly;
     find(assetPath: string): Promise<boolean>;