unreal-engine-mcp-server 0.5.2 → 0.5.4

package/src/services/metrics-server.ts

@@ -3,7 +3,6 @@ import { HealthMonitor } from './health-monitor.js';
 import { AutomationBridge } from '../automation/index.js';
 import { Logger } from '../utils/logger.js';
 import { wasmIntegration } from '../wasm/index.js';
-import { DEFAULT_AUTOMATION_HOST } from '../constants.js';
 
 interface MetricsServerOptions {
   healthMonitor: HealthMonitor;
@@ -85,7 +84,7 @@ function formatPrometheusMetrics(options: MetricsServerOptions): string {
   return lines.join('\n') + '\n';
 }
 
-export function startMetricsServer(options: MetricsServerOptions): void {
+export function startMetricsServer(options: MetricsServerOptions): http.Server | null {
   const { logger } = options;
 
   const portEnv = process.env.MCP_METRICS_PORT || process.env.PROMETHEUS_PORT;
@@ -93,7 +92,31 @@ export function startMetricsServer(options: MetricsServerOptions): void {
 
   if (!port || !Number.isFinite(port) || port <= 0) {
     logger.debug('Metrics server disabled (set MCP_METRICS_PORT to enable Prometheus /metrics endpoint).');
-    return;
+    return null;
+  }
+
+  const host = process.env.MCP_METRICS_HOST || '127.0.0.1';
+
+  // Simple rate limiting: max 60 requests per minute per IP
+  const RATE_LIMIT_WINDOW_MS = 60000;
+  const RATE_LIMIT_MAX_REQUESTS = 60;
+  const requestCounts = new Map<string, { count: number; resetAt: number }>();
+
+  function checkRateLimit(ip: string): boolean {
+    const now = Date.now();
+    const record = requestCounts.get(ip);
+
+    if (!record || now >= record.resetAt) {
+      requestCounts.set(ip, { count: 1, resetAt: now + RATE_LIMIT_WINDOW_MS });
+      return true;
+    }
+
+    if (record.count >= RATE_LIMIT_MAX_REQUESTS) {
+      return false;
+    }
+
+    record.count++;
+    return true;
   }
 
   try {
@@ -117,26 +140,37 @@ export function startMetricsServer(options: MetricsServerOptions): void {
         return;
       }
 
+      const clientIp = req.socket.remoteAddress || 'unknown';
+      if (!checkRateLimit(clientIp)) {
+        res.statusCode = 429;
+        res.setHeader('Retry-After', '60');
+        res.end('Too Many Requests');
+        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 as any);
+        logger.warn('Failed to render /metrics payload', err as Error);
         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.listen(port, host, () => {
+      logger.info(`Prometheus metrics server listening on http://${host}:${port}/metrics`);
     });
 
     server.on('error', (err) => {
       logger.warn('Metrics server error', err as any);
     });
+
+    return server;
   } catch (err) {
     logger.warn('Failed to start metrics server', err as any);
+    return null;
   }
 }

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

@@ -487,7 +487,7 @@ Supported actions:
             'create_volumetric_fog', 'create_particle_trail', 'create_environment_effect', 'create_impact_effect', 'create_niagara_ribbon',
             'activate', 'activate_effect', 'deactivate', 'reset', 'advance_simulation',
             'add_niagara_module', 'connect_niagara_pins', 'remove_niagara_node', 'set_niagara_parameter',
-            'clear_debug_shapes', 'cleanup'
+            'clear_debug_shapes', 'cleanup', 'list_debug_shapes'
           ],
           description: 'Action'
         },
@@ -737,7 +737,7 @@ Supported actions:
             'get_properties', 'set_properties', 'duplicate', 'rename', 'delete', 'list', 'get_metadata', 'set_metadata',
             'add_spawnable_from_class', 'add_track', 'add_section', 'set_display_rate', 'set_tick_resolution',
             'set_work_range', 'set_view_range', 'set_track_muted', 'set_track_solo', 'set_track_locked',
-            'list_tracks', 'remove_track'
+            'list_tracks', 'remove_track', 'list_track_types'
           ],
           description: 'Action'
         },
@@ -1100,7 +1100,7 @@ Supported actions:
             'spawn_light', 'create_light', 'spawn_sky_light', 'create_sky_light', 'ensure_single_sky_light',
             'create_lightmass_volume', 'create_lighting_enabled_level', 'create_dynamic_light',
             'setup_global_illumination', 'configure_shadows', 'set_exposure', 'set_ambient_occlusion', 'setup_volumetric_fog',
-            'build_lighting'
+            'build_lighting', 'list_light_types'
           ],
           description: 'Action'
         },

package/src/tools/debug.ts

@@ -611,4 +611,12 @@ export class DebugVisualizationTools {
       return { success: false, error: `Failed to clear debug shapes: ${err}` };
     }
   }
+
+  async listDebugShapes() {
+    if (this.automationBridge) {
+      const response = await this.automationBridge.sendAutomationRequest('list_debug_shapes', {});
+      return response;
+    }
+    return { success: false, error: 'AUTOMATION_BRIDGE_REQUIRED', message: 'Listing debug shapes requires Automation Bridge' };
+  }
 }

package/src/tools/handlers/actor-handlers.ts

@@ -2,33 +2,14 @@ import { ITools } from '../../types/tool-interfaces.js';
 import { executeAutomationRequest } from './common-handlers.js';
 import { normalizeArgs } from './argument-helper.js';
 import { ResponseFactory } from '../../utils/response-factory.js';
+import { ACTOR_CLASS_ALIASES, getRequiredComponent } from '../../config/class-aliases.js';
 
 type ActorActionHandler = (args: any, tools: ITools) => Promise<any>;
 
 const handlers: Record<string, ActorActionHandler> = {
     spawn: async (args, tools) => {
-        // Class name aliases for user-friendly names
-        const classAliases: Record<string, string> = {
-            'SplineActor': '/Script/Engine.Actor',  // Use Actor with SplineComponent
-            'Spline': '/Script/Engine.Actor',       // Use Actor with SplineComponent
-            'PointLight': '/Script/Engine.PointLight',
-            'SpotLight': '/Script/Engine.SpotLight',
-            'DirectionalLight': '/Script/Engine.DirectionalLight',
-            'Camera': '/Script/Engine.CameraActor',
-            'CameraActor': '/Script/Engine.CameraActor',
-            'StaticMeshActor': '/Script/Engine.StaticMeshActor',
-            'SkeletalMeshActor': '/Script/Engine.SkeletalMeshActor',
-            'PlayerStart': '/Script/Engine.PlayerStart',
-            'TriggerBox': '/Script/Engine.TriggerBox',
-            'TriggerSphere': '/Script/Engine.TriggerSphere',
-            'BlockingVolume': '/Script/Engine.BlockingVolume',
-            'Pawn': '/Script/Engine.Pawn',
-            'Character': '/Script/Engine.Character',
-            'Actor': '/Script/Engine.Actor'
-        };
-
         const params = normalizeArgs(args, [
-            { key: 'classPath', aliases: ['class', 'type', 'actorClass'], required: true, map: classAliases },
+            { key: 'classPath', aliases: ['class', 'type', 'actorClass'], required: true, map: ACTOR_CLASS_ALIASES },
             { key: 'actorName', aliases: ['name'] },
             { key: 'timeoutMs', default: undefined }
         ]);
@@ -39,20 +20,13 @@ const handlers: Record<string, ActorActionHandler> = {
         // failure so tests can exercise timeout handling deterministically
         // without relying on editor performance.
         if (typeof timeoutMs === 'number' && timeoutMs > 0 && timeoutMs < 200) {
-            return {
-                success: false,
-                error: `Timeout too small for spawn operation: ${timeoutMs}ms`,
-                message: 'Timeout too small for spawn operation'
-            };
+            throw new Error(`Timeout too small for spawn operation: ${timeoutMs}ms`);
         }
 
         // For SplineActor alias, add SplineComponent automatically
-        // Check original args for raw input or assume normalized classPath check is sufficient if map didn't obscure it?
-        // Map transforms 'SplineActor' -> '/Script/Engine.Actor', so we check original args.
+        // Check original args for raw input since map transforms the alias
         const originalClass = args.classPath || args.class || args.type || args.actorClass;
-        const componentToAdd = (originalClass === 'SplineActor' || originalClass === 'Spline')
-            ? 'SplineComponent'
-            : undefined;
+        const componentToAdd = getRequiredComponent(originalClass);
 
         const result = await tools.actorTools.spawn({
             classPath: params.classPath,

package/src/tools/handlers/asset-handlers.ts

@@ -188,9 +188,27 @@ export async function handleAssetTools(action: string, args: any, tools: ITools)
           throw new Error('No paths provided for delete action');
         }
 
-        const res = await tools.assetTools.deleteAssets({ paths });
+        // Normalize paths: strip object sub-path suffix (e.g., /Game/Folder/Asset.Asset -> /Game/Folder/Asset)
+        // This handles the common pattern where full object paths are provided instead of package paths
+        const normalizedPaths = paths.map(p => {
+          let normalized = p.replace(/\\/g, '/').trim();
+          // If the path contains a dot after the last slash, it's likely an object path (e.g., /Game/Folder/Asset.Asset)
+          const lastSlash = normalized.lastIndexOf('/');
+          if (lastSlash >= 0) {
+            const afterSlash = normalized.substring(lastSlash + 1);
+            const dotIndex = afterSlash.indexOf('.');
+            if (dotIndex > 0) {
+              // Strip the .ObjectName suffix
+              normalized = normalized.substring(0, lastSlash + 1 + dotIndex);
+            }
+          }
+          return normalized;
+        });
+
+        const res = await tools.assetTools.deleteAssets({ paths: normalizedPaths });
         return ResponseFactory.success(res, 'Assets deleted successfully');
       }
+
       case 'generate_lods': {
         const params = normalizeArgs(args, [
           { key: 'assetPath', required: true },

package/src/tools/handlers/blueprint-handlers.ts

@@ -368,7 +368,7 @@ export async function handleBlueprintTools(action: string, args: any, tools: ITo
 }
 
 export async function handleBlueprintGet(args: any, tools: ITools) {
-  const res = await executeAutomationRequest(tools, 'blueprint_get', args, 'Automation bridge not available for blueprint operations');
+  const res = await executeAutomationRequest(tools, 'blueprint_get', args, 'Automation bridge not available for blueprint operations') as { success?: boolean; message?: string } | null;
   if (res && res.success) {
     return cleanObject({
       ...res,

package/src/tools/handlers/common-handlers.ts

@@ -1,12 +1,19 @@
 import { ITools } from '../../types/tool-interfaces.js';
+import type { HandlerArgs, Vector3, Rotator } from '../../types/handler-types.js';
 
-export function ensureArgsPresent(args: any) {
+/**
+ * Validates that args is not null/undefined.
+ */
+export function ensureArgsPresent(args: unknown): asserts args is Record<string, unknown> {
   if (args === null || args === undefined) {
     throw new Error('Invalid arguments: null or undefined');
   }
 }
 
-export function requireAction(args: any): string {
+/**
+ * Extracts and validates the 'action' field from args.
+ */
+export function requireAction(args: HandlerArgs): string {
   ensureArgsPresent(args);
   const action = args.action;
   if (typeof action !== 'string' || action.trim() === '') {
@@ -15,20 +22,26 @@ export function requireAction(args: any): string {
   return action;
 }
 
-export function requireNonEmptyString(value: any, field: string, message?: string): string {
+/**
+ * Validates that a value is a non-empty string.
+ */
+export function requireNonEmptyString(value: unknown, field: string, message?: string): string {
   if (typeof value !== 'string' || value.trim() === '') {
     throw new Error(message ?? `Invalid ${field}: must be a non-empty string`);
   }
   return value;
 }
 
+/**
+ * Execute a request via the automation bridge.
+ */
 export async function executeAutomationRequest(
   tools: ITools,
   toolName: string,
-  args: any,
+  args: HandlerArgs,
   errorMessage: string = 'Automation bridge not available',
   options: { timeoutMs?: number } = {}
-) {
+): Promise<unknown> {
   const automationBridge = tools.automationBridge;
   // If the bridge is missing or not a function, we can't proceed with automation requests
   if (!automationBridge || typeof automationBridge.sendAutomationRequest !== 'function') {
@@ -42,11 +55,14 @@ export async function executeAutomationRequest(
   return await automationBridge.sendAutomationRequest(toolName, args, options);
 }
 
+/** Input type for location normalization */
+type LocationInput = Vector3 | [number, number, number] | number[] | null | undefined;
+
 /**
  * Normalize location to [x, y, z] array format
  * Accepts both {x,y,z} object and [x,y,z] array formats
  */
-export function normalizeLocation(location: any): [number, number, number] | undefined {
+export function normalizeLocation(location: LocationInput): [number, number, number] | undefined {
   if (!location) return undefined;
 
   // Already array format
@@ -56,17 +72,21 @@ export function normalizeLocation(location: any): [number, number, number] | und
 
   // Object format {x, y, z}
   if (typeof location === 'object' && ('x' in location || 'y' in location || 'z' in location)) {
-    return [Number(location.x) || 0, Number(location.y) || 0, Number(location.z) || 0];
+    const loc = location as Vector3;
+    return [Number(loc.x) || 0, Number(loc.y) || 0, Number(loc.z) || 0];
   }
 
   return undefined;
 }
 
+/** Input type for rotation normalization */
+type RotationInput = Rotator | [number, number, number] | number[] | null | undefined;
+
 /**
  * Normalize rotation to {pitch, yaw, roll} object format
  * Accepts both {pitch,yaw,roll} object and [pitch,yaw,roll] array formats
  */
-export function normalizeRotation(rotation: any): { pitch: number; yaw: number; roll: number } | undefined {
+export function normalizeRotation(rotation: RotationInput): Rotator | undefined {
   if (!rotation) return undefined;
 
   // Array format [pitch, yaw, roll]
@@ -76,10 +96,11 @@ export function normalizeRotation(rotation: any): { pitch: number; yaw: number;
 
   // Already object format
   if (typeof rotation === 'object') {
+    const rot = rotation as Rotator;
     return {
-      pitch: Number(rotation.pitch) || 0,
-      yaw: Number(rotation.yaw) || 0,
-      roll: Number(rotation.roll) || 0
+      pitch: Number(rot.pitch) || 0,
+      yaw: Number(rot.yaw) || 0,
+      roll: Number(rot.roll) || 0
     };
   }
 

package/src/tools/handlers/editor-handlers.ts

@@ -1,8 +1,9 @@
 import { cleanObject } from '../../utils/safe-json.js';
 import { ITools } from '../../types/tool-interfaces.js';
+import type { EditorArgs } from '../../types/handler-types.js';
 import { executeAutomationRequest, requireNonEmptyString } from './common-handlers.js';
 
-export async function handleEditorTools(action: string, args: any, tools: ITools) {
+export async function handleEditorTools(action: string, args: EditorArgs, tools: ITools) {
   switch (action) {
     case 'play': {
       const res = await tools.editorTools.playInEditor(args.timeoutMs);
@@ -16,14 +17,14 @@ export async function handleEditorTools(action: string, args: any, tools: ITools
     case 'eject': {
       const inPie = await tools.editorTools.isInPIE();
       if (!inPie) {
-        return { success: false, error: 'NOT_IN_PIE', message: 'Cannot eject while not in PIE' };
+        throw new Error('Cannot eject while not in PIE');
       }
       return await executeAutomationRequest(tools, 'control_editor', { action: 'eject' });
     }
     case 'possess': {
       const inPie = await tools.editorTools.isInPIE();
       if (!inPie) {
-        return { success: false, error: 'NOT_IN_PIE', message: 'Cannot possess actor while not in PIE' };
+        throw new Error('Cannot possess actor while not in PIE');
       }
       return await executeAutomationRequest(tools, 'control_editor', args);
     }
@@ -40,7 +41,7 @@ export async function handleEditorTools(action: string, args: any, tools: ITools
       return cleanObject(res);
     }
     case 'console_command': {
-      const res = await tools.editorTools.executeConsoleCommand(args.command);
+      const res = await tools.editorTools.executeConsoleCommand(args.command ?? '');
       return cleanObject(res);
     }
     case 'set_camera': {
@@ -63,17 +64,17 @@ export async function handleEditorTools(action: string, args: any, tools: ITools
       return { success: true, message: 'Stepped frame', action: 'step_frame' };
     }
     case 'create_bookmark': {
-      const idx = parseInt(args.bookmarkName) || 0;
+      const idx = parseInt(args.bookmarkName ?? '0') || 0;
       await tools.editorTools.executeConsoleCommand(`r.SetBookmark ${idx}`);
       return { success: true, message: `Created bookmark ${idx}`, action: 'create_bookmark' };
     }
     case 'jump_to_bookmark': {
-      const idx = parseInt(args.bookmarkName) || 0;
+      const idx = parseInt(args.bookmarkName ?? '0') || 0;
       await tools.editorTools.executeConsoleCommand(`r.JumpToBookmark ${idx}`);
       return { success: true, message: `Jumped to bookmark ${idx}`, action: 'jump_to_bookmark' };
     }
     case 'set_preferences': {
-      const res = await tools.editorTools.setEditorPreferences(args.category, args.preferences);
+      const res = await tools.editorTools.setEditorPreferences(args.category ?? '', args.preferences ?? {});
       return cleanObject(res);
     }
     case 'open_asset': {

package/src/tools/handlers/effect-handlers.ts

@@ -100,6 +100,10 @@ export async function handleEffectTools(action: string, args: any, tools: ITools
   if (action === 'clear_debug_shapes') {
     return executeAutomationRequest(tools, action, args);
   }
+  // Discovery action: list available debug shape types
+  if (action === 'list_debug_shapes') {
+    return executeAutomationRequest(tools, 'list_debug_shapes', args);
+  }
   if (action === 'cleanup') {
     args.action = 'cleanup';
     args.subAction = 'cleanup';

package/src/tools/handlers/graph-handlers.ts

@@ -1,8 +1,9 @@
 import { cleanObject } from '../../utils/safe-json.js';
 import { ITools } from '../../types/tool-interfaces.js';
+import type { GraphArgs } from '../../types/handler-types.js';
 import { executeAutomationRequest } from './common-handlers.js';
 
-export async function handleGraphTools(toolName: string, action: string, args: any, tools: ITools) {
+export async function handleGraphTools(toolName: string, action: string, args: GraphArgs, tools: ITools) {
     // Common validation
     if (!args.assetPath && !args.blueprintPath && !args.systemPath) {
         // Some actions might not need a path if they operate on "currently open" asset, 
@@ -20,11 +21,11 @@ export async function handleGraphTools(toolName: string, action: string, args: a
         case 'manage_behavior_tree':
             return handleBehaviorTree(action, args, tools);
         default:
-            return { success: false, error: 'UNKNOWN_TOOL', message: `Unknown graph tool: ${toolName}` };
+            throw new Error(`Unknown graph tool: ${toolName}`);
     }
 }
 
-async function handleBlueprintGraph(action: string, args: any, tools: ITools) {
+async function handleBlueprintGraph(action: string, args: GraphArgs, tools: ITools) {
     const processedArgs = { ...args, subAction: action };
 
     // Default graphName
@@ -95,7 +96,7 @@ async function handleBlueprintGraph(action: string, args: any, tools: ITools) {
     return cleanObject({ ...res, ...(res.result || {}) });
 }
 
-async function handleNiagaraGraph(action: string, args: any, tools: ITools) {
+async function handleNiagaraGraph(action: string, args: GraphArgs, tools: ITools) {
     const payload = { ...args, subAction: action };
     // Map systemPath to assetPath if missing
     if (payload.systemPath && !payload.assetPath) {
@@ -105,12 +106,12 @@ async function handleNiagaraGraph(action: string, args: any, tools: ITools) {
     return cleanObject({ ...res, ...(res.result || {}) });
 }
 
-async function handleMaterialGraph(action: string, args: any, tools: ITools) {
+async function handleMaterialGraph(action: string, args: GraphArgs, tools: ITools) {
     const res: any = await executeAutomationRequest(tools, 'manage_material_graph', { ...args, subAction: action }, 'Automation bridge not available');
     return cleanObject({ ...res, ...(res.result || {}) });
 }
 
-async function handleBehaviorTree(action: string, args: any, tools: ITools) {
+async function handleBehaviorTree(action: string, args: GraphArgs, tools: ITools) {
     const res: any = await executeAutomationRequest(tools, 'manage_behavior_tree', { ...args, subAction: action }, 'Automation bridge not available');
     return cleanObject({ ...res, ...(res.result || {}) });
 }

package/src/tools/handlers/level-handlers.ts

@@ -1,8 +1,9 @@
 import { cleanObject } from '../../utils/safe-json.js';
 import { ITools } from '../../types/tool-interfaces.js';
+import type { LevelArgs } from '../../types/handler-types.js';
 import { executeAutomationRequest, requireNonEmptyString } from './common-handlers.js';
 
-export async function handleLevelTools(action: string, args: any, tools: ITools) {
+export async function handleLevelTools(action: string, args: LevelArgs, tools: ITools) {
   switch (action) {
     case 'load':
     case 'load_level': {
@@ -118,14 +119,14 @@ export async function handleLevelTools(action: string, args: any, tools: ITools)
     case 'export_level': {
       const res = await tools.levelTools.exportLevel({
         levelPath: args.levelPath,
-        exportPath: args.exportPath || args.destinationPath,
+        exportPath: args.exportPath ?? args.destinationPath ?? '',
         timeoutMs: typeof args.timeoutMs === 'number' ? args.timeoutMs : undefined
       });
       return cleanObject(res);
     }
     case 'import_level': {
       const res = await tools.levelTools.importLevel({
-        packagePath: args.packagePath || args.sourcePath, // Allow sourcePath as fallback for backward compat
+        packagePath: args.packagePath ?? args.sourcePath ?? '',
         destinationPath: args.destinationPath,
         timeoutMs: typeof args.timeoutMs === 'number' ? args.timeoutMs : undefined
       });
@@ -140,7 +141,7 @@ export async function handleLevelTools(action: string, args: any, tools: ITools)
       return cleanObject(res);
     }
     case 'delete': {
-      const levelPaths = Array.isArray(args.levelPaths) ? args.levelPaths : [args.levelPath];
+      const levelPaths = Array.isArray(args.levelPaths) ? args.levelPaths.filter((p): p is string => typeof p === 'string') : (args.levelPath ? [args.levelPath] : []);
       const res = await tools.levelTools.deleteLevels({ levelPaths });
       return cleanObject(res);
     }

package/src/tools/handlers/lighting-handlers.ts

@@ -1,8 +1,9 @@
 import { cleanObject } from '../../utils/safe-json.js';
 import { ITools } from '../../types/tool-interfaces.js';
+import type { LightingArgs } from '../../types/handler-types.js';
 import { normalizeLocation } from './common-handlers.js';
 
-export async function handleLightingTools(action: string, args: any, tools: ITools) {
+export async function handleLightingTools(action: string, args: LightingArgs, tools: ITools) {
   // Normalize location parameter to accept both {x,y,z} and [x,y,z] formats
   const normalizedLocation = normalizeLocation(args.location);
 
@@ -141,6 +142,9 @@ export async function handleLightingTools(action: string, args: any, tools: IToo
         useTemplate: args.useTemplate
       }));
     }
+    case 'list_light_types': {
+      return cleanObject(await tools.lightingTools.listLightTypes());
+    }
     default:
       throw new Error(`Unknown lighting action: ${action}`);
   }