unreal-engine-mcp-server 0.4.4 → 0.4.5

package/.env.production

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

package/.github/workflows/smithery-build.yml

@@ -0,0 +1,29 @@
+name: Smithery Build
+
+on:
+  push:
+    branches: [ main ]
+  pull_request:
+    branches: [ main ]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '18'
+          cache: 'npm'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Type-check
+        run: npm run type-check
+
+      - name: Smithery build
+        run: npm run smithery:ci

package/CHANGELOG.md

@@ -0,0 +1,26 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## [0.4.5] - 2025-10-03
+### Added
+- Expose `UE_PROJECT_PATH` environment variable across runtime config, Smithery manifest, and client example configs. This allows tools that need an absolute .uproject path (e.g., engine_start) to work without additional manual configuration.
+- Added `projectPath` to the runtime `configSchema` so Smithery's session UI can inject a project path into the server environment.
+
+### Changed
+- Make `createServer` a synchronous factory (removed `async`) and updated `createServerDefault` and `startStdioServer` to use the synchronous factory. This aligns the exported default with Smithery’s expectations and prevents auto-start mismatches in the bundled output.
+- Provide a default for `ueHost` in the exported `configSchema` so the Smithery configuration dialog pre-fills the host input.
+
+### Documentation
+- Updated `README.md`, `claude_desktop_config_example.json`, and `mcp-config-example.json` to include `UE_PROJECT_PATH` and usage notes.
+- Updated `smithery.yaml` and `server.json` manifest to declare `UE_PROJECT_PATH` and default values.
+
+### Build
+- Rebuilt the Smithery bundle and TypeScript output to ensure schema and defaults are exported in the distributed artifact.
+
+### Fixes
+- Fixes Smithery UI blank ueHost field by defining a default in the runtime schema.
+
+
+## [0.4.4] - 2025-09-30
+- Previous release notes retained in upstream repo.

package/README.md

@@ -5,6 +5,7 @@
 [![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/)
+[![smithery badge](https://smithery.ai/badge/@ChiR24/unreal_mcp_server)](https://smithery.ai/server/@ChiR24/unreal_mcp_server)
 
 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.
 
@@ -105,7 +106,8 @@ Then enable Python execution in: Edit > Project Settings > Plugins > Remote Cont
       "env": {
         "UE_HOST": "127.0.0.1",
         "UE_RC_HTTP_PORT": "30010",
-        "UE_RC_WS_PORT": "30020"
+        "UE_RC_WS_PORT": "30020",
+        "UE_PROJECT_PATH": "C:/Users/YourName/Documents/Unreal Projects/YourProject"
       }
     }
   }
@@ -123,7 +125,8 @@ Then enable Python execution in: Edit > Project Settings > Plugins > Remote Cont
       "env": {
         "UE_HOST": "127.0.0.1",
         "UE_RC_HTTP_PORT": "30010",
-        "UE_RC_WS_PORT": "30020"
+        "UE_RC_WS_PORT": "30020",
+        "UE_PROJECT_PATH": "C:/Users/YourName/Documents/Unreal Projects/YourProject"
       }
     }
   }
@@ -177,6 +180,7 @@ 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
+UE_PROJECT_PATH="C:/Users/YourName/Documents/Unreal Projects/YourProject"  # Absolute path to your .uproject file
 LOG_LEVEL=info                 # debug | info | warn | error
 ```
 
@@ -187,6 +191,13 @@ docker build -t unreal-mcp .
 docker run -it --rm unreal-mcp
 ```
 
+Pull from Docker Hub
+
+```bash
+docker pull mcp/server/unreal-engine-mcp-server:latest
+docker run --rm -it mcp/server/unreal-engine-mcp-server:latest
+```
+
 ## Development
 
 ```bash

package/claude_desktop_config_example.json

@@ -6,7 +6,8 @@
       "env": {
         "UE_HOST": "127.0.0.1",
         "UE_RC_WS_PORT": "30020",
-        "UE_RC_HTTP_PORT": "30010"
+        "UE_RC_HTTP_PORT": "30010",
+        "UE_PROJECT_PATH": "C:/Users/YourName/Documents/Unreal Projects/YourProject"
       }
     }
   }

package/dist/index.d.ts

@@ -1,7 +1,8 @@
 import 'dotenv/config';
 import { Server } from '@modelcontextprotocol/sdk/server/index.js';
 import { UnrealBridge } from './unreal-bridge.js';
-export declare function createServer(): Promise<{
+import { z } from 'zod';
+export declare function createServer(): {
     server: Server<{
         method: string;
         params?: {
@@ -26,6 +27,50 @@ export declare function createServer(): Promise<{
         } | undefined;
     }>;
     bridge: UnrealBridge;
+};
+export declare const configSchema: z.ZodObject<{
+    ueHost: z.ZodDefault<z.ZodOptional<z.ZodString>>;
+    ueHttpPort: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+    ueWsPort: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+    logLevel: z.ZodDefault<z.ZodOptional<z.ZodEnum<["debug", "info", "warn", "error"]>>>;
+    projectPath: z.ZodDefault<z.ZodOptional<z.ZodString>>;
+}, "strip", z.ZodTypeAny, {
+    projectPath: string;
+    ueHost: string;
+    ueHttpPort: number;
+    ueWsPort: number;
+    logLevel: "debug" | "info" | "warn" | "error";
+}, {
+    projectPath?: string | undefined;
+    ueHost?: string | undefined;
+    ueHttpPort?: number | undefined;
+    ueWsPort?: number | undefined;
+    logLevel?: "debug" | "info" | "warn" | "error" | undefined;
+}>;
+export default function createServerDefault({ config }?: {
+    config?: any;
+}): Server<{
+    method: string;
+    params?: {
+        [x: string]: unknown;
+        _meta?: {
+            [x: string]: unknown;
+            progressToken?: string | number | undefined;
+        } | undefined;
+    } | undefined;
+}, {
+    method: string;
+    params?: {
+        [x: string]: unknown;
+        _meta?: {
+            [x: string]: unknown;
+        } | undefined;
+    } | undefined;
+}, {
+    [x: string]: unknown;
+    _meta?: {
+        [x: string]: unknown;
+    } | undefined;
 }>;
 export declare function startStdioServer(): Promise<void>;
 //# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -33,10 +33,11 @@ import { handleConsolidatedToolCall } from './tools/consolidated-tool-handlers.j
 import { prompts } from './prompts/index.js';
 import { CallToolRequestSchema, ListToolsRequestSchema, ListResourcesRequestSchema, ReadResourceRequestSchema, ListPromptsRequestSchema, GetPromptRequestSchema } from '@modelcontextprotocol/sdk/types.js';
 import { responseValidator } from './utils/response-validator.js';
-import { ErrorHandler } from './utils/error-handler.js';
+import { z } from 'zod';
 import { routeStdoutLogsToStderr } from './utils/stdio-redirect.js';
-import { cleanObject } from './utils/safe-json.js';
 import { createElicitationHelper } from './utils/elicitation.js';
+import { cleanObject } from './utils/safe-json.js';
+import { ErrorHandler } from './utils/error-handler.js';
 const log = new Logger('UE-MCP');
 // Ensure stdout remains JSON-only for MCP by routing logs to stderr unless opted out.
 routeStdoutLogsToStderr();
@@ -62,7 +63,7 @@ const CONFIG = {
     RETRY_DELAY_MS: 2000,
     // Server info
     SERVER_NAME: 'unreal-engine-mcp',
-    SERVER_VERSION: '0.4.4',
+    SERVER_VERSION: '0.4.5',
     // Monitoring
     HEALTH_CHECK_INTERVAL_MS: 30000 // 30 seconds
 };
@@ -116,7 +117,7 @@ async function performHealthCheck(bridge) {
         }
     }
 }
-export async function createServer() {
+export function createServer() {
     const bridge = new UnrealBridge();
     // Disable auto-reconnect loops; connect only on-demand
     bridge.setAutoReconnectEnabled(false);
@@ -215,8 +216,7 @@ export async function createServer() {
             prompts: {
                 listChanged: false
             },
-            logging: {},
-            elicitation: {}
+            logging: {}
         }
     });
     // Optional elicitation helper – used only if client supports it.
@@ -618,8 +618,40 @@ export async function createServer() {
     });
     return { server, bridge };
 }
+// Export configuration schema for Smithery session UI and validation
+export const configSchema = z.object({
+    ueHost: z.string().optional().default('127.0.0.1').describe('Unreal Engine host (e.g. 127.0.0.1)'),
+    ueHttpPort: z.number().int().optional().default(30010).describe('Remote Control HTTP port'),
+    ueWsPort: z.number().int().optional().default(30020).describe('Remote Control WebSocket port'),
+    logLevel: z.enum(['debug', 'info', 'warn', 'error']).optional().default('info').describe('Runtime log level'),
+    projectPath: z.string().optional().default('C:/Users/YourName/Documents/Unreal Projects/YourProject').describe('Absolute path to your Unreal .uproject file')
+});
+// Default export expected by Smithery TypeScript runtime. Accepts an optional config object
+// and injects values into the environment before creating the server.
+export default function createServerDefault({ config } = {}) {
+    try {
+        if (config) {
+            if (typeof config.ueHost === 'string' && config.ueHost.trim())
+                process.env.UE_HOST = config.ueHost;
+            if (config.ueHttpPort !== undefined)
+                process.env.UE_RC_HTTP_PORT = String(config.ueHttpPort);
+            if (config.ueWsPort !== undefined)
+                process.env.UE_RC_WS_PORT = String(config.ueWsPort);
+            if (typeof config.logLevel === 'string')
+                process.env.LOG_LEVEL = config.logLevel;
+            if (typeof config.projectPath === 'string' && config.projectPath.trim())
+                process.env.UE_PROJECT_PATH = config.projectPath;
+        }
+    }
+    catch (e) {
+        // Non-fatal: log and continue (console to avoid circular logger dependencies at top-level)
+        console.debug('[createServerDefault] Failed to apply config to environment:', e?.message || e);
+    }
+    const { server } = createServer();
+    return server;
+}
 export async function startStdioServer() {
-    const { server } = await createServer();
+    const { server } = createServer();
     const transport = new StdioServerTransport();
     // Add debugging for transport messages
     const originalWrite = process.stdout.write;
@@ -633,11 +665,5 @@ export async function startStdioServer() {
     await server.connect(transport);
     log.info('Unreal Engine MCP Server started on stdio');
 }
-// Start the server when run directly
-if (import.meta.url === `file://${process.argv[1].replace(/\\/g, '/')}`) {
-    startStdioServer().catch(error => {
-        console.error('Failed to start server:', error);
-        process.exit(1);
-    });
-}
+// Direct execution is handled via src/cli.ts to keep this module side-effect free.
 //# sourceMappingURL=index.js.map

package/dist/tools/consolidated-tool-definitions.d.ts

@@ -227,43 +227,55 @@ export declare const consolidatedToolDefinitions: ({
             };
             location: {
                 type: string;
+                description: string;
                 properties: {
                     x: {
                         type: string;
+                        description: string;
                     };
                     y: {
                         type: string;
+                        description: string;
                     };
                     z: {
                         type: string;
+                        description: string;
                     };
                 };
             };
             rotation: {
                 type: string;
+                description: string;
                 properties: {
                     pitch: {
                         type: string;
+                        description: string;
                     };
                     yaw: {
                         type: string;
+                        description: string;
                     };
                     roll: {
                         type: string;
+                        description: string;
                     };
                 };
             };
             force: {
                 type: string;
+                description: string;
                 properties: {
                     x: {
                         type: string;
+                        description: string;
                     };
                     y: {
                         type: string;
+                        description: string;
                     };
                     z: {
                         type: string;
+                        description: string;
                     };
                 };
             };
@@ -437,29 +449,37 @@ export declare const consolidatedToolDefinitions: ({
             };
             location: {
                 type: string;
+                description: string;
                 properties: {
                     x: {
                         type: string;
+                        description: string;
                     };
                     y: {
                         type: string;
+                        description: string;
                     };
                     z: {
                         type: string;
+                        description: string;
                     };
                 };
             };
             rotation: {
                 type: string;
+                description: string;
                 properties: {
                     pitch: {
                         type: string;
+                        description: string;
                     };
                     yaw: {
                         type: string;
+                        description: string;
                     };
                     roll: {
                         type: string;
+                        description: string;
                     };
                 };
             };
@@ -674,15 +694,19 @@ export declare const consolidatedToolDefinitions: ({
             };
             location: {
                 type: string;
+                description: string;
                 properties: {
                     x: {
                         type: string;
+                        description: string;
                     };
                     y: {
                         type: string;
+                        description: string;
                     };
                     z: {
                         type: string;
+                        description: string;
                     };
                 };
             };
@@ -1067,15 +1091,19 @@ export declare const consolidatedToolDefinitions: ({
             };
             location: {
                 type: string;
+                description: string;
                 properties: {
                     x: {
                         type: string;
+                        description: string;
                     };
                     y: {
                         type: string;
+                        description: string;
                     };
                     z: {
                         type: string;
+                        description: string;
                     };
                 };
             };
@@ -1480,26 +1508,33 @@ export declare const consolidatedToolDefinitions: ({
             };
             location: {
                 type: string;
+                description: string;
                 properties: {
                     x: {
                         type: string;
+                        description: string;
                     };
                     y: {
                         type: string;
+                        description: string;
                     };
                     z: {
                         type: string;
+                        description: string;
                     };
                 };
             };
             subdivisions: {
                 type: string;
+                description: string;
             };
             heightFunction: {
                 type: string;
+                description: string;
             };
             materialPath: {
                 type: string;
+                description: string;
             };
             bounds: {
                 type: string;
@@ -1626,15 +1661,19 @@ export declare const consolidatedToolDefinitions: ({
             };
             position: {
                 type: string;
+                description: string;
                 properties: {
                     x: {
                         type: string;
+                        description: string;
                     };
                     y: {
                         type: string;
+                        description: string;
                     };
                     z: {
                         type: string;
+                        description: string;
                     };
                 };
             };
@@ -1824,15 +1863,19 @@ export declare const consolidatedToolDefinitions: ({
             };
             location: {
                 type: string;
+                description: string;
                 properties: {
                     x: {
                         type: string;
+                        description: string;
                     };
                     y: {
                         type: string;
+                        description: string;
                     };
                     z: {
                         type: string;
+                        description: string;
                     };
                 };
             };