unreal-engine-mcp-server 0.2.1 → 0.3.1

package/src/tools/tool-definitions.ts

@@ -4,7 +4,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: {
@@ -35,7 +46,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: {
@@ -58,7 +79,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: {
@@ -93,7 +124,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: {
@@ -114,7 +151,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: {
@@ -135,7 +178,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: {
@@ -157,7 +206,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: {}
@@ -173,7 +225,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: {}
@@ -189,7 +244,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: {
@@ -225,7 +289,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: {
@@ -246,7 +316,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: {
@@ -269,7 +345,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: {
@@ -290,7 +372,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: {
@@ -320,7 +405,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: {
@@ -349,7 +440,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: {
@@ -379,7 +473,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: {
@@ -400,7 +497,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: {
@@ -424,7 +524,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: {
@@ -444,7 +547,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: {
@@ -463,7 +569,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: {
@@ -487,7 +596,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: {
@@ -516,7 +629,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: {
@@ -536,7 +655,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: {
@@ -558,7 +683,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: {
@@ -581,7 +709,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: {
@@ -602,7 +733,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: {
@@ -632,7 +769,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: {
@@ -665,7 +805,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: {
@@ -686,7 +829,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: {
@@ -706,7 +852,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: {
@@ -726,7 +875,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: {
@@ -748,7 +900,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: {
@@ -777,7 +932,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: {
@@ -808,7 +966,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: {
@@ -829,7 +990,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: {
@@ -849,7 +1013,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: {
@@ -883,7 +1050,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/src/tools/tool-handlers.ts

@@ -86,16 +86,24 @@ export async function handleToolCall(
           break;
         }
         
+        // Normalize virtual content path: map /Content -> /Game (case-insensitive)
+        const rawDir: string = 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);
+          console.log('[list_assets] Starting asset listing for directory:', normDir);
           
-          // First try: Use Python for most reliable listing
+          // 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
 
@@ -197,8 +205,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
                 },
@@ -222,7 +231,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
@@ -244,6 +253,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: any) => {
+            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: any) => {
+            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: { [key: string]: any[] } = {};
@@ -257,7 +284,7 @@ except Exception as e:
           });
           
           // 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
@@ -287,7 +314,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;
       
@@ -611,7 +638,12 @@ 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':