unreal-engine-mcp-server 0.3.0 → 0.3.1

package/src/index.ts

@@ -75,6 +75,10 @@ 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)
@@ -84,7 +88,7 @@ const CONFIG = {
   RETRY_DELAY_MS: 2000,
   // Server info
   SERVER_NAME: 'unreal-engine-mcp',
-  SERVER_VERSION: '0.3.0',
+  SERVER_VERSION: '0.3.1',
   // Monitoring
   HEALTH_CHECK_INTERVAL_MS: 30000 // 30 seconds
 };
@@ -111,11 +115,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 +132,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 +146,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...');
+  log.debug('Initializing response validation...');
   const toolDefs = CONFIG.USE_CONSOLIDATED_TOOLS ? consolidatedToolDefinitions : toolDefinitions;
   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);
@@ -272,6 +301,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 +316,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 +331,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 +346,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 +372,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 +416,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: [{
@@ -394,6 +445,20 @@ export async function createServer() {
   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
     const tools = {

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}` };
     }
   }
 

package/src/tools/consolidated-tool-definitions.ts

@@ -74,18 +74,28 @@ Examples:
     description: `Spawn, delete, and apply physics to actors in the level.
 
 When to use this tool:
-- You need to place an actor or mesh in the level, remove an actor, or nudge an actor with a physics force.
+- Place an actor/mesh, remove an actor, or nudge an actor with a physics force.
+
+Supported actions:
+- spawn
+- delete
+- apply_force
 
 Spawning:
 - classPath can be a class name (e.g., StaticMeshActor, CameraActor) OR an asset path (e.g., /Engine/BasicShapes/Cube, /Game/Meshes/SM_Rock).
-- If an asset path is provided, a StaticMeshActor is auto-spawned with the mesh assigned.
+- Asset paths auto-spawn StaticMeshActor with the mesh assigned.
 
 Deleting:
-- Finds actors by label/name (case-insensitive). Deletes matching actors.
+- Finds actors by label/name (case-insensitive) and deletes matches.
 
 Apply force:
 - Applies a world-space force vector to an actor with physics enabled.
 
+Tips:
+- classPath accepts classes or asset paths; simple names like Cube auto-resolve to engine assets.
+- location/rotation are optional; defaults are used if omitted.
+- For delete/apply_force, provide actorName.
+
 Examples:
 - {"action":"spawn","classPath":"/Engine/BasicShapes/Cube","location":{"x":0,"y":0,"z":100}}
 - {"action":"delete","actorName":"Cube_1"}
@@ -154,9 +164,15 @@ Examples:
 When to use this tool:
 - Start/stop a PIE session, move the viewport camera, or change viewmode (Lit/Unlit/Wireframe/etc.).
 
+Supported actions:
+- play
+- stop
+- set_camera
+- set_view_mode
+
 Notes:
-- View modes are validated and unsafe modes are blocked.
-- Camera accepts location and/or rotation (both optional). Values are normalized.
+- View modes are validated; unsafe modes are blocked.
+- Camera accepts location/rotation (optional); values normalized.
 
 Examples:
 - {"action":"play"}
@@ -225,6 +241,18 @@ Examples:
 When to use this tool:
 - Switch to a level, save the current level, stream sublevels, add a light, or start a lighting build.
 
+Supported actions:
+- load
+- save
+- stream
+- create_light
+- build_lighting
+
+Tips:
+- Use /Game paths for levels (e.g., /Game/Maps/Level).
+- For streaming, set shouldBeLoaded and shouldBeVisible accordingly.
+- For lights, provide lightType and optional location/intensity.
+
 Examples:
 - {"action":"load","levelPath":"/Game/Maps/Lobby"}
 - {"action":"stream","levelName":"Sublevel_A","shouldBeLoaded":true,"shouldBeVisible":true}
@@ -290,6 +318,16 @@ Examples:
 When to use this tool:
 - Generate an Anim Blueprint for a skeleton, play a Montage/Animation on an actor, or enable ragdoll.
 
+Supported actions:
+- create_animation_bp
+- play_montage
+- setup_ragdoll
+
+Tips:
+- Ensure the montage/animation is compatible with the target actor/skeleton.
+- setup_ragdoll requires a valid physicsAssetName on the skeleton.
+- Use savePath when creating new assets.
+
 Examples:
 - {"action":"create_animation_bp","name":"ABP_Hero","skeletonPath":"/Game/Characters/Hero/SK_Hero_Skeleton","savePath":"/Game/Characters/Hero"}
 - {"action":"play_montage","actorName":"Hero","montagePath":"/Game/Anim/MT_Attack"}
@@ -338,6 +376,15 @@ Examples:
 When to use this tool:
 - Spawn a Niagara system at a location, create a particle effect by type tag, or draw debug geometry for planning.
 
+Supported actions:
+- particle
+- niagara
+- debug_shape
+
+Tips:
+- Set color as RGBA [r,g,b,a]; scale defaults to 1 if omitted.
+- Use debug shapes for quick layout planning and measurements.
+
 Examples:
 - {"action":"niagara","systemPath":"/Game/FX/NS_Explosion","location":{"x":0,"y":0,"z":200},"scale":1.0}
 - {"action":"particle","effectType":"Smoke","name":"SMK1","location":{"x":100,"y":0,"z":50}}
@@ -407,6 +454,14 @@ Examples:
 When to use this tool:
 - Quickly scaffold a Blueprint asset or add a component to an existing Blueprint.
 
+Supported actions:
+- create
+- add_component
+
+Tips:
+- blueprintType can be Actor, Pawn, Character, etc.
+- Component names should be unique within the Blueprint.
+
 Examples:
 - {"action":"create","name":"BP_Switch","blueprintType":"Actor","savePath":"/Game/Blueprints"}
 - {"action":"add_component","name":"BP_Switch","componentType":"PointLightComponent","componentName":"KeyLight"}`,
@@ -449,10 +504,19 @@ Examples:
 When to use this tool:
 - Create a procedural terrain alternative, add/paint foliage, or attempt a landscape workflow.
 
+Supported actions:
+- create_landscape
+- sculpt
+- add_foliage
+- paint_foliage
+
 Important:
 - Native Landscape creation via Python is limited and may return a helpful error suggesting Landscape Mode in the editor.
 - Foliage helpers create FoliageType assets and support simple placement.
 
+Tips:
+- Adjust brushSize and strength to tune sculpting results.
+
 Examples:
 - {"action":"create_landscape","name":"Landscape_Basic","sizeX":1024,"sizeY":1024}
 - {"action":"add_foliage","name":"FT_Grass","meshPath":"/Game/Foliage/SM_Grass","density":300}
@@ -512,6 +576,21 @@ Examples:
 When to use this tool:
 - Toggle profiling and FPS stats, adjust quality (sg.*), play a sound, create/show a basic widget, take a screenshot, or launch/quit the editor.
 
+Supported actions:
+- profile
+- show_fps
+- set_quality
+- play_sound
+- create_widget
+- show_widget
+- screenshot
+- engine_start
+- engine_quit
+
+Tips:
+- Screenshot resolution format: 1920x1080.
+- engine_start can read UE project path from env; provide editorExe/projectPath if needed.
+
 Examples:
 - {"action":"show_fps","enabled":true}
 - {"action":"set_quality","category":"Shadows","level":2}
@@ -595,6 +674,9 @@ Safety:
 - Dangerous commands are blocked (quit/exit, GPU crash triggers, unsafe visualizebuffer modes, etc.).
 - Unknown commands will return a warning instead of crashing.
 
+Tips:
+- Prefer dedicated tools (system_control, control_editor) when available for structured control.
+
 Examples:
 - {"command":"stat fps"}
 - {"command":"viewmode wireframe"}
@@ -627,6 +709,18 @@ Examples:
 When to use this tool:
 - Automate Remote Control (RC) preset authoring and interaction from the assistant.
 
+Supported actions:
+- create_preset
+- expose_actor
+- expose_property
+- list_fields
+- set_property
+- get_property
+
+Tips:
+- value must be JSON-serializable.
+- Use objectPath/presetPath with full asset/object paths.
+
 Examples:
 - {"action":"create_preset","name":"LivePreset","path":"/Game/RCPresets"}
 - {"action":"expose_actor","presetPath":"/Game/RCPresets/LivePreset","actorName":"CameraActor"}
@@ -672,6 +766,26 @@ Examples:
 When to use this tool:
 - Build quick cinematics: create/open a sequence, add a camera or actors, tweak properties, and play.
 
+Supported actions:
+- create
+- open
+- add_camera
+- add_actor
+- add_actors
+- remove_actors
+- get_bindings
+- add_spawnable_from_class
+- play
+- pause
+- stop
+- set_properties
+- get_properties
+- set_playback_speed
+
+Tips:
+- Set spawnable=true to auto-create a camera actor.
+- Use frameRate/lengthInFrames to define timing; use playbackStart/End to trim.
+
 Examples:
 - {"action":"create","name":"Intro","path":"/Game/Cinematics"}
 - {"action":"add_camera","spawnable":true}
@@ -735,6 +849,14 @@ Examples:
 When to use this tool:
 - Inspect an object by path (class default object or actor/component) and optionally modify properties.
 
+Supported actions:
+- inspect_object
+- set_property
+
+Tips:
+- propertyName is case-sensitive; ensure it exists on the target object.
+- For class default objects (CDOs), use the /Script/...Default__Class path.
+
 Examples:
 - {"action":"inspect_object","objectPath":"/Script/Engine.Default__Engine"}
 - {"action":"set_property","objectPath":"/Game/MyActor","propertyName":"CustomBool","value":true}`,

package/src/tools/consolidated-tool-handlers.ts

@@ -1,6 +1,9 @@
 // Consolidated tool handlers - maps 13 tools to all 36 operations
 import { handleToolCall } from './tool-handlers.js';
 import { cleanObject } from '../utils/safe-json.js';
+import { Logger } from '../utils/logger.js';
+
+const log = new Logger('ConsolidatedToolHandler');
 
 export async function handleConsolidatedToolCall(
   name: string,
@@ -8,7 +11,8 @@ export async function handleConsolidatedToolCall(
   tools: any
 ) {
   const startTime = Date.now();
-  console.log(`[ConsolidatedToolHandler] Starting execution of ${name} at ${new Date().toISOString()}`);
+  // Use scoped logger (stderr) to avoid polluting stdout JSON
+  log.debug(`Starting execution of ${name} at ${new Date().toISOString()}`);
   
   try {
     // Validate args is not null/undefined