unreal-engine-mcp-server 0.5.3 → 0.5.5

package/src/tools/handlers/level-handlers.ts

@@ -1,253 +0,0 @@
-import { cleanObject } from '../../utils/safe-json.js';
-import { ITools } from '../../types/tool-interfaces.js';
-import type { LevelArgs } from '../../types/handler-types.js';
-import { executeAutomationRequest, requireNonEmptyString } from './common-handlers.js';
-
-export async function handleLevelTools(action: string, args: LevelArgs, tools: ITools) {
-  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': {
-      // Accept savePath, destinationPath, or levelPath as the target
-      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': {
-      // Delegate directly to the plugin's manage_level.create_light handler.
-      const res = await executeAutomationRequest(tools, 'manage_level', args);
-      return cleanObject(res);
-    }
-    case 'spawn_light': {
-      // Fallback to control_actor spawn if manage_level spawn_light is not supported
-      const lightClassMap: Record<string, string> = {
-        '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 as any) || '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.filter((p): p is string => typeof p === 'string') : (args.levelPath ? [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': {
-      // Calculate origin/extent if min/max provided for C++ handler compatibility
-      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 // Allow other args to override if explicit
-      };
-
-      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, // Map label to name
-        ...args
-      });
-      return cleanObject(res);
-    }
-    case 'cleanup_invalid_datalayers': {
-      // Route to manage_world_partition
-      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');
-
-      // Prefer an editor-side existence check when the automation bridge is available.
-      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: any = 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);
-  }
-}

package/src/tools/handlers/lighting-handlers.ts

@@ -1,151 +0,0 @@
-import { cleanObject } from '../../utils/safe-json.js';
-import { ITools } from '../../types/tool-interfaces.js';
-import type { LightingArgs } from '../../types/handler-types.js';
-import { normalizeLocation } from './common-handlers.js';
-
-export async function handleLightingTools(action: string, args: LightingArgs, tools: ITools) {
-  // Normalize location parameter to accept both {x,y,z} and [x,y,z] formats
-  const normalizedLocation = normalizeLocation(args.location);
-
-  switch (action) {
-    case 'spawn_light':
-    case 'create_light': {
-      // Map generic create_light to specific types if provided
-      const lightType = args.lightType ? args.lightType.toLowerCase() : 'point';
-      const commonParams = {
-        name: args.name,
-        location: normalizedLocation || args.location,
-        rotation: args.rotation,
-        intensity: args.intensity,
-        color: args.color,
-        castShadows: args.castShadows
-      };
-
-      if (lightType === 'directional') {
-        return cleanObject(await tools.lightingTools.createDirectionalLight({
-          ...commonParams,
-          temperature: args.temperature,
-          useAsAtmosphereSunLight: args.useAsAtmosphereSunLight
-        }));
-      } else if (lightType === 'spot') {
-        return cleanObject(await tools.lightingTools.createSpotLight({
-          ...commonParams,
-          location: normalizedLocation || [0, 0, 0],
-          rotation: args.rotation || [0, 0, 0],
-          innerCone: args.innerCone,
-          outerCone: args.outerCone,
-          radius: args.radius
-        }));
-      } else if (lightType === 'rect') {
-        return cleanObject(await tools.lightingTools.createRectLight({
-          ...commonParams,
-          location: normalizedLocation || [0, 0, 0],
-          rotation: args.rotation || [0, 0, 0],
-          width: args.width,
-          height: args.height
-        }));
-      } else {
-        // Default to Point
-        return cleanObject(await tools.lightingTools.createPointLight({
-          ...commonParams,
-          radius: args.radius,
-          falloffExponent: args.falloffExponent
-        }));
-      }
-    }
-    case 'create_dynamic_light': {
-      return cleanObject(await tools.lightingTools.createDynamicLight({
-        name: args.name,
-        lightType: args.lightType,
-        location: args.location,
-        rotation: args.rotation,
-        intensity: args.intensity,
-        color: args.color,
-        pulse: args.pulse
-      }));
-    }
-    case 'spawn_sky_light':
-    case 'create_sky_light': {
-      return cleanObject(await tools.lightingTools.createSkyLight({
-        name: args.name,
-        sourceType: args.sourceType,
-        cubemapPath: args.cubemapPath,
-        intensity: args.intensity,
-        recapture: args.recapture
-      }));
-    }
-    case 'ensure_single_sky_light': {
-      return cleanObject(await tools.lightingTools.ensureSingleSkyLight({
-        name: args.name,
-        recapture: args.recapture
-      }));
-    }
-    case 'create_lightmass_volume': {
-      return cleanObject(await tools.lightingTools.createLightmassVolume({
-        name: args.name,
-        location: args.location,
-        size: args.size
-      }));
-    }
-    case 'setup_volumetric_fog': {
-      return cleanObject(await tools.lightingTools.setupVolumetricFog({
-        enabled: args.enabled !== false,
-        density: args.density,
-        scatteringIntensity: args.scatteringIntensity,
-        fogHeight: args.fogHeight
-      }));
-    }
-    case 'setup_global_illumination': {
-      return cleanObject(await tools.lightingTools.setupGlobalIllumination({
-        method: args.method,
-        quality: args.quality,
-        indirectLightingIntensity: args.indirectLightingIntensity,
-        bounces: args.bounces
-      }));
-    }
-    case 'configure_shadows': {
-      return cleanObject(await tools.lightingTools.configureShadows({
-        shadowQuality: args.shadowQuality,
-        cascadedShadows: args.cascadedShadows,
-        shadowDistance: args.shadowDistance,
-        contactShadows: args.contactShadows,
-        rayTracedShadows: args.rayTracedShadows
-      }));
-    }
-    case 'set_exposure': {
-      return cleanObject(await tools.lightingTools.setExposure({
-        method: args.method,
-        compensationValue: args.compensationValue,
-        minBrightness: args.minBrightness,
-        maxBrightness: args.maxBrightness
-      }));
-    }
-    case 'set_ambient_occlusion': {
-      return cleanObject(await tools.lightingTools.setAmbientOcclusion({
-        enabled: args.enabled !== false,
-        intensity: args.intensity,
-        radius: args.radius,
-        quality: args.quality
-      }));
-    }
-    case 'build_lighting': {
-      return cleanObject(await tools.lightingTools.buildLighting({
-        quality: args.quality,
-        buildOnlySelected: args.buildOnlySelected,
-        buildReflectionCaptures: args.buildReflectionCaptures
-      }));
-    }
-    case 'create_lighting_enabled_level': {
-      return cleanObject(await tools.lightingTools.createLightingEnabledLevel({
-        levelName: args.levelName,
-        copyActors: args.copyActors,
-        useTemplate: args.useTemplate
-      }));
-    }
-    case 'list_light_types': {
-      return cleanObject(await tools.lightingTools.listLightTypes());
-    }
-    default:
-      throw new Error(`Unknown lighting action: ${action}`);
-  }
-}

package/src/tools/handlers/performance-handlers.ts

@@ -1,132 +0,0 @@
-import { cleanObject } from '../../utils/safe-json.js';
-import { ITools } from '../../types/tool-interfaces.js';
-
-export async function handlePerformanceTools(action: string, args: any, tools: ITools) {
-  switch (action) {
-    case 'start_profiling': {
-      return cleanObject(await tools.performanceTools.startProfiling({
-        type: args.type || 'All',
-        duration: args.duration
-      }));
-    }
-    case 'stop_profiling': {
-      return cleanObject(await tools.performanceTools.stopProfiling());
-    }
-    case 'run_benchmark': {
-      return cleanObject(await tools.performanceTools.runBenchmark({
-        duration: args.duration,
-        outputPath: args.outputPath
-      }));
-    }
-    case 'show_fps': {
-      return cleanObject(await tools.performanceTools.showFPS({
-        enabled: args.enabled !== false,
-        verbose: args.verbose
-      }));
-    }
-    case 'show_stats': {
-      return cleanObject(await tools.performanceTools.showStats({
-        category: args.category || args.type || 'Unit',
-        enabled: args.enabled !== false
-      }));
-    }
-    case 'set_scalability': {
-      const category = args.category || 'ViewDistance';
-      const level = typeof args.level === 'number' ? args.level : 3;
-      return cleanObject(await tools.performanceTools.setScalability({
-        category,
-        level
-      }));
-    }
-    case 'set_resolution_scale': {
-      return cleanObject(await tools.performanceTools.setResolutionScale({
-        scale: args.scale
-      }));
-    }
-    case 'set_vsync': {
-      return cleanObject(await tools.performanceTools.setVSync({
-        enabled: args.enabled !== false
-      }));
-    }
-    case 'set_frame_rate_limit': {
-      return cleanObject(await tools.performanceTools.setFrameRateLimit({
-        maxFPS: args.maxFPS
-      }));
-    }
-    case 'enable_gpu_timing': {
-      return cleanObject(await tools.performanceTools.enableGPUTiming({
-        enabled: args.enabled !== false
-      }));
-    }
-    case 'generate_memory_report': {
-      return cleanObject(await tools.performanceTools.generateMemoryReport({
-        detailed: args.detailed,
-        outputPath: args.outputPath
-      }));
-    }
-    case 'configure_texture_streaming': {
-      return cleanObject(await tools.performanceTools.configureTextureStreaming({
-        enabled: args.enabled !== false,
-        poolSize: args.poolSize,
-        boostPlayerLocation: args.boostPlayerLocation
-      }));
-    }
-    case 'configure_lod': {
-      return cleanObject(await tools.performanceTools.configureLOD({
-        forceLOD: args.forceLOD,
-        lodBias: args.lodBias,
-        distanceScale: args.distanceScale
-      }));
-    }
-    case 'apply_baseline_settings': {
-      return cleanObject(await tools.performanceTools.applyBaselinePerformanceSettings({
-        distanceScale: args.distanceScale,
-        skeletalBias: args.skeletalBias,
-        vsync: args.vsync,
-        maxFPS: args.maxFPS,
-        hzb: args.hzb
-      }));
-    }
-    case 'optimize_draw_calls':
-    case 'merge_actors': {
-      // If action is merge_actors, force mergeActors param to true
-      const mergeParams = action === 'merge_actors' ? { ...args, mergeActors: true } : args;
-      return cleanObject(await tools.performanceTools.optimizeDrawCalls({
-        enableInstancing: mergeParams.enableInstancing,
-        enableBatching: mergeParams.enableBatching,
-        mergeActors: mergeParams.mergeActors,
-        actors: mergeParams.actors
-      }));
-    }
-    case 'configure_occlusion_culling': {
-      return cleanObject(await tools.performanceTools.configureOcclusionCulling({
-        enabled: args.enabled !== false,
-        method: args.method,
-        freezeRendering: args.freezeRendering
-      }));
-    }
-    case 'optimize_shaders': {
-      return cleanObject(await tools.performanceTools.optimizeShaders({
-        compileOnDemand: args.compileOnDemand,
-        cacheShaders: args.cacheShaders,
-        reducePermutations: args.reducePermutations
-      }));
-    }
-    case 'configure_nanite': {
-      return cleanObject(await tools.performanceTools.configureNanite({
-        enabled: args.enabled !== false,
-        maxPixelsPerEdge: args.maxPixelsPerEdge,
-        streamingPoolSize: args.streamingPoolSize
-      }));
-    }
-    case 'configure_world_partition': {
-      return cleanObject(await tools.performanceTools.configureWorldPartition({
-        enabled: args.enabled !== false,
-        streamingDistance: args.streamingDistance,
-        cellSize: args.cellSize
-      }));
-    }
-    default:
-      throw new Error(`Unknown performance action: ${action}`);
-  }
-}

package/src/tools/handlers/pipeline-handlers.ts

@@ -1,128 +0,0 @@
-import { cleanObject } from '../../utils/safe-json.js';
-import { ITools } from '../../types/tool-interfaces.js';
-import type { PipelineArgs } from '../../types/handler-types.js';
-import { executeAutomationRequest } from './common-handlers.js';
-import { spawn } from 'child_process';
-import path from 'path';
-import fs from 'fs';
-
-export async function handlePipelineTools(action: string, args: PipelineArgs, tools: ITools) {
-  switch (action) {
-    case 'run_ubt': {
-      const target = args.target;
-      const platform = args.platform || 'Win64';
-      const configuration = args.configuration || 'Development';
-      const extraArgs = args.arguments || '';
-
-      if (!target) {
-        throw new Error('Target is required for run_ubt');
-      }
-
-      // Try to find UnrealBuildTool
-      let ubtPath = 'UnrealBuildTool'; // Assume in PATH by default
-      const enginePath = process.env.UE_ENGINE_PATH || process.env.UNREAL_ENGINE_PATH;
-
-      if (enginePath) {
-        const possiblePath = path.join(enginePath, 'Engine', 'Binaries', 'DotNET', 'UnrealBuildTool', 'UnrealBuildTool.exe');
-        if (fs.existsSync(possiblePath)) {
-          ubtPath = possiblePath;
-        }
-      }
-
-      let projectPath = process.env.UE_PROJECT_PATH;
-      if (!projectPath && args.projectPath) {
-        projectPath = args.projectPath;
-      }
-
-      if (!projectPath) {
-        throw new Error('UE_PROJECT_PATH environment variable is not set and no projectPath argument was provided.');
-      }
-
-      // If projectPath points to a .uproject file, use it. If it's a directory, look for a .uproject file.
-      let uprojectFile = projectPath;
-      if (!uprojectFile.endsWith('.uproject')) {
-        // Find first .uproject in the directory
-        try {
-          const files = fs.readdirSync(projectPath);
-          const found = files.find(f => f.endsWith('.uproject'));
-          if (found) {
-            uprojectFile = path.join(projectPath, found);
-          }
-        } catch (_e) {
-          throw new Error(`Could not read project directory: ${projectPath}`);
-        }
-      }
-
-      const cmdArgs = [
-        target,
-        platform,
-        configuration,
-        `-Project="${uprojectFile}"`,
-        extraArgs
-      ].filter(Boolean);
-
-      return new Promise((resolve) => {
-        const child = spawn(ubtPath, cmdArgs, { shell: true });
-
-        const MAX_OUTPUT_SIZE = 20 * 1024; // 20KB cap
-        let stdout = '';
-        let stderr = '';
-
-        child.stdout.on('data', (data) => {
-          const str = data.toString();
-          process.stderr.write(str); // Stream to server console (stderr to avoid MCP corruption)
-          stdout += str;
-          if (stdout.length > MAX_OUTPUT_SIZE) {
-            stdout = stdout.substring(stdout.length - MAX_OUTPUT_SIZE);
-          }
-        });
-
-        child.stderr.on('data', (data) => {
-          const str = data.toString();
-          process.stderr.write(str); // Stream to server console
-          stderr += str;
-          if (stderr.length > MAX_OUTPUT_SIZE) {
-            stderr = stderr.substring(stderr.length - MAX_OUTPUT_SIZE);
-          }
-        });
-
-        child.on('close', (code) => {
-          const truncatedNote = (stdout.length >= MAX_OUTPUT_SIZE || stderr.length >= MAX_OUTPUT_SIZE)
-            ? '\n[Output truncated for response payload]'
-            : '';
-
-          if (code === 0) {
-            resolve({
-              success: true,
-              message: 'UnrealBuildTool finished successfully',
-              output: stdout + truncatedNote,
-              command: `${ubtPath} ${cmdArgs.join(' ')}`
-            });
-          } else {
-            resolve({
-              success: false,
-              error: 'UBT_FAILED',
-              message: `UnrealBuildTool failed with code ${code}`,
-              output: stdout + truncatedNote,
-              errorOutput: stderr + truncatedNote,
-              command: `${ubtPath} ${cmdArgs.join(' ')}`
-            });
-          }
-        });
-
-        child.on('error', (err) => {
-          resolve({
-            success: false,
-            error: 'SPAWN_FAILED',
-            message: `Failed to spawn UnrealBuildTool: ${err.message}`,
-            command: `${ubtPath} ${cmdArgs.join(' ')}`
-          });
-        });
-      });
-    }
-    default:
-      // Fallback to automation bridge if we add more actions later that are bridge-supported
-      const res = await executeAutomationRequest(tools, 'manage_pipeline', { ...args, subAction: action }, 'Automation bridge not available for manage_pipeline');
-      return cleanObject(res);
-  }
-}