unreal-engine-mcp-server 0.2.1 → 0.3.1

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,35 @@ 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:
+- Place an actor/mesh, remove an actor, or nudge an actor with a physics force.
+
+Supported actions:
+- spawn
+- delete
+- apply_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).
+- Asset paths auto-spawn StaticMeshActor with the mesh assigned.
+
+Deleting:
+- Finds actors by label/name (case-insensitive) and deletes matches.
+
+Apply force:
+- Applies a world-space force vector to an actor with physics enabled.
+
+Tips:
+- classPath accepts classes or asset paths; simple names like Cube auto-resolve to engine assets.
+- location/rotation are optional; defaults are used if omitted.
+- For delete/apply_force, provide actorName.
+
+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 +159,26 @@ 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.).
+
+Supported actions:
+- play
+- stop
+- set_camera
+- set_view_mode
+
+Notes:
+- View modes are validated; unsafe modes are blocked.
+- Camera accepts location/rotation (optional); values 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 +236,28 @@ 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.
+
+Supported actions:
+- load
+- save
+- stream
+- create_light
+- build_lighting
+
+Tips:
+- Use /Game paths for levels (e.g., /Game/Maps/Level).
+- For streaming, set shouldBeLoaded and shouldBeVisible accordingly.
+- For lights, provide lightType and optional location/intensity.
+
+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 +313,25 @@ 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.
+
+Supported actions:
+- create_animation_bp
+- play_montage
+- setup_ragdoll
+
+Tips:
+- Ensure the montage/animation is compatible with the target actor/skeleton.
+- setup_ragdoll requires a valid physicsAssetName on the skeleton.
+- Use savePath when creating new assets.
+
+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 +371,24 @@ 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.
+
+Supported actions:
+- particle
+- niagara
+- debug_shape
+
+Tips:
+- Set color as RGBA [r,g,b,a]; scale defaults to 1 if omitted.
+- Use debug shapes for quick layout planning and measurements.
+
+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 +449,22 @@ 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.
+
+Supported actions:
+- create
+- add_component
+
+Tips:
+- blueprintType can be Actor, Pawn, Character, etc.
+- Component names should be unique within the 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 +499,28 @@ 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.
+
+Supported actions:
+- create_landscape
+- sculpt
+- add_foliage
+- paint_foliage
+
+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.
+
+Tips:
+- Adjust brushSize and strength to tune sculpting results.
+
+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 +571,31 @@ 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.
+
+Supported actions:
+- profile
+- show_fps
+- set_quality
+- play_sound
+- create_widget
+- show_widget
+- screenshot
+- engine_start
+- engine_quit
+
+Tips:
+- Screenshot resolution format: 1920x1080.
+- engine_start can read UE project path from env; provide editorExe/projectPath if needed.
+
+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 +665,22 @@ 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.
+
+Tips:
+- Prefer dedicated tools (system_control, control_editor) when available for structured control.
+
+Examples:
+- {"command":"stat fps"}
+- {"command":"viewmode wireframe"}
+- {"command":"r.ScreenPercentage 75"}`,
     inputSchema: {
       type: 'object',
       properties: {
@@ -507,7 +704,29 @@ 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.
+
+Supported actions:
+- create_preset
+- expose_actor
+- expose_property
+- list_fields
+- set_property
+- get_property
+
+Tips:
+- value must be JSON-serializable.
+- Use objectPath/presetPath with full asset/object paths.
+
+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 +761,37 @@ 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.
+
+Supported actions:
+- create
+- open
+- add_camera
+- add_actor
+- add_actors
+- remove_actors
+- get_bindings
+- add_spawnable_from_class
+- play
+- pause
+- stop
+- set_properties
+- get_properties
+- set_playback_speed
+
+Tips:
+- Set spawnable=true to auto-create a camera actor.
+- Use frameRate/lengthInFrames to define timing; use playbackStart/End to trim.
+
+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 +844,22 @@ 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.
+
+Supported actions:
+- inspect_object
+- set_property
+
+Tips:
+- propertyName is case-sensitive; ensure it exists on the target object.
+- For class default objects (CDOs), use the /Script/...Default__Class path.
+
+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,6 +1,9 @@
-// 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';
+import { Logger } from '../utils/logger.js';
+
+const log = new Logger('ConsolidatedToolHandler');
 
 export async function handleConsolidatedToolCall(
   name: string,
@@ -8,7 +11,8 @@ export async function handleConsolidatedToolCall(
   tools: any
 ) {
   const startTime = Date.now();
-  console.log(`[ConsolidatedToolHandler] Starting execution of ${name} at ${new Date().toISOString()}`);
+  // Use scoped logger (stderr) to avoid polluting stdout JSON
+  log.debug(`Starting execution of ${name} at ${new Date().toISOString()}`);
   
   try {
     // Validate args is not null/undefined