unreal-engine-mcp-server 0.4.0 → 0.4.3

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

@@ -4,6 +4,129 @@ import { Logger } from '../utils/logger.js';
 
 const log = new Logger('ConsolidatedToolHandler');
 
+const ACTION_REQUIRED_ERROR = 'Missing required parameter: action';
+
+function ensureArgsPresent(args: any) {
+  if (args === null || args === undefined) {
+    throw new Error('Invalid arguments: null or undefined');
+  }
+}
+
+function requireAction(args: any): string {
+  ensureArgsPresent(args);
+  const action = args.action;
+  if (typeof action !== 'string' || action.trim() === '') {
+    throw new Error(ACTION_REQUIRED_ERROR);
+  }
+  return action;
+}
+
+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;
+}
+
+function requirePositiveNumber(value: any, field: string, message?: string): number {
+  if (typeof value !== 'number' || !isFinite(value) || value <= 0) {
+    throw new Error(message ?? `Invalid ${field}: must be a positive number`);
+  }
+  return value;
+}
+
+function requireVector3Components(
+  vector: any,
+  message: string
+): [number, number, number] {
+  if (
+    !vector ||
+    typeof vector.x !== 'number' ||
+    typeof vector.y !== 'number' ||
+    typeof vector.z !== 'number'
+  ) {
+    throw new Error(message);
+  }
+  return [vector.x, vector.y, vector.z];
+}
+
+function getElicitationTimeoutMs(tools: any): number | undefined {
+  if (!tools) return undefined;
+  const direct = tools.elicitationTimeoutMs;
+  if (typeof direct === 'number' && Number.isFinite(direct)) {
+    return direct;
+  }
+  if (typeof tools.getElicitationTimeoutMs === 'function') {
+    const value = tools.getElicitationTimeoutMs();
+    if (typeof value === 'number' && Number.isFinite(value)) {
+      return value;
+    }
+  }
+  return undefined;
+}
+
+async function elicitMissingPrimitiveArgs(
+  tools: any,
+  args: any,
+  prompt: string,
+  fieldSchemas: Record<string, { type: 'string' | 'number' | 'integer' | 'boolean'; title?: string; description?: string; enum?: string[]; enumNames?: string[]; minimum?: number; maximum?: number; minLength?: number; maxLength?: number; pattern?: string; format?: string; default?: unknown }>
+) {
+  if (
+    !tools ||
+    typeof tools.supportsElicitation !== 'function' ||
+    !tools.supportsElicitation() ||
+    typeof tools.elicit !== 'function'
+  ) {
+    return;
+  }
+
+  const properties: Record<string, any> = {};
+  const required: string[] = [];
+
+  for (const [key, schema] of Object.entries(fieldSchemas)) {
+    const value = args?.[key];
+    const missing =
+      value === undefined ||
+      value === null ||
+      (typeof value === 'string' && value.trim() === '');
+    if (missing) {
+      properties[key] = schema;
+      required.push(key);
+    }
+  }
+
+  if (required.length === 0) return;
+
+  const timeoutMs = getElicitationTimeoutMs(tools);
+  const options: any = {
+    fallback: async () => ({ ok: false, error: 'missing-params' })
+  };
+  if (typeof timeoutMs === 'number') {
+    options.timeoutMs = timeoutMs;
+  }
+
+  try {
+    const elicited = await tools.elicit(
+      prompt,
+      { type: 'object', properties, required },
+      options
+    );
+
+    if (elicited?.ok && elicited.value) {
+      for (const key of required) {
+        const value = elicited.value[key];
+        if (value === undefined || value === null) continue;
+        args[key] = typeof value === 'string' ? value.trim() : value;
+      }
+    }
+  } catch (err) {
+    log.debug('Special elicitation fallback skipped', {
+      prompt,
+      err: (err as any)?.message || String(err)
+    });
+  }
+}
+
 export async function handleConsolidatedToolCall(
   name: string,
   args: any,
@@ -14,26 +137,12 @@ export async function handleConsolidatedToolCall(
   log.debug(`Starting execution of ${name} at ${new Date().toISOString()}`);
   
   try {
-    // Validate args is not null/undefined
-    if (args === null || args === undefined) {
-      throw new Error('Invalid arguments: null or undefined');
-    }
-    
+    ensureArgsPresent(args);
 
     switch (name) {
       // 1. ASSET MANAGER
       case 'manage_asset':
-        // Validate args is not null/undefined
-        if (args === null || args === undefined) {
-          throw new Error('Invalid arguments: null or undefined');
-        }
-        
-        // Validate action exists
-        if (!args.action) {
-          throw new Error('Missing required parameter: action');
-        }
-        
-switch (args.action) {
+        switch (requireAction(args)) {
           case 'list': {
             if (args.directory !== undefined && args.directory !== null && typeof args.directory !== 'string') {
               throw new Error('Invalid directory: must be a string');
@@ -42,20 +151,81 @@ switch (args.action) {
             return cleanObject({ success: true, ...res });
           }
           case 'import': {
-            if (typeof args.sourcePath !== 'string' || args.sourcePath.trim() === '') {
-              throw new Error('Invalid sourcePath');
-            }
-            if (typeof args.destinationPath !== 'string' || args.destinationPath.trim() === '') {
-              throw new Error('Invalid destinationPath');
+            let sourcePath = typeof args.sourcePath === 'string' ? args.sourcePath.trim() : '';
+            let destinationPath = typeof args.destinationPath === 'string' ? args.destinationPath.trim() : '';
+
+            if ((!sourcePath || !destinationPath) && typeof tools.supportsElicitation === 'function' && tools.supportsElicitation() && typeof tools.elicit === 'function') {
+              const schemaProps: Record<string, any> = {};
+              const required: string[] = [];
+
+              if (!sourcePath) {
+                schemaProps.sourcePath = {
+                  type: 'string',
+                  title: 'Source File Path',
+                  description: 'Full path to the asset file on disk to import'
+                };
+                required.push('sourcePath');
+              }
+
+              if (!destinationPath) {
+                schemaProps.destinationPath = {
+                  type: 'string',
+                  title: 'Destination Path',
+                  description: 'Unreal content path where the asset should be imported (e.g., /Game/MCP/Assets)'
+                };
+                required.push('destinationPath');
+              }
+
+              if (required.length > 0) {
+                const timeoutMs = getElicitationTimeoutMs(tools);
+                const options: any = { fallback: async () => ({ ok: false, error: 'missing-import-params' }) };
+                if (typeof timeoutMs === 'number') {
+                  options.timeoutMs = timeoutMs;
+                }
+                const elicited = await tools.elicit(
+                  'Provide the missing import parameters for manage_asset.import',
+                  { type: 'object', properties: schemaProps, required },
+                  options
+                );
+
+                if (elicited?.ok && elicited.value) {
+                  if (typeof elicited.value.sourcePath === 'string') {
+                    sourcePath = elicited.value.sourcePath.trim();
+                  }
+                  if (typeof elicited.value.destinationPath === 'string') {
+                    destinationPath = elicited.value.destinationPath.trim();
+                  }
+                }
+              }
             }
-            const res = await tools.assetTools.importAsset(args.sourcePath, args.destinationPath);
+
+            const sourcePathValidated = requireNonEmptyString(sourcePath || args.sourcePath, 'sourcePath', 'Invalid sourcePath');
+            const destinationPathValidated = requireNonEmptyString(destinationPath || args.destinationPath, 'destinationPath', 'Invalid destinationPath');
+            const res = await tools.assetTools.importAsset(sourcePathValidated, destinationPathValidated);
             return cleanObject(res);
           }
           case 'create_material': {
-            if (typeof args.name !== 'string' || args.name.trim() === '') {
-              throw new Error('Invalid name: must be a non-empty string');
-            }
-            const res = await tools.materialTools.createMaterial(args.name, args.path || '/Game/Materials');
+            await elicitMissingPrimitiveArgs(
+              tools,
+              args,
+              'Provide the material details for manage_asset.create_material',
+              {
+                name: {
+                  type: 'string',
+                  title: 'Material Name',
+                  description: 'Name for the new material asset'
+                },
+                path: {
+                  type: 'string',
+                  title: 'Save Path',
+                  description: 'Optional Unreal content path where the material should be saved'
+                }
+              }
+            );
+            const sanitizedName = typeof args.name === 'string' ? args.name.trim() : args.name;
+            const sanitizedPath = typeof args.path === 'string' ? args.path.trim() : args.path;
+            const name = requireNonEmptyString(sanitizedName, 'name', 'Invalid name: must be a non-empty string');
+            const res = await tools.materialTools.createMaterial(name, sanitizedPath || '/Game/Materials');
             return cleanObject(res);
           }
           default:
@@ -64,41 +234,72 @@ switch (args.action) {
 
       // 2. ACTOR CONTROL
       case 'control_actor':
-        // Validate action exists
-        if (!args.action) {
-          throw new Error('Missing required parameter: action');
-        }
-        
-switch (args.action) {
+        switch (requireAction(args)) {
           case 'spawn': {
-            if (!args.classPath || typeof args.classPath !== 'string' || args.classPath.trim() === '') {
-              throw new Error('Invalid classPath: must be a non-empty string');
-            }
+            await elicitMissingPrimitiveArgs(
+              tools,
+              args,
+              'Provide the spawn parameters for control_actor.spawn',
+              {
+                classPath: {
+                  type: 'string',
+                  title: 'Actor Class or Asset Path',
+                  description: 'Class name (e.g., StaticMeshActor) or asset path (e.g., /Engine/BasicShapes/Cube) to spawn'
+                }
+              }
+            );
+            const classPathInput = typeof args.classPath === 'string' ? args.classPath.trim() : args.classPath;
+            const classPath = requireNonEmptyString(classPathInput, 'classPath', 'Invalid classPath: must be a non-empty string');
+            const actorNameInput = typeof args.actorName === 'string' && args.actorName.trim() !== ''
+              ? args.actorName
+              : (typeof args.name === 'string' ? args.name : undefined);
             const res = await tools.actorTools.spawn({
-              classPath: args.classPath,
+              classPath,
               location: args.location,
-              rotation: args.rotation
+              rotation: args.rotation,
+              actorName: actorNameInput
             });
             return cleanObject(res);
           }
           case 'delete': {
-            if (!args.actorName || typeof args.actorName !== 'string' || args.actorName.trim() === '') {
-              throw new Error('Invalid actorName');
-            }
-            const res = await tools.bridge.executeEditorFunction('DELETE_ACTOR', { actor_name: args.actorName });
+            await elicitMissingPrimitiveArgs(
+              tools,
+              args,
+              'Which actor should control_actor.delete remove?',
+              {
+                actorName: {
+                  type: 'string',
+                  title: 'Actor Name',
+                  description: 'Exact label of the actor to delete'
+                }
+              }
+            );
+            const actorNameArg = typeof args.actorName === 'string' && args.actorName.trim() !== ''
+              ? args.actorName
+              : (typeof args.name === 'string' ? args.name : undefined);
+            const actorName = requireNonEmptyString(actorNameArg, 'actorName', 'Invalid actorName');
+            const res = await tools.bridge.executeEditorFunction('DELETE_ACTOR', { actor_name: actorName });
             return cleanObject(res);
           }
           case 'apply_force': {
-            if (!args.actorName || typeof args.actorName !== 'string' || args.actorName.trim() === '') {
-              throw new Error('Invalid actorName');
-            }
-            if (!args.force || typeof args.force.x !== 'number' || typeof args.force.y !== 'number' || typeof args.force.z !== 'number') {
-              throw new Error('Invalid force: must have numeric x,y,z');
-            }
+            await elicitMissingPrimitiveArgs(
+              tools,
+              args,
+              'Provide the target actor for control_actor.apply_force',
+              {
+                actorName: {
+                  type: 'string',
+                  title: 'Actor Name',
+                  description: 'Physics-enabled actor that should receive the force'
+                }
+              }
+            );
+            const actorName = requireNonEmptyString(args.actorName, 'actorName', 'Invalid actorName');
+            const vector = requireVector3Components(args.force, 'Invalid force: must have numeric x,y,z');
             const res = await tools.physicsTools.applyForce({
-              actorName: args.actorName,
+              actorName,
               forceType: 'Force',
-              vector: [args.force.x, args.force.y, args.force.z]
+              vector
             });
             return cleanObject(res);
           }
@@ -108,12 +309,7 @@ switch (args.action) {
 
       // 3. EDITOR CONTROL
       case 'control_editor':
-        // Validate action exists
-        if (!args.action) {
-          throw new Error('Missing required parameter: action');
-        }
-        
-switch (args.action) {
+        switch (requireAction(args)) {
           case 'play': {
             const res = await tools.editorTools.playInEditor();
             return cleanObject(res);
@@ -127,11 +323,9 @@ switch (args.action) {
             return cleanObject(res);
           }
           case 'set_game_speed': {
-            if (typeof args.speed !== 'number' || !isFinite(args.speed) || args.speed <= 0) {
-              throw new Error('Invalid speed: must be a positive number');
-            }
+            const speed = requirePositiveNumber(args.speed, 'speed', 'Invalid speed: must be a positive number');
             // Use console command via bridge
-            const res = await tools.bridge.executeConsoleCommand(`slomo ${args.speed}`);
+            const res = await tools.bridge.executeConsoleCommand(`slomo ${speed}`);
             return cleanObject(res);
           }
           case 'eject': {
@@ -147,8 +341,20 @@ switch (args.action) {
             return cleanObject(res);
           }
           case 'set_view_mode': {
-            if (!args.viewMode || typeof args.viewMode !== 'string') throw new Error('Missing required parameter: viewMode');
-            const res = await tools.bridge.setSafeViewMode(args.viewMode);
+            await elicitMissingPrimitiveArgs(
+              tools,
+              args,
+              'Provide the view mode for control_editor.set_view_mode',
+              {
+                viewMode: {
+                  type: 'string',
+                  title: 'View Mode',
+                  description: 'Viewport view mode (e.g., Lit, Unlit, Wireframe)'
+                }
+              }
+            );
+            const viewMode = requireNonEmptyString(args.viewMode, 'viewMode', 'Missing required parameter: viewMode');
+            const res = await tools.bridge.setSafeViewMode(viewMode);
             return cleanObject(res);
           }
           default:
@@ -157,11 +363,22 @@ switch (args.action) {
 
       // 4. LEVEL MANAGER
 case 'manage_level':
-        if (!args.action) throw new Error('Missing required parameter: action');
-        switch (args.action) {
+        switch (requireAction(args)) {
           case 'load': {
-            if (!args.levelPath || typeof args.levelPath !== 'string') throw new Error('Missing required parameter: levelPath');
-            const res = await tools.levelTools.loadLevel({ levelPath: args.levelPath, streaming: !!args.streaming });
+            await elicitMissingPrimitiveArgs(
+              tools,
+              args,
+              'Select the level to load for manage_level.load',
+              {
+                levelPath: {
+                  type: 'string',
+                  title: 'Level Path',
+                  description: 'Content path of the level asset to load (e.g., /Game/Maps/MyLevel)'
+                }
+              }
+            );
+            const levelPath = requireNonEmptyString(args.levelPath, 'levelPath', 'Missing required parameter: levelPath');
+            const res = await tools.levelTools.loadLevel({ levelPath, streaming: !!args.streaming });
             return cleanObject(res);
           }
           case 'save': {
@@ -169,19 +386,136 @@ case 'manage_level':
             return cleanObject(res);
           }
           case 'stream': {
-            if (!args.levelName || typeof args.levelName !== 'string') throw new Error('Missing required parameter: levelName');
-            const res = await tools.levelTools.streamLevel({ levelName: args.levelName, shouldBeLoaded: !!args.shouldBeLoaded, shouldBeVisible: !!args.shouldBeVisible });
+            await elicitMissingPrimitiveArgs(
+              tools,
+              args,
+              'Provide the streaming level name for manage_level.stream',
+              {
+                levelName: {
+                  type: 'string',
+                  title: 'Level Name',
+                  description: 'Streaming level name to toggle'
+                }
+              }
+            );
+            const levelName = requireNonEmptyString(args.levelName, 'levelName', 'Missing required parameter: levelName');
+            const res = await tools.levelTools.streamLevel({ levelName, shouldBeLoaded: !!args.shouldBeLoaded, shouldBeVisible: !!args.shouldBeVisible });
             return cleanObject(res);
           }
           case 'create_light': {
-            if (!args.lightType) throw new Error('Missing required parameter: lightType');
-            if (!args.name || typeof args.name !== 'string' || args.name.trim() === '') throw new Error('Invalid name');
-            const t = String(args.lightType).toLowerCase();
-            if (t === 'directional') return cleanObject(await tools.lightingTools.createDirectionalLight({ name: args.name, intensity: args.intensity }));
-            if (t === 'point') return cleanObject(await tools.lightingTools.createPointLight({ name: args.name, location: args.location ? [args.location.x, args.location.y, args.location.z] : [0,0,0], intensity: args.intensity }));
-            if (t === 'spot') return cleanObject(await tools.lightingTools.createSpotLight({ name: args.name, location: args.location ? [args.location.x, args.location.y, args.location.z] : [0,0,0], rotation: [0,0,0], intensity: args.intensity }));
-            if (t === 'rect') return cleanObject(await tools.lightingTools.createRectLight({ name: args.name, location: args.location ? [args.location.x, args.location.y, args.location.z] : [0,0,0], rotation: [0,0,0], intensity: args.intensity }));
-            throw new Error(`Unknown light type: ${args.lightType}`);
+            await elicitMissingPrimitiveArgs(
+              tools,
+              args,
+              'Provide the light details for manage_level.create_light',
+              {
+                lightType: {
+                  type: 'string',
+                  title: 'Light Type',
+                  description: 'Directional, Point, Spot, Rect, or Sky'
+                },
+                name: {
+                  type: 'string',
+                  title: 'Light Name',
+                  description: 'Name for the new light actor'
+                }
+              }
+            );
+            const lightType = requireNonEmptyString(args.lightType, 'lightType', 'Missing required parameter: lightType');
+            const name = requireNonEmptyString(args.name, 'name', 'Invalid name');
+            const typeKey = lightType.toLowerCase();
+            const toVector = (value: any, fallback: [number, number, number]): [number, number, number] => {
+              if (Array.isArray(value) && value.length === 3) {
+                return [Number(value[0]) || 0, Number(value[1]) || 0, Number(value[2]) || 0];
+              }
+              if (value && typeof value === 'object') {
+                return [Number(value.x) || 0, Number(value.y) || 0, Number(value.z) || 0];
+              }
+              return fallback;
+            };
+            const toRotator = (value: any, fallback: [number, number, number]): [number, number, number] => {
+              if (Array.isArray(value) && value.length === 3) {
+                return [Number(value[0]) || 0, Number(value[1]) || 0, Number(value[2]) || 0];
+              }
+              if (value && typeof value === 'object') {
+                return [Number(value.pitch) || 0, Number(value.yaw) || 0, Number(value.roll) || 0];
+              }
+              return fallback;
+            };
+            const toColor = (value: any): [number, number, number] | undefined => {
+              if (Array.isArray(value) && value.length === 3) {
+                return [Number(value[0]) || 0, Number(value[1]) || 0, Number(value[2]) || 0];
+              }
+              if (value && typeof value === 'object') {
+                return [Number(value.r) || 0, Number(value.g) || 0, Number(value.b) || 0];
+              }
+              return undefined;
+            };
+
+            const location = toVector(args.location, [0, 0, typeKey === 'directional' ? 500 : 0]);
+            const rotation = toRotator(args.rotation, [0, 0, 0]);
+            const color = toColor(args.color);
+            const castShadows = typeof args.castShadows === 'boolean' ? args.castShadows : undefined;
+
+            if (typeKey === 'directional') {
+              return cleanObject(await tools.lightingTools.createDirectionalLight({
+                name,
+                intensity: args.intensity,
+                color,
+                rotation,
+                castShadows,
+                temperature: args.temperature
+              }));
+            }
+            if (typeKey === 'point') {
+              return cleanObject(await tools.lightingTools.createPointLight({
+                name,
+                location,
+                intensity: args.intensity,
+                radius: args.radius,
+                color,
+                falloffExponent: args.falloffExponent,
+                castShadows
+              }));
+            }
+            if (typeKey === 'spot') {
+              const innerCone = typeof args.innerCone === 'number' ? args.innerCone : undefined;
+              const outerCone = typeof args.outerCone === 'number' ? args.outerCone : undefined;
+              if (innerCone !== undefined && outerCone !== undefined && innerCone >= outerCone) {
+                throw new Error('innerCone must be less than outerCone');
+              }
+              return cleanObject(await tools.lightingTools.createSpotLight({
+                name,
+                location,
+                rotation,
+                intensity: args.intensity,
+                innerCone: args.innerCone,
+                outerCone: args.outerCone,
+                radius: args.radius,
+                color,
+                castShadows
+              }));
+            }
+            if (typeKey === 'rect') {
+              return cleanObject(await tools.lightingTools.createRectLight({
+                name,
+                location,
+                rotation,
+                intensity: args.intensity,
+                width: args.width,
+                height: args.height,
+                color
+              }));
+            }
+            if (typeKey === 'sky' || typeKey === 'skylight') {
+              return cleanObject(await tools.lightingTools.createSkyLight({
+                name,
+                sourceType: args.sourceType,
+                cubemapPath: args.cubemapPath,
+                intensity: args.intensity,
+                recapture: args.recapture
+              }));
+            }
+            throw new Error(`Unknown light type: ${lightType}`);
           }
           case 'build_lighting': {
             const res = await tools.lightingTools.buildLighting({ quality: args.quality || 'High', buildReflectionCaptures: true });
@@ -193,29 +527,75 @@ case 'manage_level':
 
       // 5. ANIMATION & PHYSICS
 case 'animation_physics':
-        // Validate action exists
-        if (!args.action) {
-          throw new Error('Missing required parameter: action');
-        }
-        
-        switch (args.action) {
+        switch (requireAction(args)) {
           case 'create_animation_bp': {
-            if (typeof args.name !== 'string' || args.name.trim() === '') throw new Error('Invalid name');
-            if (typeof args.skeletonPath !== 'string' || args.skeletonPath.trim() === '') throw new Error('Invalid skeletonPath');
-            const res = await tools.animationTools.createAnimationBlueprint({ name: args.name, skeletonPath: args.skeletonPath, savePath: args.savePath });
+            await elicitMissingPrimitiveArgs(
+              tools,
+              args,
+              'Provide details for animation_physics.create_animation_bp',
+              {
+                name: {
+                  type: 'string',
+                  title: 'Blueprint Name',
+                  description: 'Name of the Animation Blueprint to create'
+                },
+                skeletonPath: {
+                  type: 'string',
+                  title: 'Skeleton Path',
+                  description: 'Content path of the skeleton asset to bind'
+                }
+              }
+            );
+            const name = requireNonEmptyString(args.name, 'name', 'Invalid name');
+            const skeletonPath = requireNonEmptyString(args.skeletonPath, 'skeletonPath', 'Invalid skeletonPath');
+            const res = await tools.animationTools.createAnimationBlueprint({ name, skeletonPath, savePath: args.savePath });
             return cleanObject(res);
           }
           case 'play_montage': {
-            if (typeof args.actorName !== 'string' || args.actorName.trim() === '') throw new Error('Invalid actorName');
+            await elicitMissingPrimitiveArgs(
+              tools,
+              args,
+              'Provide playback details for animation_physics.play_montage',
+              {
+                actorName: {
+                  type: 'string',
+                  title: 'Actor Name',
+                  description: 'Actor that should play the montage'
+                },
+                montagePath: {
+                  type: 'string',
+                  title: 'Montage Path',
+                  description: 'Montage or animation asset path to play'
+                }
+              }
+            );
+            const actorName = requireNonEmptyString(args.actorName, 'actorName', 'Invalid actorName');
             const montagePath = args.montagePath || args.animationPath;
-            if (typeof montagePath !== 'string' || montagePath.trim() === '') throw new Error('Invalid montagePath');
-            const res = await tools.animationTools.playAnimation({ actorName: args.actorName, animationType: 'Montage', animationPath: montagePath, playRate: args.playRate });
+            const validatedMontage = requireNonEmptyString(montagePath, 'montagePath', 'Invalid montagePath');
+            const res = await tools.animationTools.playAnimation({ actorName, animationType: 'Montage', animationPath: validatedMontage, playRate: args.playRate });
             return cleanObject(res);
           }
           case 'setup_ragdoll': {
-            if (typeof args.skeletonPath !== 'string' || args.skeletonPath.trim() === '') throw new Error('Invalid skeletonPath');
-            if (typeof args.physicsAssetName !== 'string' || args.physicsAssetName.trim() === '') throw new Error('Invalid physicsAssetName');
-            const res = await tools.physicsTools.setupRagdoll({ skeletonPath: args.skeletonPath, physicsAssetName: args.physicsAssetName, blendWeight: args.blendWeight, savePath: args.savePath });
+            await elicitMissingPrimitiveArgs(
+              tools,
+              args,
+              'Provide setup details for animation_physics.setup_ragdoll',
+              {
+                skeletonPath: {
+                  type: 'string',
+                  title: 'Skeleton Path',
+                  description: 'Content path for the skeleton asset'
+                },
+                physicsAssetName: {
+                  type: 'string',
+                  title: 'Physics Asset Name',
+                  description: 'Name of the physics asset to apply'
+                }
+              }
+            );
+            const skeletonPath = requireNonEmptyString(args.skeletonPath, 'skeletonPath', 'Invalid skeletonPath');
+            const physicsAssetName = requireNonEmptyString(args.physicsAssetName, 'physicsAssetName', 'Invalid physicsAssetName');
+            const res = await tools.physicsTools.setupRagdoll({ skeletonPath, physicsAssetName, blendWeight: args.blendWeight, savePath: args.savePath });
             return cleanObject(res);
           }
           default:
@@ -224,20 +604,61 @@ case 'animation_physics':
 
 // 6. EFFECTS SYSTEM
       case 'create_effect':
-        switch (args.action) {
+        switch (requireAction(args)) {
           case 'particle': {
+            await elicitMissingPrimitiveArgs(
+              tools,
+              args,
+              'Provide the particle effect details for create_effect.particle',
+              {
+                effectType: {
+                  type: 'string',
+                  title: 'Effect Type',
+                  description: 'Preset effect type to spawn (e.g., Fire, Smoke)'
+                }
+              }
+            );
             const res = await tools.niagaraTools.createEffect({ effectType: args.effectType, name: args.name, location: args.location, scale: args.scale, customParameters: args.customParameters });
             return cleanObject(res);
           }
           case 'niagara': {
-            if (typeof args.systemPath !== 'string' || args.systemPath.trim() === '') throw new Error('Invalid systemPath');
-            // Create or ensure system exists (spawning in editor is not universally supported via RC)
-            const name = args.name || args.systemPath.split('/').pop();
-            const res = await tools.niagaraTools.createSystem({ name, savePath: args.savePath || '/Game/Effects/Niagara' });
+            await elicitMissingPrimitiveArgs(
+              tools,
+              args,
+              'Provide the Niagara system path for create_effect.niagara',
+              {
+                systemPath: {
+                  type: 'string',
+                  title: 'Niagara System Path',
+                  description: 'Asset path of the Niagara system to spawn'
+                }
+              }
+            );
+            const systemPath = requireNonEmptyString(args.systemPath, 'systemPath', 'Invalid systemPath');
+            const verifyResult = await tools.bridge.executePythonWithResult(`
+import unreal, json
+path = r"${systemPath}"
+exists = unreal.EditorAssetLibrary.does_asset_exist(path)
+print('RESULT:' + json.dumps({'success': exists, 'exists': exists, 'path': path}))
+`.trim());
+            if (!verifyResult?.exists) {
+              return cleanObject({ success: false, error: `Niagara system not found at ${systemPath}` });
+            }
+            const loc = Array.isArray(args.location)
+              ? { x: args.location[0], y: args.location[1], z: args.location[2] }
+              : args.location || { x: 0, y: 0, z: 0 };
+            const res = await tools.niagaraTools.spawnEffect({
+              systemPath,
+              location: [loc.x ?? 0, loc.y ?? 0, loc.z ?? 0],
+              rotation: Array.isArray(args.rotation) ? args.rotation : undefined,
+              scale: args.scale
+            });
             return cleanObject(res);
           }
           case 'debug_shape': {
-            const shape = String(args.shape || 'Sphere').toLowerCase();
+            const shapeInput = args.shape ?? 'Sphere';
+            const shape = String(shapeInput).trim().toLowerCase();
+            const originalShapeLabel = String(shapeInput).trim() || 'shape';
             const loc = args.location || { x: 0, y: 0, z: 0 };
             const size = args.size || 100;
             const color = args.color || [255, 0, 0, 255];
@@ -264,7 +685,7 @@ case 'animation_physics':
               return cleanObject(await tools.debugTools.drawDebugString({ location: [loc.x, loc.y, loc.z], text, color, duration }));
             }
             // Default fallback
-            return cleanObject(await tools.debugTools.drawDebugSphere({ center: [loc.x, loc.y, loc.z], radius: size, color, duration }));
+            return cleanObject({ success: false, error: `Unsupported debug shape: ${originalShapeLabel}` });
           }
           default:
             throw new Error(`Unknown effect action: ${args.action}`);
@@ -272,12 +693,56 @@ case 'animation_physics':
 
 // 7. BLUEPRINT MANAGER
       case 'manage_blueprint':
-        switch (args.action) {
+        switch (requireAction(args)) {
           case 'create': {
-            const res = await tools.blueprintTools.createBlueprint({ name: args.name, blueprintType: args.blueprintType || 'Actor', savePath: args.savePath });
+            await elicitMissingPrimitiveArgs(
+              tools,
+              args,
+              'Provide details for manage_blueprint.create',
+              {
+                name: {
+                  type: 'string',
+                  title: 'Blueprint Name',
+                  description: 'Name for the new Blueprint asset'
+                },
+                blueprintType: {
+                  type: 'string',
+                  title: 'Blueprint Type',
+                  description: 'Base type such as Actor, Pawn, Character, etc.'
+                }
+              }
+            );
+            const res = await tools.blueprintTools.createBlueprint({
+              name: args.name,
+              blueprintType: args.blueprintType || 'Actor',
+              savePath: args.savePath,
+              parentClass: args.parentClass
+            });
             return cleanObject(res);
           }
           case 'add_component': {
+            await elicitMissingPrimitiveArgs(
+              tools,
+              args,
+              'Provide details for manage_blueprint.add_component',
+              {
+                name: {
+                  type: 'string',
+                  title: 'Blueprint Name',
+                  description: 'Blueprint asset to modify'
+                },
+                componentType: {
+                  type: 'string',
+                  title: 'Component Type',
+                  description: 'Component class to add (e.g., StaticMeshComponent)'
+                },
+                componentName: {
+                  type: 'string',
+                  title: 'Component Name',
+                  description: 'Name for the new component'
+                }
+              }
+            );
             const res = await tools.blueprintTools.addComponent({ blueprintName: args.name, componentType: args.componentType, componentName: args.componentName });
             return cleanObject(res);
           }
@@ -287,7 +752,7 @@ case 'animation_physics':
 
 // 8. ENVIRONMENT BUILDER
       case 'build_environment':
-        switch (args.action) {
+        switch (requireAction(args)) {
           case 'create_landscape': {
             const res = await tools.landscapeTools.createLandscape({ name: args.name, sizeX: args.sizeX, sizeY: args.sizeY, materialPath: args.materialPath });
             return cleanObject(res);
@@ -359,8 +824,7 @@ case 'animation_physics':
 
       // 9. SYSTEM CONTROL
 case 'system_control':
-        if (!args.action) throw new Error('Missing required parameter: action');
-        switch (args.action) {
+        switch (requireAction(args)) {
           case 'profile': {
             const res = await tools.performanceTools.startProfiling({ type: args.profileType, duration: args.duration });
             return cleanObject(res);
@@ -374,16 +838,48 @@ case 'system_control':
             return cleanObject(res);
           }
           case 'play_sound': {
+            await elicitMissingPrimitiveArgs(
+              tools,
+              args,
+              'Provide the audio asset for system_control.play_sound',
+              {
+                soundPath: {
+                  type: 'string',
+                  title: 'Sound Asset Path',
+                  description: 'Asset path of the sound to play'
+                }
+              }
+            );
+            const soundPath = requireNonEmptyString(args.soundPath, 'soundPath', 'Missing required parameter: soundPath');
             if (args.location && typeof args.location === 'object') {
               const loc = [args.location.x || 0, args.location.y || 0, args.location.z || 0];
-              const res = await tools.audioTools.playSoundAtLocation({ soundPath: args.soundPath, location: loc as [number, number, number], volume: args.volume, pitch: args.pitch, startTime: args.startTime });
+              const res = await tools.audioTools.playSoundAtLocation({ soundPath, location: loc as [number, number, number], volume: args.volume, pitch: args.pitch, startTime: args.startTime });
               return cleanObject(res);
             }
-            const res = await tools.audioTools.playSound2D({ soundPath: args.soundPath, volume: args.volume, pitch: args.pitch, startTime: args.startTime });
+            const res = await tools.audioTools.playSound2D({ soundPath, volume: args.volume, pitch: args.pitch, startTime: args.startTime });
             return cleanObject(res);
           }
           case 'create_widget': {
-            const res = await tools.uiTools.createWidget({ name: args.widgetName, type: args.widgetType, savePath: args.savePath });
+            await elicitMissingPrimitiveArgs(
+              tools,
+              args,
+              'Provide details for system_control.create_widget',
+              {
+                widgetName: {
+                  type: 'string',
+                  title: 'Widget Name',
+                  description: 'Name for the new UI widget asset'
+                },
+                widgetType: {
+                  type: 'string',
+                  title: 'Widget Type',
+                  description: 'Widget type such as HUD, Menu, Overlay, etc.'
+                }
+              }
+            );
+            const widgetName = requireNonEmptyString(args.widgetName ?? args.name, 'widgetName', 'Missing required parameter: widgetName');
+            const widgetType = requireNonEmptyString(args.widgetType, 'widgetType', 'Missing required parameter: widgetType');
+            const res = await tools.uiTools.createWidget({ name: widgetName, type: widgetType as any, savePath: args.savePath });
             return cleanObject(res);
           }
           case 'show_widget': {
@@ -418,8 +914,22 @@ case 'console_command':
           return { success: false, error: 'Command blocked for safety' } as any;
         }
         try {
-          const res = await tools.bridge.executeConsoleCommand(cmd);
-          return cleanObject({ success: true, command: cmd, result: res });
+          const raw = await tools.bridge.executeConsoleCommand(cmd);
+          const summary = tools.bridge.summarizeConsoleCommand(cmd, raw);
+          const output = summary.output || '';
+          const looksInvalid = /unknown|invalid/i.test(output);
+          return cleanObject({
+            success: summary.returnValue !== false && !looksInvalid,
+            command: summary.command,
+            output: output || undefined,
+            logLines: summary.logLines?.length ? summary.logLines : undefined,
+            returnValue: summary.returnValue,
+            message: !looksInvalid
+              ? (output || 'Command executed')
+              : undefined,
+            error: looksInvalid ? output : undefined,
+            raw: summary.raw
+          });
         } catch (e: any) {
           return cleanObject({ success: false, command: cmd, error: e?.message || String(e) });
         }
@@ -427,12 +937,10 @@ case 'console_command':
 
       // 11. REMOTE CONTROL PRESETS - Direct implementation
       case 'manage_rc':
-        if (!args.action) throw new Error('Missing required parameter: action');
-        
         // Handle RC operations directly through RcTools
         let rcResult: any;
-        
-        switch (args.action) {
+        const rcAction = requireAction(args);
+        switch (rcAction) {
           // Support both 'create_preset' and 'create' for compatibility
           case 'create_preset':
           case 'create':
@@ -459,8 +967,10 @@ case 'console_command':
             break;
             
           case 'delete':
-            if (!args.presetId) throw new Error('Missing required parameter: presetId');
-            rcResult = await tools.rcTools.deletePreset(args.presetId);
+          case 'delete_preset':
+            const presetIdentifier = args.presetId || args.presetPath;
+            if (!presetIdentifier) throw new Error('Missing required parameter: presetId');
+            rcResult = await tools.rcTools.deletePreset(presetIdentifier);
             if (rcResult.success) {
               rcResult.message = 'Preset deleted successfully';
             }
@@ -557,7 +1067,7 @@ case 'console_command':
             break;
             
           default:
-            throw new Error(`Unknown RC action: ${args.action}. Valid actions are: create_preset, expose_actor, expose_property, list_fields, set_property, get_property, or their simplified versions: create, list, delete, expose, get_exposed, set_value, get_value, call_function`);
+            throw new Error(`Unknown RC action: ${rcAction}. Valid actions are: create_preset, expose_actor, expose_property, list_fields, set_property, get_property, or their simplified versions: create, list, delete, expose, get_exposed, set_value, get_value, call_function`);
         }
         
         // Return result directly - MCP formatting will be handled by response validator
@@ -566,14 +1076,13 @@ case 'console_command':
 
       // 12. SEQUENCER / CINEMATICS
       case 'manage_sequence':
-        if (!args.action) throw new Error('Missing required parameter: action');
-        
         // Direct handling for sequence operations
         const seqResult = await (async () => {
           const sequenceTools = tools.sequenceTools;
           if (!sequenceTools) throw new Error('Sequence tools not available');
+          const action = requireAction(args);
           
-          switch (args.action) {
+          switch (action) {
             case 'create':
               return await sequenceTools.create({ name: args.name, path: args.path });
             case 'open':
@@ -613,7 +1122,7 @@ case 'console_command':
               if (args.speed === undefined) throw new Error('Missing required parameter: speed');
               return await sequenceTools.setPlaybackSpeed({ speed: args.speed });
             default:
-              throw new Error(`Unknown sequence action: ${args.action}`);
+              throw new Error(`Unknown sequence action: ${action}`);
           }
         })();
         
@@ -622,8 +1131,8 @@ case 'console_command':
         return cleanObject(seqResult);
       // 13. INTROSPECTION
 case 'inspect':
-        if (!args.action) throw new Error('Missing required parameter: action');
-        switch (args.action) {
+  const inspectAction = requireAction(args);
+  switch (inspectAction) {
           case 'inspect_object': {
             const res = await tools.introspectionTools.inspectObject({ objectPath: args.objectPath, detailed: args.detailed });
             return cleanObject(res);
@@ -633,7 +1142,7 @@ case 'inspect':
             return cleanObject(res);
           }
           default:
-            throw new Error(`Unknown inspect action: ${args.action}`);
+            throw new Error(`Unknown inspect action: ${inspectAction}`);
         }