unreal-engine-mcp-server 0.2.1 → 0.3.0

package/src/tools/consolidated-tool-definitions.ts

@@ -1,10 +1,29 @@
-// Consolidated tool definitions - reduced from 36 to 10 multi-purpose tools
+// Consolidated tool definitions - reduced from 36 to 13 multi-purpose tools
 
 export const consolidatedToolDefinitions = [
   // 1. ASSET MANAGER - Combines asset operations
   {
     name: 'manage_asset',
-    description: 'Manage assets - list, import, create materials',
+    description: `Search, browse, import, and create simple material assets.
+
+When to use this tool:
+- You want to list assets in the project Content directory (use /Game; /Content is auto-mapped).
+- You want to import files from disk into the project (e.g., FBX, PNG, WAV, EXR).
+- You want to generate a very basic Material asset by name at a path.
+
+Supported actions:
+- list: Returns assets in a folder (recursive behavior is auto-enabled for /Game).
+- import: Imports a file into the project at a destination path (e.g., /Game/Folder).
+- create_material: Creates a simple Material asset at a path.
+
+Tips:
+- Unreal uses /Game for project content; this server maps /Content → /Game automatically.
+- For large projects, listing /Game returns a sample subset for speed; refine to subfolders.
+
+Examples:
+- {"action":"list","directory":"/Game/ThirdPerson"}
+- {"action":"import","sourcePath":"C:/Temp/Tree.fbx","destinationPath":"/Game/Environment/Trees"}
+- {"action":"create_material","name":"M_Mask","path":"/Game/Materials"}`,
     inputSchema: {
       type: 'object',
       properties: {
@@ -52,7 +71,25 @@ export const consolidatedToolDefinitions = [
   // 2. ACTOR CONTROL - Combines actor operations
   {
     name: 'control_actor',
-    description: 'Control actors - spawn, delete, apply physics. For spawning, supports both actor classes (e.g., StaticMeshActor, CameraActor) and asset paths (e.g., /Engine/BasicShapes/Cube) which will auto-spawn as StaticMeshActor',
+    description: `Spawn, delete, and apply physics to actors in the level.
+
+When to use this tool:
+- You need to place an actor or mesh in the level, remove an actor, or nudge an actor with a physics force.
+
+Spawning:
+- classPath can be a class name (e.g., StaticMeshActor, CameraActor) OR an asset path (e.g., /Engine/BasicShapes/Cube, /Game/Meshes/SM_Rock).
+- If an asset path is provided, a StaticMeshActor is auto-spawned with the mesh assigned.
+
+Deleting:
+- Finds actors by label/name (case-insensitive). Deletes matching actors.
+
+Apply force:
+- Applies a world-space force vector to an actor with physics enabled.
+
+Examples:
+- {"action":"spawn","classPath":"/Engine/BasicShapes/Cube","location":{"x":0,"y":0,"z":100}}
+- {"action":"delete","actorName":"Cube_1"}
+- {"action":"apply_force","actorName":"PhysicsBox","force":{"x":0,"y":0,"z":5000}}`,
     inputSchema: {
       type: 'object',
       properties: {
@@ -112,7 +149,20 @@ export const consolidatedToolDefinitions = [
   // 3. EDITOR CONTROL - Combines editor operations
   {
     name: 'control_editor',
-    description: 'Control editor - PIE mode, camera, viewport',
+    description: `Play/Stop PIE, position the editor camera, and switch common view modes.
+
+When to use this tool:
+- Start/stop a PIE session, move the viewport camera, or change viewmode (Lit/Unlit/Wireframe/etc.).
+
+Notes:
+- View modes are validated and unsafe modes are blocked.
+- Camera accepts location and/or rotation (both optional). Values are normalized.
+
+Examples:
+- {"action":"play"}
+- {"action":"set_camera","location":{"x":0,"y":-600,"z":250},"rotation":{"pitch":0,"yaw":0,"roll":0}}
+- {"action":"set_view_mode","viewMode":"Wireframe"}
+- {"action":"stop"}`,
     inputSchema: {
       type: 'object',
       properties: {
@@ -170,7 +220,16 @@ export const consolidatedToolDefinitions = [
   // 4. LEVEL MANAGER - Combines level and lighting operations
   {
     name: 'manage_level',
-    description: 'Manage levels and lighting',
+    description: `Load/save/stream levels, create lights, and trigger lighting builds.
+
+When to use this tool:
+- Switch to a level, save the current level, stream sublevels, add a light, or start a lighting build.
+
+Examples:
+- {"action":"load","levelPath":"/Game/Maps/Lobby"}
+- {"action":"stream","levelName":"Sublevel_A","shouldBeLoaded":true,"shouldBeVisible":true}
+- {"action":"create_light","lightType":"Directional","name":"KeyLight","intensity":5.0}
+- {"action":"build_lighting","quality":"High"}`,
     inputSchema: {
       type: 'object',
       properties: {
@@ -226,7 +285,15 @@ export const consolidatedToolDefinitions = [
   // 5. ANIMATION SYSTEM - Combines animation and physics setup
   {
     name: 'animation_physics',
-    description: 'Animation and physics systems',
+    description: `Create animation blueprints, play montages, and set up simple ragdolls.
+
+When to use this tool:
+- Generate an Anim Blueprint for a skeleton, play a Montage/Animation on an actor, or enable ragdoll.
+
+Examples:
+- {"action":"create_animation_bp","name":"ABP_Hero","skeletonPath":"/Game/Characters/Hero/SK_Hero_Skeleton","savePath":"/Game/Characters/Hero"}
+- {"action":"play_montage","actorName":"Hero","montagePath":"/Game/Anim/MT_Attack"}
+- {"action":"setup_ragdoll","skeletonPath":"/Game/Characters/Hero/SK_Hero_Skeleton","physicsAssetName":"PHYS_Hero"}`,
     inputSchema: {
       type: 'object',
       properties: {
@@ -266,7 +333,15 @@ export const consolidatedToolDefinitions = [
   // 6. EFFECTS SYSTEM - Combines particles and visual effects
   {
     name: 'create_effect',
-    description: 'Create visual effects - particles, Niagara',
+    description: `Create particles/FX and lightweight debug shapes for rapid iteration.
+
+When to use this tool:
+- Spawn a Niagara system at a location, create a particle effect by type tag, or draw debug geometry for planning.
+
+Examples:
+- {"action":"niagara","systemPath":"/Game/FX/NS_Explosion","location":{"x":0,"y":0,"z":200},"scale":1.0}
+- {"action":"particle","effectType":"Smoke","name":"SMK1","location":{"x":100,"y":0,"z":50}}
+- {"action":"debug_shape","shape":"Sphere","location":{"x":0,"y":0,"z":0},"size":100,"duration":5}`,
     inputSchema: {
       type: 'object',
       properties: {
@@ -327,7 +402,14 @@ export const consolidatedToolDefinitions = [
   // 7. BLUEPRINT MANAGER - Blueprint operations
   {
     name: 'manage_blueprint',
-    description: 'Create and modify blueprints',
+    description: `Create new Blueprints and add components programmatically.
+
+When to use this tool:
+- Quickly scaffold a Blueprint asset or add a component to an existing Blueprint.
+
+Examples:
+- {"action":"create","name":"BP_Switch","blueprintType":"Actor","savePath":"/Game/Blueprints"}
+- {"action":"add_component","name":"BP_Switch","componentType":"PointLightComponent","componentName":"KeyLight"}`,
     inputSchema: {
       type: 'object',
       properties: {
@@ -362,7 +444,19 @@ export const consolidatedToolDefinitions = [
   // 8. ENVIRONMENT BUILDER - Landscape and foliage
   {
     name: 'build_environment',
-    description: 'Build environment - landscape, foliage',
+    description: `Environment authoring helpers (landscape, foliage).
+
+When to use this tool:
+- Create a procedural terrain alternative, add/paint foliage, or attempt a landscape workflow.
+
+Important:
+- Native Landscape creation via Python is limited and may return a helpful error suggesting Landscape Mode in the editor.
+- Foliage helpers create FoliageType assets and support simple placement.
+
+Examples:
+- {"action":"create_landscape","name":"Landscape_Basic","sizeX":1024,"sizeY":1024}
+- {"action":"add_foliage","name":"FT_Grass","meshPath":"/Game/Foliage/SM_Grass","density":300}
+- {"action":"paint_foliage","foliageType":"/Game/Foliage/Types/FT_Grass","position":{"x":0,"y":0,"z":0},"brushSize":300}`,
     inputSchema: {
       type: 'object',
       properties: {
@@ -413,7 +507,16 @@ export const consolidatedToolDefinitions = [
   // 9. PERFORMANCE & AUDIO - System settings
   {
     name: 'system_control',
-    description: 'Control performance, audio, UI, screenshots, and engine lifecycle',
+    description: `Performance toggles, quality settings, audio playback, simple UI helpers, screenshots, and engine lifecycle.
+
+When to use this tool:
+- Toggle profiling and FPS stats, adjust quality (sg.*), play a sound, create/show a basic widget, take a screenshot, or launch/quit the editor.
+
+Examples:
+- {"action":"show_fps","enabled":true}
+- {"action":"set_quality","category":"Shadows","level":2}
+- {"action":"play_sound","soundPath":"/Game/Audio/SFX/Click","volume":0.5}
+- {"action":"screenshot","resolution":"1920x1080"}`,
     inputSchema: {
       type: 'object',
       properties: {
@@ -483,7 +586,19 @@ export const consolidatedToolDefinitions = [
   // 10. CONSOLE COMMAND - Universal tool
   {
     name: 'console_command',
-    description: 'Execute any console command in Unreal Engine',
+    description: `Execute an Unreal console command with built-in safety.
+
+When to use this tool:
+- Fire a specific command (e.g., stat fps, viewmode wireframe, r.ScreenPercentage 75).
+
+Safety:
+- Dangerous commands are blocked (quit/exit, GPU crash triggers, unsafe visualizebuffer modes, etc.).
+- Unknown commands will return a warning instead of crashing.
+
+Examples:
+- {"command":"stat fps"}
+- {"command":"viewmode wireframe"}
+- {"command":"r.ScreenPercentage 75"}`,
     inputSchema: {
       type: 'object',
       properties: {
@@ -507,7 +622,17 @@ export const consolidatedToolDefinitions = [
   // 11. REMOTE CONTROL PRESETS
   {
     name: 'manage_rc',
-    description: 'Manage Remote Control presets: create, expose, list fields, set/get values',
+    description: `Create and manage Remote Control presets; expose actors/properties; set/get values.
+
+When to use this tool:
+- Automate Remote Control (RC) preset authoring and interaction from the assistant.
+
+Examples:
+- {"action":"create_preset","name":"LivePreset","path":"/Game/RCPresets"}
+- {"action":"expose_actor","presetPath":"/Game/RCPresets/LivePreset","actorName":"CameraActor"}
+- {"action":"expose_property","presetPath":"/Game/RCPresets/LivePreset","objectPath":"/Script/Engine.Default__Engine","propertyName":"GameUserSettings"}
+- {"action":"list_fields","presetPath":"/Game/RCPresets/LivePreset"}
+- {"action":"set_property","objectPath":"/Game/MyActor","propertyName":"CustomFloat","value":0.5}`,
     inputSchema: {
       type: 'object',
       properties: {
@@ -542,7 +667,17 @@ export const consolidatedToolDefinitions = [
   // 12. SEQUENCER / CINEMATICS
   {
     name: 'manage_sequence',
-    description: 'Create/open sequences, add cameras/actors, manage bindings, control playback, and set properties',
+    description: `Create/open Level Sequences, bind actors, add cameras, and control playback.
+
+When to use this tool:
+- Build quick cinematics: create/open a sequence, add a camera or actors, tweak properties, and play.
+
+Examples:
+- {"action":"create","name":"Intro","path":"/Game/Cinematics"}
+- {"action":"add_camera","spawnable":true}
+- {"action":"add_actor","actorName":"Hero"}
+- {"action":"play","loopMode":"once"}
+- {"action":"set_properties","path":"/Game/Cinematics/Intro","frameRate":24,"lengthInFrames":480}`,
     inputSchema: {
       type: 'object',
       properties: {
@@ -595,7 +730,14 @@ export const consolidatedToolDefinitions = [
   // 13. INTROSPECTION
   {
     name: 'inspect',
-    description: 'Inspect objects and set properties safely',
+    description: `Read object info and set properties with validation.
+
+When to use this tool:
+- Inspect an object by path (class default object or actor/component) and optionally modify properties.
+
+Examples:
+- {"action":"inspect_object","objectPath":"/Script/Engine.Default__Engine"}
+- {"action":"set_property","objectPath":"/Game/MyActor","propertyName":"CustomBool","value":true}`,
     inputSchema: {
       type: 'object',
       properties: {

package/src/tools/consolidated-tool-handlers.ts

@@ -1,4 +1,4 @@
-// Consolidated tool handlers - maps 10 tools to all 36 operations
+// Consolidated tool handlers - maps 13 tools to all 36 operations
 import { handleToolCall } from './tool-handlers.js';
 import { cleanObject } from '../utils/safe-json.js';
 

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,7 @@ export const toolDefinitions = [
   },
   {
     name: 'build_lighting',
-    description: 'Build lighting for the current level',
+    description: 'Start a lighting build at an optional quality level (Preview/Medium/High/Production).',
     inputSchema: {
       type: 'object',
       properties: {
@@ -536,7 +649,7 @@ export const toolDefinitions = [
   // Landscape Tools
   {
     name: 'create_landscape',
-    description: 'Create a new landscape',
+    description: 'Attempt to create a landscape. Native Python APIs are limited; you may receive a guidance message to use Landscape Mode in the editor.',
     inputSchema: {
       type: 'object',
       properties: {
@@ -558,7 +671,7 @@ 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).',
     inputSchema: {
       type: 'object',
       properties: {
@@ -581,7 +694,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: {