unreal-engine-mcp-server 0.5.4 → 0.5.5

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

@@ -1,244 +0,0 @@
-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) => {
-        const params = normalizeArgs(args, [
-            { key: 'classPath', aliases: ['class', 'type', 'actorClass'], required: true, map: ACTOR_CLASS_ALIASES },
-            { key: 'actorName', aliases: ['name'] },
-            { key: 'timeoutMs', default: undefined }
-        ]);
-
-        const timeoutMs = typeof params.timeoutMs === 'number' ? params.timeoutMs : undefined;
-
-        // Extremely small timeouts are treated as an immediate timeout-style
-        // failure so tests can exercise timeout handling deterministically
-        // without relying on editor performance.
-        if (typeof timeoutMs === 'number' && timeoutMs > 0 && timeoutMs < 200) {
-            throw new Error(`Timeout too small for spawn operation: ${timeoutMs}ms`);
-        }
-
-        // For SplineActor alias, add SplineComponent automatically
-        // Check original args for raw input since map transforms the alias
-        const originalClass = args.classPath || args.class || args.type || args.actorClass;
-        const componentToAdd = getRequiredComponent(originalClass);
-
-        const result = await tools.actorTools.spawn({
-            classPath: params.classPath,
-            actorName: params.actorName,
-            location: args.location,
-            rotation: args.rotation,
-            meshPath: args.meshPath,
-            timeoutMs,
-            ...(componentToAdd ? { componentToAdd } : {})
-        });
-
-        // Ensure successful spawn returns the actual actor name
-        if (result && result.success && result.actorName) {
-            return {
-                ...result,
-                message: `Spawned actor: ${result.actorName}`,
-                // Explicitly return the actual name so the client can use it
-                name: result.actorName
-            };
-        }
-        return result;
-    },
-    delete: async (args, tools) => {
-        if (args.actorNames && Array.isArray(args.actorNames)) {
-            return tools.actorTools.delete({ actorNames: args.actorNames });
-        }
-        const params = normalizeArgs(args, [
-            { key: 'actorName', aliases: ['name'], required: true }
-        ]);
-        return tools.actorTools.delete({ actorName: params.actorName });
-    },
-    apply_force: async (args, tools) => {
-        const params = normalizeArgs(args, [
-            { key: 'actorName', aliases: ['name'], required: true }
-        ]);
-        const force = args.force;
-
-        // Function to attempt applying force, returning the result or throwing
-        const tryApplyForce = async () => {
-            return await tools.actorTools.applyForce({
-                actorName: params.actorName,
-                force
-            });
-        };
-
-        try {
-            // Initial attempt
-            return await tryApplyForce();
-        } catch (error: any) {
-            // Check if error is due to physics
-            const errorMsg = error.message || String(error);
-
-            if (errorMsg.toUpperCase().includes('PHYSICS')) {
-                try {
-                    // Auto-enable physics logic
-                    const compsResult = await tools.actorTools.getComponents(params.actorName);
-                    if (compsResult && compsResult.success && Array.isArray(compsResult.components)) {
-                        const meshComp = compsResult.components.find((c: any) => {
-                            const name = c.name || c;
-                            const match = typeof name === 'string' && (
-                                name.toLowerCase().includes('staticmesh') ||
-                                name.toLowerCase().includes('mesh') ||
-                                name.toLowerCase().includes('primitive')
-                            );
-                            return match;
-                        });
-
-                        if (meshComp) {
-                            const compName = meshComp.name || meshComp;
-                            await tools.actorTools.setComponentProperties({
-                                actorName: params.actorName,
-                                componentName: compName,
-                                properties: { SimulatePhysics: true, bSimulatePhysics: true, Mobility: 2 }
-                            });
-
-                            // Retry
-                            return await tryApplyForce();
-                        }
-                    }
-                } catch (retryError: any) {
-                    // If retry fails, append debug info to original error and rethrow
-                    throw new Error(`${errorMsg} (Auto-enable physics failed: ${retryError.message})`);
-                }
-            }
-
-            // Re-throw if not a physics error or if auto-enable logic matched nothing
-            throw error;
-        }
-    },
-    set_transform: async (args, tools) => {
-        const params = normalizeArgs(args, [
-            { key: 'actorName', aliases: ['name'], required: true }
-        ]);
-        return tools.actorTools.setTransform({
-            actorName: params.actorName,
-            location: args.location,
-            rotation: args.rotation,
-            scale: args.scale
-        });
-    },
-    get_transform: async (args, tools) => {
-        const params = normalizeArgs(args, [
-            { key: 'actorName', aliases: ['name'], required: true }
-        ]);
-        return tools.actorTools.getTransform(params.actorName);
-    },
-    duplicate: async (args, tools) => {
-        const params = normalizeArgs(args, [
-            { key: 'actorName', aliases: ['name'], required: true },
-            { key: 'newName', aliases: ['nameTo'] }
-        ]);
-        return tools.actorTools.duplicate({
-            actorName: params.actorName,
-            newName: params.newName,
-            offset: args.offset
-        });
-    },
-    attach: async (args, tools) => {
-        const params = normalizeArgs(args, [
-            { key: 'childActor', aliases: ['actorName', 'child'], required: true },
-            { key: 'parentActor', aliases: ['parent'], required: true }
-        ]);
-        return tools.actorTools.attach({ childActor: params.childActor, parentActor: params.parentActor });
-    },
-    detach: async (args, tools) => {
-        const params = normalizeArgs(args, [
-            { key: 'actorName', aliases: ['childActor', 'child'], required: true }
-        ]);
-        return tools.actorTools.detach(params.actorName);
-    },
-    add_tag: async (args, tools) => {
-        const params = normalizeArgs(args, [
-            { key: 'actorName', aliases: ['name'], required: true },
-            { key: 'tag', required: true }
-        ]);
-        return tools.actorTools.addTag({ actorName: params.actorName, tag: params.tag });
-    },
-    remove_tag: async (args, tools) => {
-        const params = normalizeArgs(args, [
-            { key: 'actorName', aliases: ['name'], required: true },
-            { key: 'tag', required: true }
-        ]);
-        return tools.actorTools.removeTag({ actorName: params.actorName, tag: params.tag });
-    },
-    find_by_tag: async (args, tools) => {
-        const params = normalizeArgs(args, [
-            { key: 'tag', default: '' }
-        ]);
-        return tools.actorTools.findByTag({ tag: params.tag, matchType: args.matchType });
-    },
-    delete_by_tag: async (args, tools) => {
-        const params = normalizeArgs(args, [
-            { key: 'tag', required: true }
-        ]);
-        return tools.actorTools.deleteByTag(params.tag);
-    },
-    spawn_blueprint: async (args, tools) => {
-        const params = normalizeArgs(args, [
-            { key: 'blueprintPath', aliases: ['path', 'bp'], required: true },
-            { key: 'actorName', aliases: ['name'] }
-        ]);
-        const result = await tools.actorTools.spawnBlueprint({
-            blueprintPath: params.blueprintPath,
-            actorName: params.actorName,
-            location: args.location,
-            rotation: args.rotation
-        });
-
-        if (result && result.success && result.actorName) {
-            return {
-                ...result,
-                message: `Spawned blueprint: ${result.actorName}`,
-                name: result.actorName
-            };
-        }
-        return result;
-    },
-    list: async (args, tools) => {
-        const result = await tools.actorTools.listActors();
-        if (result && result.actors && Array.isArray(result.actors)) {
-            const limit = typeof args.limit === 'number' ? args.limit : 50;
-            const count = result.actors.length;
-            const names = result.actors.slice(0, limit).map((a: any) => a.label || a.name).join(', ');
-            const remaining = count - limit;
-            const suffix = remaining > 0 ? `... and ${remaining} others` : '';
-            (result as any).message = `Found ${count} actors: ${names}${suffix}`;
-        }
-        return result;
-    },
-    find_by_name: async (args, tools) => {
-        // Support both actorName and name parameters for consistency
-        const params = normalizeArgs(args, [
-            { key: 'name', aliases: ['actorName', 'query'], required: true }
-        ]);
-
-        // Use the plugin's fuzzy query endpoint (contains-match) instead of the
-        // exact lookup endpoint. This improves "spawn then find" reliability.
-        return tools.actorTools.findByName(params.name);
-    }
-};
-
-export async function handleActorTools(action: string, args: any, tools: ITools) {
-    try {
-        const handler = handlers[action];
-        if (handler) {
-            const res = await handler(args, tools);
-            return ResponseFactory.success(res);
-        }
-        // Fallback to direct bridge call or error
-        const res = await executeAutomationRequest(tools, 'control_actor', args);
-        return ResponseFactory.success(res);
-    } catch (error) {
-        return ResponseFactory.error(error);
-    }
-}

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

@@ -1,237 +0,0 @@
-import { cleanObject } from '../../utils/safe-json.js';
-import { ITools } from '../../types/tool-interfaces.js';
-import { executeAutomationRequest } from './common-handlers.js';
-
-export async function handleAnimationTools(action: string, args: any, tools: ITools) {
-  const animAction = String(action || '').toLowerCase();
-
-  // Route specific actions to their dedicated handlers
-  if (animAction === 'create_animation_blueprint' || animAction === 'create_anim_blueprint' || animAction === 'create_animation_bp') {
-    const name = args.name ?? args.blueprintName;
-    const skeletonPath = args.skeletonPath ?? args.targetSkeleton;
-    const savePath = args.savePath ?? args.path ?? '/Game/Animations';
-
-    // Auto-resolve skeleton from actorName if not provided
-    if (!skeletonPath && args.actorName) {
-      try {
-        const compsRes: any = await tools.actorTools.getComponents(args.actorName);
-        if (compsRes && Array.isArray(compsRes.components)) {
-          const meshComp = compsRes.components.find((c: any) => c.type === 'SkeletalMeshComponent' || c.className === 'SkeletalMeshComponent');
-          if (meshComp && meshComp.skeletalMesh) {
-            // SkeletalMeshComponent usually has a 'skeletalMesh' property which is the path to the mesh
-            // We can use inspect on that mesh to find its skeleton? 
-            // Or maybe getComponents returned extra details?
-            // Assuming we get the mesh path, we still need the skeleton.
-            // But often creating AnimBP for a Mesh acts as shortcut?
-            // Actually, if we have the *mesh* path, we can try to use that if the C++ handler supports it, 
-            // OR we might need to inspect the mesh asset to find its skeleton.
-            // For now, let's settle for: if user provided meshPath but not skeletonPath, we might need a way to look it up.
-            // But here we only have actorName.
-            // Let's defer this complexity unless required. 
-            // Correction: The walkthrough issue said "Skeleton missing".
-            // Let's assume user MUST provide it or we fail.
-            // But if we can help, we should.
-            // If we have meshPath, we can pass it as 'meshPath' and let C++ handle finding the skeleton?
-            // The C++ 'create_animation_blueprint' handler expects 'skeletonPath'.
-            // So we'd need to modify C++ to check meshPath->Skeleton.
-            // Since I'm editing TS only right now, I'll allow passing 'meshPath' in payload if skeletonPath is missing, 
-            // and hope C++ was updated or I should update C++ later.
-            // Actually, checking args, if 'meshPath' is passed, we should pass it along.
-          }
-        }
-      } catch (_e) { }
-    }
-
-    const payload = {
-      ...args,
-      name,
-      skeletonPath,
-      savePath
-    };
-
-    return await executeAutomationRequest(tools, 'create_animation_blueprint', payload, 'Automation bridge not available for animation blueprint creation');
-  }
-
-  if (animAction === 'play_anim_montage' || animAction === 'play_montage') {
-    const resp: any = await executeAutomationRequest(
-      tools,
-      'play_anim_montage',
-      args,
-      'Automation bridge not available for montage playback'
-    );
-    const result = resp?.result ?? resp ?? {};
-    const errorCode = typeof result.error === 'string' ? result.error.toUpperCase() : '';
-    const message = typeof result.message === 'string' ? result.message : '';
-    const msgLower = message.toLowerCase();
-
-    // Check for actor not found - return proper failure state
-    if (msgLower.includes('actor not found') || msgLower.includes('no animation played') || errorCode === 'ACTOR_NOT_FOUND') {
-      return cleanObject({
-        success: false,
-        error: 'ACTOR_NOT_FOUND',
-        message: message || 'Actor not found; no animation played',
-        actorName: args.actorName
-      });
-    }
-
-    if (
-      errorCode === 'INVALID_ARGUMENT' &&
-      msgLower.includes('actorname required') &&
-      typeof args.playRate === 'number' &&
-      args.playRate === 0
-    ) {
-      return cleanObject({
-        success: true,
-        noOp: true,
-        message: 'Montage playback skipped: playRate 0 with missing actorName treated as no-op.'
-      });
-    }
-
-    return cleanObject(resp);
-  }
-
-  if (animAction === 'setup_ragdoll' || animAction === 'activate_ragdoll') {
-    // Auto-resolve meshPath from actorName if missing
-    if (args.actorName && !args.meshPath && !args.skeletonPath) {
-      try {
-        const compsRes: any = await tools.actorTools.getComponents(args.actorName);
-        if (compsRes && Array.isArray(compsRes.components)) {
-          const meshComp = compsRes.components.find((c: any) => c.type === 'SkeletalMeshComponent' || c.className === 'SkeletalMeshComponent');
-          if (meshComp && meshComp.path) {
-            args.meshPath = meshComp.path;
-          }
-        }
-      } catch (_e) {
-        // Ignore component lookup errors, fallback to C++ handling
-      }
-    }
-
-    const resp: any = await executeAutomationRequest(tools, 'setup_ragdoll', args, 'Automation bridge not available for ragdoll setup');
-    const result = resp?.result ?? resp ?? {};
-    const message = typeof result.message === 'string' ? result.message : '';
-    const msgLower = message.toLowerCase();
-
-    // Check for actor not found - return proper failure state
-    if (msgLower.includes('actor not found') || msgLower.includes('no ragdoll applied')) {
-      return cleanObject({
-        success: false,
-        error: 'ACTOR_NOT_FOUND',
-        message: message || 'Actor not found; no ragdoll applied',
-        actorName: args.actorName
-      });
-    }
-
-    return cleanObject(resp);
-  }
-
-  // Flatten blend space axis parameters for C++ handler
-  if (animAction === 'create_blend_space' || animAction === 'create_blend_tree') {
-    if (args.horizontalAxis) {
-      args.minX = args.horizontalAxis.minValue;
-      args.maxX = args.horizontalAxis.maxValue;
-    }
-    if (args.verticalAxis) {
-      args.minY = args.verticalAxis.minValue;
-      args.maxY = args.verticalAxis.maxValue;
-    }
-  }
-
-  switch (animAction) {
-    case 'create_blend_space':
-      return cleanObject(await tools.animationTools.createBlendSpace({
-        name: args.name,
-        path: args.path || args.savePath,
-        skeletonPath: args.skeletonPath,
-        horizontalAxis: args.horizontalAxis,
-        verticalAxis: args.verticalAxis
-      }));
-    case 'create_state_machine':
-      return cleanObject(await tools.animationTools.createStateMachine({
-        machineName: args.machineName || args.name,
-        states: args.states,
-        transitions: args.transitions,
-        blueprintPath: args.blueprintPath || args.path || args.savePath
-      }));
-    case 'setup_ik':
-      return cleanObject(await tools.animationTools.setupIK({
-        actorName: args.actorName,
-        ikBones: args.ikBones,
-        enableFootPlacement: args.enableFootPlacement
-      }));
-    case 'create_procedural_anim':
-      return cleanObject(await tools.animationTools.createProceduralAnim({
-        systemName: args.systemName || args.name,
-        baseAnimation: args.baseAnimation,
-        modifiers: args.modifiers,
-        savePath: args.savePath || args.path
-      }));
-    case 'create_blend_tree':
-      return cleanObject(await tools.animationTools.createBlendTree({
-        treeName: args.treeName || args.name,
-        blendType: args.blendType,
-        basePose: args.basePose,
-        additiveAnimations: args.additiveAnimations,
-        savePath: args.savePath || args.path
-      }));
-    case 'cleanup':
-      return cleanObject(await tools.animationTools.cleanup(args.artifacts));
-    case 'create_animation_asset': {
-      let assetType = args.assetType;
-      if (!assetType && args.name) {
-        if (args.name.toLowerCase().endsWith('montage') || args.name.toLowerCase().includes('montage')) {
-          assetType = 'montage';
-        }
-      }
-      return cleanObject(await tools.animationTools.createAnimationAsset({
-        name: args.name,
-        path: args.path || args.savePath,
-        skeletonPath: args.skeletonPath,
-        assetType
-      }));
-    }
-    case 'add_notify':
-      return cleanObject(await tools.animationTools.addNotify({
-        animationPath: args.animationPath,
-        assetPath: args.assetPath,
-        notifyName: args.notifyName || args.name,
-        time: args.time ?? args.startTime
-      }));
-    case 'configure_vehicle':
-      return cleanObject(await tools.physicsTools.configureVehicle({
-        vehicleName: args.vehicleName,
-        vehicleType: args.vehicleType,
-        wheels: args.wheels,
-        engine: args.engine,
-        transmission: args.transmission,
-        pluginDependencies: args.pluginDependencies ?? args.plugins
-      }));
-    case 'setup_physics_simulation': {
-      // Support both meshPath/skeletonPath and actorName parameters
-      const payload: any = {
-        meshPath: args.meshPath,
-        skeletonPath: args.skeletonPath,
-        physicsAssetName: args.physicsAssetName,
-        savePath: args.savePath
-      };
-
-      // If actorName is provided but no meshPath, resolve the skeletal mesh from the actor
-      if (args.actorName && !args.meshPath && !args.skeletonPath) {
-        payload.actorName = args.actorName;
-      }
-
-      // Ensure at least one source is provided
-      if (!payload.meshPath && !payload.skeletonPath && !payload.actorName) {
-        return cleanObject({
-          success: false,
-          error: 'INVALID_ARGUMENT',
-          message: 'setup_physics_simulation requires meshPath, skeletonPath, or actorName parameter'
-        });
-      }
-
-      return cleanObject(await tools.physicsTools.setupPhysicsSimulation(payload));
-    }
-    default:
-      const res = await executeAutomationRequest(tools, 'animation_physics', args, 'Automation bridge not available for animation/physics operations');
-      return cleanObject(res);
-  }
-}

package/src/tools/handlers/argument-helper.ts

@@ -1,142 +0,0 @@
-import { ITools } from '../../types/tool-interfaces.js';
-
-export interface ArgConfig {
-  /** The primary key to store the normalized value in. */
-  key: string;
-  /** A list of alternative keys (aliases) to look for in the input args. */
-  aliases?: string[];
-  /** If true, the value must be a non-empty string. Throws an error if missing or empty. */
-  required?: boolean;
-  /** If provided, uses this default value if no valid input is found. */
-  default?: any;
-  /** If provided, maps the input string using this dictionary (e.g. for friendly class names). */
-  map?: Record<string, string>;
-  /** Custom validation function. Throws or returns invalid message string if check fails. */
-  validator?: (val: any) => void | string;
-}
-
-/**
- * Normalizes a raw arguments object based on a list of configurations.
- * Handles aliasing, defaults, required checks, and value mapping.
- *
- * @param args The raw arguments object from the tool call.
- * @param configs A list of configuration objects for each expected argument.
- * @returns A new object containing the normalized arguments.
- * @throws Error if a required argument is missing or validation fails.
- */
-export function normalizeArgs(args: any, configs: ArgConfig[]): any {
-  const normalized: any = { ...args }; // Start with a shallow copy to preserve extra args
-
-  for (const config of configs) {
-    let val: any = undefined;
-
-    // 1. Check primary key
-    if (args[config.key] !== undefined && args[config.key] !== null && args[config.key] !== '') {
-      val = args[config.key];
-    }
-
-    // 2. Check aliases if primary not found
-    if (val === undefined && config.aliases) {
-      for (const alias of config.aliases) {
-        if (args[alias] !== undefined && args[alias] !== null && args[alias] !== '') {
-          val = args[alias];
-          break;
-        }
-      }
-    }
-
-    // 3. Apply default if still undefined
-    if (val === undefined && config.default !== undefined) {
-      val = config.default;
-    }
-
-    // 4. Validate 'required'
-    if (config.required) {
-      if (val === undefined || val === null || (typeof val === 'string' && val.trim() === '')) {
-        const aliasStr = config.aliases ? ` (or ${config.aliases.join(', ')})` : '';
-        throw new Error(`Missing required argument: ${config.key}${aliasStr}`);
-      }
-    }
-
-    // 5. Apply map
-    if (config.map && typeof val === 'string') {
-      // Check for exact match first
-      if (config.map[val]) {
-        val = config.map[val];
-      }
-    }
-
-    // 6. Custom validator
-    if (config.validator && val !== undefined) {
-      const err = config.validator(val);
-      if (typeof err === 'string') {
-        throw new Error(`Invalid argument '${config.key}': ${err}`);
-      }
-    }
-
-    // 7. Store result (only if we found something or used a default)
-    if (val !== undefined) {
-      normalized[config.key] = val;
-    }
-  }
-
-  return normalized;
-}
-
-/**
- * Helper to resolve an object path.
- * Can use a direct path, an actor name, or try to find an actor by name via the tool.
- */
-export async function resolveObjectPath(
-  args: any,
-  tools: ITools,
-  config?: {
-    pathKeys?: string[];     // defaults to ['objectPath', 'path']
-    actorKeys?: string[];    // defaults to ['actorName', 'name']
-    fallbackToName?: boolean; // if true, returns the name itself if resolution fails (default true)
-  }
-): Promise<string | undefined> {
-  const pathKeys = config?.pathKeys || ['objectPath', 'path'];
-  const actorKeys = config?.actorKeys || ['actorName', 'name'];
-  const fallback = config?.fallbackToName !== false;
-
-  // 1. Try direct path keys
-  for (const key of pathKeys) {
-    if (typeof args[key] === 'string' && args[key].trim().length > 0) {
-      return args[key].trim().replace(/\/+$/, '');
-    }
-  }
-
-  // 2. Try actor keys - direct pass-through first
-  let potentialName: string | undefined;
-  for (const key of actorKeys) {
-    if (typeof args[key] === 'string' && args[key].trim().length > 0) {
-      potentialName = args[key].trim();
-      break;
-    }
-  }
-
-  if (potentialName) {
-    // 3. Try smart resolution via actor tools
-    if (tools.actorTools && typeof (tools.actorTools as any).findByName === 'function') {
-      try {
-        const res: any = await (tools.actorTools as any).findByName(potentialName);
-        const container: any = res && (res.result || res);
-        const actors = container && Array.isArray(container.actors) ? container.actors : [];
-        if (actors.length > 0) {
-          const first = actors[0];
-          const resolvedPath = first.path || first.objectPath || first.levelPath;
-          if (typeof resolvedPath === 'string' && resolvedPath.trim().length > 0) {
-            return resolvedPath.trim();
-          }
-        }
-      } catch {
-        // Ignore lookup errors
-      }
-    }
-    // Fallback to the name itself
-    if (fallback) return potentialName;
-  }
-
-  return undefined;
-}