unreal-engine-mcp-server 0.3.0 → 0.4.0

package/dist/utils/response-validator.js

@@ -27,7 +27,8 @@ export class ResponseValidator {
         try {
             const validator = this.ajv.compile(outputSchema);
             this.validators.set(toolName, validator);
-            log.info(`Registered output schema for tool: ${toolName}`);
+            // Demote per-tool schema registration to debug to reduce log noise
+            log.debug(`Registered output schema for tool: ${toolName}`);
         }
         catch (_error) {
             log.error(`Failed to compile output schema for ${toolName}:`, _error);
@@ -75,14 +76,17 @@ export class ResponseValidator {
         };
     }
     /**
-     * Wrap a tool response with validation
+     * Wrap a tool response with validation and MCP-compliant content shape.
+     *
+     * MCP tools/call responses must contain a `content` array. Many internal
+     * handlers return structured JSON objects (e.g., { success, message, ... }).
+     * This wrapper serializes such objects into a single text block while keeping
+     * existing `content` responses intact.
      */
     wrapResponse(toolName, response) {
         // Ensure response is safe to serialize first
         try {
-            // The response should already be cleaned, but double-check
             if (response && typeof response === 'object') {
-                // Make sure we can serialize it
                 JSON.stringify(response);
             }
         }
@@ -90,21 +94,45 @@ export class ResponseValidator {
             log.error(`Response for ${toolName} contains circular references, cleaning...`);
             response = cleanObject(response);
         }
-        const validation = this.validateResponse(toolName, response);
-        // Add validation metadata
+        // If handler already returned MCP content, keep it as-is (still validate)
+        const alreadyMcpShaped = response && typeof response === 'object' && Array.isArray(response.content);
+        // Choose the payload to validate: if already MCP-shaped, validate the
+        // structured content extracted from text; otherwise validate the object directly.
+        const validationTarget = alreadyMcpShaped ? response : response;
+        const validation = this.validateResponse(toolName, validationTarget);
         if (!validation.valid) {
             log.warn(`Tool ${toolName} response validation failed:`, validation.errors);
-            // Add warning to response but don't fail
-            if (response && typeof response === 'object') {
-                response._validation = {
-                    valid: false,
-                    errors: validation.errors
-                };
+        }
+        // If it's already MCP-shaped, return as-is (optionally append validation meta)
+        if (alreadyMcpShaped) {
+            if (!validation.valid) {
+                try {
+                    response._validation = { valid: false, errors: validation.errors };
+                }
+                catch { }
             }
+            return response;
+        }
+        // Otherwise, wrap structured result into MCP content
+        let text;
+        try {
+            // Pretty-print small objects for readability
+            text = typeof response === 'string'
+                ? response
+                : JSON.stringify(response ?? { success: true }, null, 2);
+        }
+        catch (_e) {
+            text = String(response);
+        }
+        const wrapped = {
+            content: [
+                { type: 'text', text }
+            ]
+        };
+        if (!validation.valid) {
+            wrapped._validation = { valid: false, errors: validation.errors };
         }
-        // Don't add structuredContent to the response - it's for internal validation only
-        // Adding it can cause circular references
-        return response;
+        return wrapped;
     }
     /**
      * Get validation statistics

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "unreal-engine-mcp-server",
-"version": "0.3.0",
-  "description": "Production-ready MCP server for Unreal Engine integration with consolidated and individual tool modes",
+  "version": "0.4.0",
+  "description": "Production-ready MCP server for Unreal Engine integration using consolidated tools only",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "bin": {
-    "unreal-mcp-server": "dist/cli.js"
+    "unreal-engine-mcp-server": "dist/cli.js"
   },
   "scripts": {
     "build": "tsc -p tsconfig.json",
@@ -34,9 +34,9 @@
   "license": "MIT",
   "mcpName": "io.github.ChiR24/unreal-engine-mcp",
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.4.0",
+    "@modelcontextprotocol/sdk": "^1.18.1",
     "ajv": "^8.12.0",
-    "axios": "^1.7.2",
+    "axios": "^1.12.2",
     "dotenv": "^16.4.5",
     "ws": "^8.18.0",
     "yargs": "^17.7.2",

package/server.json

@@ -2,13 +2,13 @@
   "$schema": "https://static.modelcontextprotocol.io/schemas/2025-07-09/server.schema.json",
   "name": "io.github.ChiR24/unreal-engine-mcp",
   "description": "Production-ready MCP server for Unreal Engine with comprehensive game development tools",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "packages": [
     {
       "registry_type": "npm",
       "registry_base_url": "https://registry.npmjs.org",
       "identifier": "unreal-engine-mcp-server",
-      "version": "0.3.0",
+      "version": "0.4.0",
       "transport": {
         "type": "stdio"
       },

package/src/index.ts

@@ -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';
@@ -75,16 +74,19 @@ const metrics: PerformanceMetrics = {
   recentErrors: []
 };
 
+// Health check timer and last success tracking (stop pings after inactivity)
+let healthCheckTimer: NodeJS.Timeout | undefined;
+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
 };
@@ -111,11 +113,16 @@ function trackPerformance(startTime: number, success: boolean) {
 
 // Health check function
 async function performHealthCheck(bridge: UnrealBridge): Promise<boolean> {
+  // 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) {
     // Fallback: minimal Python ping (if Python plugin is enabled)
@@ -123,11 +130,13 @@ async function performHealthCheck(bridge: UnrealBridge): Promise<boolean> {
       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;
     }
   }
@@ -135,50 +144,68 @@ async function performHealthCheck(bridge: UnrealBridge): Promise<boolean> {
 
 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;
+// Initialize response validation with schemas
+  log.debug('Initializing response validation...');
+  const toolDefs = consolidatedToolDefinitions;
   toolDefs.forEach((tool: any) => {
     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 (): Promise<boolean> => {
+    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);
@@ -198,6 +225,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);
@@ -272,6 +300,10 @@ export async function createServer() {
     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: [{
@@ -283,6 +315,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: [{
@@ -294,6 +330,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: [{
@@ -305,6 +345,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 {
@@ -327,11 +371,13 @@ 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: any = {};
       let featureFlags: any = {};
-      try { versionInfo = await bridge.getEngineVersion(); } catch {}
-      try { featureFlags = await bridge.getFeatureFlags(); } catch {}
+      if (bridge.isConnected) {
+        try { versionInfo = await bridge.getEngineVersion(); } catch {}
+        try { featureFlags = await bridge.getFeatureFlags(); } catch {}
+      }
       const health = {
         status: metrics.connectionStatus,
         uptime: Math.floor(uptimeMs / 1000),
@@ -369,6 +415,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: [{
@@ -382,20 +432,34 @@ 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}`
+      } as any;
+      trackPerformance(startTime, false);
+      return notConnected;
+    }
     
-    // Create tools object for handler
+// Create tools object for handler
     const tools = {
       actorTools,
       assetTools,
@@ -409,6 +473,7 @@ export async function createServer() {
       lightingTools,
       landscapeTools,
       foliageTools,
+      buildEnvAdvanced,
       debugTools,
       performanceTools,
       audioTools,
@@ -418,19 +483,18 @@ 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`);
       

package/src/resources/actors.ts

@@ -34,25 +34,63 @@ 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 as any).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: any) => 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}` };
     }
   }