unreal-engine-mcp-server 0.5.2 → 0.5.4

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

@@ -1,11 +1,73 @@
 import { cleanObject } from '../../utils/safe-json.js';
 import { ITools } from '../../types/tool-interfaces.js';
+import type { PipelineArgs } from '../../types/handler-types.js';
 import { executeAutomationRequest } from './common-handlers.js';
 import { spawn } from 'child_process';
 import path from 'path';
 import fs from 'fs';
 
-export async function handlePipelineTools(action: string, args: any, tools: ITools) {
+function validateUbtArgumentsString(extraArgs: string): void {
+  if (!extraArgs || typeof extraArgs !== 'string') {
+    return;
+  }
+
+  const forbiddenChars = ['\n', '\r', ';', '|', '`', '&&', '||', '>', '<'];
+  for (const char of forbiddenChars) {
+    if (extraArgs.includes(char)) {
+      throw new Error(
+        `UBT arguments contain forbidden character(s) and are blocked for safety. Blocked: ${JSON.stringify(char)}.`
+      );
+    }
+  }
+}
+
+function tokenizeArgs(extraArgs: string): string[] {
+  if (!extraArgs) {
+    return [];
+  }
+
+  const args: string[] = [];
+  let current = '';
+  let inQuotes = false;
+  let escapeNext = false;
+
+  for (let i = 0; i < extraArgs.length; i++) {
+    const ch = extraArgs[i];
+
+    if (escapeNext) {
+      current += ch;
+      escapeNext = false;
+      continue;
+    }
+
+    if (ch === '\\') {
+      escapeNext = true;
+      continue;
+    }
+
+    if (ch === '"') {
+      inQuotes = !inQuotes;
+      continue;
+    }
+
+    if (!inQuotes && /\s/.test(ch)) {
+      if (current.length > 0) {
+        args.push(current);
+        current = '';
+      }
+    } else {
+      current += ch;
+    }
+  }
+
+  if (current.length > 0) {
+    args.push(current);
+  }
+
+  return args;
+}
+
+export async function handlePipelineTools(action: string, args: PipelineArgs, tools: ITools) {
   switch (action) {
     case 'run_ubt': {
       const target = args.target;
@@ -14,11 +76,12 @@ export async function handlePipelineTools(action: string, args: any, tools: IToo
       const extraArgs = args.arguments || '';
 
       if (!target) {
-        return { success: false, error: 'MISSING_TARGET', message: 'Target is required for run_ubt' };
+        throw new Error('Target is required for run_ubt');
       }
 
-      // Try to find UnrealBuildTool
-      let ubtPath = 'UnrealBuildTool'; // Assume in PATH by default
+      validateUbtArgumentsString(extraArgs);
+
+      let ubtPath = 'UnrealBuildTool';
       const enginePath = process.env.UE_ENGINE_PATH || process.env.UNREAL_ENGINE_PATH;
 
       if (enginePath) {
@@ -34,13 +97,11 @@ export async function handlePipelineTools(action: string, args: any, tools: IToo
       }
 
       if (!projectPath) {
-        return { success: false, error: 'MISSING_PROJECT_PATH', message: 'UE_PROJECT_PATH environment variable is not set and no projectPath argument was provided.' };
+        throw new Error('UE_PROJECT_PATH environment variable is not set and no projectPath argument was provided.');
       }
 
-      // If projectPath points to a .uproject file, use it. If it's a directory, look for a .uproject file.
       let uprojectFile = projectPath;
       if (!uprojectFile.endsWith('.uproject')) {
-        // Find first .uproject in the directory
         try {
           const files = fs.readdirSync(projectPath);
           const found = files.find(f => f.endsWith('.uproject'));
@@ -48,20 +109,23 @@ export async function handlePipelineTools(action: string, args: any, tools: IToo
             uprojectFile = path.join(projectPath, found);
           }
         } catch (_e) {
-          return { success: false, error: 'INVALID_PROJECT_PATH', message: `Could not read project directory: ${projectPath}` };
+          throw new Error(`Could not read project directory: ${projectPath}`);
         }
       }
 
+      const projectArg = `-Project="${uprojectFile}"`;
+      const extraTokens = tokenizeArgs(extraArgs);
+
       const cmdArgs = [
         target,
         platform,
         configuration,
-        `-Project="${uprojectFile}"`,
-        extraArgs
-      ].filter(Boolean);
+        projectArg,
+        ...extraTokens
+      ];
 
       return new Promise((resolve) => {
-        const child = spawn(ubtPath, cmdArgs, { shell: true });
+        const child = spawn(ubtPath, cmdArgs, { shell: false });
 
         const MAX_OUTPUT_SIZE = 20 * 1024; // 20KB cap
         let stdout = '';
@@ -90,12 +154,14 @@ export async function handlePipelineTools(action: string, args: any, tools: IToo
             ? '\n[Output truncated for response payload]'
             : '';
 
+          const quotedArgs = cmdArgs.map(arg => arg.includes(' ') ? `"${arg}"` : arg);
+
           if (code === 0) {
             resolve({
               success: true,
               message: 'UnrealBuildTool finished successfully',
               output: stdout + truncatedNote,
-              command: `${ubtPath} ${cmdArgs.join(' ')}`
+              command: `${ubtPath} ${quotedArgs.join(' ')}`
             });
           } else {
             resolve({
@@ -104,23 +170,24 @@ export async function handlePipelineTools(action: string, args: any, tools: IToo
               message: `UnrealBuildTool failed with code ${code}`,
               output: stdout + truncatedNote,
               errorOutput: stderr + truncatedNote,
-              command: `${ubtPath} ${cmdArgs.join(' ')}`
+              command: `${ubtPath} ${quotedArgs.join(' ')}`
             });
           }
         });
 
         child.on('error', (err) => {
+          const quotedArgs = cmdArgs.map(arg => arg.includes(' ') ? `"${arg}"` : arg);
+
           resolve({
             success: false,
             error: 'SPAWN_FAILED',
             message: `Failed to spawn UnrealBuildTool: ${err.message}`,
-            command: `${ubtPath} ${cmdArgs.join(' ')}`
+            command: `${ubtPath} ${quotedArgs.join(' ')}`
           });
         });
       });
     }
     default:
-      // Fallback to automation bridge if we add more actions later that are bridge-supported
       const res = await executeAutomationRequest(tools, 'manage_pipeline', { ...args, subAction: action }, 'Automation bridge not available for manage_pipeline');
       return cleanObject(res);
   }

package/src/tools/input.ts

@@ -8,6 +8,42 @@ interface ToolDefinition {
     outputSchema: object;
 }
 
+// Common valid key names for UE5 Enhanced Input (not exhaustive, but covers primary cases)
+const VALID_KEY_NAMES = new Set([
+    // Keyboard - Letters
+    'A', 'B', 'C', 'D', 'E', 'F', 'G', 'H', 'I', 'J', 'K', 'L', 'M',
+    'N', 'O', 'P', 'Q', 'R', 'S', 'T', 'U', 'V', 'W', 'X', 'Y', 'Z',
+    // Keyboard - Numbers
+    'Zero', 'One', 'Two', 'Three', 'Four', 'Five', 'Six', 'Seven', 'Eight', 'Nine',
+    // Keyboard - Function keys
+    'F1', 'F2', 'F3', 'F4', 'F5', 'F6', 'F7', 'F8', 'F9', 'F10', 'F11', 'F12',
+    // Keyboard - Special
+    'SpaceBar', 'Enter', 'Escape', 'Tab', 'BackSpace', 'CapsLock',
+    'LeftShift', 'RightShift', 'LeftControl', 'RightControl', 'LeftAlt', 'RightAlt',
+    'LeftCommand', 'RightCommand', 'Insert', 'Delete', 'Home', 'End', 'PageUp', 'PageDown',
+    'Up', 'Down', 'Left', 'Right',
+    // Keyboard - Punctuation
+    'Semicolon', 'Equals', 'Comma', 'Hyphen', 'Underscore', 'Period', 'Slash', 'Tilde',
+    'LeftBracket', 'Backslash', 'RightBracket', 'Apostrophe', 'Quote',
+    // Mouse - Buttons
+    'LeftMouseButton', 'RightMouseButton', 'MiddleMouseButton', 'ThumbMouseButton', 'ThumbMouseButton2',
+    // Mouse - Axes (must be mapped separately, not as composite 2D)
+    'MouseX', 'MouseY', 'MouseWheelAxis', 'MouseScrollUp', 'MouseScrollDown',
+    // Gamepad - Face Buttons
+    'Gamepad_FaceButton_Bottom', 'Gamepad_FaceButton_Right', 'Gamepad_FaceButton_Left', 'Gamepad_FaceButton_Top',
+    // Gamepad - Shoulder/Trigger
+    'Gamepad_LeftShoulder', 'Gamepad_RightShoulder', 'Gamepad_LeftTrigger', 'Gamepad_RightTrigger',
+    'Gamepad_LeftTriggerAxis', 'Gamepad_RightTriggerAxis',
+    // Gamepad - Sticks
+    'Gamepad_LeftThumbstick', 'Gamepad_RightThumbstick',
+    'Gamepad_LeftStick_Up', 'Gamepad_LeftStick_Down', 'Gamepad_LeftStick_Left', 'Gamepad_LeftStick_Right',
+    'Gamepad_RightStick_Up', 'Gamepad_RightStick_Down', 'Gamepad_RightStick_Left', 'Gamepad_RightStick_Right',
+    // Gamepad - D-Pad
+    'Gamepad_DPad_Up', 'Gamepad_DPad_Down', 'Gamepad_DPad_Left', 'Gamepad_DPad_Right',
+    // Gamepad - Special
+    'Gamepad_Special_Left', 'Gamepad_Special_Right'
+]);
+
 export class InputTools {
     private automationBridge: AutomationBridge | null = null;
 
@@ -37,11 +73,33 @@ export class InputTools {
 
     async addMapping(contextPath: string, actionPath: string, key: string) {
         if (!this.automationBridge) throw new Error('Automation bridge not set');
+
+        // Validate key name
+        if (!key || typeof key !== 'string' || key.trim().length === 0) {
+            return { success: false, error: 'INVALID_ARGUMENT', message: 'Key name is required.' };
+        }
+
+        const trimmedKey = key.trim();
+
+        // Check for common mistakes (composite 2D axis names)
+        if (trimmedKey === 'MouseXY2D' || trimmedKey === 'Mouse2D' || trimmedKey === 'MouseXY') {
+            return {
+                success: false,
+                error: 'INVALID_ARGUMENT',
+                message: `Invalid key name '${trimmedKey}'. For mouse axis input, use separate mappings with 'MouseX' and 'MouseY' keys instead of composite 2D axis names.`
+            };
+        }
+
+        // Warn if key is not in our known list (but still attempt the mapping)
+        if (!VALID_KEY_NAMES.has(trimmedKey)) {
+            console.warn(`[InputTools] Key '${trimmedKey}' is not in the standard key list. Attempting mapping anyway.`);
+        }
+
         return this.automationBridge.sendAutomationRequest('manage_input', {
             action: 'add_mapping',
             contextPath,
             actionPath,
-            key
+            key: trimmedKey
         });
     }
 
@@ -55,6 +113,7 @@ export class InputTools {
     }
 }
 
+
 export const inputTools: ToolDefinition = {
     name: 'manage_input',
     description: `Enhanced Input management.

package/src/tools/lighting.ts

@@ -29,6 +29,17 @@ export class LightingTools {
     return `Light_${Date.now()}_${Math.floor(Math.random() * 1000)}`;
   }
 
+  /**
+   * List available light types (classes)
+   */
+  async listLightTypes() {
+    if (!this.automationBridge) {
+      throw new Error('Automation Bridge required to list light types');
+    }
+    const response = await this.automationBridge.sendAutomationRequest('list_light_types', {});
+    return response;
+  }
+
   /**
    * Spawn a light actor using the Automation Bridge.
    * @param lightClass The Unreal light class name (e.g. 'DirectionalLight', 'PointLight')

package/src/tools/physics.ts

@@ -332,7 +332,7 @@ export class PhysicsTools {
    */
   async configureVehicle(params: {
     vehicleName: string;
-    vehicleType: 'Car' | 'Bike' | 'Tank' | 'Aircraft';
+    vehicleType: string;
     wheels?: Array<{
       name: string;
       radius: number;

package/src/tools/sequence.ts

@@ -361,6 +361,17 @@ export class SequenceTools extends BaseTool implements ISequenceTools {
     return resp;
   }
 
+  /**
+   * List available track types
+   */
+  async listTrackTypes(): Promise<StandardActionResponse> {
+    const resp = await this.sendAction('list_track_types', {});
+    if (!resp.success && this.isUnknownActionResponse(resp)) {
+      return { success: false, error: 'UNKNOWN_PLUGIN_ACTION', message: 'Automation plugin does not implement list_track_types' } as const;
+    }
+    return resp;
+  }
+
   /**
    * Set playback work range
    */