unreal-engine-mcp-server 0.4.7 → 0.5.0

package/dist/tools/handlers/inspect-handlers.js

@@ -0,0 +1,383 @@
+import { cleanObject } from '../../utils/safe-json.js';
+import { executeAutomationRequest } from './common-handlers.js';
+import { normalizeArgs, resolveObjectPath } from './argument-helper.js';
+async function resolveComponentObjectPathFromArgs(args, tools) {
+    const componentName = typeof args.componentName === 'string' ? args.componentName.trim() : '';
+    const componentPath = typeof args.componentPath === 'string' ? args.componentPath.trim() : '';
+    const direct = componentPath || ((componentName.includes(':') || componentName.includes('.')) &&
+        (componentName.startsWith('/Game') || componentName.startsWith('/Script') || componentName.startsWith('/Engine'))
+        ? componentName
+        : '');
+    if (direct)
+        return direct;
+    const actorName = await resolveObjectPath(args, tools, { pathKeys: [], actorKeys: ['actorName', 'name', 'objectPath'] });
+    if (!actorName) {
+        throw new Error('Invalid actorName: required to resolve componentName');
+    }
+    if (!componentName) {
+        throw new Error('Invalid componentName: must be a non-empty string');
+    }
+    const compsRes = await executeAutomationRequest(tools, 'inspect', {
+        action: 'get_components',
+        actorName: actorName,
+        objectPath: actorName
+    }, 'Failed to get components');
+    let components = [];
+    if (compsRes.success) {
+        components = Array.isArray(compsRes?.components) ? compsRes.components : [];
+    }
+    const needle = componentName.toLowerCase();
+    if (components.length > 0) {
+        let match = components.find((c) => String(c?.name || '').toLowerCase() === needle)
+            ?? components.find((c) => String(c?.path || '').toLowerCase() === needle)
+            ?? components.find((c) => String(c?.path || '').toLowerCase().endsWith(`:${needle}`))
+            ?? components.find((c) => String(c?.path || '').toLowerCase().endsWith(`.${needle}`));
+        if (!match) {
+            match = components.find((c) => String(c?.name || '').toLowerCase().startsWith(needle));
+        }
+        if (match) {
+            if (typeof match.path === 'string' && match.path.trim().length > 0) {
+                return match.path.trim();
+            }
+            if (typeof match.name === 'string' && match.name.trim().length > 0) {
+                return `${actorName}.${match.name}`;
+            }
+        }
+    }
+    return `${actorName}.${componentName}`;
+}
+export async function handleInspectTools(action, args, tools) {
+    switch (action) {
+        case 'inspect_object': {
+            const objectPath = await resolveObjectPath(args, tools);
+            if (!objectPath) {
+                throw new Error('Invalid objectPath: must be a non-empty string');
+            }
+            const payload = {
+                ...args,
+                objectPath,
+                action: 'inspect_object',
+                detailed: true
+            };
+            const res = await executeAutomationRequest(tools, 'inspect', payload, 'Automation bridge not available for inspect operations');
+            if (res && res.success === false) {
+                const errorCode = String(res.error || '').toUpperCase();
+                const msg = String(res.message || '');
+                if (errorCode === 'OBJECT_NOT_FOUND' || msg.toLowerCase().includes('object not found')) {
+                    return cleanObject({
+                        success: false,
+                        handled: true,
+                        notFound: true,
+                        error: res.error,
+                        message: res.message || 'Object not found'
+                    });
+                }
+            }
+            return cleanObject(res);
+        }
+        case 'get_property': {
+            const objectPath = await resolveObjectPath(args, tools);
+            const propertyName = normalizeArgs(args, [{ key: 'propertyName', aliases: ['propertyPath'], required: true }]).propertyName;
+            if (!objectPath) {
+                throw new Error('Invalid objectPath: must be a non-empty string');
+            }
+            const res = await tools.introspectionTools.getProperty({
+                objectPath,
+                propertyName
+            });
+            if (!res.success && (res.error === 'PROPERTY_NOT_FOUND' || String(res.error).includes('not found'))) {
+                const actorName = await resolveObjectPath(args, tools, { pathKeys: [], actorKeys: ['actorName', 'name', 'objectPath'] });
+                if (actorName) {
+                    const triedPaths = [];
+                    try {
+                        const rootRes = await tools.introspectionTools.getProperty({
+                            objectPath: actorName,
+                            propertyName: 'RootComponent'
+                        });
+                        const rootPath = typeof rootRes.value === 'string' ? rootRes.value : (rootRes.value?.path || rootRes.value?.objectPath);
+                        if (rootRes.success && rootPath && typeof rootPath === 'string' && rootPath.length > 0 && rootPath !== 'None') {
+                            triedPaths.push(rootPath);
+                            const propRes = await tools.introspectionTools.getProperty({
+                                objectPath: rootPath,
+                                propertyName
+                            });
+                            if (propRes.success) {
+                                return cleanObject({
+                                    ...propRes,
+                                    message: `Resolved property '${propertyName}' on RootComponent (Smart Lookup)`,
+                                    foundOnComponent: 'RootComponent'
+                                });
+                            }
+                        }
+                    }
+                    catch (_e) { }
+                    try {
+                        const shortName = String(args.objectPath || '').trim();
+                        const compsRes = await tools.actorTools.getComponents(shortName);
+                        if (compsRes.success && (Array.isArray(compsRes.components) || Array.isArray(compsRes))) {
+                            const list = Array.isArray(compsRes.components) ? compsRes.components : (Array.isArray(compsRes) ? compsRes : []);
+                            const triedPaths = [];
+                            for (const comp of list) {
+                                const compName = comp.name;
+                                const compPath = comp.path || (compName ? `${actorName}.${compName}` : undefined);
+                                if (!compPath)
+                                    continue;
+                                triedPaths.push(compPath);
+                                const compRes = await tools.introspectionTools.getProperty({
+                                    objectPath: compPath,
+                                    propertyName
+                                });
+                                if (compRes.success) {
+                                    return cleanObject({
+                                        ...compRes,
+                                        message: `Resolved property '${propertyName}' on component '${comp.name}' (Smart Lookup)`,
+                                        foundOnComponent: comp.name
+                                    });
+                                }
+                            }
+                            return cleanObject({
+                                ...res,
+                                message: res.message + ` (Smart Lookup failed. Tried: ${triedPaths.length} paths. First: ${triedPaths[0]}. Components: ${list.map((c) => c.name).join(',')})`,
+                                smartLookupTriedPaths: triedPaths
+                            });
+                        }
+                        else {
+                            return cleanObject({
+                                ...res,
+                                message: res.message + ' (Smart Lookup failed: get_components returned ' + (compsRes.success ? 'success but no list' : 'failure: ' + compsRes.error) + ' | Name: ' + shortName + ' Path: ' + actorName + ')',
+                                smartLookupGetComponentsError: compsRes
+                            });
+                        }
+                    }
+                    catch (_e) {
+                        return cleanObject({
+                            ...res,
+                            message: res.message + ' (Smart Lookup exception: ' + _e.message + ')',
+                            error: _e
+                        });
+                    }
+                }
+            }
+            return cleanObject(res);
+        }
+        case 'set_property': {
+            const objectPath = await resolveObjectPath(args, tools);
+            const params = normalizeArgs(args, [
+                { key: 'propertyName', aliases: ['propertyPath'], required: true },
+                { key: 'value' }
+            ]);
+            if (!objectPath) {
+                throw new Error('Invalid objectPath: must be a non-empty string');
+            }
+            const res = await tools.introspectionTools.setProperty({
+                objectPath,
+                propertyName: params.propertyName,
+                value: params.value
+            });
+            if (res && res.success === false) {
+                const errorCode = String(res.error || '').toUpperCase();
+                if (errorCode === 'PROPERTY_NOT_FOUND') {
+                    return cleanObject({
+                        ...res,
+                        error: 'UNKNOWN_PROPERTY'
+                    });
+                }
+            }
+            return cleanObject(res);
+        }
+        case 'get_components': {
+            const actorName = await resolveObjectPath(args, tools, { pathKeys: [], actorKeys: ['actorName', 'name', 'objectPath'] });
+            if (!actorName) {
+                throw new Error('Invalid actorName');
+            }
+            const res = await executeAutomationRequest(tools, 'inspect', {
+                action: 'get_components',
+                actorName: actorName,
+                objectPath: actorName
+            }, 'Failed to get components');
+            return cleanObject(res);
+        }
+        case 'get_component_property': {
+            const componentObjectPath = await resolveComponentObjectPathFromArgs(args, tools);
+            const params = normalizeArgs(args, [
+                { key: 'propertyName', aliases: ['propertyPath'], required: true }
+            ]);
+            const res = await tools.introspectionTools.getProperty({
+                objectPath: componentObjectPath,
+                propertyName: params.propertyName
+            });
+            return cleanObject(res);
+        }
+        case 'set_component_property': {
+            const componentObjectPath = await resolveComponentObjectPathFromArgs(args, tools);
+            const params = normalizeArgs(args, [
+                { key: 'propertyName', aliases: ['propertyPath'], required: true },
+                { key: 'value' }
+            ]);
+            const res = await tools.introspectionTools.setProperty({
+                objectPath: componentObjectPath,
+                propertyName: params.propertyName,
+                value: params.value
+            });
+            return cleanObject(res);
+        }
+        case 'get_metadata': {
+            const actorName = await resolveObjectPath(args, tools);
+            if (!actorName)
+                throw new Error('Invalid actorName');
+            return cleanObject(await tools.actorTools.getMetadata(actorName));
+        }
+        case 'add_tag': {
+            const actorName = await resolveObjectPath(args, tools);
+            const params = normalizeArgs(args, [
+                { key: 'tag', required: true }
+            ]);
+            if (!actorName)
+                throw new Error('Invalid actorName');
+            return cleanObject(await tools.actorTools.addTag({
+                actorName,
+                tag: params.tag
+            }));
+        }
+        case 'find_by_tag':
+            const params = normalizeArgs(args, [{ key: 'tag' }]);
+            return cleanObject(await tools.actorTools.findByTag({
+                tag: params.tag
+            }));
+        case 'create_snapshot': {
+            const actorName = await resolveObjectPath(args, tools);
+            if (!actorName)
+                throw new Error('actorName is required for create_snapshot');
+            return cleanObject(await tools.actorTools.createSnapshot({
+                actorName,
+                snapshotName: args.snapshotName
+            }));
+        }
+        case 'restore_snapshot': {
+            const actorName = await resolveObjectPath(args, tools);
+            if (!actorName)
+                throw new Error('actorName is required for restore_snapshot');
+            return cleanObject(await tools.actorTools.restoreSnapshot({
+                actorName,
+                snapshotName: args.snapshotName
+            }));
+        }
+        case 'export': {
+            const actorName = await resolveObjectPath(args, tools);
+            if (!actorName)
+                throw new Error('actorName may be required for export depending on context (exporting actor requires it)');
+            const params = normalizeArgs(args, [
+                { key: 'destinationPath', aliases: ['outputPath'] }
+            ]);
+            return cleanObject(await tools.actorTools.exportActor({
+                actorName: actorName || '',
+                destinationPath: params.destinationPath
+            }));
+        }
+        case 'delete_object': {
+            const actorName = await resolveObjectPath(args, tools);
+            try {
+                if (!actorName)
+                    throw new Error('actorName is required for delete_object');
+                const res = await tools.actorTools.delete({
+                    actorName
+                });
+                return cleanObject(res);
+            }
+            catch (err) {
+                const msg = String(err?.message || err || '');
+                const lower = msg.toLowerCase();
+                if (lower.includes('actor not found')) {
+                    return cleanObject({
+                        success: false,
+                        error: 'NOT_FOUND',
+                        handled: true,
+                        message: msg,
+                        deleted: actorName,
+                        notFound: true
+                    });
+                }
+                throw err;
+            }
+        }
+        case 'list_objects':
+            return cleanObject(await tools.actorTools.listActors(args));
+        case 'find_by_class': {
+            const params = normalizeArgs(args, [
+                { key: 'className', aliases: ['classPath'], required: true }
+            ]);
+            const res = await tools.introspectionTools.findObjectsByClass(params.className);
+            if (!res || res.success === false) {
+                return cleanObject({
+                    success: false,
+                    error: res?.error || 'OPERATION_FAILED',
+                    message: res?.message || 'find_by_class failed',
+                    className: params.className,
+                    objects: [],
+                    count: 0
+                });
+            }
+            return cleanObject(res);
+        }
+        case 'get_bounding_box': {
+            const actorName = await resolveObjectPath(args, tools);
+            try {
+                if (!actorName)
+                    throw new Error('actorName is required for get_bounding_box');
+                const res = await tools.actorTools.getBoundingBox(actorName);
+                return cleanObject(res);
+            }
+            catch (err) {
+                const msg = String(err?.message || err || '');
+                const lower = msg.toLowerCase();
+                if (lower.includes('actor not found')) {
+                    return cleanObject({
+                        success: false,
+                        error: 'NOT_FOUND',
+                        handled: true,
+                        message: msg,
+                        actorName,
+                        notFound: true
+                    });
+                }
+                throw err;
+            }
+        }
+        case 'inspect_class': {
+            const params = normalizeArgs(args, [
+                { key: 'className', aliases: ['classPath'], required: true }
+            ]);
+            let className = params.className;
+            if (className && !className.includes('/') && !className.includes('.')) {
+                if (className === 'Landscape') {
+                    className = '/Script/Landscape.Landscape';
+                }
+                else if (['Actor', 'Pawn', 'Character', 'StaticMeshActor'].includes(className)) {
+                    className = `/Script/Engine.${className}`;
+                }
+            }
+            const res = await tools.introspectionTools.getCDO(className);
+            if (!res || res.success === false) {
+                if (args.className && !args.className.includes('/') && !className.startsWith('/Script/')) {
+                    const retryName = `/Script/Engine.${args.className}`;
+                    const resRetry = await tools.introspectionTools.getCDO(retryName);
+                    if (resRetry && resRetry.success) {
+                        return cleanObject(resRetry);
+                    }
+                }
+                return cleanObject({
+                    success: false,
+                    error: res?.error || 'OPERATION_FAILED',
+                    message: res?.message || `inspect_class failed for '${className}'`,
+                    className,
+                    cdo: res?.cdo ?? null
+                });
+            }
+            return cleanObject(res);
+        }
+        default:
+            const res = await executeAutomationRequest(tools, 'inspect', args, 'Automation bridge not available for inspect operations');
+            return cleanObject(res);
+    }
+}
+//# sourceMappingURL=inspect-handlers.js.map

package/dist/tools/handlers/level-handlers.d.ts

@@ -0,0 +1,3 @@
+import { ITools } from '../../types/tool-interfaces.js';
+export declare function handleLevelTools(action: string, args: any, tools: ITools): Promise<any>;
+//# sourceMappingURL=level-handlers.d.ts.map

package/dist/tools/handlers/level-handlers.js

@@ -0,0 +1,237 @@
+import { cleanObject } from '../../utils/safe-json.js';
+import { executeAutomationRequest, requireNonEmptyString } from './common-handlers.js';
+export async function handleLevelTools(action, args, tools) {
+    switch (action) {
+        case 'load':
+        case 'load_level': {
+            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 targetPath = args.levelPath || args.savePath;
+            if (targetPath) {
+                const res = await tools.levelTools.saveLevelAs({ targetPath });
+                return cleanObject(res);
+            }
+            const res = await tools.levelTools.saveLevel({ levelName: args.levelName });
+            return cleanObject(res);
+        }
+        case 'save_as':
+        case 'save_level_as': {
+            const targetPath = args.savePath || args.destinationPath || args.levelPath;
+            if (!targetPath) {
+                return {
+                    success: false,
+                    error: 'INVALID_ARGUMENT',
+                    message: 'savePath is required for save_as action',
+                    action
+                };
+            }
+            const res = await tools.levelTools.saveLevelAs({ targetPath });
+            return cleanObject(res);
+        }
+        case 'create_level': {
+            const levelName = requireNonEmptyString(args.levelName || (args.levelPath ? args.levelPath.split('/').pop() : ''), 'levelName', 'Missing required parameter: levelName');
+            const res = await tools.levelTools.createLevel({ levelName, savePath: args.savePath || args.levelPath });
+            return cleanObject(res);
+        }
+        case 'add_sublevel': {
+            const subLevelPath = requireNonEmptyString(args.subLevelPath || args.levelPath, 'subLevelPath', 'Missing required parameter: subLevelPath');
+            const res = await tools.levelTools.addSubLevel({
+                subLevelPath,
+                parentLevel: args.parentLevel || args.parentPath,
+                streamingMethod: args.streamingMethod
+            });
+            return cleanObject(res);
+        }
+        case 'stream': {
+            const levelPath = typeof args.levelPath === 'string' ? args.levelPath : undefined;
+            const levelName = typeof args.levelName === 'string' ? args.levelName : undefined;
+            if (!levelPath && !levelName) {
+                return cleanObject({
+                    success: false,
+                    error: 'INVALID_ARGUMENT',
+                    message: 'Missing required parameter: levelPath (or levelName)',
+                    action
+                });
+            }
+            if (typeof args.shouldBeLoaded !== 'boolean') {
+                return cleanObject({
+                    success: false,
+                    error: 'INVALID_ARGUMENT',
+                    message: 'Missing required parameter: shouldBeLoaded (boolean)',
+                    action,
+                    levelPath,
+                    levelName
+                });
+            }
+            const res = await tools.levelTools.streamLevel({
+                levelPath,
+                levelName,
+                shouldBeLoaded: args.shouldBeLoaded,
+                shouldBeVisible: args.shouldBeVisible
+            });
+            return cleanObject(res);
+        }
+        case 'create_light': {
+            const res = await executeAutomationRequest(tools, 'manage_level', args);
+            return cleanObject(res);
+        }
+        case 'spawn_light': {
+            const lightClassMap = {
+                'Point': '/Script/Engine.PointLight',
+                'Directional': '/Script/Engine.DirectionalLight',
+                'Spot': '/Script/Engine.SpotLight',
+                'Sky': '/Script/Engine.SkyLight',
+                'Rect': '/Script/Engine.RectLight'
+            };
+            const lightType = args.lightType || 'Point';
+            const classPath = lightClassMap[lightType] || '/Script/Engine.PointLight';
+            try {
+                const res = await tools.actorTools.spawn({
+                    classPath,
+                    actorName: args.name,
+                    location: args.location,
+                    rotation: args.rotation
+                });
+                return { ...cleanObject(res), action: 'spawn_light' };
+            }
+            catch (_e) {
+                return await executeAutomationRequest(tools, 'manage_level', args);
+            }
+        }
+        case 'build_lighting': {
+            return cleanObject(await tools.lightingTools.buildLighting({
+                quality: args.quality || 'Preview',
+                buildOnlySelected: false,
+                buildReflectionCaptures: false
+            }));
+        }
+        case 'export_level': {
+            const res = await tools.levelTools.exportLevel({
+                levelPath: args.levelPath,
+                exportPath: args.exportPath || args.destinationPath,
+                timeoutMs: typeof args.timeoutMs === 'number' ? args.timeoutMs : undefined
+            });
+            return cleanObject(res);
+        }
+        case 'import_level': {
+            const res = await tools.levelTools.importLevel({
+                packagePath: args.packagePath || args.sourcePath,
+                destinationPath: args.destinationPath,
+                timeoutMs: typeof args.timeoutMs === 'number' ? args.timeoutMs : undefined
+            });
+            return cleanObject(res);
+        }
+        case 'list_levels': {
+            const res = await tools.levelTools.listLevels();
+            return cleanObject(res);
+        }
+        case 'get_summary': {
+            const res = await tools.levelTools.getLevelSummary(args.levelPath);
+            return cleanObject(res);
+        }
+        case 'delete': {
+            const levelPaths = Array.isArray(args.levelPaths) ? args.levelPaths : [args.levelPath];
+            const res = await tools.levelTools.deleteLevels({ levelPaths });
+            return cleanObject(res);
+        }
+        case 'set_metadata': {
+            const levelPath = requireNonEmptyString(args.levelPath, 'levelPath', 'Missing required parameter: levelPath');
+            const metadata = (args.metadata && typeof args.metadata === 'object') ? args.metadata : {};
+            const res = await executeAutomationRequest(tools, 'set_metadata', { assetPath: levelPath, metadata });
+            return cleanObject(res);
+        }
+        case 'load_cells': {
+            let origin = args.origin;
+            let extent = args.extent;
+            if (!origin && args.min && args.max) {
+                const min = args.min;
+                const max = args.max;
+                origin = [(min[0] + max[0]) / 2, (min[1] + max[1]) / 2, (min[2] + max[2]) / 2];
+                extent = [(max[0] - min[0]) / 2, (max[1] - min[1]) / 2, (max[2] - min[2]) / 2];
+            }
+            const payload = {
+                subAction: 'load_cells',
+                origin: origin,
+                extent: extent,
+                ...args
+            };
+            const res = await executeAutomationRequest(tools, 'manage_world_partition', payload);
+            return cleanObject(res);
+        }
+        case 'set_datalayer': {
+            const dataLayerName = args.dataLayerName || args.dataLayerLabel;
+            if (!dataLayerName || typeof dataLayerName !== 'string' || dataLayerName.trim().length === 0) {
+                return cleanObject({
+                    success: false,
+                    error: 'INVALID_ARGUMENT',
+                    message: 'Missing required parameter: dataLayerLabel (or dataLayerName)',
+                    action
+                });
+            }
+            if (!args.dataLayerState || typeof args.dataLayerState !== 'string') {
+                return cleanObject({
+                    success: false,
+                    error: 'INVALID_ARGUMENT',
+                    message: 'Missing required parameter: dataLayerState',
+                    action,
+                    dataLayerName
+                });
+            }
+            const res = await executeAutomationRequest(tools, 'manage_world_partition', {
+                subAction: 'set_datalayer',
+                actorPath: args.actorPath,
+                dataLayerName,
+                ...args
+            });
+            return cleanObject(res);
+        }
+        case 'cleanup_invalid_datalayers': {
+            const res = await executeAutomationRequest(tools, 'manage_world_partition', {
+                subAction: 'cleanup_invalid_datalayers'
+            }, 'World Partition support not available');
+            return cleanObject(res);
+        }
+        case 'validate_level': {
+            const levelPath = requireNonEmptyString(args.levelPath, 'levelPath', 'Missing required parameter: levelPath');
+            const automationBridge = tools.automationBridge;
+            if (!automationBridge || typeof automationBridge.sendAutomationRequest !== 'function' || !automationBridge.isConnected()) {
+                return cleanObject({
+                    success: false,
+                    error: 'BRIDGE_UNAVAILABLE',
+                    message: 'Automation bridge not available; cannot validate level asset',
+                    levelPath
+                });
+            }
+            try {
+                const resp = await automationBridge.sendAutomationRequest('execute_editor_function', {
+                    functionName: 'ASSET_EXISTS_SIMPLE',
+                    path: levelPath
+                });
+                const result = resp?.result ?? resp ?? {};
+                const exists = Boolean(result.exists);
+                return cleanObject({
+                    success: true,
+                    exists,
+                    levelPath: result.path ?? levelPath,
+                    classPath: result.class,
+                    error: exists ? undefined : 'NOT_FOUND',
+                    message: exists ? 'Level asset exists' : 'Level asset not found'
+                });
+            }
+            catch (err) {
+                return cleanObject({
+                    success: false,
+                    error: 'VALIDATION_FAILED',
+                    message: `Level validation failed: ${err instanceof Error ? err.message : String(err)}`,
+                    levelPath
+                });
+            }
+        }
+        default:
+            return await executeAutomationRequest(tools, 'manage_level', args);
+    }
+}
+//# sourceMappingURL=level-handlers.js.map

package/dist/tools/handlers/lighting-handlers.d.ts

@@ -0,0 +1,3 @@
+import { ITools } from '../../types/tool-interfaces.js';
+export declare function handleLightingTools(action: string, args: any, tools: ITools): Promise<any>;
+//# sourceMappingURL=lighting-handlers.d.ts.map