unreal-engine-mcp-server 0.4.0 → 0.4.4

package/dist/tools/consolidated-tool-handlers.js

@@ -2,27 +2,112 @@
 import { cleanObject } from '../utils/safe-json.js';
 import { Logger } from '../utils/logger.js';
 const log = new Logger('ConsolidatedToolHandler');
+const ACTION_REQUIRED_ERROR = 'Missing required parameter: action';
+function ensureArgsPresent(args) {
+    if (args === null || args === undefined) {
+        throw new Error('Invalid arguments: null or undefined');
+    }
+}
+function requireAction(args) {
+    ensureArgsPresent(args);
+    const action = args.action;
+    if (typeof action !== 'string' || action.trim() === '') {
+        throw new Error(ACTION_REQUIRED_ERROR);
+    }
+    return action;
+}
+function requireNonEmptyString(value, field, message) {
+    if (typeof value !== 'string' || value.trim() === '') {
+        throw new Error(message ?? `Invalid ${field}: must be a non-empty string`);
+    }
+    return value;
+}
+function requirePositiveNumber(value, field, message) {
+    if (typeof value !== 'number' || !isFinite(value) || value <= 0) {
+        throw new Error(message ?? `Invalid ${field}: must be a positive number`);
+    }
+    return value;
+}
+function requireVector3Components(vector, message) {
+    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) {
+    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, args, prompt, fieldSchemas) {
+    if (!tools ||
+        typeof tools.supportsElicitation !== 'function' ||
+        !tools.supportsElicitation() ||
+        typeof tools.elicit !== 'function') {
+        return;
+    }
+    const properties = {};
+    const required = [];
+    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 = {
+        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?.message || String(err)
+        });
+    }
+}
 export async function handleConsolidatedToolCall(name, args, tools) {
     const startTime = Date.now();
     // Use scoped logger (stderr) to avoid polluting stdout JSON
     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');
@@ -31,20 +116,66 @@ export async function handleConsolidatedToolCall(name, args, tools) {
                         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 = {};
+                            const required = [];
+                            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 = { 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:
@@ -52,40 +183,57 @@ export async function handleConsolidatedToolCall(name, args, tools) {
                 }
             // 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);
                     }
@@ -94,11 +242,7 @@ export async function handleConsolidatedToolCall(name, args, tools) {
                 }
             // 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);
@@ -112,11 +256,9 @@ export async function handleConsolidatedToolCall(name, args, tools) {
                         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': {
@@ -132,9 +274,15 @@ export async function handleConsolidatedToolCall(name, args, tools) {
                         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:
@@ -142,13 +290,17 @@ export async function handleConsolidatedToolCall(name, args, tools) {
                 }
             // 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': {
@@ -156,26 +308,124 @@ export async function handleConsolidatedToolCall(name, args, tools) {
                         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, fallback) => {
+                            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, fallback) => {
+                            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) => {
+                            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 });
@@ -186,34 +436,60 @@ export async function handleConsolidatedToolCall(name, args, tools) {
                 }
             // 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:
@@ -221,21 +497,51 @@ export async function handleConsolidatedToolCall(name, args, tools) {
                 }
             // 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];
@@ -269,19 +575,53 @@ export async function handleConsolidatedToolCall(name, args, tools) {
                             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}`);
                 }
             // 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);
                     }
@@ -290,7 +630,7 @@ export async function handleConsolidatedToolCall(name, args, tools) {
                 }
             // 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);
@@ -364,9 +704,7 @@ export async function handleConsolidatedToolCall(name, args, tools) {
                 }
             // 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);
@@ -380,16 +718,38 @@ export async function handleConsolidatedToolCall(name, args, tools) {
                         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, volume: args.volume, pitch: args.pitch, startTime: args.startTime });
+                            const res = await tools.audioTools.playSoundAtLocation({ soundPath, location: loc, 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, savePath: args.savePath });
                         return cleanObject(res);
                     }
                     case 'show_widget': {
@@ -423,19 +783,32 @@ export async function handleConsolidatedToolCall(name, args, tools) {
                     return { success: false, error: 'Command blocked for safety' };
                 }
                 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) {
                     return cleanObject({ success: false, command: cmd, error: e?.message || String(e) });
                 }
             // 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;
-                switch (args.action) {
+                const rcAction = requireAction(args);
+                switch (rcAction) {
                     // Support both 'create_preset' and 'create' for compatibility
                     case 'create_preset':
                     case 'create':
@@ -461,9 +834,11 @@ export async function handleConsolidatedToolCall(name, args, tools) {
                         rcResult = await tools.rcTools.listPresets();
                         break;
                     case 'delete':
-                        if (!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(args.presetId);
+                        rcResult = await tools.rcTools.deletePreset(presetIdentifier);
                         if (rcResult.success) {
                             rcResult.message = 'Preset deleted successfully';
                         }
@@ -558,21 +933,20 @@ export async function handleConsolidatedToolCall(name, args, tools) {
                         };
                         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
                 // Clean to prevent circular references
                 return cleanObject(rcResult);
             // 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');
-                    switch (args.action) {
+                    const action = requireAction(args);
+                    switch (action) {
                         case 'create':
                             return await sequenceTools.create({ name: args.name, path: args.path });
                         case 'open':
@@ -616,7 +990,7 @@ export async function handleConsolidatedToolCall(name, args, tools) {
                                 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}`);
                     }
                 })();
                 // Return result directly - MCP formatting will be handled by response validator
@@ -624,9 +998,8 @@ export async function handleConsolidatedToolCall(name, args, tools) {
                 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);
@@ -636,7 +1009,7 @@ export async function handleConsolidatedToolCall(name, args, tools) {
                         return cleanObject(res);
                     }
                     default:
-                        throw new Error(`Unknown inspect action: ${args.action}`);
+                        throw new Error(`Unknown inspect action: ${inspectAction}`);
                 }
             default:
                 throw new Error(`Unknown consolidated tool: ${name}`);