unreal-engine-mcp-server 0.4.7 → 0.5.0

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

@@ -0,0 +1,194 @@
+import { ITools } from '../../types/tool-interfaces.js';
+import { cleanObject } from '../../utils/safe-json.js';
+import { requireNonEmptyString } from './common-handlers.js';
+
+function toVec3Array(v: any): [number, number, number] | undefined {
+  if (!v || typeof v !== 'object') return undefined;
+  const x = Number(v.x);
+  const y = Number(v.y);
+  const z = Number(v.z);
+  if (!Number.isFinite(x) || !Number.isFinite(y) || !Number.isFinite(z)) return undefined;
+  return [x, y, z];
+}
+
+function toRotArray(r: any): [number, number, number] | undefined {
+  if (!r || typeof r !== 'object') return undefined;
+  const pitch = Number(r.pitch);
+  const yaw = Number(r.yaw);
+  const roll = Number(r.roll);
+  if (!Number.isFinite(pitch) || !Number.isFinite(yaw) || !Number.isFinite(roll)) return undefined;
+  return [pitch, yaw, roll];
+}
+
+function getTimeoutMs(): number {
+  const envDefault = Number(process.env.MCP_AUTOMATION_REQUEST_TIMEOUT_MS ?? '120000');
+  return Number.isFinite(envDefault) && envDefault > 0 ? envDefault : 120000;
+}
+
+export async function handleAudioTools(
+  action: string,
+  args: any,
+  tools: ITools
+) {
+  switch (action) {
+    case 'create_sound_cue':
+      requireNonEmptyString(args?.name, 'name', 'Missing required parameter: name');
+      requireNonEmptyString(args?.wavePath ?? args?.soundPath, 'soundPath', 'Missing required parameter: soundPath (or wavePath)');
+      return cleanObject(await tools.audioTools.createSoundCue({
+        name: args.name,
+        // MCP schema uses soundPath; AudioTools uses wavePath.
+        wavePath: args.wavePath ?? args.soundPath,
+        savePath: args.savePath,
+        settings: args.settings
+      }));
+
+    case 'play_sound_at_location':
+      requireNonEmptyString(args?.soundPath, 'soundPath', 'Missing required parameter: soundPath');
+      return cleanObject(await tools.audioTools.playSoundAtLocation({
+        soundPath: args.soundPath,
+        location: toVec3Array(args.location) ?? [0, 0, 0],
+        rotation: toRotArray(args.rotation),
+        volume: args.volume,
+        pitch: args.pitch,
+        startTime: args.startTime,
+        attenuationPath: args.attenuationPath,
+        concurrencyPath: args.concurrencyPath
+      }));
+
+    case 'play_sound_2d':
+      requireNonEmptyString(args?.soundPath, 'soundPath', 'Missing required parameter: soundPath');
+      return cleanObject(await tools.audioTools.playSound2D({
+        soundPath: args.soundPath,
+        volume: args.volume,
+        pitch: args.pitch,
+        startTime: args.startTime
+      }));
+
+    case 'create_audio_component':
+      requireNonEmptyString(args?.actorName, 'actorName', 'Missing required parameter: actorName');
+      requireNonEmptyString(args?.componentName, 'componentName', 'Missing required parameter: componentName');
+      requireNonEmptyString(args?.soundPath, 'soundPath', 'Missing required parameter: soundPath');
+      return cleanObject(await tools.audioTools.createAudioComponent({
+        actorName: args.actorName,
+        componentName: args.componentName,
+        soundPath: args.soundPath,
+        autoPlay: args.autoPlay,
+        is3D: args.is3D
+      }));
+
+    case 'set_sound_attenuation':
+      requireNonEmptyString(args?.name, 'name', 'Missing required parameter: name');
+      return cleanObject(await tools.audioTools.setSoundAttenuation({
+        name: args.name,
+        innerRadius: args.innerRadius,
+        falloffDistance: args.falloffDistance,
+        attenuationShape: args.attenuationShape,
+        falloffMode: args.falloffMode
+      }));
+
+    case 'create_sound_class':
+      requireNonEmptyString(args?.name, 'name', 'Missing required parameter: name');
+      return cleanObject(await tools.audioTools.createSoundClass({
+        name: args.name,
+        parentClass: args.parentClass,
+        properties: args.properties
+      }));
+
+    case 'create_sound_mix':
+      requireNonEmptyString(args?.name, 'name', 'Missing required parameter: name');
+      return cleanObject(await tools.audioTools.createSoundMix({
+        name: args.name,
+        classAdjusters: args.classAdjusters
+      }));
+
+    case 'push_sound_mix':
+      requireNonEmptyString(args?.mixName ?? args?.name, 'mixName', 'Missing required parameter: mixName (or name)');
+      return cleanObject(await tools.audioTools.pushSoundMix({
+        mixName: args.mixName ?? args.name
+      }));
+
+    case 'pop_sound_mix':
+      requireNonEmptyString(args?.mixName ?? args?.name, 'mixName', 'Missing required parameter: mixName (or name)');
+      return cleanObject(await tools.audioTools.popSoundMix({
+        mixName: args.mixName ?? args.name
+      }));
+
+    case 'create_ambient_sound':
+      requireNonEmptyString(args?.soundPath, 'soundPath', 'Missing required parameter: soundPath');
+      return cleanObject(await tools.audioTools.createAmbientSound({
+        soundPath: args.soundPath,
+        location: toVec3Array(args.location) ?? [0, 0, 0],
+        volume: args.volume,
+        pitch: args.pitch,
+        startTime: args.startTime,
+        attenuationPath: args.attenuationPath,
+        concurrencyPath: args.concurrencyPath
+      }));
+
+    case 'create_reverb_zone':
+      requireNonEmptyString(args?.name, 'name', 'Missing required parameter: name');
+      return cleanObject(await tools.audioTools.createReverbZone({
+        name: args.name,
+        location: toVec3Array(args.location) ?? [0, 0, 0],
+        size: toVec3Array(args.size) ?? [0, 0, 0],
+        reverbEffect: args.reverbEffect,
+        volume: args.volume,
+        fadeTime: args.fadeTime
+      }));
+
+    case 'enable_audio_analysis':
+      return cleanObject(await tools.audioTools.enableAudioAnalysis({
+        enabled: args.enabled,
+        fftSize: args.fftSize,
+        outputType: args.outputType
+      }));
+
+    case 'fade_sound':
+      requireNonEmptyString(args?.soundName, 'soundName', 'Missing required parameter: soundName');
+      return cleanObject(await tools.audioTools.fadeSound({
+        soundName: args.soundName,
+        targetVolume: args.targetVolume,
+        fadeTime: args.fadeTime,
+        fadeType: args.fadeType
+      }));
+
+    case 'set_doppler_effect':
+      return cleanObject(await tools.audioTools.setDopplerEffect({
+        enabled: args.enabled,
+        scale: args.scale
+      }));
+
+    case 'set_audio_occlusion':
+      return cleanObject(await tools.audioTools.setAudioOcclusion({
+        enabled: args.enabled,
+        lowPassFilterFrequency: args.lowPassFilterFrequency,
+        volumeAttenuation: args.volumeAttenuation
+      }));
+
+    case 'spawn_sound_at_location':
+      // Direct pass-through to C++ handler
+      return cleanObject(await tools.automationBridge?.sendAutomationRequest('spawn_sound_at_location', args, { timeoutMs: getTimeoutMs() }));
+
+    case 'play_sound_attached':
+      return cleanObject(await tools.automationBridge?.sendAutomationRequest('play_sound_attached', args, { timeoutMs: getTimeoutMs() }));
+
+    case 'set_sound_mix_class_override':
+      return cleanObject(await tools.automationBridge?.sendAutomationRequest('set_sound_mix_class_override', args, { timeoutMs: getTimeoutMs() }));
+
+    case 'clear_sound_mix_class_override':
+      return cleanObject(await tools.automationBridge?.sendAutomationRequest('clear_sound_mix_class_override', args, { timeoutMs: getTimeoutMs() }));
+
+    case 'set_base_sound_mix':
+      return cleanObject(await tools.automationBridge?.sendAutomationRequest('set_base_sound_mix', args, { timeoutMs: getTimeoutMs() }));
+
+    case 'prime_sound':
+      return cleanObject(await tools.automationBridge?.sendAutomationRequest('prime_sound', args, { timeoutMs: getTimeoutMs() }));
+
+    case 'fade_sound_in':
+    case 'fade_sound_out':
+      return cleanObject(await tools.automationBridge?.sendAutomationRequest(action, args, { timeoutMs: getTimeoutMs() }));
+
+    default:
+      return cleanObject({ success: false, error: 'UNKNOWN_ACTION', message: `Unknown audio action: ${action}` });
+  }
+}

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

@@ -0,0 +1,380 @@
+import { cleanObject } from '../../utils/safe-json.js';
+import { ITools } from '../../types/tool-interfaces.js';
+import { executeAutomationRequest } from './common-handlers.js';
+
+export async function handleBlueprintTools(action: string, args: any, tools: ITools) {
+  switch (action) {
+    case 'create': {
+      // Support 'path' or 'blueprintPath' argument by splitting it into name and savePath if not provided
+      let name = args.name;
+      let savePath = args.savePath;
+      const pathArg = args.path || args.blueprintPath;
+
+      if (pathArg) {
+        const parts = pathArg.split('/');
+        const extractName = parts.pop(); // The last part is the name
+
+        // If name wasn't provided, use the extracted name
+        if (!name) {
+          name = extractName;
+        }
+
+        // If savePath wasn't provided, use the extracted path
+        if (!savePath) {
+          savePath = parts.join('/');
+        }
+      }
+
+      if (!savePath) savePath = '/Game';
+
+      const res = await tools.blueprintTools.createBlueprint({
+        name: name,
+        blueprintType: args.blueprintType,
+        savePath: savePath,
+        parentClass: args.parentClass,
+        properties: args.properties,
+        timeoutMs: args.timeoutMs,
+        waitForCompletion: args.waitForCompletion,
+        waitForCompletionTimeoutMs: args.waitForCompletionTimeoutMs
+      });
+      return cleanObject(res);
+    }
+    case 'ensure_exists': {
+      const res = await tools.blueprintTools.waitForBlueprint(args.name || args.blueprintPath || args.path, args.timeoutMs);
+      return cleanObject(res);
+    }
+    case 'add_variable': {
+      const res = await tools.blueprintTools.addVariable({
+        blueprintName: args.name || args.blueprintPath || args.path,
+        variableName: args.variableName,
+        variableType: args.variableType,
+        defaultValue: args.defaultValue,
+        category: args.category,
+        isReplicated: args.isReplicated,
+        isPublic: args.isPublic,
+        variablePinType: args.variablePinType,
+        timeoutMs: args.timeoutMs,
+        waitForCompletion: args.waitForCompletion,
+        waitForCompletionTimeoutMs: args.waitForCompletionTimeoutMs
+      });
+      return cleanObject(res);
+    }
+    case 'set_variable_metadata': {
+      const res = await tools.blueprintTools.setVariableMetadata({
+        blueprintName: args.name || args.blueprintPath || args.path,
+        variableName: args.variableName,
+        metadata: args.metadata,
+        timeoutMs: args.timeoutMs
+      });
+      return cleanObject(res);
+    }
+    case 'remove_variable': {
+      const res = await tools.blueprintTools.removeVariable({
+        blueprintName: args.name || args.blueprintPath || args.path,
+        variableName: args.variableName,
+        timeoutMs: args.timeoutMs,
+        waitForCompletion: args.waitForCompletion,
+        waitForCompletionTimeoutMs: args.waitForCompletionTimeoutMs
+      });
+      return cleanObject(res);
+    }
+    case 'rename_variable': {
+      const res = await tools.blueprintTools.renameVariable({
+        blueprintName: args.name || args.blueprintPath || args.path,
+        oldName: args.oldName,
+        newName: args.newName,
+        timeoutMs: args.timeoutMs,
+        waitForCompletion: args.waitForCompletion,
+        waitForCompletionTimeoutMs: args.waitForCompletionTimeoutMs
+      });
+      return cleanObject(res);
+    }
+    case 'set_metadata': {
+      const assetPathRaw = typeof args.assetPath === 'string' ? args.assetPath.trim() : '';
+      const blueprintPathRaw = typeof args.blueprintPath === 'string' ? args.blueprintPath.trim() : '';
+      const nameRaw = typeof args.name === 'string' ? args.name.trim() : '';
+      const savePathRaw = typeof args.savePath === 'string' ? args.savePath.trim() : '';
+
+      let assetPath = assetPathRaw;
+      if (!assetPath) {
+        if (blueprintPathRaw) {
+          assetPath = blueprintPathRaw;
+        } else if (nameRaw && savePathRaw) {
+          const base = savePathRaw.replace(/\/$/, '');
+          assetPath = `${base}/${nameRaw}`;
+        }
+      }
+      if (!assetPath) {
+        throw new Error('Invalid parameters: assetPath or blueprintPath or name+savePath required for set_metadata');
+      }
+
+      const metadata = (args.metadata && typeof args.metadata === 'object') ? args.metadata : {};
+      const res = await executeAutomationRequest(tools, 'set_metadata', { assetPath, metadata });
+      return cleanObject(res);
+    }
+    case 'add_event': {
+      const blueprintName = args.blueprintPath || args.path || args.name;
+      const usedNameForBlueprint = !args.blueprintPath && !args.path && args.name;
+
+      const res: any = await tools.blueprintTools.addEvent({
+        blueprintName: blueprintName,
+        eventType: args.eventType,
+        customEventName: args.customEventName || (!usedNameForBlueprint ? args.name : undefined),
+        parameters: args.parameters,
+        timeoutMs: args.timeoutMs,
+        waitForCompletion: args.waitForCompletion,
+        waitForCompletionTimeoutMs: args.waitForCompletionTimeoutMs
+      });
+
+      if (res && res.success === false) {
+        const msg = (res.message || '').toLowerCase();
+        if (msg.includes('already exists') || msg.includes('duplicate')) {
+          return cleanObject({
+            success: false,
+            error: 'EVENT_ALREADY_EXISTS',
+            message: res.message || 'Event already exists',
+            blueprintName
+          });
+        }
+      }
+      return cleanObject(res);
+    }
+    case 'remove_event': {
+      const res = await tools.blueprintTools.removeEvent({
+        blueprintName: args.name || args.blueprintPath || args.path,
+        eventName: args.eventName,
+        customEventName: args.customEventName,
+        timeoutMs: args.timeoutMs,
+        waitForCompletion: args.waitForCompletion,
+        waitForCompletionTimeoutMs: args.waitForCompletionTimeoutMs
+      });
+      return cleanObject(res);
+    }
+    case 'add_function': {
+      // Prioritize explicit path for blueprint, allowing 'name' to be function name
+      const blueprintName = args.blueprintPath || args.path || args.name;
+      const usedNameForBlueprint = !args.blueprintPath && !args.path && args.name;
+
+      const res = await tools.blueprintTools.addFunction({
+        blueprintName: blueprintName,
+        functionName: args.functionName || args.memberName || (!usedNameForBlueprint ? args.name : undefined),
+        inputs: args.inputs,
+        outputs: args.outputs,
+        isPublic: args.isPublic,
+        category: args.category,
+        timeoutMs: args.timeoutMs,
+        waitForCompletion: args.waitForCompletion,
+        waitForCompletionTimeoutMs: args.waitForCompletionTimeoutMs
+      });
+      return cleanObject(res);
+    }
+    case 'add_component': {
+      const res = await tools.blueprintTools.addComponent({
+        blueprintName: args.name || args.blueprintPath || args.path,
+        componentType: args.componentType || args.componentClass,
+        componentName: args.componentName,
+        attachTo: args.attachTo,
+        transform: args.transform,
+        properties: args.properties,
+        compile: args.applyAndSave,
+        save: args.applyAndSave,
+        timeoutMs: args.timeoutMs,
+        waitForCompletion: args.waitForCompletion,
+        waitForCompletionTimeoutMs: args.waitForCompletionTimeoutMs
+      });
+      return cleanObject(res);
+    }
+    case 'modify_scs': {
+      const res = await tools.blueprintTools.modifyConstructionScript({
+        blueprintPath: args.name || args.blueprintPath || args.path,
+        operations: args.operations,
+        compile: args.applyAndSave,
+        save: args.applyAndSave,
+        timeoutMs: args.timeoutMs,
+        waitForCompletion: args.waitForCompletion,
+        waitForCompletionTimeoutMs: args.waitForCompletionTimeoutMs
+      });
+      return cleanObject(res);
+    }
+    case 'set_scs_transform': {
+      const res = await tools.blueprintTools.setSCSComponentTransform({
+        blueprintPath: args.name || args.blueprintPath || args.path,
+        componentName: args.componentName,
+        location: args.location,
+        rotation: args.rotation,
+        scale: args.scale,
+        timeoutMs: args.timeoutMs
+      });
+      return cleanObject(res);
+    }
+    case 'add_construction_script': {
+      const res = await tools.blueprintTools.addConstructionScript({
+        blueprintName: args.name || args.blueprintPath || args.path,
+        scriptName: args.scriptName,
+        timeoutMs: args.timeoutMs,
+        waitForCompletion: args.waitForCompletion,
+        waitForCompletionTimeoutMs: args.waitForCompletionTimeoutMs
+      });
+      return cleanObject(res);
+    }
+    case 'add_node': {
+      if ((args.nodeType === 'CallFunction' || args.nodeType === 'K2Node_CallFunction') && !args.functionName && !args.memberName) {
+        throw new Error('CallFunction node requires functionName parameter');
+      }
+
+      // Map common node aliases to K2Node types
+      const nodeAliases: Record<string, string> = {
+        'CallFunction': 'K2Node_CallFunction',
+        'VariableGet': 'K2Node_VariableGet',
+        'VariableSet': 'K2Node_VariableSet',
+        'If': 'K2Node_IfThenElse',
+        'Branch': 'K2Node_IfThenElse',
+        'Switch': 'K2Node_Switch',
+        'Select': 'K2Node_Select',
+        'Cast': 'K2Node_DynamicCast',
+        'CustomEvent': 'K2Node_CustomEvent',
+        'Event': 'K2Node_Event',
+        'MakeArray': 'K2Node_MakeArray',
+        'ForEach': 'K2Node_ForEachElementInEnum' // Note: ForEachLoop is a macro, this is different
+      };
+
+      const resolvedNodeType = nodeAliases[args.nodeType] || args.nodeType;
+
+      // Validation for Event nodes
+      if ((resolvedNodeType === 'K2Node_Event' || resolvedNodeType === 'K2Node_CustomEvent') && !args.eventName && !args.customEventName && !args.name) {
+        // Allow 'name' as fallback for customEventName/eventName
+        if (!args.eventName) args.eventName = args.name;
+
+        if (!args.eventName) {
+          throw new Error(`${resolvedNodeType} requires eventName (or customEventName) parameter`);
+        }
+      }
+
+      const res = await tools.blueprintTools.addNode({
+        blueprintName: args.name || args.blueprintPath || args.path,
+        nodeType: resolvedNodeType,
+        graphName: args.graphName,
+        functionName: args.functionName,
+        variableName: args.variableName,
+        nodeName: args.nodeName,
+        eventName: args.eventName || args.customEventName,
+        memberClass: args.memberClass,
+        posX: args.posX,
+        posY: args.posY,
+        timeoutMs: args.timeoutMs
+      });
+      return cleanObject(res);
+    }
+    case 'add_scs_component': {
+      const res = await tools.blueprintTools.addSCSComponent({
+        blueprintPath: args.name || args.blueprintPath || args.path,
+        componentClass: args.componentClass || args.componentType,
+        componentName: args.componentName,
+        meshPath: args.meshPath,
+        materialPath: args.materialPath,
+        timeoutMs: args.timeoutMs
+      });
+      return cleanObject(res);
+    }
+    case 'reparent_scs_component': {
+      const res = await tools.blueprintTools.reparentSCSComponent({
+        blueprintPath: args.name || args.blueprintPath || args.path,
+        componentName: args.componentName,
+        newParent: args.newParent,
+        timeoutMs: args.timeoutMs
+      });
+      return cleanObject(res);
+    }
+    case 'set_scs_property': {
+      const res = await tools.blueprintTools.setSCSComponentProperty({
+        blueprintPath: args.name || args.blueprintPath || args.path,
+        componentName: args.componentName,
+        propertyName: args.propertyName,
+        propertyValue: args.propertyValue,
+        timeoutMs: args.timeoutMs
+      });
+      return cleanObject(res);
+    }
+    case 'remove_scs_component': {
+      const res = await tools.blueprintTools.removeSCSComponent({
+        blueprintPath: args.name || args.blueprintPath || args.path,
+        componentName: args.componentName,
+        timeoutMs: args.timeoutMs
+      });
+      return cleanObject(res);
+    }
+    case 'get_scs': {
+      const res = await tools.blueprintTools.getBlueprintSCS({
+        blueprintPath: args.name || args.blueprintPath || args.path,
+        timeoutMs: args.timeoutMs
+      });
+      return cleanObject(res);
+    }
+    case 'set_default': {
+      const res = await tools.blueprintTools.setBlueprintDefault({
+        blueprintName: args.name || args.blueprintPath || args.path,
+        propertyName: args.propertyName,
+        value: args.value
+      });
+      return cleanObject(res);
+    }
+    case 'compile': {
+      const res = await tools.blueprintTools.compileBlueprint({
+        blueprintName: args.name || args.blueprintPath || args.path,
+        saveAfterCompile: args.saveAfterCompile
+      });
+      return cleanObject(res);
+    }
+    case 'probe_handle': {
+      const res = await tools.blueprintTools.probeSubobjectDataHandle({
+        componentClass: args.componentClass
+      });
+      return cleanObject(res);
+    }
+    case 'get': {
+      const res = await tools.blueprintTools.getBlueprintInfo({
+        blueprintPath: args.name || args.blueprintPath || args.path,
+        timeoutMs: args.timeoutMs
+      });
+      return cleanObject(res);
+    }
+    case 'connect_pins':
+    case 'break_pin_links':
+    case 'delete_node':
+    case 'create_reroute_node':
+    case 'set_node_property':
+    case 'get_node_details':
+    case 'get_pin_details':
+    case 'get_graph_details': {
+      const processedArgs = {
+        ...args,
+        subAction: action,
+        blueprintPath: args.blueprintPath || args.path || args.name
+      };
+      const res = await executeAutomationRequest(tools, 'manage_blueprint_graph', processedArgs, 'Automation bridge not available for blueprint graph operations');
+      return cleanObject(res);
+    }
+    default: {
+      // Translate applyAndSave to compile/save flags for modify_scs action
+      const processedArgs = { ...args };
+      if (args.action === 'modify_scs' && args.applyAndSave === true) {
+        processedArgs.compile = true;
+        processedArgs.save = true;
+      }
+      const res = await executeAutomationRequest(tools, 'manage_blueprint', processedArgs, 'Automation bridge not available for blueprint operations');
+      return cleanObject(res);
+    }
+  }
+}
+
+export async function handleBlueprintGet(args: any, tools: ITools) {
+  const res = await executeAutomationRequest(tools, 'blueprint_get', args, 'Automation bridge not available for blueprint operations');
+  if (res && res.success) {
+    return cleanObject({
+      ...res,
+      blueprint: args.blueprintPath || args.path || args.name || 'Unknown Blueprint',
+      message: res.message || 'Blueprint fetched'
+    });
+  }
+  return cleanObject(res);
+}

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

@@ -0,0 +1,87 @@
+import { ITools } from '../../types/tool-interfaces.js';
+
+export function ensureArgsPresent(args: any) {
+  if (args === null || args === undefined) {
+    throw new Error('Invalid arguments: null or undefined');
+  }
+}
+
+export function requireAction(args: any): string {
+  ensureArgsPresent(args);
+  const action = args.action;
+  if (typeof action !== 'string' || action.trim() === '') {
+    throw new Error('Missing required parameter: action');
+  }
+  return action;
+}
+
+export function requireNonEmptyString(value: any, 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;
+}
+
+export async function executeAutomationRequest(
+  tools: ITools,
+  toolName: string,
+  args: any,
+  errorMessage: string = 'Automation bridge not available',
+  options: { timeoutMs?: number } = {}
+) {
+  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') {
+    throw new Error(errorMessage);
+  }
+
+  if (!automationBridge.isConnected()) {
+    throw new Error(`Automation bridge is not connected to Unreal Engine. Please check if the editor is running and the plugin is enabled. Action: ${toolName}`);
+  }
+
+  return await automationBridge.sendAutomationRequest(toolName, args, options);
+}
+
+/**
+ * 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 {
+  if (!location) return undefined;
+
+  // Already array format
+  if (Array.isArray(location) && location.length >= 3) {
+    return [Number(location[0]) || 0, Number(location[1]) || 0, Number(location[2]) || 0];
+  }
+
+  // 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];
+  }
+
+  return 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 {
+  if (!rotation) return undefined;
+
+  // Array format [pitch, yaw, roll]
+  if (Array.isArray(rotation) && rotation.length >= 3) {
+    return { pitch: Number(rotation[0]) || 0, yaw: Number(rotation[1]) || 0, roll: Number(rotation[2]) || 0 };
+  }
+
+  // Already object format
+  if (typeof rotation === 'object') {
+    return {
+      pitch: Number(rotation.pitch) || 0,
+      yaw: Number(rotation.yaw) || 0,
+      roll: Number(rotation.roll) || 0
+    };
+  }
+
+  return undefined;
+}