unreal-engine-mcp-server 0.2.1 → 0.3.0

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,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: {
@@ -525,7 +638,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: {
@@ -547,7 +660,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: {
@@ -569,7 +682,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: {

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.js

@@ -191,7 +191,7 @@ print(f"RESULT:{{'success': {saved}, 'message': 'All dirty packages saved'}}")
                         try {
                             this.ws.terminate(); // Use terminate instead of close for immediate cleanup
                         }
-                        catch (e) {
+                        catch (_e) {
                             // Ignore close errors
                         }
                     }
@@ -218,7 +218,7 @@ print(f"RESULT:{{'success': {saved}, 'message': 'All dirty packages saved'}}")
                             this.ws.terminate();
                         }
                     }
-                    catch (e) {
+                    catch (_e) {
                         // Ignore close errors
                     }
                     this.ws = undefined;

package/dist/utils/response-validator.js

@@ -29,8 +29,8 @@ export class ResponseValidator {
             this.validators.set(toolName, validator);
             log.info(`Registered output schema for tool: ${toolName}`);
         }
-        catch (error) {
-            log.error(`Failed to compile output schema for ${toolName}:`, error);
+        catch (_error) {
+            log.error(`Failed to compile output schema for ${toolName}:`, _error);
         }
     }
     /**
@@ -86,7 +86,7 @@ export class ResponseValidator {
                 JSON.stringify(response);
             }
         }
-        catch (error) {
+        catch (_error) {
             log.error(`Response for ${toolName} contains circular references, cleaning...`);
             response = cleanObject(response);
         }

package/dist/utils/safe-json.js

@@ -1,7 +1,7 @@
 // Utility to safely serialize objects with circular references
 export function safeStringify(obj, space) {
     const seen = new WeakSet();
-    return JSON.stringify(obj, (key, value) => {
+    return JSON.stringify(obj, (_key, value) => {
         // Handle undefined, functions, symbols
         if (value === undefined || typeof value === 'function' || typeof value === 'symbol') {
             return undefined;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "unreal-engine-mcp-server",
-  "version": "0.2.1",
+"version": "0.3.0",
   "description": "Production-ready MCP server for Unreal Engine integration with consolidated and individual tool modes",
   "type": "module",
   "main": "dist/index.js",
@@ -11,16 +11,11 @@
   "scripts": {
     "build": "tsc -p tsconfig.json",
     "start": "node dist/index.js",
-    "test:live": "node test-introspection-live.js",
     "dev": "ts-node-esm src/index.ts",
     "lint": "eslint . --ext .ts",
     "lint:fix": "eslint . --ext .ts --fix",
     "clean": "rimraf dist",
-    "prepare": "npm run build",
-    "test": "vitest run",
-    "test:watch": "vitest",
-    "test:coverage": "vitest run --coverage",
-    "test:tool4": "vitest run src/tests/consolidated-tool-4.test.ts"
+    "prepare": "npm run build"
   },
   "engines": {
     "node": ">=18"
@@ -52,12 +47,10 @@
     "@types/ws": "^8.5.10",
     "@typescript-eslint/eslint-plugin": "^8.43.0",
     "@typescript-eslint/parser": "^8.43.0",
-    "@vitest/coverage-v8": "^1.6.0",
     "cross-env": "^10.0.0",
     "eslint": "^8.57.0",
     "rimraf": "^6.0.1",
     "ts-node": "^10.9.2",
-    "typescript": "^5.4.5",
-    "vitest": "^1.6.0"
+    "typescript": "^5.4.5"
   }
 }

package/server.json

@@ -2,13 +2,13 @@
   "$schema": "https://static.modelcontextprotocol.io/schemas/2025-07-09/server.schema.json",
   "name": "io.github.ChiR24/unreal-engine-mcp",
   "description": "Production-ready MCP server for Unreal Engine with comprehensive game development tools",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "packages": [
     {
       "registry_type": "npm",
       "registry_base_url": "https://registry.npmjs.org",
       "identifier": "unreal-engine-mcp-server",
-      "version": "0.2.1",
+      "version": "0.3.0",
       "transport": {
         "type": "stdio"
       },

package/src/index.ts

@@ -43,7 +43,7 @@ import {
 import { responseValidator } from './utils/response-validator.js';
 import { ErrorHandler } from './utils/error-handler.js';
 import { routeStdoutLogsToStderr } from './utils/stdio-redirect.js';
-import { sanitizeResponse, cleanObject } from './utils/safe-json.js';
+import { cleanObject } from './utils/safe-json.js';
 
 const log = new Logger('UE-MCP');
 
@@ -77,14 +77,14 @@ const metrics: PerformanceMetrics = {
 
 // Configuration
 const CONFIG = {
-  // Tool mode: true = consolidated (10 tools), false = individual (36+ tools)
+  // Tool mode: true = consolidated (13 tools), false = individual (36+ tools)
   USE_CONSOLIDATED_TOOLS: process.env.USE_CONSOLIDATED_TOOLS !== 'false',
   // Connection retry settings
   MAX_RETRY_ATTEMPTS: 3,
   RETRY_DELAY_MS: 2000,
   // Server info
   SERVER_NAME: 'unreal-engine-mcp',
-  SERVER_VERSION: '0.2.1',
+  SERVER_VERSION: '0.3.0',
   // Monitoring
   HEALTH_CHECK_INTERVAL_MS: 30000 // 30 seconds
 };
@@ -382,7 +382,7 @@ export async function createServer() {
     throw new Error(`Unknown resource: ${uri}`);
   });
 
-  // Handle tool listing - switch between consolidated (10) or individual (36) tools
+  // Handle tool listing - switch between consolidated (13) or individual (36) tools
   server.setRequestHandler(ListToolsRequestSchema, async () => {
     log.info(`Serving ${CONFIG.USE_CONSOLIDATED_TOOLS ? 'consolidated' : 'individual'} tools`);
     return {
@@ -390,7 +390,7 @@ export async function createServer() {
     };
   });
 
-  // Handle tool calls - switch between consolidated (10) or individual (36) tools
+  // Handle tool calls - switch between consolidated (13) or individual (36) tools
   server.setRequestHandler(CallToolRequestSchema, async (request) => {
     const { name, arguments: args } = request.params;
     const startTime = Date.now();

package/src/resources/assets.ts

@@ -10,10 +10,10 @@ export class AssetResources {
     return page !== undefined ? `${dir}::${recursive ? 1 : 0}::${page}` : `${dir}::${recursive ? 1 : 0}`; 
   }
 
-  async list(dir = '/Game', recursive = false, limit = 50) {
+  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
+    _recursive = false; // Force non-recursive
     
     // Cache fast-path
     try {
@@ -105,7 +105,7 @@ export class AssetResources {
    * Directory-based listing for paths with too many assets
    * Shows only immediate children (folders and files) to avoid timeouts
    */
-  private async listDirectoryOnly(dir: string, recursive: boolean, limit: number) {
+  private async listDirectoryOnly(dir: string, _recursive: boolean, limit: number) {
     // Always return only immediate children to avoid timeout and improve navigation
     try {
       const py = `