unreal-engine-mcp-server 0.3.1 → 0.4.3

package/dist/utils/validation.js

@@ -1,6 +1,7 @@
 /**
  * Validation and sanitization utilities for Unreal Engine assets
  */
+import { toRotTuple, toVec3Tuple } from './normalize.js';
 /**
  * Maximum path length allowed in Unreal Engine
  */
@@ -63,12 +64,22 @@ export function sanitizePath(path) {
     if (!path || typeof path !== 'string') {
         return '/Game';
     }
+    // Normalize slashes
+    path = path.replace(/\\/g, '/');
     // Ensure path starts with /
     if (!path.startsWith('/')) {
         path = `/${path}`;
     }
     // Split path into segments and sanitize each
-    const segments = path.split('/').filter(s => s.length > 0);
+    let segments = path.split('/').filter(s => s.length > 0);
+    if (segments.length === 0) {
+        return '/Game';
+    }
+    // Ensure the first segment is a valid root (Game, Engine, Script, Temp)
+    const ROOTS = new Set(['Game', 'Engine', 'Script', 'Temp']);
+    if (!ROOTS.has(segments[0])) {
+        segments = ['Game', ...segments];
+    }
     const sanitizedSegments = segments.map(segment => {
         // Don't sanitize Game, Engine, or other root folders
         if (['Game', 'Engine', 'Script', 'Temp'].includes(segment)) {
@@ -139,10 +150,14 @@ export function resolveSkeletalMeshPath(input) {
     }
     // Common skeleton to mesh mappings
     const skeletonToMeshMap = {
-        '/Game/Mannequin/Character/Mesh/UE4_Mannequin_Skeleton': '/Game/Characters/Mannequins/Meshes/SKM_Manny',
-        '/Game/Characters/Mannequins/Meshes/SK_Mannequin': '/Game/Characters/Mannequins/Meshes/SKM_Manny',
-        '/Game/Mannequin/Character/Mesh/SK_Mannequin': '/Game/Characters/Mannequins/Meshes/SKM_Manny',
-        '/Game/Characters/Mannequin_UE4/Meshes/UE4_Mannequin_Skeleton': '/Game/Characters/Mannequins/Meshes/SKM_Quinn',
+        '/Game/Mannequin/Character/Mesh/UE4_Mannequin_Skeleton': '/Game/Characters/Mannequins/Meshes/SKM_Manny_Simple',
+        '/Game/Characters/Mannequins/Meshes/SK_Mannequin': '/Game/Characters/Mannequins/Meshes/SKM_Manny_Simple',
+        '/Game/Mannequin/Character/Mesh/SK_Mannequin': '/Game/Characters/Mannequins/Meshes/SKM_Manny_Simple',
+        '/Game/Characters/Mannequin_UE4/Meshes/UE4_Mannequin_Skeleton': '/Game/Characters/Mannequins/Meshes/SKM_Quinn_Simple',
+        '/Game/Characters/Mannequins/Skeletons/UE5_Mannequin_Skeleton': '/Game/Characters/Mannequins/Meshes/SKM_Manny_Simple',
+        '/Game/Characters/Mannequins/Skeletons/UE5_Female_Mannequin_Skeleton': '/Game/Characters/Mannequins/Meshes/SKM_Quinn_Simple',
+        '/Game/Characters/Mannequins/Skeletons/UE5_Manny_Skeleton': '/Game/Characters/Mannequins/Meshes/SKM_Manny_Simple',
+        '/Game/Characters/Mannequins/Skeletons/UE5_Quinn_Skeleton': '/Game/Characters/Mannequins/Meshes/SKM_Quinn_Simple'
     };
     // Check if this is a known skeleton path
     if (skeletonToMeshMap[input]) {
@@ -152,8 +167,16 @@ export function resolveSkeletalMeshPath(input) {
     if (input.includes('_Skeleton')) {
         // Try common replacements
         let meshPath = input.replace('_Skeleton', '');
-        meshPath = meshPath.replace('/SK_', '/SKM_');
-        meshPath = meshPath.replace('UE4_Mannequin', 'SKM_Manny');
+        // Mapping for replacements
+        const replacements = {
+            '/SK_': '/SKM_',
+            'UE4_Mannequin': 'SKM_Manny',
+            'UE5_Mannequin': 'SKM_Manny',
+            'UE5_Manny': 'SKM_Manny',
+            'UE5_Quinn': 'SKM_Quinn'
+        };
+        // Apply all replacements using regex
+        meshPath = meshPath.replace(new RegExp(Object.keys(replacements).join('|'), 'g'), match => replacements[match]);
         return meshPath;
     }
     // If it starts with SK_ (skeleton prefix), try SKM_ (skeletal mesh prefix)
@@ -170,4 +193,44 @@ export function resolveSkeletalMeshPath(input) {
 export async function concurrencyDelay(ms = 100) {
     return new Promise(resolve => setTimeout(resolve, ms));
 }
+/**
+ * Ensure the provided value is a finite number within optional bounds.
+ * @throws if the value is not a finite number or violates bounds
+ */
+export function validateNumber(value, label, { min, max, allowZero = true } = {}) {
+    if (typeof value !== 'number' || !Number.isFinite(value)) {
+        throw new Error(`Invalid ${label}: expected a finite number`);
+    }
+    if (!allowZero && value === 0) {
+        throw new Error(`Invalid ${label}: zero is not allowed`);
+    }
+    if (typeof min === 'number' && value < min) {
+        throw new Error(`Invalid ${label}: must be >= ${min}`);
+    }
+    if (typeof max === 'number' && value > max) {
+        throw new Error(`Invalid ${label}: must be <= ${max}`);
+    }
+    return value;
+}
+/**
+ * Validate an array (tuple) of finite numbers, preserving the original shape.
+ * @throws if the tuple has the wrong length or contains invalid values
+ */
+export function ensureVector3(value, label) {
+    const tuple = toVec3Tuple(value);
+    if (!tuple) {
+        throw new Error(`Invalid ${label}: expected an object with x,y,z or an array of 3 numbers`);
+    }
+    return tuple;
+}
+export function ensureColorRGB(value, label) {
+    return ensureVector3(value, label);
+}
+export function ensureRotation(value, label) {
+    const tuple = toRotTuple(value);
+    if (!tuple) {
+        throw new Error(`Invalid ${label}: expected an object with pitch,yaw,roll or an array of 3 numbers`);
+    }
+    return tuple;
+}
 //# sourceMappingURL=validation.js.map

package/mcp-config-example.json

@@ -5,8 +5,8 @@
       "args": ["PATH_TO/unreal-engine-mcp-server/dist/cli.js"],
       "env": {
         "UE_HOST": "127.0.0.1",
-        "UE_RC_WS_PORT": "30010",
-        "UE_RC_HTTP_PORT": "30020",
+        "UE_RC_HTTP_PORT": "30010",
+        "UE_RC_WS_PORT": "30020",
         "UE_PROJECT_PATH": "C:/Users/YourName/Documents/Unreal Projects/YourProject"
       }
     }

package/package.json

@@ -1,7 +1,8 @@
 {
   "name": "unreal-engine-mcp-server",
-  "version": "0.3.1",
-  "description": "Production-ready MCP server for Unreal Engine integration with consolidated and individual tool modes",
+  "version": "0.4.3",
+  "mcpName": "io.github.ChiR24/unreal-engine-mcp",
+  "description": "Production-ready MCP server for Unreal Engine integration with 13 tools",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -15,7 +16,8 @@
     "lint": "eslint . --ext .ts",
     "lint:fix": "eslint . --ext .ts --fix",
     "clean": "rimraf dist",
-    "prepare": "npm run build"
+    "prepare": "npm run build",
+    "test:tools": "node tests/run-unreal-tool-tests.mjs"
   },
   "engines": {
     "node": ">=18"
@@ -32,22 +34,21 @@
   ],
   "author": "Unreal Engine MCP Team",
   "license": "MIT",
-  "mcpName": "io.github.ChiR24/unreal-engine-mcp",
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.4.0",
-    "ajv": "^8.12.0",
-    "axios": "^1.7.2",
+    "@modelcontextprotocol/sdk": "^1.18.2",
+    "ajv": "^8.17.1",
+    "axios": "^1.12.2",
     "dotenv": "^16.4.5",
+    "json5": "^2.2.3",
     "ws": "^8.18.0",
-    "yargs": "^17.7.2",
-    "zod": "^3.22.4"
+    "yargs": "^17.7.2"
   },
   "devDependencies": {
+    "@types/json5": "^0.0.30",
     "@types/node": "^20.12.7",
     "@types/ws": "^8.5.10",
     "@typescript-eslint/eslint-plugin": "^8.43.0",
     "@typescript-eslint/parser": "^8.43.0",
-    "cross-env": "^10.0.0",
     "eslint": "^8.57.0",
     "rimraf": "^6.0.1",
     "ts-node": "^10.9.2",

package/server.json

@@ -1,35 +1,41 @@
 {
-  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-07-09/server.schema.json",
+  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-09-16/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.3.1",
+  "description": "MCP server for Unreal Engine 5 with 13 tools for game development automation.",
+  "version": "0.4.3",
   "packages": [
     {
-      "registry_type": "npm",
-      "registry_base_url": "https://registry.npmjs.org",
+      "registryType": "npm",
+      "registryBaseUrl": "https://registry.npmjs.org",
       "identifier": "unreal-engine-mcp-server",
-      "version": "0.3.1",
+      "version": "0.4.3",
       "transport": {
         "type": "stdio"
       },
-      "environment_variables": [
+      "environmentVariables": [
         {
           "name": "UE_HOST",
-          "description": "Unreal Engine host address",
-          "is_required": false,
+          "description": "Unreal Engine host address (default: 127.0.0.1)",
+          "isRequired": false,
           "value": "127.0.0.1"
         },
         {
           "name": "UE_RC_HTTP_PORT",
-          "description": "Remote Control HTTP port",
-          "is_required": false,
+          "description": "Remote Control HTTP port (default: 30010)",
+          "isRequired": false,
           "value": "30010"
         },
         {
           "name": "UE_RC_WS_PORT",
-          "description": "Remote Control WebSocket port",
-          "is_required": false,
+          "description": "Remote Control WebSocket port (default: 30020)",
+          "isRequired": false,
           "value": "30020"
+        },
+        {
+          "name": "LOG_LEVEL",
+          "description": "Logging level: debug, info, warn, error (default: info)",
+          "isRequired": false,
+          "value": "info"
         }
       ]
     }
@@ -40,12 +46,26 @@
     "modelcontextprotocol",
     "unreal-engine",
     "ue5",
+    "ue6",
     "game-development",
     "remote-control",
     "automation",
     "3d",
     "gamedev",
-    "cinematics"
+    "cinematics",
+    "level-design",
+    "animation",
+    "physics",
+    "niagara",
+    "vfx",
+    "blueprint",
+    "lighting",
+    "rendering",
+    "play-in-editor",
+    "asset-management",
+    "actor-control",
+    "sequencer",
+    "production"
   ],
   "author": "ChiR24",
   "homepage": "https://github.com/ChiR24/Unreal_mcp",
@@ -54,6 +74,9 @@
     "url": "https://github.com/ChiR24/Unreal_mcp.git",
     "source": "github"
   },
+  "bugs": {
+    "url": "https://github.com/ChiR24/Unreal_mcp/issues"
+  },
   "engines": {
     "node": ">=18"
   }

package/src/index.ts

@@ -17,6 +17,7 @@ import { BlueprintTools } from './tools/blueprint.js';
 import { LevelTools } from './tools/level.js';
 import { LightingTools } from './tools/lighting.js';
 import { LandscapeTools } from './tools/landscape.js';
+import { BuildEnvironmentAdvanced } from './tools/build_environment_advanced.js';
 import { FoliageTools } from './tools/foliage.js';
 import { DebugVisualizationTools } from './tools/debug.js';
 import { PerformanceTools } from './tools/performance.js';
@@ -27,8 +28,6 @@ import { SequenceTools } from './tools/sequence.js';
 import { IntrospectionTools } from './tools/introspection.js';
 import { VisualTools } from './tools/visual.js';
 import { EngineTools } from './tools/engine.js';
-import { toolDefinitions } from './tools/tool-definitions.js';
-import { handleToolCall } from './tools/tool-handlers.js';
 import { consolidatedToolDefinitions } from './tools/consolidated-tool-definitions.js';
 import { handleConsolidatedToolCall } from './tools/consolidated-tool-handlers.js';
 import { prompts } from './prompts/index.js';
@@ -44,6 +43,7 @@ import { responseValidator } from './utils/response-validator.js';
 import { ErrorHandler } from './utils/error-handler.js';
 import { routeStdoutLogsToStderr } from './utils/stdio-redirect.js';
 import { cleanObject } from './utils/safe-json.js';
+import { createElicitationHelper } from './utils/elicitation.js';
 
 const log = new Logger('UE-MCP');
 
@@ -81,14 +81,13 @@ let lastHealthSuccessAt = 0;
 
 // Configuration
 const CONFIG = {
-  // Tool mode: true = consolidated (13 tools), false = individual (36+ tools)
-  USE_CONSOLIDATED_TOOLS: process.env.USE_CONSOLIDATED_TOOLS !== 'false',
+  // Tooling: use consolidated tools only (13 tools)
   // Connection retry settings
   MAX_RETRY_ATTEMPTS: 3,
   RETRY_DELAY_MS: 2000,
   // Server info
   SERVER_NAME: 'unreal-engine-mcp',
-  SERVER_VERSION: '0.3.1',
+  SERVER_VERSION: '0.4.3',
   // Monitoring
   HEALTH_CHECK_INTERVAL_MS: 30000 // 30 seconds
 };
@@ -149,9 +148,9 @@ export async function createServer() {
   // Disable auto-reconnect loops; connect only on-demand
   bridge.setAutoReconnectEnabled(false);
   
-  // Initialize response validation with schemas
+// Initialize response validation with schemas
   log.debug('Initializing response validation...');
-  const toolDefs = CONFIG.USE_CONSOLIDATED_TOOLS ? consolidatedToolDefinitions : toolDefinitions;
+  const toolDefs = consolidatedToolDefinitions;
   toolDefs.forEach((tool: any) => {
     if (tool.outputSchema) {
       responseValidator.registerSchema(tool.name, tool.outputSchema);
@@ -227,6 +226,7 @@ export async function createServer() {
   const lightingTools = new LightingTools(bridge);
   const landscapeTools = new LandscapeTools(bridge);
   const foliageTools = new FoliageTools(bridge);
+  const buildEnvAdvanced = new BuildEnvironmentAdvanced(bridge);
   const debugTools = new DebugVisualizationTools(bridge);
   const performanceTools = new PerformanceTools(bridge);
   const audioTools = new AudioTools(bridge);
@@ -246,12 +246,39 @@ export async function createServer() {
       capabilities: {
         resources: {},
         tools: {},
-        prompts: {},
-        logging: {}
+        prompts: {
+          listChanged: false
+        },
+        logging: {},
+        elicitation: {}
       }
     }
   );
 
+  // Optional elicitation helper – used only if client supports it.
+  const elicitation = createElicitationHelper(server as any, log);
+  const defaultElicitationTimeoutMs = elicitation.getDefaultTimeoutMs();
+
+  const createNotConnectedResponse = (toolName: string) => {
+    const payload = {
+      success: false,
+      error: 'UE_NOT_CONNECTED',
+      message: 'Unreal Engine is not connected (after 3 attempts). Please open UE and try again.',
+      retriable: false,
+      scope: `tool-call/${toolName}`
+    } as const;
+
+    return responseValidator.wrapResponse(toolName, {
+      ...payload,
+      content: [
+        {
+          type: 'text',
+          text: JSON.stringify(payload, null, 2)
+        }
+      ]
+    });
+  };
+
   // Handle resource listing
   server.setRequestHandler(ListResourcesRequestSchema, async () => {
     return {
@@ -433,34 +460,28 @@ export async function createServer() {
     throw new Error(`Unknown resource: ${uri}`);
   });
 
-  // Handle tool listing - switch between consolidated (13) or individual (36) tools
+// Handle tool listing - consolidated tools only
   server.setRequestHandler(ListToolsRequestSchema, async () => {
-    log.info(`Serving ${CONFIG.USE_CONSOLIDATED_TOOLS ? 'consolidated' : 'individual'} tools`);
+    log.info('Serving consolidated tools');
     return {
-      tools: CONFIG.USE_CONSOLIDATED_TOOLS ? consolidatedToolDefinitions : toolDefinitions
+      tools: consolidatedToolDefinitions
     };
   });
 
-  // Handle tool calls - switch between consolidated (13) or individual (36) tools
+  // Handle tool calls - consolidated tools only (13)
   server.setRequestHandler(CallToolRequestSchema, async (request) => {
-    const { name, arguments: args } = request.params;
+    const { name } = request.params;
+    let args: any = request.params.arguments || {};
     const startTime = Date.now();
 
     // Ensure connection only when needed, with 3 attempts
     const connected = await ensureConnectedOnDemand();
     if (!connected) {
-      const notConnected = {
-        content: [{ type: 'text', text: 'Unreal Engine is not connected (after 3 attempts). Please open UE and try again.' }],
-        success: false,
-        error: 'UE_NOT_CONNECTED',
-        retriable: false,
-        scope: `tool-call/${name}`
-      } as any;
       trackPerformance(startTime, false);
-      return notConnected;
+      return createNotConnectedResponse(name);
     }
     
-    // Create tools object for handler
+// Create tools object for handler
     const tools = {
       actorTools,
       assetTools,
@@ -474,6 +495,7 @@ export async function createServer() {
       lightingTools,
       landscapeTools,
       foliageTools,
+      buildEnvAdvanced,
       debugTools,
       performanceTools,
       audioTools,
@@ -483,19 +505,81 @@ export async function createServer() {
       introspectionTools,
       visualTools,
       engineTools,
+      // Elicitation (client-optional)
+      elicit: elicitation.elicit,
+      supportsElicitation: elicitation.supports,
+  elicitationTimeoutMs: defaultElicitationTimeoutMs,
+      // Resources for listing and info
+      assetResources,
+      actorResources,
+      levelResources,
       bridge
     };
     
-    // Use consolidated or individual handler based on configuration
+// Execute consolidated tool handler
     try {
       log.debug(`Executing tool: ${name}`);
       
-      let result;
-      if (CONFIG.USE_CONSOLIDATED_TOOLS) {
-        result = await handleConsolidatedToolCall(name, args, tools);
-      } else {
-        result = await handleToolCall(name, args, tools);
+      // Opportunistic generic elicitation for missing primitive required fields
+      try {
+        const toolDef: any = (consolidatedToolDefinitions as any[]).find(t => t.name === name);
+        const inputSchema: any = toolDef?.inputSchema;
+        const elicitFn: any = (tools as any).elicit;
+        if (inputSchema && typeof elicitFn === 'function') {
+          const props = inputSchema.properties || {};
+          const required: string[] = Array.isArray(inputSchema.required) ? inputSchema.required : [];
+          const missing = required.filter((k: string) => {
+            const v = (args as any)[k];
+            if (v === undefined || v === null) return true;
+            if (typeof v === 'string' && v.trim() === '') return true;
+            return false;
+          });
+
+          // Build a flat primitive-only schema subset per MCP Elicitation rules
+          const primitiveProps: any = {};
+          for (const k of missing) {
+            const p = props[k];
+            if (!p || typeof p !== 'object') continue;
+            const t = (p.type || '').toString();
+            const isEnum = Array.isArray(p.enum);
+            if (t === 'string' || t === 'number' || t === 'integer' || t === 'boolean' || isEnum) {
+              primitiveProps[k] = {
+                type: t || (isEnum ? 'string' : undefined),
+                title: p.title,
+                description: p.description,
+                enum: p.enum,
+                enumNames: p.enumNames,
+                minimum: p.minimum,
+                maximum: p.maximum,
+                minLength: p.minLength,
+                maxLength: p.maxLength,
+                pattern: p.pattern,
+                format: p.format,
+                default: p.default
+              };
+            }
+          }
+
+          if (Object.keys(primitiveProps).length > 0) {
+            const elicitOptions: any = { fallback: async () => ({ ok: false, error: 'missing-params' }) };
+            if (typeof (tools as any).elicitationTimeoutMs === 'number' && Number.isFinite((tools as any).elicitationTimeoutMs)) {
+              elicitOptions.timeoutMs = (tools as any).elicitationTimeoutMs;
+            }
+            const elicitRes = await elicitFn(
+              `Provide missing parameters for ${name}`,
+              { type: 'object', properties: primitiveProps, required: Object.keys(primitiveProps) },
+              elicitOptions
+            );
+            if (elicitRes && elicitRes.ok && elicitRes.value) {
+              args = { ...args, ...elicitRes.value };
+            }
+          }
+        }
+      } catch (e) {
+        log.debug('Generic elicitation prefill skipped', { err: (e as any)?.message || String(e) });
       }
+
+      let result = await handleConsolidatedToolCall(name, args, tools);
       
       log.debug(`Tool ${name} returned result`);
       
@@ -531,14 +615,25 @@ export async function createServer() {
         });
         if (metrics.recentErrors.length > 20) metrics.recentErrors.splice(0, metrics.recentErrors.length - 20);
       } catch {}
-      
-      return {
+
+      const sanitizedError = cleanObject(errorResponse);
+      let errorText = '';
+      try {
+        errorText = JSON.stringify(sanitizedError, null, 2);
+      } catch {
+        errorText = sanitizedError.message || errorResponse.message || `Failed to execute ${name}`;
+      }
+
+      const wrappedError = {
+        ...sanitizedError,
+        isError: true,
         content: [{
           type: 'text',
-          text: errorResponse.message || `Failed to execute ${name}`
-        }],
-        ...errorResponse
+          text: errorText
+        }]
       };
+
+      return responseValidator.wrapResponse(name, wrappedError);
     }
   });
 
@@ -548,11 +643,18 @@ export async function createServer() {
       prompts: prompts.map(p => ({
         name: p.name,
         description: p.description,
-        arguments: Object.entries(p.arguments || {}).map(([name, schema]) => ({
-          name,
-          description: schema.description,
-          required: schema.required || false
-        }))
+        arguments: Object.entries(p.arguments || {}).map(([name, schema]) => {
+          const meta: Record<string, unknown> = {};
+          if (schema.type) meta.type = schema.type;
+          if (schema.enum) meta.enum = schema.enum;
+          if (schema.default !== undefined) meta.default = schema.default;
+          return {
+            name,
+            description: schema.description,
+            required: schema.required ?? false,
+            ...(Object.keys(meta).length ? { _meta: meta } : {})
+          };
+        })
       }))
     };
   });
@@ -563,18 +665,12 @@ export async function createServer() {
     if (!prompt) {
       throw new Error(`Unknown prompt: ${request.params.name}`);
     }
-    
-    // Return a template for the lighting setup
+
+    const args = (request.params.arguments || {}) as Record<string, unknown>;
+    const messages = prompt.build(args);
     return {
-      messages: [
-        {
-          role: 'user',
-          content: {
-            type: 'text',
-            text: `Set up three-point lighting with ${request.params.arguments?.intensity || 'medium'} intensity`
-          }
-        }
-      ]
+      description: prompt.description,
+      messages
     };
   });