unreal-engine-mcp-server 0.3.1 → 0.4.3

package/.env.production

@@ -19,7 +19,7 @@ LOG_LEVEL=info
 
 # Server Settings
 SERVER_NAME=unreal-engine-mcp
-SERVER_VERSION=0.3.1
+SERVER_VERSION=0.4.3
 
 # Connection Settings
 MAX_RETRY_ATTEMPTS=3

package/.github/copilot-instructions.md

@@ -0,0 +1,45 @@
+# Unreal MCP – AI Agent Guide
+
+## Architecture essentials
+- `src/index.ts` boots the Model Context Protocol server, registers output schemas, and connects to Unreal only when a tool/resource call requires it via `ensureConnectedOnDemand`.
+- Consolidated tool routing lives in `src/tools/consolidated-tool-definitions.ts` and `src/tools/consolidated-tool-handlers.ts`, shrinking the surface to 13 multi-action tools that wrap the specialized classes in `src/tools/*`.
+- The Unreal bridge (`src/unreal-bridge.ts`) owns HTTP/WS transport, command throttling, health checks, and graceful fallbacks so callers never talk to Remote Control directly.
+- Health/metrics (connection status, latency, recent errors) are tracked in `index.ts` and exposed through the `ue://health` resource for quick diagnostics.
+
+## Key directories
+- `src/tools/` – domain-specific helpers (actors, landscapes, audio, niagara, etc.) that emit Python scripts or console commands.
+- `src/resources/` – read-only listings (assets, actors, levels) with caching and path normalization utilities.
+- `src/utils/` – shared helpers: validation/coercion, `escapePythonString`, result interpretation, AJV-powered response validation, stdout redirection.
+- `docs/unreal-tool-test-cases.md` + `tests/run-unreal-tool-tests.mjs` – declarative test matrix consumed by the automated harness; reports land in `tests/reports/` with time-stamped JSON.
+
+## Tool workflow expectations
+- New tool actions must be declared in the consolidated definitions (input/output schema) and wired in the handler switch before delegating to the relevant class in `src/tools/*`.
+- Always return plain JS objects with `success`, `message`, `error`, and optional `warnings` arrays; let `responseValidator.wrapResponse` handle MCP formatting.
+- Shared helpers like `interpretStandardResult` and `cleanObject` keep payloads JSON-safe—use them instead of ad-hoc parsing.
+- When validating inputs, reuse `ensureVector3`, `ensureRotation`, and other utilities from `src/utils/validation.ts` to keep error messaging consistent.
+
+## Unreal bridge & Python usage
+- Prefer `bridge.executePythonWithResult` for multi-line scripts; it captures stdout, parses the last `RESULT:` block, and falls back to the console `py` command when plugins are missing.
+- Python snippets should print a single `RESULT:` JSON payload and sanitize inputs with `escapePythonString` or typed coercion helpers.
+- `UnrealBridge.httpCall` enforces timeouts, queues commands, and blocks dangerous console strings (`buildpaths`, `rebuildnavigation`, etc.); avoid bypassing it with raw HTTP.
+- Auto-reconnect is disabled by default—tool handlers should call `ensureConnectedOnDemand()` instead of assuming a live session.
+
+## Response & validation conventions
+- Every consolidated tool has an AJV schema; mismatches surface as `_validation` warnings in responses and appear in stderr logs.
+- For Python-driven tools, use the `interpretResult`/`interpretStandardResult` helpers to turn raw bridge output into the normalized `{ success, message, error, warnings }` shape.
+- Keep warning text short and user-facing—the test harness searches response strings for keywords to grade scenarios.
+
+## Build & test workflow
+- `npm run build` compiles TypeScript to `dist/`; `npm run lint` enforces the ESLint rules shipped in `.eslintrc.json`.
+- `npm run test:tools` launches the compiled server via stdio, iterates the Markdown-defined cases, and writes a JSON run summary under `tests/reports/`.
+- Override harness behavior with env vars like `UNREAL_MCP_SERVER_CMD`, `UNREAL_MCP_SERVER_ARGS`, `UNREAL_MCP_TEST_DOC`, or `UNREAL_MCP_FBX_FILE` when Unreal lives elsewhere.
+
+## Unreal environment & configuration
+- Ensure the project enables: Remote Control API, Remote Control Web Interface, Python Editor Script Plugin, Editor Scripting Utilities, Sequencer, and Level Sequence Editor before invoking automation.
+- Default connection settings come from `UE_HOST`, `UE_RC_HTTP_PORT`, and `UE_RC_WS_PORT` (see README for the `DefaultEngine.ini` snippet that unlocks remote execution).
+- Tools defensively return `UE_NOT_CONNECTED` or asset-not-found errors; keep that contract when extending behavior so clients can retry intelligently.
+
+## Debugging & monitoring
+- Logs are routed to stderr via `routeStdoutLogsToStderr()` to keep MCP stdout JSON-only—check the terminal for detailed stack traces or validation warnings.
+- Use the `ue://health` and `ue://version` resources to confirm bridge connectivity, last health-check timestamp, and detected engine version.
+- The command queue in `UnrealBridge` spaces out console/Python traffic; heavy operations may need explicit `__callTimeoutMs` in the payload to extend HTTP timeouts.

package/.github/workflows/publish-mcp.yml

@@ -49,7 +49,7 @@ jobs:
       - name: Update server.json version
         run: |
           VERSION=${{ steps.version.outputs.version }}
-          jq --arg v "$VERSION" '.version = $v | .packages[] |= if .registry_type == "npm" then .version = $v else . end' server.json > tmp && mv tmp server.json
+          jq --arg v "$VERSION" '.version = $v | .packages[] |= if .registryType == "npm" then .version = $v else . end' server.json > tmp && mv tmp server.json
           echo "Updated server.json:"
           cat server.json
 

package/README.md

@@ -4,6 +4,7 @@
 [![NPM Package](https://img.shields.io/npm/v/unreal-engine-mcp-server)](https://www.npmjs.com/package/unreal-engine-mcp-server)
 [![MCP SDK](https://img.shields.io/badge/MCP%20SDK-TypeScript-blue)](https://github.com/modelcontextprotocol/sdk)
 [![Unreal Engine](https://img.shields.io/badge/Unreal%20Engine-5.0--5.6-orange)](https://www.unrealengine.com/)
+[![MCP Registry](https://img.shields.io/badge/MCP%20Registry-Published-green)](https://registry.modelcontextprotocol.io/)
 
 A comprehensive Model Context Protocol (MCP) server that enables AI assistants to control Unreal Engine via Remote Control API. Built with TypeScript and designed for game development automation.
 
@@ -24,11 +25,26 @@ A comprehensive Model Context Protocol (MCP) server that enables AI assistants t
 ### Prerequisites
 - Node.js 18+
 - Unreal Engine 5.0-5.6
-- Required UE Plugins:
-  - Remote Control
-  - Web Remote Control
-  - Python Script Plugin
-  - Editor Scripting Utilities
+- Required UE Plugins (enable via **Edit ▸ Plugins**):
+  - **Remote Control API** – core Remote Control HTTP/WS endpoints
+  - **Remote Control Web Interface** – enables WebSocket bridge used by this server
+  - **Python Editor Script Plugin** – exposes Python runtime for automation
+  - **Editor Scripting Utilities** – unlocks Editor Actor/Asset subsystems used throughout the tools
+  - **Sequencer** *(built-in)* – keep enabled for cinematic tools
+  - **Level Sequence Editor** – required for `manage_sequence` operations
+
+> 💡 After toggling any plugin, restart the editor to finalize activation. Keep `Editor Scripting Utilities` and `Python Editor Script Plugin` enabled prior to connecting, otherwise many subsystem-based tools (actor spawning, audio, foliage, UI widgets) will refuse to run for safety.
+
+### Plugin feature map
+
+| Plugin | Location | Used By | Notes |
+|--------|----------|---------|-------|
+| Remote Control API | Developer Tools ▸ Remote Control | All tools | Provides HTTP/WS endpoints consumed by the MCP bridge |
+| Remote Control Web Interface | Developer Tools ▸ Remote Control | All tools | Enables persistent WebSocket session |
+| Python Editor Script Plugin | Scripting | Landscapes, lighting, audio, physics, sequences, UI | Required for every Python execution path |
+| Editor Scripting Utilities | Scripting | Actors, foliage, assets, landscapes, UI | Supplies Editor Actor/Asset subsystems in UE5.6 |
+| Sequencer | Built-in | Sequencer tools | Ensure not disabled in project settings |
+| Level Sequence Editor | Animation | Sequencer tools | Activate before calling `manage_sequence` operations |
 
 ### Installation
 
@@ -114,7 +130,7 @@ Then enable Python execution in: Edit > Project Settings > Plugins > Remote Cont
 }
 ```
 
-## Available Tools (13 Consolidated)
+## Available Tools (13)
 
 | Tool | Description |
 |------|-------------|
@@ -161,7 +177,6 @@ Blueprints, Materials, Textures, Static/Skeletal Meshes, Levels, Sounds, Particl
 UE_HOST=127.0.0.1              # Unreal Engine host
 UE_RC_HTTP_PORT=30010          # Remote Control HTTP port
 UE_RC_WS_PORT=30020            # Remote Control WebSocket port
-USE_CONSOLIDATED_TOOLS=true    # Use 13 consolidated tools (false = 37 individual)
 LOG_LEVEL=info                 # debug | info | warn | error
 ```
 

package/dist/index.js

@@ -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';
@@ -37,6 +36,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');
 // Ensure stdout remains JSON-only for MCP by routing logs to stderr unless opted out.
 routeStdoutLogsToStderr();
@@ -56,14 +56,13 @@ let healthCheckTimer;
 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
 };
@@ -123,7 +122,7 @@ export async function createServer() {
     bridge.setAutoReconnectEnabled(false);
     // Initialize response validation with schemas
     log.debug('Initializing response validation...');
-    const toolDefs = CONFIG.USE_CONSOLIDATED_TOOLS ? consolidatedToolDefinitions : toolDefinitions;
+    const toolDefs = consolidatedToolDefinitions;
     toolDefs.forEach((tool) => {
         if (tool.outputSchema) {
             responseValidator.registerSchema(tool.name, tool.outputSchema);
@@ -196,6 +195,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);
@@ -212,10 +212,34 @@ 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, log);
+    const defaultElicitationTimeoutMs = elicitation.getDefaultTimeoutMs();
+    const createNotConnectedResponse = (toolName) => {
+        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}`
+        };
+        return responseValidator.wrapResponse(toolName, {
+            ...payload,
+            content: [
+                {
+                    type: 'text',
+                    text: JSON.stringify(payload, null, 2)
+                }
+            ]
+        });
+    };
     // Handle resource listing
     server.setRequestHandler(ListResourcesRequestSchema, async () => {
         return {
@@ -394,29 +418,23 @@ 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 = 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}`
-            };
             trackPerformance(startTime, false);
-            return notConnected;
+            return createNotConnectedResponse(name);
         }
         // Create tools object for handler
         const tools = {
@@ -432,6 +450,7 @@ export async function createServer() {
             lightingTools,
             landscapeTools,
             foliageTools,
+            buildEnvAdvanced,
             debugTools,
             performanceTools,
             audioTools,
@@ -441,18 +460,76 @@ 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);
+            // Opportunistic generic elicitation for missing primitive required fields
+            try {
+                const toolDef = consolidatedToolDefinitions.find(t => t.name === name);
+                const inputSchema = toolDef?.inputSchema;
+                const elicitFn = tools.elicit;
+                if (inputSchema && typeof elicitFn === 'function') {
+                    const props = inputSchema.properties || {};
+                    const required = Array.isArray(inputSchema.required) ? inputSchema.required : [];
+                    const missing = required.filter((k) => {
+                        const v = args[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 = {};
+                    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 = { fallback: async () => ({ ok: false, error: 'missing-params' }) };
+                        if (typeof tools.elicitationTimeoutMs === 'number' && Number.isFinite(tools.elicitationTimeoutMs)) {
+                            elicitOptions.timeoutMs = tools.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 };
+                        }
+                    }
+                }
             }
-            else {
-                result = await handleToolCall(name, args, tools);
+            catch (e) {
+                log.debug('Generic elicitation prefill skipped', { err: e?.message || String(e) });
             }
+            let result = await handleConsolidatedToolCall(name, args, tools);
             log.debug(`Tool ${name} returned result`);
             // Clean the result to remove circular references
             result = cleanObject(result);
@@ -483,13 +560,23 @@ export async function createServer() {
                     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);
         }
     });
     // Handle prompt listing
@@ -498,11 +585,21 @@ 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 = {};
+                    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 } : {})
+                    };
+                })
             }))
         };
     });
@@ -512,17 +609,11 @@ 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 || {});
+        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
         };
     });
     return { server, bridge };

package/dist/prompts/index.d.ts

@@ -2,13 +2,20 @@ export interface PromptArgument {
     type: string;
     description?: string;
     enum?: string[];
-    default?: any;
+    default?: unknown;
     required?: boolean;
 }
-export interface Prompt {
+export interface PromptTemplate {
     name: string;
     description: string;
     arguments?: Record<string, PromptArgument>;
+    build: (args: Record<string, unknown>) => Array<{
+        role: 'user' | 'assistant';
+        content: {
+            type: 'text';
+            text: string;
+        };
+    }>;
 }
-export declare const prompts: Prompt[];
+export declare const prompts: PromptTemplate[];
 //# sourceMappingURL=index.d.ts.map