unreal-engine-mcp-server 0.3.1 → 0.4.0

package/.env.production

@@ -19,7 +19,7 @@ LOG_LEVEL=info
 
 # Server Settings
 SERVER_NAME=unreal-engine-mcp
-SERVER_VERSION=0.3.1
+SERVER_VERSION=0.4.0
 
 # Connection Settings
 MAX_RETRY_ATTEMPTS=3

package/README.md

@@ -114,7 +114,7 @@ Then enable Python execution in: Edit > Project Settings > Plugins > Remote Cont
 }
 ```
 
-## Available Tools (13 Consolidated)
+## Available Tools (13)
 
 | Tool | Description |
 |------|-------------|
@@ -161,7 +161,6 @@ Blueprints, Materials, Textures, Static/Skeletal Meshes, Levels, Sounds, Particl
 UE_HOST=127.0.0.1              # Unreal Engine host
 UE_RC_HTTP_PORT=30010          # Remote Control HTTP port
 UE_RC_WS_PORT=30020            # Remote Control WebSocket port
-USE_CONSOLIDATED_TOOLS=true    # Use 13 consolidated tools (false = 37 individual)
 LOG_LEVEL=info                 # debug | info | warn | error
 ```
 

package/dist/index.js

@@ -17,6 +17,7 @@ import { BlueprintTools } from './tools/blueprint.js';
 import { LevelTools } from './tools/level.js';
 import { LightingTools } from './tools/lighting.js';
 import { LandscapeTools } from './tools/landscape.js';
+import { BuildEnvironmentAdvanced } from './tools/build_environment_advanced.js';
 import { FoliageTools } from './tools/foliage.js';
 import { DebugVisualizationTools } from './tools/debug.js';
 import { PerformanceTools } from './tools/performance.js';
@@ -27,8 +28,6 @@ import { SequenceTools } from './tools/sequence.js';
 import { IntrospectionTools } from './tools/introspection.js';
 import { VisualTools } from './tools/visual.js';
 import { EngineTools } from './tools/engine.js';
-import { toolDefinitions } from './tools/tool-definitions.js';
-import { handleToolCall } from './tools/tool-handlers.js';
 import { consolidatedToolDefinitions } from './tools/consolidated-tool-definitions.js';
 import { handleConsolidatedToolCall } from './tools/consolidated-tool-handlers.js';
 import { prompts } from './prompts/index.js';
@@ -56,14 +55,13 @@ let healthCheckTimer;
 let lastHealthSuccessAt = 0;
 // Configuration
 const CONFIG = {
-    // Tool mode: true = consolidated (13 tools), false = individual (36+ tools)
-    USE_CONSOLIDATED_TOOLS: process.env.USE_CONSOLIDATED_TOOLS !== 'false',
+    // Tooling: use consolidated tools only (13 tools)
     // Connection retry settings
     MAX_RETRY_ATTEMPTS: 3,
     RETRY_DELAY_MS: 2000,
     // Server info
     SERVER_NAME: 'unreal-engine-mcp',
-    SERVER_VERSION: '0.3.1',
+    SERVER_VERSION: '0.4.0',
     // Monitoring
     HEALTH_CHECK_INTERVAL_MS: 30000 // 30 seconds
 };
@@ -123,7 +121,7 @@ export async function createServer() {
     bridge.setAutoReconnectEnabled(false);
     // Initialize response validation with schemas
     log.debug('Initializing response validation...');
-    const toolDefs = CONFIG.USE_CONSOLIDATED_TOOLS ? consolidatedToolDefinitions : toolDefinitions;
+    const toolDefs = consolidatedToolDefinitions;
     toolDefs.forEach((tool) => {
         if (tool.outputSchema) {
             responseValidator.registerSchema(tool.name, tool.outputSchema);
@@ -196,6 +194,7 @@ export async function createServer() {
     const lightingTools = new LightingTools(bridge);
     const landscapeTools = new LandscapeTools(bridge);
     const foliageTools = new FoliageTools(bridge);
+    const buildEnvAdvanced = new BuildEnvironmentAdvanced(bridge);
     const debugTools = new DebugVisualizationTools(bridge);
     const performanceTools = new PerformanceTools(bridge);
     const audioTools = new AudioTools(bridge);
@@ -394,14 +393,14 @@ export async function createServer() {
         }
         throw new Error(`Unknown resource: ${uri}`);
     });
-    // Handle tool listing - switch between consolidated (13) or individual (36) tools
+    // Handle tool listing - consolidated tools only
     server.setRequestHandler(ListToolsRequestSchema, async () => {
-        log.info(`Serving ${CONFIG.USE_CONSOLIDATED_TOOLS ? 'consolidated' : 'individual'} tools`);
+        log.info('Serving consolidated tools');
         return {
-            tools: CONFIG.USE_CONSOLIDATED_TOOLS ? consolidatedToolDefinitions : toolDefinitions
+            tools: consolidatedToolDefinitions
         };
     });
-    // Handle tool calls - switch between consolidated (13) or individual (36) tools
+    // Handle tool calls - consolidated tools only (13)
     server.setRequestHandler(CallToolRequestSchema, async (request) => {
         const { name, arguments: args } = request.params;
         const startTime = Date.now();
@@ -432,6 +431,7 @@ export async function createServer() {
             lightingTools,
             landscapeTools,
             foliageTools,
+            buildEnvAdvanced,
             debugTools,
             performanceTools,
             audioTools,
@@ -441,18 +441,16 @@ export async function createServer() {
             introspectionTools,
             visualTools,
             engineTools,
+            // Resources for listing and info
+            assetResources,
+            actorResources,
+            levelResources,
             bridge
         };
-        // Use consolidated or individual handler based on configuration
+        // Execute consolidated tool handler
         try {
             log.debug(`Executing tool: ${name}`);
-            let result;
-            if (CONFIG.USE_CONSOLIDATED_TOOLS) {
-                result = await handleConsolidatedToolCall(name, args, tools);
-            }
-            else {
-                result = await handleToolCall(name, args, tools);
-            }
+            let result = await handleConsolidatedToolCall(name, args, tools);
             log.debug(`Tool ${name} returned result`);
             // Clean the result to remove circular references
             result = cleanObject(result);

package/dist/resources/assets.d.ts

@@ -5,6 +5,7 @@ export declare class AssetResources {
     private cache;
     private get ttlMs();
     private makeKey;
+    private normalizeDir;
     list(dir?: string, _recursive?: boolean, limit?: number): Promise<any>;
     /**
      * List assets with pagination support
@@ -14,8 +15,8 @@ export declare class AssetResources {
      */
     listPaged(dir?: string, page?: number, pageSize?: number, recursive?: boolean): Promise<any>;
     /**
-     * Directory-based listing for paths with too many assets
-     * Shows only immediate children (folders and files) to avoid timeouts
+     * Directory-based listing of immediate children using AssetRegistry.
+     * Returns both subfolders and assets at the given path.
      */
     private listDirectoryOnly;
     find(assetPath: string): Promise<boolean>;

package/dist/resources/assets.js

@@ -9,10 +9,36 @@ export class AssetResources {
     makeKey(dir, recursive, page) {
         return page !== undefined ? `${dir}::${recursive ? 1 : 0}::${page}` : `${dir}::${recursive ? 1 : 0}`;
     }
+    // Normalize UE content paths:
+    // - Map '/Content' -> '/Game'
+    // - Ensure forward slashes
+    normalizeDir(dir) {
+        try {
+            if (!dir || typeof dir !== 'string')
+                return '/Game';
+            let d = dir.replace(/\\/g, '/');
+            if (!d.startsWith('/'))
+                d = '/' + d;
+            if (d.toLowerCase().startsWith('/content')) {
+                d = '/Game' + d.substring('/Content'.length);
+            }
+            // Collapse multiple slashes
+            d = d.replace(/\/+/g, '/');
+            // Remove trailing slash except root
+            if (d.length > 1)
+                d = d.replace(/\/$/, '');
+            return d;
+        }
+        catch {
+            return '/Game';
+        }
+    }
     async list(dir = '/Game', _recursive = false, limit = 50) {
         // ALWAYS use non-recursive listing to show only immediate children
         // This prevents timeouts and makes navigation clearer
         _recursive = false; // Force non-recursive
+        // Normalize directory first
+        dir = this.normalizeDir(dir);
         // Cache fast-path
         try {
             const key = this.makeKey(dir, false);
@@ -45,7 +71,8 @@ export class AssetResources {
         // Ensure pageSize doesn't exceed safe limit
         const safePageSize = Math.min(pageSize, 50);
         const offset = page * safePageSize;
-        // Check cache for this specific page
+        // Normalize directory and check cache for this specific page
+        dir = this.normalizeDir(dir);
         const cacheKey = this.makeKey(dir, recursive, page);
         const cached = this.cache.get(cacheKey);
         if (cached && (Date.now() - cached.timestamp) < this.ttlMs) {
@@ -91,8 +118,8 @@ export class AssetResources {
         };
     }
     /**
-     * Directory-based listing for paths with too many assets
-     * Shows only immediate children (folders and files) to avoid timeouts
+     * Directory-based listing of immediate children using AssetRegistry.
+     * Returns both subfolders and assets at the given path.
      */
     async listDirectoryOnly(dir, _recursive, limit) {
         // Always return only immediate children to avoid timeout and improve navigation
@@ -101,65 +128,43 @@ export class AssetResources {
 import unreal
 import json
 
-_dir = r"${dir}"
+_dir = r"${this.normalizeDir(dir)}"
 
 try:
-    # ALWAYS non-recursive - get only immediate children
-    all_paths = unreal.EditorAssetLibrary.list_assets(_dir, False, False)
-    
-    # Organize into immediate children only
-    immediate_folders = set()
-    immediate_assets = []
-    
-    for path in all_paths:
-        # Remove the base directory to get relative path
-        relative = path.replace(_dir, '').strip('/')
-        if not relative:
-            continue
-            
-        # Split to check depth
-        parts = relative.split('/')
-        
-        if len(parts) == 1:
-            # This is an immediate child asset
-            immediate_assets.append(path)
-        elif len(parts) > 1:
-            # This indicates a subfolder exists
-            immediate_folders.add(parts[0])
-    
-    result = []
-    
-    # Add folders first
-    for folder in sorted(immediate_folders):
-        result.append({
-            'n': folder,
-            'p': _dir + '/' + folder,
-            'c': 'Folder',
-            'isFolder': True
-        })
-    
-    # Add immediate assets (limit to prevent socket issues)
-    for asset_path in immediate_assets[:min(${limit}, len(immediate_assets))]:
-        name = asset_path.split('/')[-1].split('.')[0]
-        result.append({
-            'n': name,
-            'p': asset_path,
-            'c': 'Asset'
-        })
-    
-    # Always showing immediate children only
-    note = f'Showing immediate children of {_dir} ({len(immediate_folders)} folders, {len(immediate_assets)} files)'
-    
+    ar = unreal.AssetRegistryHelpers.get_asset_registry()
+    # Immediate subfolders
+    sub_paths = ar.get_sub_paths(_dir, False)
+    folders_list = []
+    for p in sub_paths:
+        try:
+            name = p.split('/')[-1]
+            folders_list.append({'n': name, 'p': p})
+        except Exception:
+            pass
+
+    # Immediate assets at this path
+    assets_data = ar.get_assets_by_path(_dir, False)
+    assets = []
+    for a in assets_data[:${limit}]:
+        try:
+            assets.append({
+                'n': str(a.asset_name),
+                'p': str(a.object_path),
+                'c': str(a.asset_class)
+            })
+        except Exception:
+            pass
+
     print("RESULT:" + json.dumps({
-        'success': True, 
-        'assets': result, 
-        'count': len(result),
-        'folders': len(immediate_folders),
-        'files': len(immediate_assets),
-        'note': note
+        'success': True,
+        'path': _dir,
+        'folders': len(folders_list),
+        'files': len(assets),
+        'folders_list': folders_list,
+        'assets': assets
     }))
 except Exception as e:
-    print("RESULT:" + json.dumps({'success': False, 'error': str(e), 'assets': []}))
+    print("RESULT:" + json.dumps({'success': False, 'error': str(e), 'path': _dir}))
 `.trim();
             const resp = await this.bridge.executePython(py);
             let output = '';
@@ -177,20 +182,34 @@ except Exception as e:
                 try {
                     const parsed = JSON.parse(m[1]);
                     if (parsed.success) {
-                        // Transform to standard format
-                        const assets = parsed.assets.map((a) => ({
+                        // Map folders and assets to a clear response
+                        const foldersArr = Array.isArray(parsed.folders_list) ? parsed.folders_list.map((f) => ({
+                            Name: f.n,
+                            Path: f.p,
+                            Class: 'Folder',
+                            isFolder: true
+                        })) : [];
+                        const assetsArr = Array.isArray(parsed.assets) ? parsed.assets.map((a) => ({
                             Name: a.n,
                             Path: a.p,
-                            Class: a.c,
-                            isFolder: a.isFolder || false
-                        }));
+                            Class: a.c || 'Asset',
+                            isFolder: false
+                        })) : [];
+                        const total = foldersArr.length + assetsArr.length;
+                        const summary = {
+                            total,
+                            folders: foldersArr.length,
+                            assets: assetsArr.length
+                        };
                         return {
-                            assets,
-                            count: parsed.count,
-                            folders: parsed.folders,
-                            files: parsed.files,
-                            note: parsed.note,
-                            method: 'directory_listing'
+                            success: true,
+                            path: parsed.path || this.normalizeDir(dir),
+                            summary,
+                            foldersList: foldersArr,
+                            assets: assetsArr,
+                            count: total,
+                            note: `Immediate children of ${parsed.path || this.normalizeDir(dir)}: ${foldersArr.length} folder(s), ${assetsArr.length} asset(s)`,
+                            method: 'asset_registry_listing'
                         };
                     }
                 }
@@ -202,10 +221,13 @@ except Exception as e:
         }
         // Fallback: return empty with explanation
         return {
+            success: true,
+            path: this.normalizeDir(dir),
+            summary: { total: 0, folders: 0, assets: 0 },
+            foldersList: [],
             assets: [],
-            warning: 'Directory contains too many assets. Showing immediate children only.',
-            suggestion: 'Navigate to specific subdirectories for detailed listings.',
-            method: 'directory_timeout_fallback'
+            warning: 'No items at this path or failed to query AssetRegistry.',
+            method: 'asset_registry_fallback'
         };
     }
     async find(assetPath) {
@@ -213,9 +235,11 @@ except Exception as e:
         if (!assetPath || typeof assetPath !== 'string' || assetPath.trim() === '' || assetPath.endsWith('/')) {
             return false;
         }
+        // Normalize asset path (support users passing /Content/...)
+        const ap = this.normalizeDir(assetPath);
         const py = `
 import unreal
-apath = r"${assetPath}"
+apath = r"${ap}"
 try:
     exists = unreal.EditorAssetLibrary.does_asset_exist(apath)
     print("RESULT:{'success': True, 'exists': %s}" % ('True' if exists else 'False'))

package/dist/resources/levels.js

@@ -62,9 +62,9 @@ export class LevelResources {
         }
     }
     async saveCurrentLevel() {
-        // Prefer Python save (or LevelEditorSubsystem) then fallback
+        // Strict modern API: require LevelEditorSubsystem
         try {
-            const py = '\nimport unreal, json\ntry:\n    les = unreal.get_editor_subsystem(unreal.LevelEditorSubsystem)\n    if les: les.save_current_level()\n    else: unreal.EditorLevelLibrary.save_current_level()\n    print(\'RESULT:\' + json.dumps({\'success\': True}))\nexcept Exception as e:\n    print(\'RESULT:\' + json.dumps({\'success\': False, \'error\': str(e)}))\n'.trim();
+            const py = '\nimport unreal, json\ntry:\n    les = unreal.get_editor_subsystem(unreal.LevelEditorSubsystem)\n    if not les:\n        print(\'RESULT:\' + json.dumps({\'success\': False, \'error\': \'LevelEditorSubsystem not available\'}))\n    else:\n        les.save_current_level()\n        print(\'RESULT:\' + json.dumps({\'success\': True}))\nexcept Exception as e:\n    print(\'RESULT:\' + json.dumps({\'success\': False, \'error\': str(e)}))\n'.trim();
             const resp = await this.bridge.executePython(py);
             // Handle LogOutput format from executePython
             let out = '';

package/dist/tools/assets.js

@@ -7,8 +7,12 @@ export class AssetTools {
     }
     async importAsset(sourcePath, destinationPath) {
         try {
-            // Sanitize destination path (remove trailing slash)
-            const cleanDest = destinationPath.replace(/\/$/, '');
+            // Sanitize destination path (remove trailing slash) and normalize UE path
+            let cleanDest = destinationPath.replace(/\/$/, '');
+            // Map /Content -> /Game for UE asset destinations
+            if (/^\/?content(\/|$)/i.test(cleanDest)) {
+                cleanDest = '/Game' + cleanDest.replace(/^\/?content/i, '');
+            }
             // Create test FBX file if it's a test file
             if (sourcePath.includes('test_model.fbx')) {
                 // Create the file outside of Python, before import

package/dist/tools/build_environment_advanced.js

@@ -45,17 +45,8 @@ try:
         proc_mesh_comp = proc_actor.get_component_by_class(unreal.ProceduralMeshComponent)
     except:
         # Fallback: Create empty actor and add ProceduralMeshComponent
-        proc_actor = subsys.spawn_actor_from_class(
-            unreal.Actor,
-            location,
-            unreal.Rotator(0, 0, 0)
-        )
-        proc_actor.set_actor_label(f"{name}_ProceduralTerrain")
-        
-        # Add procedural mesh component
-        proc_mesh_comp = unreal.ProceduralMeshComponent()
-        proc_actor.add_instance_component(proc_mesh_comp)
-        proc_mesh_comp.register_component()
+        # If spawning ProceduralMeshActor failed, surface a clear error about the plugin requirement
+        raise Exception("Failed to spawn ProceduralMeshActor. Ensure the 'Procedural Mesh Component' plugin is enabled and available.")
     
     if proc_mesh_comp:
         # Generate terrain mesh
@@ -170,6 +161,10 @@ try:
     subsys = unreal.get_editor_subsystem(unreal.EditorActorSubsystem)
     asset_tools = unreal.AssetToolsHelpers.get_asset_tools()
     
+    # Validate Procedural Foliage plugin/classes are available
+    if not hasattr(unreal, 'ProceduralFoliageVolume') or not hasattr(unreal, 'ProceduralFoliageSpawner'):
+        raise Exception("Procedural Foliage plugin not available. Please enable the 'Procedural Foliage' plugin and try again.")
+    
     # Create ProceduralFoliageVolume
     volume_actor = subsys.spawn_actor_from_class(
         unreal.ProceduralFoliageVolume,
@@ -177,7 +172,7 @@ try:
         unreal.Rotator(0, 0, 0)
     )
     volume_actor.set_actor_label(f"{name}_ProceduralFoliageVolume")
-    volume_actor.set_actor_scale3d(bounds_size / 100)  # Scale is in meters
+    volume_actor.set_actor_scale3d(unreal.Vector(bounds_size.x/100.0, bounds_size.y/100.0, bounds_size.z/100.0))  # Scale is in meters
     
     # Get the procedural component
     proc_comp = volume_actor.procedural_component
@@ -208,13 +203,14 @@ try:
             )
         
         if spawner:
-            # Configure spawner
-            spawner.random_seed = seed
-            spawner.tile_size = max(bounds_size.x, bounds_size.y)
+            # Configure spawner (use set_editor_property for read-only attributes)
+            spawner.set_editor_property('random_seed', seed)
+            spawner.set_editor_property('tile_size', max(bounds_size.x, bounds_size.y))
             
             # Create foliage types
             foliage_types = []
-            for ft_params in ${JSON.stringify(params.foliageTypes)}:
+            ft_input = json.loads(r'''${JSON.stringify(params.foliageTypes)}''')
+            for ft_params in ft_input:
                 # Load mesh
                 mesh = unreal.EditorAssetLibrary.load_asset(ft_params['meshPath'])
                 if mesh:
@@ -233,26 +229,26 @@ try:
                         ft_asset = unreal.FoliageType_InstancedStaticMesh()
                     
                     if ft_asset:
-                        # Configure foliage type
-                        ft_asset.mesh = mesh
-                        ft_asset.density = ft_params.get('density', 1.0)
-                        ft_asset.random_yaw = ft_params.get('randomYaw', True)
-                        ft_asset.align_to_normal = ft_params.get('alignToNormal', True)
+                        # Configure foliage type (use set_editor_property)
+                        ft_asset.set_editor_property('mesh', mesh)
+                        ft_asset.set_editor_property('density', ft_params.get('density', 1.0))
+                        ft_asset.set_editor_property('random_yaw', ft_params.get('randomYaw', True))
+                        ft_asset.set_editor_property('align_to_normal', ft_params.get('alignToNormal', True))
                         
                         min_scale = ft_params.get('minScale', 0.8)
                         max_scale = ft_params.get('maxScale', 1.2)
-                        ft_asset.scale_x = unreal.FloatInterval(min_scale, max_scale)
-                        ft_asset.scale_y = unreal.FloatInterval(min_scale, max_scale)
-                        ft_asset.scale_z = unreal.FloatInterval(min_scale, max_scale)
+                        ft_asset.set_editor_property('scale_x', unreal.FloatInterval(min_scale, max_scale))
+                        ft_asset.set_editor_property('scale_y', unreal.FloatInterval(min_scale, max_scale))
+                        ft_asset.set_editor_property('scale_z', unreal.FloatInterval(min_scale, max_scale))
                         
-                        ft_obj.foliage_type_object = ft_asset
+                        ft_obj.set_editor_property('foliage_type_object', ft_asset)
                         foliage_types.append(ft_obj)
             
             # Set foliage types on spawner
-            spawner.foliage_types = foliage_types
+            spawner.set_editor_property('foliage_types', foliage_types)
             
             # Assign spawner to component
-            proc_comp.foliage_spawner = spawner
+            proc_comp.set_editor_property('foliage_spawner', spawner)
             
             # Save spawner asset
             unreal.EditorAssetLibrary.save_asset(spawner.get_path_name())
@@ -413,23 +409,31 @@ try:
             # Load mesh
             mesh = unreal.EditorAssetLibrary.load_asset(mesh_path)
             if mesh:
-                # Configure grass type
+                # Configure grass type (use set_editor_property)
                 grass_variety = unreal.GrassVariety()
-                grass_variety.grass_mesh = mesh
-                grass_variety.grass_density = density * 100  # Convert to per square meter
-                grass_variety.use_grid = True
-                grass_variety.placement_jitter = 1.0
-                grass_variety.start_cull_distance = 10000
-                grass_variety.end_cull_distance = 20000
-                grass_variety.min_lod = -1
-                grass_variety.scaling = unreal.GrassScaling.UNIFORM
-                grass_variety.scale_x = unreal.FloatInterval(min_scale, max_scale)
-                grass_variety.scale_y = unreal.FloatInterval(min_scale, max_scale)
-                grass_variety.scale_z = unreal.FloatInterval(min_scale, max_scale)
-                grass_variety.random_rotation = True
-                grass_variety.align_to_surface = True
+                grass_variety.set_editor_property('grass_mesh', mesh)
+                # GrassDensity is PerPlatformFloat in UE5+; set via struct instance
+                pp_density = unreal.PerPlatformFloat()
+                pp_density.set_editor_property('Default', float(density * 100.0))
+                grass_variety.set_editor_property('grass_density', pp_density)
+                grass_variety.set_editor_property('use_grid', True)
+                grass_variety.set_editor_property('placement_jitter', 1.0)
+                # Set cull distances as PerPlatformInt and LOD as int (engine uses mixed types here)
+                pp_start = unreal.PerPlatformInt()
+                pp_start.set_editor_property('Default', 10000)
+                grass_variety.set_editor_property('start_cull_distance', pp_start)
+                pp_end = unreal.PerPlatformInt()
+                pp_end.set_editor_property('Default', 20000)
+                grass_variety.set_editor_property('end_cull_distance', pp_end)
+                grass_variety.set_editor_property('min_lod', -1)
+                grass_variety.set_editor_property('scaling', unreal.GrassScaling.UNIFORM)
+                grass_variety.set_editor_property('scale_x', unreal.FloatInterval(min_scale, max_scale))
+                grass_variety.set_editor_property('scale_y', unreal.FloatInterval(min_scale, max_scale))
+                grass_variety.set_editor_property('scale_z', unreal.FloatInterval(min_scale, max_scale))
+                grass_variety.set_editor_property('random_rotation', True)
+                grass_variety.set_editor_property('align_to_surface', True)
                 
-                grass_type.grass_varieties = [grass_variety]
+                grass_type.set_editor_property('grass_varieties', [grass_variety])
                 
                 # Save asset
                 unreal.EditorAssetLibrary.save_asset(grass_type.get_path_name())