unreal-engine-mcp-server 0.4.6 → 0.5.0

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

@@ -0,0 +1,358 @@
+import { cleanObject } from '../../utils/safe-json.js';
+import { executeAutomationRequest } from './common-handlers.js';
+export async function handleBlueprintTools(action, args, tools) {
+    switch (action) {
+        case 'create': {
+            let name = args.name;
+            let savePath = args.savePath;
+            const pathArg = args.path || args.blueprintPath;
+            if (pathArg) {
+                const parts = pathArg.split('/');
+                const extractName = parts.pop();
+                if (!name) {
+                    name = extractName;
+                }
+                if (!savePath) {
+                    savePath = parts.join('/');
+                }
+            }
+            if (!savePath)
+                savePath = '/Game';
+            const res = await tools.blueprintTools.createBlueprint({
+                name: name,
+                blueprintType: args.blueprintType,
+                savePath: savePath,
+                parentClass: args.parentClass,
+                properties: args.properties,
+                timeoutMs: args.timeoutMs,
+                waitForCompletion: args.waitForCompletion,
+                waitForCompletionTimeoutMs: args.waitForCompletionTimeoutMs
+            });
+            return cleanObject(res);
+        }
+        case 'ensure_exists': {
+            const res = await tools.blueprintTools.waitForBlueprint(args.name || args.blueprintPath || args.path, args.timeoutMs);
+            return cleanObject(res);
+        }
+        case 'add_variable': {
+            const res = await tools.blueprintTools.addVariable({
+                blueprintName: args.name || args.blueprintPath || args.path,
+                variableName: args.variableName,
+                variableType: args.variableType,
+                defaultValue: args.defaultValue,
+                category: args.category,
+                isReplicated: args.isReplicated,
+                isPublic: args.isPublic,
+                variablePinType: args.variablePinType,
+                timeoutMs: args.timeoutMs,
+                waitForCompletion: args.waitForCompletion,
+                waitForCompletionTimeoutMs: args.waitForCompletionTimeoutMs
+            });
+            return cleanObject(res);
+        }
+        case 'set_variable_metadata': {
+            const res = await tools.blueprintTools.setVariableMetadata({
+                blueprintName: args.name || args.blueprintPath || args.path,
+                variableName: args.variableName,
+                metadata: args.metadata,
+                timeoutMs: args.timeoutMs
+            });
+            return cleanObject(res);
+        }
+        case 'remove_variable': {
+            const res = await tools.blueprintTools.removeVariable({
+                blueprintName: args.name || args.blueprintPath || args.path,
+                variableName: args.variableName,
+                timeoutMs: args.timeoutMs,
+                waitForCompletion: args.waitForCompletion,
+                waitForCompletionTimeoutMs: args.waitForCompletionTimeoutMs
+            });
+            return cleanObject(res);
+        }
+        case 'rename_variable': {
+            const res = await tools.blueprintTools.renameVariable({
+                blueprintName: args.name || args.blueprintPath || args.path,
+                oldName: args.oldName,
+                newName: args.newName,
+                timeoutMs: args.timeoutMs,
+                waitForCompletion: args.waitForCompletion,
+                waitForCompletionTimeoutMs: args.waitForCompletionTimeoutMs
+            });
+            return cleanObject(res);
+        }
+        case 'set_metadata': {
+            const assetPathRaw = typeof args.assetPath === 'string' ? args.assetPath.trim() : '';
+            const blueprintPathRaw = typeof args.blueprintPath === 'string' ? args.blueprintPath.trim() : '';
+            const nameRaw = typeof args.name === 'string' ? args.name.trim() : '';
+            const savePathRaw = typeof args.savePath === 'string' ? args.savePath.trim() : '';
+            let assetPath = assetPathRaw;
+            if (!assetPath) {
+                if (blueprintPathRaw) {
+                    assetPath = blueprintPathRaw;
+                }
+                else if (nameRaw && savePathRaw) {
+                    const base = savePathRaw.replace(/\/$/, '');
+                    assetPath = `${base}/${nameRaw}`;
+                }
+            }
+            if (!assetPath) {
+                throw new Error('Invalid parameters: assetPath or blueprintPath or name+savePath required for set_metadata');
+            }
+            const metadata = (args.metadata && typeof args.metadata === 'object') ? args.metadata : {};
+            const res = await executeAutomationRequest(tools, 'set_metadata', { assetPath, metadata });
+            return cleanObject(res);
+        }
+        case 'add_event': {
+            const blueprintName = args.blueprintPath || args.path || args.name;
+            const usedNameForBlueprint = !args.blueprintPath && !args.path && args.name;
+            const res = await tools.blueprintTools.addEvent({
+                blueprintName: blueprintName,
+                eventType: args.eventType,
+                customEventName: args.customEventName || (!usedNameForBlueprint ? args.name : undefined),
+                parameters: args.parameters,
+                timeoutMs: args.timeoutMs,
+                waitForCompletion: args.waitForCompletion,
+                waitForCompletionTimeoutMs: args.waitForCompletionTimeoutMs
+            });
+            if (res && res.success === false) {
+                const msg = (res.message || '').toLowerCase();
+                if (msg.includes('already exists') || msg.includes('duplicate')) {
+                    return cleanObject({
+                        success: false,
+                        error: 'EVENT_ALREADY_EXISTS',
+                        message: res.message || 'Event already exists',
+                        blueprintName
+                    });
+                }
+            }
+            return cleanObject(res);
+        }
+        case 'remove_event': {
+            const res = await tools.blueprintTools.removeEvent({
+                blueprintName: args.name || args.blueprintPath || args.path,
+                eventName: args.eventName,
+                customEventName: args.customEventName,
+                timeoutMs: args.timeoutMs,
+                waitForCompletion: args.waitForCompletion,
+                waitForCompletionTimeoutMs: args.waitForCompletionTimeoutMs
+            });
+            return cleanObject(res);
+        }
+        case 'add_function': {
+            const blueprintName = args.blueprintPath || args.path || args.name;
+            const usedNameForBlueprint = !args.blueprintPath && !args.path && args.name;
+            const res = await tools.blueprintTools.addFunction({
+                blueprintName: blueprintName,
+                functionName: args.functionName || args.memberName || (!usedNameForBlueprint ? args.name : undefined),
+                inputs: args.inputs,
+                outputs: args.outputs,
+                isPublic: args.isPublic,
+                category: args.category,
+                timeoutMs: args.timeoutMs,
+                waitForCompletion: args.waitForCompletion,
+                waitForCompletionTimeoutMs: args.waitForCompletionTimeoutMs
+            });
+            return cleanObject(res);
+        }
+        case 'add_component': {
+            const res = await tools.blueprintTools.addComponent({
+                blueprintName: args.name || args.blueprintPath || args.path,
+                componentType: args.componentType || args.componentClass,
+                componentName: args.componentName,
+                attachTo: args.attachTo,
+                transform: args.transform,
+                properties: args.properties,
+                compile: args.applyAndSave,
+                save: args.applyAndSave,
+                timeoutMs: args.timeoutMs,
+                waitForCompletion: args.waitForCompletion,
+                waitForCompletionTimeoutMs: args.waitForCompletionTimeoutMs
+            });
+            return cleanObject(res);
+        }
+        case 'modify_scs': {
+            const res = await tools.blueprintTools.modifyConstructionScript({
+                blueprintPath: args.name || args.blueprintPath || args.path,
+                operations: args.operations,
+                compile: args.applyAndSave,
+                save: args.applyAndSave,
+                timeoutMs: args.timeoutMs,
+                waitForCompletion: args.waitForCompletion,
+                waitForCompletionTimeoutMs: args.waitForCompletionTimeoutMs
+            });
+            return cleanObject(res);
+        }
+        case 'set_scs_transform': {
+            const res = await tools.blueprintTools.setSCSComponentTransform({
+                blueprintPath: args.name || args.blueprintPath || args.path,
+                componentName: args.componentName,
+                location: args.location,
+                rotation: args.rotation,
+                scale: args.scale,
+                timeoutMs: args.timeoutMs
+            });
+            return cleanObject(res);
+        }
+        case 'add_construction_script': {
+            const res = await tools.blueprintTools.addConstructionScript({
+                blueprintName: args.name || args.blueprintPath || args.path,
+                scriptName: args.scriptName,
+                timeoutMs: args.timeoutMs,
+                waitForCompletion: args.waitForCompletion,
+                waitForCompletionTimeoutMs: args.waitForCompletionTimeoutMs
+            });
+            return cleanObject(res);
+        }
+        case 'add_node': {
+            if ((args.nodeType === 'CallFunction' || args.nodeType === 'K2Node_CallFunction') && !args.functionName && !args.memberName) {
+                throw new Error('CallFunction node requires functionName parameter');
+            }
+            const nodeAliases = {
+                'CallFunction': 'K2Node_CallFunction',
+                'VariableGet': 'K2Node_VariableGet',
+                'VariableSet': 'K2Node_VariableSet',
+                'If': 'K2Node_IfThenElse',
+                'Branch': 'K2Node_IfThenElse',
+                'Switch': 'K2Node_Switch',
+                'Select': 'K2Node_Select',
+                'Cast': 'K2Node_DynamicCast',
+                'CustomEvent': 'K2Node_CustomEvent',
+                'Event': 'K2Node_Event',
+                'MakeArray': 'K2Node_MakeArray',
+                'ForEach': 'K2Node_ForEachElementInEnum'
+            };
+            const resolvedNodeType = nodeAliases[args.nodeType] || args.nodeType;
+            if ((resolvedNodeType === 'K2Node_Event' || resolvedNodeType === 'K2Node_CustomEvent') && !args.eventName && !args.customEventName && !args.name) {
+                if (!args.eventName)
+                    args.eventName = args.name;
+                if (!args.eventName) {
+                    throw new Error(`${resolvedNodeType} requires eventName (or customEventName) parameter`);
+                }
+            }
+            const res = await tools.blueprintTools.addNode({
+                blueprintName: args.name || args.blueprintPath || args.path,
+                nodeType: resolvedNodeType,
+                graphName: args.graphName,
+                functionName: args.functionName,
+                variableName: args.variableName,
+                nodeName: args.nodeName,
+                eventName: args.eventName || args.customEventName,
+                memberClass: args.memberClass,
+                posX: args.posX,
+                posY: args.posY,
+                timeoutMs: args.timeoutMs
+            });
+            return cleanObject(res);
+        }
+        case 'add_scs_component': {
+            const res = await tools.blueprintTools.addSCSComponent({
+                blueprintPath: args.name || args.blueprintPath || args.path,
+                componentClass: args.componentClass || args.componentType,
+                componentName: args.componentName,
+                meshPath: args.meshPath,
+                materialPath: args.materialPath,
+                timeoutMs: args.timeoutMs
+            });
+            return cleanObject(res);
+        }
+        case 'reparent_scs_component': {
+            const res = await tools.blueprintTools.reparentSCSComponent({
+                blueprintPath: args.name || args.blueprintPath || args.path,
+                componentName: args.componentName,
+                newParent: args.newParent,
+                timeoutMs: args.timeoutMs
+            });
+            return cleanObject(res);
+        }
+        case 'set_scs_property': {
+            const res = await tools.blueprintTools.setSCSComponentProperty({
+                blueprintPath: args.name || args.blueprintPath || args.path,
+                componentName: args.componentName,
+                propertyName: args.propertyName,
+                propertyValue: args.propertyValue,
+                timeoutMs: args.timeoutMs
+            });
+            return cleanObject(res);
+        }
+        case 'remove_scs_component': {
+            const res = await tools.blueprintTools.removeSCSComponent({
+                blueprintPath: args.name || args.blueprintPath || args.path,
+                componentName: args.componentName,
+                timeoutMs: args.timeoutMs
+            });
+            return cleanObject(res);
+        }
+        case 'get_scs': {
+            const res = await tools.blueprintTools.getBlueprintSCS({
+                blueprintPath: args.name || args.blueprintPath || args.path,
+                timeoutMs: args.timeoutMs
+            });
+            return cleanObject(res);
+        }
+        case 'set_default': {
+            const res = await tools.blueprintTools.setBlueprintDefault({
+                blueprintName: args.name || args.blueprintPath || args.path,
+                propertyName: args.propertyName,
+                value: args.value
+            });
+            return cleanObject(res);
+        }
+        case 'compile': {
+            const res = await tools.blueprintTools.compileBlueprint({
+                blueprintName: args.name || args.blueprintPath || args.path,
+                saveAfterCompile: args.saveAfterCompile
+            });
+            return cleanObject(res);
+        }
+        case 'probe_handle': {
+            const res = await tools.blueprintTools.probeSubobjectDataHandle({
+                componentClass: args.componentClass
+            });
+            return cleanObject(res);
+        }
+        case 'get': {
+            const res = await tools.blueprintTools.getBlueprintInfo({
+                blueprintPath: args.name || args.blueprintPath || args.path,
+                timeoutMs: args.timeoutMs
+            });
+            return cleanObject(res);
+        }
+        case 'connect_pins':
+        case 'break_pin_links':
+        case 'delete_node':
+        case 'create_reroute_node':
+        case 'set_node_property':
+        case 'get_node_details':
+        case 'get_pin_details':
+        case 'get_graph_details': {
+            const processedArgs = {
+                ...args,
+                subAction: action,
+                blueprintPath: args.blueprintPath || args.path || args.name
+            };
+            const res = await executeAutomationRequest(tools, 'manage_blueprint_graph', processedArgs, 'Automation bridge not available for blueprint graph operations');
+            return cleanObject(res);
+        }
+        default: {
+            const processedArgs = { ...args };
+            if (args.action === 'modify_scs' && args.applyAndSave === true) {
+                processedArgs.compile = true;
+                processedArgs.save = true;
+            }
+            const res = await executeAutomationRequest(tools, 'manage_blueprint', processedArgs, 'Automation bridge not available for blueprint operations');
+            return cleanObject(res);
+        }
+    }
+}
+export async function handleBlueprintGet(args, tools) {
+    const res = await executeAutomationRequest(tools, 'blueprint_get', args, 'Automation bridge not available for blueprint operations');
+    if (res && res.success) {
+        return cleanObject({
+            ...res,
+            blueprint: args.blueprintPath || args.path || args.name || 'Unknown Blueprint',
+            message: res.message || 'Blueprint fetched'
+        });
+    }
+    return cleanObject(res);
+}
+//# sourceMappingURL=blueprint-handlers.js.map

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

@@ -0,0 +1,14 @@
+import { ITools } from '../../types/tool-interfaces.js';
+export declare function ensureArgsPresent(args: any): void;
+export declare function requireAction(args: any): string;
+export declare function requireNonEmptyString(value: any, field: string, message?: string): string;
+export declare function executeAutomationRequest(tools: ITools, toolName: string, args: any, errorMessage?: string, options?: {
+    timeoutMs?: number;
+}): Promise<import("../../automation/types.js").AutomationBridgeResponseMessage>;
+export declare function normalizeLocation(location: any): [number, number, number] | undefined;
+export declare function normalizeRotation(rotation: any): {
+    pitch: number;
+    yaw: number;
+    roll: number;
+} | undefined;
+//# sourceMappingURL=common-handlers.d.ts.map

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

@@ -0,0 +1,56 @@
+export function ensureArgsPresent(args) {
+    if (args === null || args === undefined) {
+        throw new Error('Invalid arguments: null or undefined');
+    }
+}
+export function requireAction(args) {
+    ensureArgsPresent(args);
+    const action = args.action;
+    if (typeof action !== 'string' || action.trim() === '') {
+        throw new Error('Missing required parameter: action');
+    }
+    return action;
+}
+export 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;
+}
+export async function executeAutomationRequest(tools, toolName, args, errorMessage = 'Automation bridge not available', options = {}) {
+    const automationBridge = tools.automationBridge;
+    if (!automationBridge || typeof automationBridge.sendAutomationRequest !== 'function') {
+        throw new Error(errorMessage);
+    }
+    if (!automationBridge.isConnected()) {
+        throw new Error(`Automation bridge is not connected to Unreal Engine. Please check if the editor is running and the plugin is enabled. Action: ${toolName}`);
+    }
+    return await automationBridge.sendAutomationRequest(toolName, args, options);
+}
+export function normalizeLocation(location) {
+    if (!location)
+        return undefined;
+    if (Array.isArray(location) && location.length >= 3) {
+        return [Number(location[0]) || 0, Number(location[1]) || 0, Number(location[2]) || 0];
+    }
+    if (typeof location === 'object' && ('x' in location || 'y' in location || 'z' in location)) {
+        return [Number(location.x) || 0, Number(location.y) || 0, Number(location.z) || 0];
+    }
+    return undefined;
+}
+export function normalizeRotation(rotation) {
+    if (!rotation)
+        return undefined;
+    if (Array.isArray(rotation) && rotation.length >= 3) {
+        return { pitch: Number(rotation[0]) || 0, yaw: Number(rotation[1]) || 0, roll: Number(rotation[2]) || 0 };
+    }
+    if (typeof rotation === 'object') {
+        return {
+            pitch: Number(rotation.pitch) || 0,
+            yaw: Number(rotation.yaw) || 0,
+            roll: Number(rotation.roll) || 0
+        };
+    }
+    return undefined;
+}
+//# sourceMappingURL=common-handlers.js.map

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

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

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

@@ -0,0 +1,119 @@
+import { cleanObject } from '../../utils/safe-json.js';
+import { executeAutomationRequest, requireNonEmptyString } from './common-handlers.js';
+export async function handleEditorTools(action, args, tools) {
+    switch (action) {
+        case 'play': {
+            const res = await tools.editorTools.playInEditor(args.timeoutMs);
+            return cleanObject(res);
+        }
+        case 'stop':
+        case 'stop_pie': {
+            const res = await tools.editorTools.stopPlayInEditor();
+            return cleanObject(res);
+        }
+        case 'eject': {
+            const inPie = await tools.editorTools.isInPIE();
+            if (!inPie) {
+                return { success: false, error: 'NOT_IN_PIE', message: 'Cannot eject while not in PIE' };
+            }
+            return await executeAutomationRequest(tools, 'control_editor', { action: 'eject' });
+        }
+        case 'possess': {
+            const inPie = await tools.editorTools.isInPIE();
+            if (!inPie) {
+                return { success: false, error: 'NOT_IN_PIE', message: 'Cannot possess actor while not in PIE' };
+            }
+            return await executeAutomationRequest(tools, 'control_editor', args);
+        }
+        case 'pause': {
+            const res = await tools.editorTools.pausePlayInEditor();
+            return cleanObject(res);
+        }
+        case 'resume': {
+            const res = await tools.editorTools.resumePlayInEditor();
+            return cleanObject(res);
+        }
+        case 'screenshot': {
+            const res = await tools.editorTools.takeScreenshot(args.filename, args.resolution);
+            return cleanObject(res);
+        }
+        case 'console_command': {
+            const res = await tools.editorTools.executeConsoleCommand(args.command);
+            return cleanObject(res);
+        }
+        case 'set_camera': {
+            const res = await tools.editorTools.setViewportCamera(args.location, args.rotation);
+            return cleanObject(res);
+        }
+        case 'start_recording': {
+            const filename = args.filename || 'TestRecording';
+            await tools.editorTools.executeConsoleCommand(`DemoRec ${filename}`);
+            return { success: true, message: `Started recording to ${filename}`, action: 'start_recording' };
+        }
+        case 'stop_recording': {
+            await tools.editorTools.executeConsoleCommand('DemoStop');
+            return { success: true, message: 'Stopped recording', action: 'stop_recording' };
+        }
+        case 'step_frame': {
+            await tools.editorTools.executeConsoleCommand('r.SingleFrameAdvance 1');
+            return { success: true, message: 'Stepped frame', action: 'step_frame' };
+        }
+        case 'create_bookmark': {
+            const idx = parseInt(args.bookmarkName) || 0;
+            await tools.editorTools.executeConsoleCommand(`r.SetBookmark ${idx}`);
+            return { success: true, message: `Created bookmark ${idx}`, action: 'create_bookmark' };
+        }
+        case 'jump_to_bookmark': {
+            const idx = parseInt(args.bookmarkName) || 0;
+            await tools.editorTools.executeConsoleCommand(`r.JumpToBookmark ${idx}`);
+            return { success: true, message: `Jumped to bookmark ${idx}`, action: 'jump_to_bookmark' };
+        }
+        case 'set_preferences': {
+            const res = await tools.editorTools.setEditorPreferences(args.category, args.preferences);
+            return cleanObject(res);
+        }
+        case 'open_asset': {
+            const assetPath = requireNonEmptyString(args.assetPath || args.path, 'assetPath');
+            const res = await executeAutomationRequest(tools, 'control_editor', { action: 'open_asset', assetPath });
+            return cleanObject(res);
+        }
+        case 'execute_command': {
+            const command = requireNonEmptyString(args.command, 'command');
+            const res = await tools.editorTools.executeConsoleCommand(command);
+            return { ...cleanObject(res), action: 'execute_command' };
+        }
+        case 'set_camera_fov': {
+            await tools.editorTools.executeConsoleCommand(`fov ${args.fov}`);
+            return { success: true, message: `Set FOV to ${args.fov}`, action: 'set_camera_fov' };
+        }
+        case 'set_game_speed': {
+            await tools.editorTools.executeConsoleCommand(`slomo ${args.speed}`);
+            return { success: true, message: `Set game speed to ${args.speed}`, action: 'set_game_speed' };
+        }
+        case 'set_view_mode': {
+            const viewMode = requireNonEmptyString(args.viewMode, 'viewMode');
+            const validModes = [
+                'Lit', 'Unlit', 'Wireframe', 'DetailLighting', 'LightingOnly', 'Reflections',
+                'OptimizationViewmodes', 'ShaderComplexity', 'LightmapDensity', 'StationaryLightOverlap', 'LightComplexity',
+                'PathTracing', 'Visualizer', 'LODColoration', 'CollisionPawn', 'CollisionVisibility'
+            ];
+            if (!validModes.includes(viewMode)) {
+                throw new Error(`unknown_viewmode: ${viewMode}. Must be one of: ${validModes.join(', ')}`);
+            }
+            await tools.editorTools.executeConsoleCommand(`viewmode ${viewMode}`);
+            return { success: true, message: `Set view mode to ${viewMode}`, action: 'set_view_mode' };
+        }
+        case 'set_viewport_resolution': {
+            await tools.editorTools.executeConsoleCommand(`r.SetRes ${args.width}x${args.height}`);
+            return { success: true, message: `Set viewport resolution to ${args.width}x${args.height}`, action: 'set_viewport_resolution' };
+        }
+        case 'set_viewport_realtime': {
+            const enabled = args.enabled !== undefined ? args.enabled : (args.realtime !== false);
+            await tools.editorTools.executeConsoleCommand(`r.ViewportRealtime ${enabled ? 1 : 0}`);
+            return { success: true, message: `Set viewport realtime to ${enabled}`, action: 'set_viewport_realtime' };
+        }
+        default:
+            return await executeAutomationRequest(tools, 'control_editor', args);
+    }
+}
+//# sourceMappingURL=editor-handlers.js.map

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

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