unreal-engine-mcp-server 0.2.1

package/dist/utils/safe-json.js

@@ -0,0 +1,97 @@
+// Utility to safely serialize objects with circular references
+export function safeStringify(obj, space) {
+    const seen = new WeakSet();
+    return JSON.stringify(obj, (key, value) => {
+        // Handle undefined, functions, symbols
+        if (value === undefined || typeof value === 'function' || typeof value === 'symbol') {
+            return undefined;
+        }
+        // Handle circular references
+        if (typeof value === 'object' && value !== null) {
+            if (seen.has(value)) {
+                return '[Circular Reference]';
+            }
+            seen.add(value);
+        }
+        // Handle BigInt
+        if (typeof value === 'bigint') {
+            return value.toString();
+        }
+        return value;
+    }, space);
+}
+export function sanitizeResponse(response) {
+    if (!response || typeof response !== 'object') {
+        return response;
+    }
+    // Create a clean copy without circular references
+    try {
+        const jsonStr = safeStringify(response);
+        return JSON.parse(jsonStr);
+    }
+    catch (error) {
+        console.error('Failed to sanitize response:', error);
+        // Fallback: return a simple error response
+        return {
+            content: [{
+                    type: 'text',
+                    text: 'Response contained unserializable data'
+                }],
+            error: 'Serialization error'
+        };
+    }
+}
+// Remove circular references and non-serializable properties from an object
+export function cleanObject(obj, maxDepth = 10) {
+    const seen = new WeakSet();
+    function clean(value, depth, path = 'root') {
+        // Prevent infinite recursion
+        if (depth > maxDepth) {
+            return '[Max depth reached]';
+        }
+        // Handle primitives
+        if (value === null || value === undefined) {
+            return value;
+        }
+        if (typeof value !== 'object') {
+            if (typeof value === 'function' || typeof value === 'symbol') {
+                return undefined;
+            }
+            if (typeof value === 'bigint') {
+                return value.toString();
+            }
+            return value;
+        }
+        // Check for circular reference
+        if (seen.has(value)) {
+            return '[Circular Reference]';
+        }
+        seen.add(value);
+        // Handle arrays
+        if (Array.isArray(value)) {
+            const result = value.map((item, index) => clean(item, depth + 1, `${path}[${index}]`));
+            seen.delete(value); // Remove from seen after processing
+            return result;
+        }
+        // Handle objects
+        const cleaned = {};
+        // Use Object.keys to avoid prototype properties
+        const keys = Object.keys(value);
+        for (const key of keys) {
+            try {
+                const cleanedValue = clean(value[key], depth + 1, `${path}.${key}`);
+                if (cleanedValue !== undefined) {
+                    cleaned[key] = cleanedValue;
+                }
+            }
+            catch (e) {
+                // Skip properties that throw errors when accessed
+                console.error(`Error cleaning property ${path}.${key}:`, e);
+            }
+        }
+        seen.delete(value); // Remove from seen after processing
+        return cleaned;
+    }
+    return clean(obj, 0);
+}
+//# sourceMappingURL=safe-json.js.map

package/dist/utils/stdio-redirect.d.ts

@@ -0,0 +1,2 @@
+export declare function routeStdoutLogsToStderr(): void;
+//# sourceMappingURL=stdio-redirect.d.ts.map

package/dist/utils/stdio-redirect.js

@@ -0,0 +1,20 @@
+export function routeStdoutLogsToStderr() {
+    // Enable by default. Allow opt-out with LOG_TO_STDERR=false or JSON_STDOUT_MODE=false
+    const flagRaw = String(process.env.LOG_TO_STDERR ?? process.env.JSON_STDOUT_MODE ?? 'true').toLowerCase();
+    const enabled = !(flagRaw === 'false' || flagRaw === '0' || flagRaw === 'off' || flagRaw === 'no');
+    if (!enabled)
+        return;
+    try {
+        const toErr = console.error.bind(console);
+        // Route common stdout channels to stderr to keep stdout JSON-only for MCP
+        console.log = toErr;
+        console.info = toErr;
+        console.debug = toErr;
+        // Be explicit with trace as well
+        console.trace = toErr;
+    }
+    catch {
+        // If overriding fails for any reason, just continue silently.
+    }
+}
+//# sourceMappingURL=stdio-redirect.js.map

package/dist/utils/validation.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Validation and sanitization utilities for Unreal Engine assets
+ */
+/**
+ * Sanitize an asset name for Unreal Engine
+ * @param name The name to sanitize
+ * @returns Sanitized name
+ */
+export declare function sanitizeAssetName(name: string): string;
+/**
+ * Sanitize a path for Unreal Engine
+ * @param path The path to sanitize
+ * @returns Sanitized path
+ */
+export declare function sanitizePath(path: string): string;
+/**
+ * Validate path length
+ * @param path The full path to validate
+ * @returns Object with validation result
+ */
+export declare function validatePathLength(path: string): {
+    valid: boolean;
+    error?: string;
+};
+/**
+ * Validate and sanitize asset parameters
+ * @param params Object containing name and optionally savePath
+ * @returns Sanitized parameters with validation result
+ */
+export declare function validateAssetParams(params: {
+    name: string;
+    savePath?: string;
+    [key: string]: any;
+}): {
+    valid: boolean;
+    sanitized: typeof params;
+    error?: string;
+};
+/**
+ * Extract valid skeletal mesh path from various inputs
+ * @param input The input path which might be a skeleton or mesh
+ * @returns Corrected skeletal mesh path or null
+ */
+export declare function resolveSkeletalMeshPath(input: string): string | null;
+/**
+ * Concurrency delay to prevent race conditions
+ * @param ms Milliseconds to delay
+ */
+export declare function concurrencyDelay(ms?: number): Promise<void>;
+//# sourceMappingURL=validation.d.ts.map

package/dist/utils/validation.js

@@ -0,0 +1,173 @@
+/**
+ * Validation and sanitization utilities for Unreal Engine assets
+ */
+/**
+ * Maximum path length allowed in Unreal Engine
+ */
+const MAX_PATH_LENGTH = 260;
+/**
+ * Invalid characters for Unreal Engine asset names
+ * Note: Dashes are allowed in Unreal asset names
+ */
+// eslint-disable-next-line no-useless-escape
+const INVALID_CHARS = /[@#%$&*()+=\[\]{}<>?|\\;:'"`,~!\s]/g;
+/**
+ * Reserved keywords that shouldn't be used as names
+ */
+const RESERVED_KEYWORDS = [
+    'None', 'null', 'undefined', 'true', 'false',
+    'class', 'struct', 'enum', 'interface',
+    'default', 'transient', 'native'
+];
+/**
+ * Sanitize an asset name for Unreal Engine
+ * @param name The name to sanitize
+ * @returns Sanitized name
+ */
+export function sanitizeAssetName(name) {
+    if (!name || typeof name !== 'string') {
+        return 'Asset';
+    }
+    // Remove leading/trailing whitespace
+    let sanitized = name.trim();
+    // Replace invalid characters with underscores
+    sanitized = sanitized.replace(INVALID_CHARS, '_');
+    // Remove consecutive underscores
+    sanitized = sanitized.replace(/_+/g, '_');
+    // Remove leading/trailing underscores
+    sanitized = sanitized.replace(/^_+|_+$/g, '');
+    // If name is empty after sanitization, use default
+    if (!sanitized) {
+        return 'Asset';
+    }
+    // If name is a reserved keyword, append underscore
+    if (RESERVED_KEYWORDS.includes(sanitized)) {
+        sanitized = `${sanitized}_Asset`;
+    }
+    // Ensure name starts with a letter
+    if (!/^[A-Za-z]/.test(sanitized)) {
+        sanitized = `Asset_${sanitized}`;
+    }
+    // Truncate overly long names to reduce risk of hitting path length limits
+    if (sanitized.length > 64) {
+        sanitized = sanitized.slice(0, 64);
+    }
+    return sanitized;
+}
+/**
+ * Sanitize a path for Unreal Engine
+ * @param path The path to sanitize
+ * @returns Sanitized path
+ */
+export function sanitizePath(path) {
+    if (!path || typeof path !== 'string') {
+        return '/Game';
+    }
+    // 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);
+    const sanitizedSegments = segments.map(segment => {
+        // Don't sanitize Game, Engine, or other root folders
+        if (['Game', 'Engine', 'Script', 'Temp'].includes(segment)) {
+            return segment;
+        }
+        return sanitizeAssetName(segment);
+    });
+    // Reconstruct path
+    const sanitizedPath = '/' + sanitizedSegments.join('/');
+    return sanitizedPath;
+}
+/**
+ * Validate path length
+ * @param path The full path to validate
+ * @returns Object with validation result
+ */
+export function validatePathLength(path) {
+    if (path.length > MAX_PATH_LENGTH) {
+        return {
+            valid: false,
+            error: `Path too long (${path.length} characters). Maximum allowed is ${MAX_PATH_LENGTH} characters.`
+        };
+    }
+    return { valid: true };
+}
+/**
+ * Validate and sanitize asset parameters
+ * @param params Object containing name and optionally savePath
+ * @returns Sanitized parameters with validation result
+ */
+export function validateAssetParams(params) {
+    // Sanitize name
+    const sanitizedName = sanitizeAssetName(params.name);
+    // Sanitize path if provided
+    const sanitizedPath = params.savePath
+        ? sanitizePath(params.savePath)
+        : params.savePath;
+    // Construct full path for validation
+    const fullPath = sanitizedPath
+        ? `${sanitizedPath}/${sanitizedName}`
+        : `/Game/${sanitizedName}`;
+    // Validate path length
+    const pathValidation = validatePathLength(fullPath);
+    if (!pathValidation.valid) {
+        return {
+            valid: false,
+            sanitized: params,
+            error: pathValidation.error
+        };
+    }
+    return {
+        valid: true,
+        sanitized: {
+            ...params,
+            name: sanitizedName,
+            ...(sanitizedPath && { savePath: sanitizedPath })
+        }
+    };
+}
+/**
+ * Extract valid skeletal mesh path from various inputs
+ * @param input The input path which might be a skeleton or mesh
+ * @returns Corrected skeletal mesh path or null
+ */
+export function resolveSkeletalMeshPath(input) {
+    if (!input || typeof input !== 'string') {
+        return null;
+    }
+    // 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',
+    };
+    // Check if this is a known skeleton path
+    if (skeletonToMeshMap[input]) {
+        return skeletonToMeshMap[input];
+    }
+    // If it contains _Skeleton, try to convert to mesh name
+    if (input.includes('_Skeleton')) {
+        // Try common replacements
+        let meshPath = input.replace('_Skeleton', '');
+        meshPath = meshPath.replace('/SK_', '/SKM_');
+        meshPath = meshPath.replace('UE4_Mannequin', 'SKM_Manny');
+        return meshPath;
+    }
+    // If it starts with SK_ (skeleton prefix), try SKM_ (skeletal mesh prefix)
+    if (input.includes('/SK_')) {
+        return input.replace('/SK_', '/SKM_');
+    }
+    // Return as-is if no conversion needed
+    return input;
+}
+/**
+ * Concurrency delay to prevent race conditions
+ * @param ms Milliseconds to delay
+ */
+export async function concurrencyDelay(ms = 100) {
+    return new Promise(resolve => setTimeout(resolve, ms));
+}
+//# sourceMappingURL=validation.js.map

package/mcp-config-example.json

@@ -0,0 +1,14 @@
+{
+  "mcpServers": {
+    "unreal-engine": {
+      "command": "node",
+      "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_PROJECT_PATH": "C:/Users/YourName/Documents/Unreal Projects/YourProject"
+      }
+    }
+  }
+}

package/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "unreal-engine-mcp-server",
+  "version": "0.2.1",
+  "description": "Production-ready MCP server for Unreal Engine integration with consolidated and individual tool modes",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "bin": {
+    "unreal-mcp-server": "dist/cli.js"
+  },
+  "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"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "mcp",
+    "modelcontextprotocol",
+    "unreal",
+    "unreal-engine",
+    "ue5",
+    "remote-control",
+    "automation",
+    "game-development"
+  ],
+  "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",
+    "dotenv": "^16.4.5",
+    "ws": "^8.18.0",
+    "yargs": "^17.7.2",
+    "zod": "^3.22.4"
+  },
+  "devDependencies": {
+    "@types/node": "^20.12.7",
+    "@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"
+  }
+}

package/server.json

@@ -0,0 +1,60 @@
+{
+  "$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",
+  "packages": [
+    {
+      "registry_type": "npm",
+      "registry_base_url": "https://registry.npmjs.org",
+      "identifier": "unreal-engine-mcp-server",
+      "version": "0.2.1",
+      "transport": {
+        "type": "stdio"
+      },
+      "environment_variables": [
+        {
+          "name": "UE_HOST",
+          "description": "Unreal Engine host address",
+          "is_required": false,
+          "value": "127.0.0.1"
+        },
+        {
+          "name": "UE_RC_HTTP_PORT",
+          "description": "Remote Control HTTP port",
+          "is_required": false,
+          "value": "30010"
+        },
+        {
+          "name": "UE_RC_WS_PORT",
+          "description": "Remote Control WebSocket port",
+          "is_required": false,
+          "value": "30020"
+        }
+      ]
+    }
+  ],
+  "license": "MIT",
+  "keywords": [
+    "mcp",
+    "modelcontextprotocol",
+    "unreal-engine",
+    "ue5",
+    "game-development",
+    "remote-control",
+    "automation",
+    "3d",
+    "gamedev",
+    "cinematics"
+  ],
+  "author": "ChiR24",
+  "homepage": "https://github.com/ChiR24/Unreal_mcp",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/ChiR24/Unreal_mcp.git",
+    "source": "github"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}

package/src/cli.ts

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+import { startStdioServer } from './index.js';
+
+startStdioServer().catch((err) => {
+  console.error('Failed to start server:', err);
+  process.exit(1);
+});