unreal-engine-mcp-server 0.2.1 → 0.3.1

package/dist/tools/tool-definitions.js

@@ -3,7 +3,18 @@ export const toolDefinitions = [
     // Asset Tools
     {
         name: 'list_assets',
-        description: 'List all assets in a directory',
+        description: `List assets in a folder of the project.
+
+When to use:
+- Browse project content (use /Game; /Content is auto-mapped by the server).
+- Get a quick inventory of assets in a subfolder to refine subsequent actions.
+
+Notes:
+- For /Game, the server may limit results for performance; prefer subfolders (e.g., /Game/ThirdPerson).
+- Returns a structured list with Name/Path/Class/PackagePath when available.
+
+Example:
+- {"directory":"/Game/ThirdPerson","recursive":false}`,
         inputSchema: {
             type: 'object',
             properties: {
@@ -34,7 +45,17 @@ export const toolDefinitions = [
     },
     {
         name: 'import_asset',
-        description: 'Import an asset from file system',
+        description: `Import a file from disk into the project (e.g., FBX, PNG, WAV, EXR).
+
+When to use:
+- Bring external content into /Game at a specific destination path.
+
+Notes:
+- destinationPath is a package path like /Game/Environment/Trees.
+- Keep file names simple (avoid spaces and special characters).
+
+Example:
+- {"sourcePath":"C:/Temp/Tree.fbx","destinationPath":"/Game/Environment/Trees"}`,
         inputSchema: {
             type: 'object',
             properties: {
@@ -56,7 +77,17 @@ export const toolDefinitions = [
     // Actor Tools
     {
         name: 'spawn_actor',
-        description: 'Spawn a new actor in the level',
+        description: `Spawn a new actor in the current level.
+
+When to use:
+- Place a class (e.g., StaticMeshActor, CameraActor) or spawn from an asset path (e.g., /Engine/BasicShapes/Cube).
+
+Notes:
+- If an asset path is provided, a StaticMeshActor is auto-spawned with the mesh set.
+- location/rotation are optional; defaults are used if omitted.
+
+Example:
+- {"classPath":"/Engine/BasicShapes/Cube","location":{"x":0,"y":0,"z":100}}`,
         inputSchema: {
             type: 'object',
             properties: {
@@ -91,7 +122,13 @@ export const toolDefinitions = [
     },
     {
         name: 'delete_actor',
-        description: 'Delete an actor from the level',
+        description: `Delete one or more actors by name/label.
+
+When to use:
+- Remove actors matching a label/name (case-insensitive).
+
+Example:
+- {"actorName":"Cube_1"}`,
         inputSchema: {
             type: 'object',
             properties: {
@@ -111,7 +148,13 @@ export const toolDefinitions = [
     // Material Tools
     {
         name: 'create_material',
-        description: 'Create a new material asset',
+        description: `Create a simple Material asset at a path.
+
+When to use:
+- Quickly scaffold a basic material you can edit later.
+
+Example:
+- {"name":"M_Mask","path":"/Game/Materials"}`,
         inputSchema: {
             type: 'object',
             properties: {
@@ -132,7 +175,13 @@ export const toolDefinitions = [
     },
     {
         name: 'apply_material_to_actor',
-        description: 'Apply a material to an actor in the level',
+        description: `Assign a material to an actor's mesh component.
+
+When to use:
+- Swap an actor's material by path; slotIndex defaults to 0.
+
+Example:
+- {"actorPath":"/Game/LevelActors/Cube_1","materialPath":"/Game/Materials/M_Mask","slotIndex":0}`,
         inputSchema: {
             type: 'object',
             properties: {
@@ -153,7 +202,10 @@ export const toolDefinitions = [
     // Editor Tools
     {
         name: 'play_in_editor',
-        description: 'Start Play In Editor (PIE) mode',
+        description: `Start a Play-In-Editor (PIE) session.
+
+When to use:
+- Begin simulating the level in the editor.`,
         inputSchema: {
             type: 'object',
             properties: {}
@@ -169,7 +221,10 @@ export const toolDefinitions = [
     },
     {
         name: 'stop_play_in_editor',
-        description: 'Stop Play In Editor (PIE) mode',
+        description: `Stop the active PIE session.
+
+When to use:
+- End simulation and return to the editor.`,
         inputSchema: {
             type: 'object',
             properties: {}
@@ -185,7 +240,16 @@ export const toolDefinitions = [
     },
     {
         name: 'set_camera',
-        description: 'Set viewport camera position and rotation',
+        description: `Reposition the editor viewport camera.
+
+When to use:
+- Move/aim the camera in the editor for framing.
+
+Notes:
+- Accepts object or array formats; values are normalized.
+
+Example:
+- {"location":{"x":0,"y":-600,"z":250},"rotation":{"pitch":0,"yaw":0,"roll":0}}`,
         inputSchema: {
             type: 'object',
             properties: {
@@ -220,7 +284,13 @@ export const toolDefinitions = [
     // Animation Tools
     {
         name: 'create_animation_blueprint',
-        description: 'Create an animation blueprint',
+        description: `Create an Animation Blueprint for a skeleton.
+
+When to use:
+- Generate a starter Anim BP for a given skeleton.
+
+Example:
+- {"name":"ABP_Hero","skeletonPath":"/Game/Characters/Hero/SK_Hero_Skeleton","savePath":"/Game/Characters/Hero"}`,
         inputSchema: {
             type: 'object',
             properties: {
@@ -241,7 +311,13 @@ export const toolDefinitions = [
     },
     {
         name: 'play_animation_montage',
-        description: 'Play an animation montage on an actor',
+        description: `Play a Montage/Animation on an actor.
+
+When to use:
+- Trigger a montage on a possessed or editor actor.
+
+Example:
+- {"actorName":"Hero","montagePath":"/Game/Anim/MT_Attack","playRate":1.0}`,
         inputSchema: {
             type: 'object',
             properties: {
@@ -263,7 +339,13 @@ export const toolDefinitions = [
     // Physics Tools
     {
         name: 'setup_ragdoll',
-        description: 'Setup ragdoll physics for a skeletal mesh',
+        description: `Enable simple ragdoll using a physics asset.
+
+When to use:
+- Toggle ragdoll behavior on a character skeleton.
+
+Example:
+- {"skeletonPath":"/Game/Characters/Hero/SK_Hero_Skeleton","physicsAssetName":"PHYS_Hero","blendWeight":1.0}`,
         inputSchema: {
             type: 'object',
             properties: {
@@ -284,7 +366,10 @@ export const toolDefinitions = [
     },
     {
         name: 'apply_force',
-        description: 'Apply force to an actor',
+        description: `Apply a world-space force vector to an actor with physics enabled.
+
+Example:
+- {"actorName":"PhysicsBox","force":{"x":0,"y":0,"z":5000}}`,
         inputSchema: {
             type: 'object',
             properties: {
@@ -313,7 +398,13 @@ export const toolDefinitions = [
     // Niagara Tools
     {
         name: 'create_particle_effect',
-        description: 'Create a Niagara particle effect',
+        description: `Create a simple particle/FX by tag.
+
+When to use:
+- Quickly drop a generic Fire/Smoke/Water effect for previews.
+
+Example:
+- {"effectType":"Smoke","name":"SMK1","location":{"x":100,"y":0,"z":50}}`,
         inputSchema: {
             type: 'object',
             properties: {
@@ -342,7 +433,10 @@ export const toolDefinitions = [
     },
     {
         name: 'spawn_niagara_system',
-        description: 'Spawn a Niagara system in the level',
+        description: `Spawn a Niagara system at a location.
+
+Example:
+- {"systemPath":"/Game/FX/NS_Explosion","location":{"x":0,"y":0,"z":200},"scale":1.0}`,
         inputSchema: {
             type: 'object',
             properties: {
@@ -371,7 +465,10 @@ export const toolDefinitions = [
     // Blueprint Tools
     {
         name: 'create_blueprint',
-        description: 'Create a new blueprint',
+        description: `Create a new Blueprint asset at a path.
+
+Example:
+- {"name":"BP_Switch","blueprintType":"Actor","savePath":"/Game/Blueprints"}`,
         inputSchema: {
             type: 'object',
             properties: {
@@ -392,7 +489,10 @@ export const toolDefinitions = [
     },
     {
         name: 'add_blueprint_component',
-        description: 'Add a component to a blueprint',
+        description: `Add a component to an existing Blueprint.
+
+Example:
+- {"blueprintName":"BP_Switch","componentType":"PointLightComponent","componentName":"KeyLight"}`,
         inputSchema: {
             type: 'object',
             properties: {
@@ -415,7 +515,10 @@ export const toolDefinitions = [
     // Level Tools
     {
         name: 'load_level',
-        description: 'Load a level',
+        description: `Load a level by path (e.g., /Game/Maps/Lobby).
+
+Example:
+- {"levelPath":"/Game/Maps/Lobby","streaming":false}`,
         inputSchema: {
             type: 'object',
             properties: {
@@ -435,7 +538,10 @@ export const toolDefinitions = [
     },
     {
         name: 'save_level',
-        description: 'Save the current level',
+        description: `Save the current level to a path or by name.
+
+Example:
+- {"levelName":"Lobby","savePath":"/Game/Maps"}`,
         inputSchema: {
             type: 'object',
             properties: {
@@ -454,7 +560,10 @@ export const toolDefinitions = [
     },
     {
         name: 'stream_level',
-        description: 'Stream a level in or out',
+        description: `Stream in/out a sublevel and set visibility.
+
+Example:
+- {"levelName":"Sublevel_A","shouldBeLoaded":true,"shouldBeVisible":true}`,
         inputSchema: {
             type: 'object',
             properties: {
@@ -477,7 +586,11 @@ export const toolDefinitions = [
     // Lighting Tools
     {
         name: 'create_light',
-        description: 'Create a light in the level',
+        description: `Create a light (Directional/Point/Spot/Rect/Sky) with optional transform/intensity.
+
+Examples:
+- {"lightType":"Directional","name":"KeyLight","intensity":5.0}
+- {"lightType":"Point","name":"Fill","location":{"x":0,"y":100,"z":200},"intensity":2000}`,
         inputSchema: {
             type: 'object',
             properties: {
@@ -506,7 +619,13 @@ export const toolDefinitions = [
     },
     {
         name: 'build_lighting',
-        description: 'Build lighting for the current level',
+        description: `Start a lighting build.
+
+When to use:
+- Bake lights for preview or final output (choose quality).
+
+Example:
+- {"quality":"High"}`,
         inputSchema: {
             type: 'object',
             properties: {
@@ -525,7 +644,13 @@ export const toolDefinitions = [
     // Landscape Tools
     {
         name: 'create_landscape',
-        description: 'Create a new landscape',
+        description: `Attempt to create a landscape.
+
+Notes:
+- Native Python APIs are limited; you may be guided to use Landscape Mode in the editor.
+
+Example:
+- {"name":"Landscape_Basic","sizeX":1024,"sizeY":1024}`,
         inputSchema: {
             type: 'object',
             properties: {
@@ -547,7 +672,10 @@ export const toolDefinitions = [
     },
     {
         name: 'sculpt_landscape',
-        description: 'Sculpt the landscape',
+        description: `Sculpt a landscape using editor tools (best-effort; some operations may require manual Landscape Mode).
+
+Example:
+- {"landscapeName":"Landscape_Basic","tool":"Smooth","brushSize":300,"strength":0.5}`,
         inputSchema: {
             type: 'object',
             properties: {
@@ -569,7 +697,10 @@ export const toolDefinitions = [
     // Foliage Tools
     {
         name: 'add_foliage_type',
-        description: 'Add a foliage type',
+        description: `Create or load a FoliageType asset for instanced foliage workflows.
+
+Example:
+- {"name":"FT_Grass","meshPath":"/Game/Foliage/SM_Grass","density":300}`,
         inputSchema: {
             type: 'object',
             properties: {
@@ -590,7 +721,13 @@ export const toolDefinitions = [
     },
     {
         name: 'paint_foliage',
-        description: 'Paint foliage on landscape',
+        description: `Paint foliage onto the world.
+
+When to use:
+- Scatter instances using an existing FoliageType.
+
+Example:
+- {"foliageType":"/Game/Foliage/Types/FT_Grass","position":{"x":0,"y":0,"z":0},"brushSize":300}`,
         inputSchema: {
             type: 'object',
             properties: {
@@ -619,7 +756,10 @@ export const toolDefinitions = [
     // Debug Visualization Tools
     {
         name: 'draw_debug_shape',
-        description: 'Draw a debug shape',
+        description: `Draw a debug shape.
+
+Example:
+- {"shape":"Sphere","position":{"x":0,"y":0,"z":0},"size":100,"color":[255,0,0,255],"duration":3}`,
         inputSchema: {
             type: 'object',
             properties: {
@@ -652,7 +792,10 @@ export const toolDefinitions = [
     },
     {
         name: 'set_view_mode',
-        description: 'Set the viewport view mode',
+        description: `Set the viewport view mode.
+
+Example:
+- {"mode":"Wireframe"}`,
         inputSchema: {
             type: 'object',
             properties: {
@@ -672,7 +815,10 @@ export const toolDefinitions = [
     // Performance Tools
     {
         name: 'start_profiling',
-        description: 'Start performance profiling',
+        description: `Start performance profiling.
+
+Example:
+- {"type":"GPU","duration":10}`,
         inputSchema: {
             type: 'object',
             properties: {
@@ -692,7 +838,10 @@ export const toolDefinitions = [
     },
     {
         name: 'show_fps',
-        description: 'Show FPS counter',
+        description: `Show/hide the FPS counter.
+
+Example:
+- {"enabled":true,"verbose":false}`,
         inputSchema: {
             type: 'object',
             properties: {
@@ -712,7 +861,10 @@ export const toolDefinitions = [
     },
     {
         name: 'set_scalability',
-        description: 'Set scalability settings',
+        description: `Set scalability/quality levels.
+
+Example:
+- {"category":"Shadows","level":2}`,
         inputSchema: {
             type: 'object',
             properties: {
@@ -733,7 +885,10 @@ export const toolDefinitions = [
     // Audio Tools
     {
         name: 'play_sound',
-        description: 'Play a sound',
+        description: `Play a sound.
+
+Example:
+- {"soundPath":"/Game/Audio/SFX/Click","volume":0.5,"is3D":true}`,
         inputSchema: {
             type: 'object',
             properties: {
@@ -762,7 +917,10 @@ export const toolDefinitions = [
     },
     {
         name: 'create_ambient_sound',
-        description: 'Create an ambient sound',
+        description: `Create an ambient sound actor.
+
+Example:
+- {"name":"Amb_Wind","soundPath":"/Game/Audio/Amb/AMB_Wind","location":{"x":0,"y":0,"z":0},"radius":1000}`,
         inputSchema: {
             type: 'object',
             properties: {
@@ -792,7 +950,10 @@ export const toolDefinitions = [
     // UI Tools
     {
         name: 'create_widget',
-        description: 'Create a UI widget',
+        description: `Create a UI widget.
+
+Example:
+- {"name":"HUDMain","type":"HUD","savePath":"/Game/UI"}`,
         inputSchema: {
             type: 'object',
             properties: {
@@ -813,7 +974,10 @@ export const toolDefinitions = [
     },
     {
         name: 'show_widget',
-        description: 'Show or hide a widget',
+        description: `Show or hide a widget.
+
+Example:
+- {"widgetName":"HUDMain","visible":true}`,
         inputSchema: {
             type: 'object',
             properties: {
@@ -833,7 +997,10 @@ export const toolDefinitions = [
     },
     {
         name: 'create_hud',
-        description: 'Create a HUD',
+        description: `Create a HUD description/layout.
+
+Example:
+- {"name":"GameHUD","elements":[{"type":"Text","position":[10,10]}]}`,
         inputSchema: {
             type: 'object',
             properties: {
@@ -866,7 +1033,14 @@ export const toolDefinitions = [
     // Console command (universal tool)
     {
         name: 'console_command',
-        description: 'Execute any console command in Unreal Engine',
+        description: `Execute a console command.
+
+When to use:
+- Quick toggles like "stat fps", "viewmode wireframe", or r.* cvars.
+
+Examples:
+- {"command":"stat fps"}
+- {"command":"r.ScreenPercentage 75"}`,
         inputSchema: {
             type: 'object',
             properties: {

package/dist/tools/tool-handlers.js

@@ -32,15 +32,23 @@ export async function handleToolCall(name, args, tools) {
                     message = 'Failed to list assets: directory path cannot be empty';
                     break;
                 }
+                // Normalize virtual content path: map /Content -> /Game (case-insensitive)
+                const rawDir = String(args.directory).trim();
+                let normDir = rawDir.replace(/^\/?content(\/|$)/i, '/Game$1');
+                // Ensure leading slash
+                if (!normDir.startsWith('/'))
+                    normDir = '/' + normDir;
+                // Collapse duplicate slashes
+                normDir = normDir.replace(/\\+/g, '/').replace(/\/+/g, '/');
                 // Try multiple approaches to list assets
                 try {
-                    console.log('[list_assets] Starting asset listing for directory:', args.directory);
-                    // First try: Use Python for most reliable listing
+                    console.log('[list_assets] Starting asset listing for directory:', normDir);
+                    // First try: Use Python for most reliable listing (recursive if /Game)
                     const pythonCode = `
 import unreal
 import json
 
-directory = '${args.directory || '/Game'}'
+directory = '${normDir || '/Game'}'
 # Use recursive for /Game to find assets in subdirectories, but limit depth
 recursive = True if directory == '/Game' else False
 
@@ -141,8 +149,9 @@ except Exception as e:
                             const searchResult = await tools.bridge.httpCall('/remote/search/assets', 'PUT', {
                                 Query: '', // Empty query to match all (wildcard doesn't work)
                                 Filter: {
-                                    PackagePaths: [args.directory || '/Game'],
-                                    RecursivePaths: false, // Always non-recursive
+                                    PackagePaths: [normDir || '/Game'],
+                                    // Recursively search so we actually find assets in subfolders
+                                    RecursivePaths: true,
                                     ClassNames: [], // Empty to get all types
                                     RecursiveClasses: true
                                 },
@@ -165,7 +174,7 @@ except Exception as e:
                                 functionName: 'ExecuteConsoleCommand',
                                 parameters: {
                                     WorldContextObject: null,
-                                    Command: `AssetRegistry.DumpAssets ${args.directory || '/Game'}`,
+                                    Command: `AssetRegistry.DumpAssets ${normDir || '/Game'}`,
                                     SpecificPlayer: null
                                 },
                                 generateTransaction: false
@@ -186,6 +195,24 @@ except Exception as e:
                 }
                 // Include full asset list with details in the message
                 console.log('[list_assets] Formatting message - result has assets?', !!(result && result.assets), 'count:', result?.assets?.length);
+                if (result && result.assets && result.assets.length > 0) {
+                    // If Python/HTTP gives only paths, generate Name from path
+                    result.assets = result.assets.map((asset) => {
+                        if (!asset.Name && asset.Path) {
+                            const base = String(asset.Path).split('/').pop() || '';
+                            const name = base.includes('.') ? base.split('.').pop() : base;
+                            return { ...asset, Name: name };
+                        }
+                        return asset;
+                    });
+                    // Group assets by type for better organization
+                    result.assets = result.assets.map((a) => {
+                        if (a && !a.Path && a.AssetPath) {
+                            return { ...a, Path: a.AssetPath, PackagePath: a.AssetPath.split('/').slice(0, -1).join('/') };
+                        }
+                        return a;
+                    });
+                }
                 if (result && result.assets && result.assets.length > 0) {
                     // Group assets by type for better organization
                     const assetsByType = {};
@@ -197,7 +224,7 @@ except Exception as e:
                         assetsByType[type].push(asset);
                     });
                     // Format output with proper structure
-                    let assetDetails = `📁 Asset Directory: ${args.directory || '/Game'}\n`;
+                    let assetDetails = `📁 Asset Directory: ${normDir || '/Game'}\n`;
                     assetDetails += `📊 Total Assets: ${result.assets.length}\n\n`;
                     // Sort types alphabetically
                     const sortedTypes = Object.keys(assetsByType).sort();
@@ -223,7 +250,7 @@ except Exception as e:
                     // Also keep the structured data in the result for programmatic access
                 }
                 else {
-                    message = `No assets found in ${args.directory || '/Game'}`;
+                    message = `No assets found in ${normDir || '/Game'}`;
                 }
                 break;
             case 'import_asset':
@@ -529,7 +556,13 @@ print(f"RESULT:{json.dumps(result)}")
             // Landscape Tools
             case 'create_landscape':
                 result = await tools.landscapeTools.createLandscape(args);
-                message = result.message || `Landscape ${args.name} created`;
+                // Never claim success unless the tool says so; prefer error/message from UE/Python
+                if (result && typeof result === 'object') {
+                    message = result.message || result.error || (result.success ? `Landscape ${args.name} created` : `Failed to create landscape ${args.name}`);
+                }
+                else {
+                    message = `Failed to create landscape ${args.name}`;
+                }
                 break;
             case 'sculpt_landscape':
                 result = await tools.landscapeTools.sculptLandscape(args);

package/dist/unreal-bridge.d.ts

@@ -14,6 +14,7 @@ export declare class UnrealBridge {
     private reconnectAttempts;
     private readonly MAX_RECONNECT_ATTEMPTS;
     private readonly BASE_RECONNECT_DELAY;
+    private autoReconnectEnabled;
     private commandQueue;
     private isProcessing;
     private readonly MIN_COMMAND_DELAY;
@@ -32,6 +33,7 @@ export declare class UnrealBridge {
      * @param retryDelayMs Delay between retry attempts in milliseconds
      * @returns Promise that resolves when connected or rejects after all attempts fail
      */
+    private connectPromise?;
     tryConnect(maxAttempts?: number, timeoutMs?: number, retryDelayMs?: number): Promise<boolean>;
     connect(timeoutMs?: number): Promise<void>;
     httpCall<T = any>(path: string, method?: 'GET' | 'POST' | 'PUT', body?: any): Promise<T>;
@@ -39,6 +41,7 @@ export declare class UnrealBridge {
     getExposed(): Promise<any>;
     executeConsoleCommand(command: string): Promise<any>;
     executePython(command: string): Promise<any>;
+    setAutoReconnectEnabled(enabled: boolean): void;
     private scheduleReconnect;
     disconnect(): Promise<void>;
     /**
@@ -49,7 +52,7 @@ export declare class UnrealBridge {
     /**
      * Execute Python script and parse the result
      */
-    private executePythonWithResult;
+    executePythonWithResult(script: string): Promise<any>;
     /**
      * Get the Unreal Engine version via Python and parse major/minor/patch.
      */