unreal-engine-mcp-server 0.3.1 → 0.4.3

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

@@ -1,818 +1,814 @@
 // Consolidated tool handlers - maps 13 tools to all 36 operations
-import { handleToolCall } from './tool-handlers.js';
 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');
-        }
-        let mappedName;
-        let mappedArgs = { ...args };
+        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) {
-                    case 'list':
-                        // Directory is optional
-                        if (args.directory !== undefined && args.directory !== null) {
-                            if (typeof args.directory !== 'string') {
-                                throw new Error('Invalid directory: must be a string');
-                            }
+                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');
                         }
-                        mappedName = 'list_assets';
-                        mappedArgs = {
-                            directory: args.directory
-                            // recursive removed - always false internally
-                        };
-                        break;
-                    case 'import':
-                        // Validate required parameters
-                        if (args.sourcePath === undefined || args.sourcePath === null) {
-                            throw new Error('Missing required parameter: sourcePath');
-                        }
-                        if (typeof args.sourcePath !== 'string') {
-                            throw new Error('Invalid sourcePath: must be a string');
-                        }
-                        if (args.sourcePath.trim() === '') {
-                            throw new Error('Invalid sourcePath: cannot be empty');
-                        }
-                        if (args.destinationPath === undefined || args.destinationPath === null) {
-                            throw new Error('Missing required parameter: destinationPath');
-                        }
-                        if (typeof args.destinationPath !== 'string') {
-                            throw new Error('Invalid destinationPath: must be a string');
-                        }
-                        if (args.destinationPath.trim() === '') {
-                            throw new Error('Invalid destinationPath: cannot be empty');
-                        }
-                        mappedName = 'import_asset';
-                        mappedArgs = {
-                            sourcePath: args.sourcePath,
-                            destinationPath: args.destinationPath
-                        };
-                        break;
-                    case 'create_material':
-                        // Validate required parameters
-                        if (args.name === undefined || args.name === null) {
-                            throw new Error('Missing required parameter: name');
-                        }
-                        if (typeof args.name !== 'string') {
-                            throw new Error('Invalid name: must be a string');
-                        }
-                        if (args.name.trim() === '') {
-                            throw new Error('Invalid name: cannot be empty');
-                        }
-                        // Path is optional
-                        if (args.path !== undefined && args.path !== null) {
-                            if (typeof args.path !== 'string') {
-                                throw new Error('Invalid path: must be a string');
+                        const res = await tools.assetResources.list(args.directory || '/Game', false);
+                        return cleanObject({ success: true, ...res });
+                    }
+                    case 'import': {
+                        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();
+                                    }
+                                }
                             }
                         }
-                        mappedName = 'create_material';
-                        mappedArgs = {
-                            name: args.name,
-                            path: args.path
-                        };
-                        break;
+                        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': {
+                        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:
                         throw new Error(`Unknown asset action: ${args.action}`);
                 }
-                break;
             // 2. ACTOR CONTROL
             case 'control_actor':
-                // Validate action exists
-                if (!args.action) {
-                    throw new Error('Missing required parameter: action');
-                }
-                switch (args.action) {
-                    case 'spawn':
-                        // Validate spawn parameters
-                        if (!args.classPath) {
-                            throw new Error('Missing required parameter: classPath');
-                        }
-                        if (typeof args.classPath !== 'string' || args.classPath.trim() === '') {
-                            throw new Error('Invalid classPath: must be a non-empty string');
-                        }
-                        mappedName = 'spawn_actor';
-                        mappedArgs = {
-                            classPath: args.classPath,
+                switch (requireAction(args)) {
+                    case 'spawn': {
+                        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,
                             location: args.location,
-                            rotation: args.rotation
-                        };
-                        break;
-                    case 'delete':
-                        // Validate delete parameters
-                        if (!args.actorName) {
-                            throw new Error('Missing required parameter: actorName');
-                        }
-                        if (typeof args.actorName !== 'string' || args.actorName.trim() === '') {
-                            throw new Error('Invalid actorName: must be a non-empty string');
-                        }
-                        mappedName = 'delete_actor';
-                        mappedArgs = {
-                            actorName: args.actorName
-                        };
-                        break;
-                    case 'apply_force':
-                        // Validate apply_force parameters
-                        if (!args.actorName) {
-                            throw new Error('Missing required parameter: actorName');
-                        }
-                        if (typeof args.actorName !== 'string' || args.actorName.trim() === '') {
-                            throw new Error('Invalid actorName: must be a non-empty string');
-                        }
-                        if (!args.force) {
-                            throw new Error('Missing required parameter: force');
-                        }
-                        if (typeof args.force !== 'object' || args.force === null) {
-                            throw new Error('Invalid force: must be an object with x, y, z properties');
-                        }
-                        if (typeof args.force.x !== 'number' ||
-                            typeof args.force.y !== 'number' ||
-                            typeof args.force.z !== 'number') {
-                            throw new Error('Invalid force: x, y, z must all be numbers');
-                        }
-                        mappedName = 'apply_force';
-                        mappedArgs = {
-                            actorName: args.actorName,
-                            force: args.force
-                        };
-                        break;
+                            rotation: args.rotation,
+                            actorName: actorNameInput
+                        });
+                        return cleanObject(res);
+                    }
+                    case 'delete': {
+                        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': {
+                        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,
+                            forceType: 'Force',
+                            vector
+                        });
+                        return cleanObject(res);
+                    }
                     default:
                         throw new Error(`Unknown actor action: ${args.action}`);
                 }
-                break;
             // 3. EDITOR CONTROL
             case 'control_editor':
-                // Validate action exists
-                if (!args.action) {
-                    throw new Error('Missing required parameter: action');
-                }
-                switch (args.action) {
-                    case 'play':
-                        mappedName = 'play_in_editor';
-                        mappedArgs = {};
-                        break;
-                    case 'stop':
-                        mappedName = 'stop_play_in_editor';
-                        mappedArgs = {};
-                        break;
-                    case 'pause':
-                        mappedName = 'pause_play_in_editor';
-                        mappedArgs = {};
-                        break;
-                    case 'set_game_speed':
-                        // Validate game speed parameter
-                        if (args.speed === undefined || args.speed === null) {
-                            throw new Error('Missing required parameter: speed');
-                        }
-                        if (typeof args.speed !== 'number') {
-                            throw new Error('Invalid speed: must be a number');
-                        }
-                        if (isNaN(args.speed)) {
-                            throw new Error('Invalid speed: cannot be NaN');
-                        }
-                        if (!isFinite(args.speed)) {
-                            throw new Error('Invalid speed: must be finite');
-                        }
-                        if (args.speed <= 0) {
-                            throw new Error('Invalid speed: must be positive');
-                        }
-                        mappedName = 'set_game_speed';
-                        mappedArgs = {
-                            speed: args.speed
-                        };
-                        break;
-                    case 'eject':
-                        mappedName = 'eject_from_pawn';
-                        mappedArgs = {};
-                        break;
-                    case 'possess':
-                        mappedName = 'possess_pawn';
-                        mappedArgs = {};
-                        break;
-                    case 'set_camera':
-                        // Allow either location or rotation or both
-                        // Don't require both to be present
-                        mappedName = 'set_camera';
-                        mappedArgs = {
-                            location: args.location,
-                            rotation: args.rotation
-                        };
-                        break;
-                    case 'set_view_mode':
-                        // Validate view mode parameter
-                        if (!args.viewMode) {
-                            throw new Error('Missing required parameter: viewMode');
-                        }
-                        if (typeof args.viewMode !== 'string' || args.viewMode.trim() === '') {
-                            throw new Error('Invalid viewMode: must be a non-empty string');
-                        }
-                        // Normalize view mode to match what debug.ts expects
-                        const validModes = ['lit', 'unlit', 'wireframe', 'detail_lighting', 'lighting_only',
-                            'light_complexity', 'shader_complexity', 'lightmap_density',
-                            'stationary_light_overlap', 'reflections', 'visualize_buffer',
-                            'collision_pawn', 'collision_visibility', 'lod_coloration', 'quad_overdraw'];
-                        const normalizedMode = args.viewMode.toLowerCase().replace(/_/g, '');
-                        // Map to proper case for debug.ts
-                        let mappedMode = '';
-                        switch (normalizedMode) {
-                            case 'lit':
-                                mappedMode = 'Lit';
-                                break;
-                            case 'unlit':
-                                mappedMode = 'Unlit';
-                                break;
-                            case 'wireframe':
-                                mappedMode = 'Wireframe';
-                                break;
-                            case 'detaillighting':
-                                mappedMode = 'DetailLighting';
-                                break;
-                            case 'lightingonly':
-                                mappedMode = 'LightingOnly';
-                                break;
-                            case 'lightcomplexity':
-                                mappedMode = 'LightComplexity';
-                                break;
-                            case 'shadercomplexity':
-                                mappedMode = 'ShaderComplexity';
-                                break;
-                            case 'lightmapdensity':
-                                mappedMode = 'LightmapDensity';
-                                break;
-                            case 'stationarylightoverlap':
-                                mappedMode = 'StationaryLightOverlap';
-                                break;
-                            case 'reflections':
-                                mappedMode = 'ReflectionOverride';
-                                break;
-                            case 'visualizebuffer':
-                                mappedMode = 'VisualizeBuffer';
-                                break;
-                            case 'collisionpawn':
-                                mappedMode = 'CollisionPawn';
-                                break;
-                            case 'collisionvisibility':
-                                mappedMode = 'CollisionVisibility';
-                                break;
-                            case 'lodcoloration':
-                                mappedMode = 'LODColoration';
-                                break;
-                            case 'quadoverdraw':
-                                mappedMode = 'QuadOverdraw';
-                                break;
-                            default:
-                                throw new Error(`Invalid viewMode: '${args.viewMode}'. Valid modes are: ${validModes.join(', ')}`);
-                        }
-                        mappedName = 'set_view_mode';
-                        mappedArgs = {
-                            mode: mappedMode
-                        };
-                        break;
+                switch (requireAction(args)) {
+                    case 'play': {
+                        const res = await tools.editorTools.playInEditor();
+                        return cleanObject(res);
+                    }
+                    case 'stop': {
+                        const res = await tools.editorTools.stopPlayInEditor();
+                        return cleanObject(res);
+                    }
+                    case 'pause': {
+                        const res = await tools.editorTools.pausePlayInEditor();
+                        return cleanObject(res);
+                    }
+                    case 'set_game_speed': {
+                        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 ${speed}`);
+                        return cleanObject(res);
+                    }
+                    case 'eject': {
+                        const res = await tools.bridge.executeConsoleCommand('eject');
+                        return cleanObject(res);
+                    }
+                    case 'possess': {
+                        const res = await tools.bridge.executeConsoleCommand('viewself');
+                        return cleanObject(res);
+                    }
+                    case 'set_camera': {
+                        const res = await tools.editorTools.setViewportCamera(args.location, args.rotation);
+                        return cleanObject(res);
+                    }
+                    case 'set_view_mode': {
+                        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:
                         throw new Error(`Unknown editor action: ${args.action}`);
                 }
-                break;
             // 4. LEVEL MANAGER
             case 'manage_level':
-                switch (args.action) {
-                    case 'load':
-                        mappedName = 'load_level';
-                        mappedArgs = {
-                            levelPath: args.levelPath
-                        };
-                        if (args.streaming !== undefined) {
-                            mappedArgs.streaming = args.streaming;
-                        }
-                        break;
-                    case 'save':
-                        mappedName = 'save_level';
-                        mappedArgs = {
-                            levelName: args.levelName
-                        };
-                        if (args.savePath !== undefined) {
-                            mappedArgs.savePath = args.savePath;
-                        }
-                        break;
-                    case 'stream':
-                        mappedName = 'stream_level';
-                        mappedArgs = {
-                            levelName: args.levelName,
-                            shouldBeLoaded: args.shouldBeLoaded,
-                            shouldBeVisible: args.shouldBeVisible
-                        };
-                        break;
-                    case 'create_light':
-                        // Validate light type
-                        if (!args.lightType) {
-                            throw new Error('Missing required parameter: lightType');
-                        }
-                        const validLightTypes = ['directional', 'point', 'spot', 'rect', 'sky'];
-                        const normalizedLightType = String(args.lightType).toLowerCase();
-                        if (!validLightTypes.includes(normalizedLightType)) {
-                            throw new Error(`Invalid lightType: '${args.lightType}'. Valid types are: ${validLightTypes.join(', ')}`);
-                        }
-                        // Validate name
-                        if (!args.name) {
-                            throw new Error('Missing required parameter: name');
-                        }
-                        if (typeof args.name !== 'string' || args.name.trim() === '') {
-                            throw new Error('Invalid name: must be a non-empty string');
-                        }
-                        // Validate intensity if provided
-                        if (args.intensity !== undefined) {
-                            if (typeof args.intensity !== 'number' || !isFinite(args.intensity)) {
-                                throw new Error(`Invalid intensity: must be a finite number, got ${typeof args.intensity}`);
+                switch (requireAction(args)) {
+                    case 'load': {
+                        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)'
                             }
-                            if (args.intensity < 0) {
-                                throw new Error('Invalid intensity: must be non-negative');
+                        });
+                        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': {
+                        const res = await tools.levelTools.saveLevel({ levelName: args.levelName, savePath: args.savePath });
+                        return cleanObject(res);
+                    }
+                    case 'stream': {
+                        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'
                             }
-                        }
-                        // Validate location if provided
-                        if (args.location !== undefined && args.location !== null) {
-                            if (!Array.isArray(args.location) && typeof args.location !== 'object') {
-                                throw new Error('Invalid location: must be an array [x,y,z] or object {x,y,z}');
+                        });
+                        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': {
+                        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'
                             }
-                        }
-                        mappedName = 'create_light';
-                        mappedArgs = {
-                            lightType: args.lightType,
-                            name: args.name,
-                            location: args.location,
-                            intensity: args.intensity
-                        };
-                        break;
-                    case 'build_lighting':
-                        mappedName = 'build_lighting';
-                        mappedArgs = {
-                            quality: args.quality
-                        };
-                        break;
-                    default:
-                        throw new Error(`Unknown level action: ${args.action}`);
-                }
-                break;
-            // 5. ANIMATION & PHYSICS
-            case 'animation_physics':
-                // Validate action exists
-                if (!args.action) {
-                    throw new Error('Missing required parameter: action');
-                }
-                switch (args.action) {
-                    case 'create_animation_bp':
-                        // Validate required parameters
-                        if (args.name === undefined || args.name === null) {
-                            throw new Error('Missing required parameter: name');
-                        }
-                        if (typeof args.name !== 'string') {
-                            throw new Error('Invalid name: must be a string');
-                        }
-                        if (args.name.trim() === '') {
-                            throw new Error('Invalid name: cannot be empty');
-                        }
-                        if (args.skeletonPath === undefined || args.skeletonPath === null) {
-                            throw new Error('Missing required parameter: skeletonPath');
-                        }
-                        if (typeof args.skeletonPath !== 'string') {
-                            throw new Error('Invalid skeletonPath: must be a string');
-                        }
-                        if (args.skeletonPath.trim() === '') {
-                            throw new Error('Invalid skeletonPath: cannot be empty');
-                        }
-                        // Optional savePath validation
-                        if (args.savePath !== undefined && args.savePath !== null) {
-                            if (typeof args.savePath !== 'string') {
-                                throw new Error('Invalid savePath: must be a string');
+                        });
+                        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];
                             }
-                        }
-                        mappedName = 'create_animation_blueprint';
-                        mappedArgs = {
-                            name: args.name,
-                            skeletonPath: args.skeletonPath,
-                            savePath: args.savePath
+                            if (value && typeof value === 'object') {
+                                return [Number(value.x) || 0, Number(value.y) || 0, Number(value.z) || 0];
+                            }
+                            return fallback;
                         };
-                        break;
-                    case 'play_montage':
-                        // Validate required parameters
-                        if (args.actorName === undefined || args.actorName === null) {
-                            throw new Error('Missing required parameter: actorName');
-                        }
-                        if (typeof args.actorName !== 'string') {
-                            throw new Error('Invalid actorName: must be a string');
-                        }
-                        if (args.actorName.trim() === '') {
-                            throw new Error('Invalid actorName: cannot be empty');
-                        }
-                        // Check for montagePath or animationPath
-                        const montagePath = args.montagePath || args.animationPath;
-                        if (montagePath === undefined || montagePath === null) {
-                            throw new Error('Missing required parameter: montagePath or animationPath');
-                        }
-                        if (typeof montagePath !== 'string') {
-                            throw new Error('Invalid montagePath: must be a string');
-                        }
-                        if (montagePath.trim() === '') {
-                            throw new Error('Invalid montagePath: cannot be empty');
-                        }
-                        // Optional playRate validation
-                        if (args.playRate !== undefined && args.playRate !== null) {
-                            if (typeof args.playRate !== 'number') {
-                                throw new Error('Invalid playRate: must be a number');
+                        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 (isNaN(args.playRate)) {
-                                throw new Error('Invalid playRate: cannot be NaN');
+                            if (value && typeof value === 'object') {
+                                return [Number(value.pitch) || 0, Number(value.yaw) || 0, Number(value.roll) || 0];
                             }
-                            if (!isFinite(args.playRate)) {
-                                throw new Error('Invalid playRate: must be finite');
+                            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];
                             }
-                        }
-                        mappedName = 'play_animation_montage';
-                        mappedArgs = {
-                            actorName: args.actorName,
-                            montagePath: montagePath,
-                            playRate: args.playRate
+                            if (value && typeof value === 'object') {
+                                return [Number(value.r) || 0, Number(value.g) || 0, Number(value.b) || 0];
+                            }
+                            return undefined;
                         };
-                        break;
-                    case 'setup_ragdoll':
-                        // Validate required parameters
-                        if (args.skeletonPath === undefined || args.skeletonPath === null) {
-                            throw new Error('Missing required parameter: skeletonPath');
-                        }
-                        if (typeof args.skeletonPath !== 'string') {
-                            throw new Error('Invalid skeletonPath: must be a string');
-                        }
-                        if (args.skeletonPath.trim() === '') {
-                            throw new Error('Invalid skeletonPath: cannot be empty');
-                        }
-                        if (args.physicsAssetName === undefined || args.physicsAssetName === null) {
-                            throw new Error('Missing required parameter: physicsAssetName');
-                        }
-                        if (typeof args.physicsAssetName !== 'string') {
-                            throw new Error('Invalid physicsAssetName: must be a string');
-                        }
-                        if (args.physicsAssetName.trim() === '') {
-                            throw new Error('Invalid physicsAssetName: cannot be empty');
-                        }
-                        // Optional blendWeight validation
-                        if (args.blendWeight !== undefined && args.blendWeight !== null) {
-                            if (typeof args.blendWeight !== 'number') {
-                                throw new Error('Invalid blendWeight: must be a number');
+                        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');
                             }
-                            if (isNaN(args.blendWeight)) {
-                                throw new Error('Invalid blendWeight: cannot be NaN');
+                            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 });
+                        return cleanObject(res);
+                    }
+                    default:
+                        throw new Error(`Unknown level action: ${args.action}`);
+                }
+            // 5. ANIMATION & PHYSICS
+            case 'animation_physics':
+                switch (requireAction(args)) {
+                    case 'create_animation_bp': {
+                        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'
                             }
-                            if (!isFinite(args.blendWeight)) {
-                                throw new Error('Invalid blendWeight: must be finite');
+                        });
+                        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': {
+                        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'
                             }
-                        }
-                        // Optional savePath validation
-                        if (args.savePath !== undefined && args.savePath !== null) {
-                            if (typeof args.savePath !== 'string') {
-                                throw new Error('Invalid savePath: must be a string');
+                        });
+                        const actorName = requireNonEmptyString(args.actorName, 'actorName', 'Invalid actorName');
+                        const montagePath = args.montagePath || args.animationPath;
+                        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': {
+                        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'
                             }
-                        }
-                        mappedName = 'setup_ragdoll';
-                        mappedArgs = {
-                            skeletonPath: args.skeletonPath,
-                            physicsAssetName: args.physicsAssetName,
-                            blendWeight: args.blendWeight,
-                            savePath: args.savePath
-                        };
-                        break;
+                        });
+                        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:
                         throw new Error(`Unknown animation/physics action: ${args.action}`);
                 }
-                break;
             // 6. EFFECTS SYSTEM
             case 'create_effect':
-                switch (args.action) {
-                    case 'particle':
-                        mappedName = 'create_particle_effect';
-                        mappedArgs = {
-                            effectType: args.effectType,
-                            name: args.name,
-                            location: args.location
-                        };
-                        break;
-                    case 'niagara':
-                        mappedName = 'spawn_niagara_system';
-                        mappedArgs = {
-                            systemPath: args.systemPath,
-                            location: args.location,
+                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': {
+                        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
-                        };
-                        break;
-                    case 'debug_shape':
-                        mappedName = 'draw_debug_shape';
-                        // Convert location object to array for position
-                        const pos = args.location || args.position;
-                        mappedArgs = {
-                            shape: args.shape,
-                            position: pos ? [pos.x || 0, pos.y || 0, pos.z || 0] : [0, 0, 0],
-                            size: args.size,
-                            color: args.color,
-                            duration: args.duration
-                        };
-                        break;
+                        });
+                        return cleanObject(res);
+                    }
+                    case 'debug_shape': {
+                        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];
+                        const duration = args.duration || 5;
+                        if (shape === 'line') {
+                            const end = args.end || { x: loc.x + size, y: loc.y, z: loc.z };
+                            return cleanObject(await tools.debugTools.drawDebugLine({ start: [loc.x, loc.y, loc.z], end: [end.x, end.y, end.z], color, duration }));
+                        }
+                        else if (shape === 'box') {
+                            const extent = [size, size, size];
+                            return cleanObject(await tools.debugTools.drawDebugBox({ center: [loc.x, loc.y, loc.z], extent, color, duration }));
+                        }
+                        else if (shape === 'sphere') {
+                            return cleanObject(await tools.debugTools.drawDebugSphere({ center: [loc.x, loc.y, loc.z], radius: size, color, duration }));
+                        }
+                        else if (shape === 'capsule') {
+                            return cleanObject(await tools.debugTools.drawDebugCapsule({ center: [loc.x, loc.y, loc.z], halfHeight: size, radius: Math.max(10, size / 3), color, duration }));
+                        }
+                        else if (shape === 'cone') {
+                            return cleanObject(await tools.debugTools.drawDebugCone({ origin: [loc.x, loc.y, loc.z], direction: [0, 0, 1], length: size, angleWidth: 0.5, angleHeight: 0.5, color, duration }));
+                        }
+                        else if (shape === 'arrow') {
+                            const end = args.end || { x: loc.x + size, y: loc.y, z: loc.z };
+                            return cleanObject(await tools.debugTools.drawDebugArrow({ start: [loc.x, loc.y, loc.z], end: [end.x, end.y, end.z], color, duration }));
+                        }
+                        else if (shape === 'point') {
+                            return cleanObject(await tools.debugTools.drawDebugPoint({ location: [loc.x, loc.y, loc.z], size, color, duration }));
+                        }
+                        else if (shape === 'text' || shape === 'string') {
+                            const text = args.text || 'Debug';
+                            return cleanObject(await tools.debugTools.drawDebugString({ location: [loc.x, loc.y, loc.z], text, color, duration }));
+                        }
+                        // Default fallback
+                        return cleanObject({ success: false, error: `Unsupported debug shape: ${originalShapeLabel}` });
+                    }
                     default:
                         throw new Error(`Unknown effect action: ${args.action}`);
                 }
-                break;
             // 7. BLUEPRINT MANAGER
             case 'manage_blueprint':
-                switch (args.action) {
-                    case 'create':
-                        mappedName = 'create_blueprint';
-                        mappedArgs = {
+                switch (requireAction(args)) {
+                    case 'create': {
+                        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,
-                            savePath: args.savePath
-                        };
-                        break;
-                    case 'add_component':
-                        mappedName = 'add_blueprint_component';
-                        mappedArgs = {
-                            blueprintName: args.name,
-                            componentType: args.componentType,
-                            componentName: args.componentName
-                        };
-                        break;
+                            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);
+                    }
                     default:
                         throw new Error(`Unknown blueprint action: ${args.action}`);
                 }
-                break;
             // 8. ENVIRONMENT BUILDER
             case 'build_environment':
-                switch (args.action) {
-                    case 'create_landscape':
-                        mappedName = 'create_landscape';
-                        mappedArgs = {
-                            name: args.name,
+                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);
+                    }
+                    case 'sculpt': {
+                        const res = await tools.landscapeTools.sculptLandscape({ landscapeName: args.name, tool: args.tool, brushSize: args.brushSize, strength: args.strength });
+                        return cleanObject(res);
+                    }
+                    case 'add_foliage': {
+                        const res = await tools.foliageTools.addFoliageType({ name: args.name, meshPath: args.meshPath, density: args.density });
+                        return cleanObject(res);
+                    }
+                    case 'paint_foliage': {
+                        const pos = args.position ? [args.position.x || 0, args.position.y || 0, args.position.z || 0] : [0, 0, 0];
+                        const res = await tools.foliageTools.paintFoliage({ foliageType: args.foliageType, position: pos, brushSize: args.brushSize, paintDensity: args.paintDensity, eraseMode: args.eraseMode });
+                        return cleanObject(res);
+                    }
+                    case 'create_procedural_terrain': {
+                        const loc = args.location ? [args.location.x || 0, args.location.y || 0, args.location.z || 0] : [0, 0, 0];
+                        const res = await tools.buildEnvAdvanced.createProceduralTerrain({
+                            name: args.name || 'ProceduralTerrain',
+                            location: loc,
                             sizeX: args.sizeX,
                             sizeY: args.sizeY,
-                            materialPath: args.materialPath
-                        };
-                        break;
-                    case 'sculpt':
-                        mappedName = 'sculpt_landscape';
-                        mappedArgs = {
-                            landscapeName: args.name,
-                            tool: args.tool,
-                            brushSize: args.brushSize,
-                            strength: args.strength
+                            subdivisions: args.subdivisions,
+                            heightFunction: args.heightFunction,
+                            material: args.materialPath
+                        });
+                        return cleanObject(res);
+                    }
+                    case 'create_procedural_foliage': {
+                        if (!args.bounds || !args.bounds.location || !args.bounds.size)
+                            throw new Error('bounds.location and bounds.size are required');
+                        const bounds = {
+                            location: [args.bounds.location.x || 0, args.bounds.location.y || 0, args.bounds.location.z || 0],
+                            size: [args.bounds.size.x || 1000, args.bounds.size.y || 1000, args.bounds.size.z || 100]
                         };
-                        break;
-                    case 'add_foliage':
-                        // Validate foliage creation parameters to avoid bad console commands / engine warnings
-                        if (args.name === undefined || args.name === null || typeof args.name !== 'string' || args.name.trim() === '' || String(args.name).toLowerCase() === 'undefined' || String(args.name).toLowerCase() === 'any') {
-                            throw new Error(`Invalid foliage name: '${args.name}'`);
-                        }
-                        if (args.meshPath === undefined || args.meshPath === null || typeof args.meshPath !== 'string' || args.meshPath.trim() === '' || String(args.meshPath).toLowerCase() === 'undefined') {
-                            throw new Error(`Invalid meshPath: '${args.meshPath}'`);
-                        }
-                        if (args.density !== undefined) {
-                            if (typeof args.density !== 'number' || !isFinite(args.density) || args.density < 0) {
-                                throw new Error(`Invalid density: '${args.density}' (must be non-negative finite number)`);
-                            }
-                        }
-                        mappedName = 'add_foliage_type';
-                        mappedArgs = {
-                            name: args.name,
+                        const res = await tools.buildEnvAdvanced.createProceduralFoliage({
+                            name: args.name || 'ProceduralFoliage',
+                            bounds,
+                            foliageTypes: args.foliageTypes || [],
+                            seed: args.seed
+                        });
+                        return cleanObject(res);
+                    }
+                    case 'add_foliage_instances': {
+                        if (!args.foliageType)
+                            throw new Error('foliageType is required');
+                        if (!Array.isArray(args.transforms))
+                            throw new Error('transforms array is required');
+                        const transforms = args.transforms.map(t => ({
+                            location: [t.location?.x || 0, t.location?.y || 0, t.location?.z || 0],
+                            rotation: t.rotation ? [t.rotation.pitch || 0, t.rotation.yaw || 0, t.rotation.roll || 0] : undefined,
+                            scale: t.scale ? [t.scale.x || 1, t.scale.y || 1, t.scale.z || 1] : undefined
+                        }));
+                        const res = await tools.buildEnvAdvanced.addFoliageInstances({ foliageType: args.foliageType, transforms });
+                        return cleanObject(res);
+                    }
+                    case 'create_landscape_grass_type': {
+                        const res = await tools.buildEnvAdvanced.createLandscapeGrassType({
+                            name: args.name || 'GrassType',
                             meshPath: args.meshPath,
-                            density: args.density
-                        };
-                        break;
-                    case 'paint_foliage':
-                        // Validate paint parameters
-                        if (args.foliageType === undefined || args.foliageType === null || typeof args.foliageType !== 'string' || args.foliageType.trim() === '' || String(args.foliageType).toLowerCase() === 'undefined' || String(args.foliageType).toLowerCase() === 'any') {
-                            throw new Error(`Invalid foliageType: '${args.foliageType}'`);
-                        }
-                        // Convert position object to array if needed
-                        let positionArray;
-                        if (args.position) {
-                            if (Array.isArray(args.position)) {
-                                positionArray = args.position;
-                            }
-                            else if (typeof args.position === 'object') {
-                                positionArray = [args.position.x || 0, args.position.y || 0, args.position.z || 0];
-                            }
-                            else {
-                                positionArray = [0, 0, 0];
-                            }
-                        }
-                        else {
-                            positionArray = [0, 0, 0];
-                        }
-                        // Validate numbers in position
-                        if (!Array.isArray(positionArray) || positionArray.length !== 3 || positionArray.some(v => typeof v !== 'number' || !isFinite(v))) {
-                            throw new Error(`Invalid position: '${JSON.stringify(args.position)}'`);
-                        }
-                        if (args.brushSize !== undefined) {
-                            if (typeof args.brushSize !== 'number' || !isFinite(args.brushSize) || args.brushSize < 0) {
-                                throw new Error(`Invalid brushSize: '${args.brushSize}' (must be non-negative finite number)`);
-                            }
-                        }
-                        mappedName = 'paint_foliage';
-                        mappedArgs = {
-                            foliageType: args.foliageType,
-                            position: positionArray,
-                            brushSize: args.brushSize
-                        };
-                        break;
+                            density: args.density,
+                            minScale: args.minScale,
+                            maxScale: args.maxScale
+                        });
+                        return cleanObject(res);
+                    }
                     default:
                         throw new Error(`Unknown environment action: ${args.action}`);
                 }
-                break;
             // 9. SYSTEM CONTROL
             case 'system_control':
-                // Validate args is not null/undefined
-                if (args === null || args === undefined) {
-                    throw new Error('Invalid arguments: null or undefined');
-                }
-                if (typeof args !== 'object') {
-                    throw new Error('Invalid arguments: must be an object');
-                }
-                // Validate action exists
-                if (!args.action) {
-                    throw new Error('Missing required parameter: action');
-                }
-                switch (args.action) {
-                    case 'profile':
-                        // Validate profile type
-                        const validProfileTypes = ['CPU', 'GPU', 'Memory', 'RenderThread', 'GameThread', 'All'];
-                        if (!args.profileType || !validProfileTypes.includes(args.profileType)) {
-                            throw new Error(`Invalid profileType: '${args.profileType}'. Valid types: ${validProfileTypes.join(', ')}`);
-                        }
-                        mappedName = 'start_profiling';
-                        mappedArgs = {
-                            type: args.profileType,
-                            duration: args.duration
-                        };
-                        break;
-                    case 'show_fps':
-                        // Validate enabled is boolean
-                        if (args.enabled !== undefined && typeof args.enabled !== 'boolean') {
-                            throw new Error(`Invalid enabled: must be boolean, got ${typeof args.enabled}`);
-                        }
-                        mappedName = 'show_fps';
-                        mappedArgs = {
-                            enabled: args.enabled,
-                            verbose: args.verbose
-                        };
-                        break;
-                    case 'set_quality':
-                        // Validate category - normalize aliases and singular forms used by sg.*Quality
-                        const validCategories = ['ViewDistance', 'AntiAliasing', 'PostProcessing', 'PostProcess',
-                            'Shadows', 'Shadow', 'GlobalIllumination', 'Reflections', 'Reflection', 'Textures', 'Texture',
-                            'Effects', 'Foliage', 'Shading'];
-                        if (!args.category || !validCategories.includes(args.category)) {
-                            throw new Error(`Invalid category: '${args.category}'. Valid categories: ${validCategories.join(', ')}`);
-                        }
-                        // Validate level
-                        if (args.level === undefined || args.level === null) {
-                            throw new Error('Missing required parameter: level');
-                        }
-                        if (typeof args.level !== 'number' || !Number.isInteger(args.level) || args.level < 0 || args.level > 4) {
-                            throw new Error(`Invalid level: must be integer 0-4, got ${args.level}`);
-                        }
-                        // Normalize category to sg.<Base>Quality base (singular where needed)
-                        const map = {
-                            ViewDistance: 'ViewDistance',
-                            AntiAliasing: 'AntiAliasing',
-                            PostProcessing: 'PostProcess',
-                            PostProcess: 'PostProcess',
-                            Shadows: 'Shadow',
-                            Shadow: 'Shadow',
-                            GlobalIllumination: 'GlobalIllumination',
-                            Reflections: 'Reflection',
-                            Reflection: 'Reflection',
-                            Textures: 'Texture',
-                            Texture: 'Texture',
-                            Effects: 'Effects',
-                            Foliage: 'Foliage',
-                            Shading: 'Shading',
-                        };
-                        const categoryName = map[String(args.category)] || args.category;
-                        mappedName = 'set_scalability';
-                        mappedArgs = {
-                            category: categoryName,
-                            level: args.level
-                        };
-                        break;
-                    case 'play_sound':
-                        // Validate sound path
-                        if (!args.soundPath || typeof args.soundPath !== 'string') {
-                            throw new Error('Invalid soundPath: must be a non-empty string');
-                        }
-                        // Validate volume if provided
-                        if (args.volume !== undefined) {
-                            if (typeof args.volume !== 'number' || args.volume < 0 || args.volume > 1) {
-                                throw new Error(`Invalid volume: must be 0-1, got ${args.volume}`);
+                switch (requireAction(args)) {
+                    case 'profile': {
+                        const res = await tools.performanceTools.startProfiling({ type: args.profileType, duration: args.duration });
+                        return cleanObject(res);
+                    }
+                    case 'show_fps': {
+                        const res = await tools.performanceTools.showFPS({ enabled: !!args.enabled, verbose: !!args.verbose });
+                        return cleanObject(res);
+                    }
+                    case 'set_quality': {
+                        const res = await tools.performanceTools.setScalability({ category: args.category, level: args.level });
+                        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'
                             }
-                        }
-                        mappedName = 'play_sound';
-                        mappedArgs = {
-                            soundPath: args.soundPath,
-                            location: args.location,
-                            volume: args.volume,
-                            is3D: args.is3D
-                        };
-                        break;
-                    case 'create_widget':
-                        // Validate widget name
-                        if (!args.widgetName || typeof args.widgetName !== 'string' || args.widgetName.trim() === '') {
-                            throw new Error('Invalid widgetName: must be a non-empty string');
-                        }
-                        mappedName = 'create_widget';
-                        mappedArgs = {
-                            name: args.widgetName,
-                            type: args.widgetType,
-                            savePath: args.savePath
-                        };
-                        break;
-                    case 'show_widget':
-                        // Validate widget name
-                        if (!args.widgetName || typeof args.widgetName !== 'string') {
-                            throw new Error('Invalid widgetName: must be a non-empty string');
-                        }
-                        // Validate visible is boolean (default to true if not provided)
-                        const isVisible = args.visible !== undefined ? args.visible : true;
-                        if (typeof isVisible !== 'boolean') {
-                            throw new Error(`Invalid visible: must be boolean, got ${typeof isVisible}`);
-                        }
-                        mappedName = 'show_widget';
-                        mappedArgs = {
-                            widgetName: args.widgetName,
-                            visible: isVisible
-                        };
-                        break;
-                    case 'screenshot':
-                        mappedName = 'take_screenshot';
-                        mappedArgs = { resolution: args.resolution };
-                        break;
-                    case 'engine_start':
-                        mappedName = 'launch_editor';
-                        mappedArgs = { editorExe: args.editorExe, projectPath: args.projectPath };
-                        break;
-                    case 'engine_quit':
-                        mappedName = 'quit_editor';
-                        mappedArgs = {};
-                        break;
+                        });
+                        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, location: loc, volume: args.volume, pitch: args.pitch, startTime: args.startTime });
+                            return cleanObject(res);
+                        }
+                        const res = await tools.audioTools.playSound2D({ soundPath, volume: args.volume, pitch: args.pitch, startTime: args.startTime });
+                        return cleanObject(res);
+                    }
+                    case 'create_widget': {
+                        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': {
+                        const res = await tools.uiTools.setWidgetVisibility({ widgetName: args.widgetName, visible: args.visible !== false });
+                        return cleanObject(res);
+                    }
+                    case 'screenshot': {
+                        const res = await tools.visualTools.takeScreenshot({ resolution: args.resolution });
+                        return cleanObject(res);
+                    }
+                    case 'engine_start': {
+                        const res = await tools.engineTools.launchEditor({ editorExe: args.editorExe, projectPath: args.projectPath });
+                        return cleanObject(res);
+                    }
+                    case 'engine_quit': {
+                        const res = await tools.engineTools.quitEditor();
+                        return cleanObject(res);
+                    }
                     default:
                         throw new Error(`Unknown system action: ${args.action}`);
                 }
-                break;
             // 10. CONSOLE COMMAND - handle validation here
             case 'console_command':
-                // Handle empty/invalid commands gracefully
-                if (args.command === undefined || args.command === null || args.command === '' || typeof args.command !== 'string') {
-                    return {
-                        content: [{
-                                type: 'text',
-                                text: 'Empty command ignored'
-                            }],
-                        isError: false,
-                        success: true,
-                        message: 'Empty command'
-                    };
+                if (!args.command || typeof args.command !== 'string' || args.command.trim() === '') {
+                    return { success: true, message: 'Empty command' };
+                }
+                // Basic safety filter
+                const cmd = String(args.command).trim();
+                const blocked = [/\bquit\b/i, /\bexit\b/i, /debugcrash/i];
+                if (blocked.some(r => r.test(cmd))) {
+                    return { success: false, error: 'Command blocked for safety' };
                 }
-                const cmdTrimmed = args.command.trim();
-                if (cmdTrimmed.length === 0) {
-                    return {
-                        content: [{
-                                type: 'text',
-                                text: 'Empty command ignored'
-                            }],
-                        isError: false,
-                        success: true,
-                        message: 'Empty command'
-                    };
+                try {
+                    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) });
                 }
-                mappedName = 'console_command';
-                mappedArgs = args;
-                break;
             // 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':
@@ -838,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';
                         }
@@ -935,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':
@@ -993,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
@@ -1001,37 +998,23 @@ 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) {
-                    case 'inspect_object':
-                        mappedName = 'inspect_object';
-                        mappedArgs = { objectPath: args.objectPath };
-                        break;
-                    case 'set_property':
-                        mappedName = 'inspect_set_property';
-                        mappedArgs = { objectPath: args.objectPath, propertyName: args.propertyName, value: args.value };
-                        break;
+                const inspectAction = requireAction(args);
+                switch (inspectAction) {
+                    case 'inspect_object': {
+                        const res = await tools.introspectionTools.inspectObject({ objectPath: args.objectPath, detailed: args.detailed });
+                        return cleanObject(res);
+                    }
+                    case 'set_property': {
+                        const res = await tools.introspectionTools.setProperty({ objectPath: args.objectPath, propertyName: args.propertyName, value: args.value });
+                        return cleanObject(res);
+                    }
                     default:
-                        throw new Error(`Unknown inspect action: ${args.action}`);
+                        throw new Error(`Unknown inspect action: ${inspectAction}`);
                 }
-                break;
             default:
                 throw new Error(`Unknown consolidated tool: ${name}`);
         }
-        // Call the original handler with mapped name and args with timeout
-        const TOOL_TIMEOUT = 15000; // 15 seconds timeout for tool execution
-        const toolPromise = handleToolCall(mappedName, mappedArgs, tools);
-        const timeoutPromise = new Promise((_, reject) => {
-            setTimeout(() => {
-                reject(new Error(`Tool execution timeout after ${TOOL_TIMEOUT}ms`));
-            }, TOOL_TIMEOUT);
-        });
-        const result = await Promise.race([toolPromise, timeoutPromise]);
-        const duration = Date.now() - startTime;
-        console.log(`[ConsolidatedToolHandler] Completed execution of ${name} in ${duration}ms`);
-        // Clean the result to prevent circular reference errors
-        return cleanObject(result);
+        // All cases return (or throw) above; this is a type guard for exhaustiveness.
     }
     catch (err) {
         const duration = Date.now() - startTime;