unreal-engine-mcp-server 0.5.0 → 0.5.1

package/dist/utils/command-validator.js

@@ -5,14 +5,15 @@ export class CommandValidator {
         'viewmode visualizebuffer worldnormal',
         'r.gpucrash',
         'buildpaths',
-        'rebuildnavigation'
+        'rebuildnavigation',
+        'obj garbage', 'obj list', 'memreport'
     ];
     static FORBIDDEN_TOKENS = [
         'rm ', 'rm-', 'del ', 'format ', 'shutdown', 'reboot',
         'rmdir', 'mklink', 'copy ', 'move ', 'start "', 'system(',
         'import os', 'import subprocess', 'subprocess.', 'os.system',
         'exec(', 'eval(', '__import__', 'import sys', 'import importlib',
-        'with open', 'open('
+        'with open', 'open(', 'write(', 'read('
     ];
     static INVALID_PATTERNS = [
         /^\d+$/,

package/dist/utils/path-security.d.ts

@@ -0,0 +1,2 @@
+export declare function sanitizePath(path: string, allowedRoots?: string[]): string;
+//# sourceMappingURL=path-security.d.ts.map

package/dist/utils/path-security.js

@@ -0,0 +1,24 @@
+export function sanitizePath(path, allowedRoots = ['/Game', '/Engine']) {
+    if (!path || typeof path !== 'string') {
+        throw new Error('Invalid path: must be a non-empty string');
+    }
+    const trimmed = path.trim();
+    if (trimmed.length === 0) {
+        throw new Error('Invalid path: cannot be empty');
+    }
+    const normalized = trimmed.replace(/\\/g, '/');
+    if (normalized.includes('..')) {
+        throw new Error('Invalid path: directory traversal (..) is not allowed');
+    }
+    const isAllowed = allowedRoots.some(root => normalized.toLowerCase() === root.toLowerCase() ||
+        normalized.toLowerCase().startsWith(`${root.toLowerCase()}/`));
+    if (!isAllowed) {
+        throw new Error(`Invalid path: must start with one of [${allowedRoots.join(', ')}]`);
+    }
+    const invalidChars = /[<>:"|?*\x00-\x1f]/;
+    if (invalidChars.test(normalized)) {
+        throw new Error('Invalid path: contains illegal characters');
+    }
+    return normalized;
+}
+//# sourceMappingURL=path-security.js.map

package/dist/utils/response-factory.d.ts

@@ -1,7 +1,7 @@
-import { CallToolResult } from '@modelcontextprotocol/sdk/types.js';
+import { StandardActionResponse } from '../types/tool-interfaces.js';
 export declare class ResponseFactory {
-    static success(message: string, data?: unknown): CallToolResult;
-    static error(message: string, error?: unknown): CallToolResult;
-    static json(data: unknown): CallToolResult;
+    static success(data: any, message?: string): StandardActionResponse;
+    static error(error: any, defaultMessage?: string): StandardActionResponse;
+    static validationError(message: string): StandardActionResponse;
 }
 //# sourceMappingURL=response-factory.d.ts.map

package/dist/utils/response-factory.js

@@ -1,32 +1,26 @@
+import { cleanObject } from './safe-json.js';
 export class ResponseFactory {
-    static success(message, data) {
-        const content = [{ type: 'text', text: message }];
-        if (data) {
-            content.push({
-                type: 'text',
-                text: JSON.stringify(data, null, 2)
-            });
-        }
+    static success(data, message = 'Operation successful') {
         return {
-            content,
-            isError: false
+            success: true,
+            message,
+            data: cleanObject(data)
         };
     }
-    static error(message, error) {
-        const errorText = error instanceof Error ? error.message : String(error);
-        const fullMessage = error ? `${message}: ${errorText}` : message;
+    static error(error, defaultMessage = 'Operation failed') {
+        const errorMessage = error instanceof Error ? error.message : String(error || defaultMessage);
+        console.error('[ResponseFactory] Error:', error);
         return {
-            content: [{ type: 'text', text: fullMessage }],
-            isError: true
+            success: false,
+            message: errorMessage,
+            data: null
         };
     }
-    static json(data) {
+    static validationError(message) {
         return {
-            content: [{
-                    type: 'text',
-                    text: JSON.stringify(data, null, 2)
-                }],
-            isError: false
+            success: false,
+            message: `Validation Error: ${message}`,
+            data: null
         };
     }
 }

package/docs/Migration-Guide-v0.5.0.md

@@ -652,18 +652,10 @@ echo $WASM_ENABLED  # Should be "true"
 ### Documentation
 - [GraphQL API Documentation](GraphQL-API.md)
 - [WebAssembly Integration Guide](WebAssembly-Integration.md)
-- Added **GraphQL API** (optional) for complex queries.
-    - Disabled by default (`GRAPHQL_ENABLED=false`).
-    - Uses Apollo Server.
-    - Integrated with **Apollo Sandbox** (local IDE) or [Apollo Studio](https://studio.apollographql.com). - GraphQL platform
-- [Postman](https://www.postman.com/) - API testing
-
-### Learning
-- [GraphQL.org](https://graphql.org/) - Official GraphQL documentation
-- [WebAssembly.org](https://webassembly.org/) - WebAssembly specification
 
 ### Tools
 - [GraphiQL](https://github.com/graphql/graphiql) - In-browser GraphQL IDE
+- [Apollo Studio](https://studio.apollographql.com) - GraphQL platform
 - [Postman](https://www.postman.com/) - API testing
 
 ### Learning

package/docs/testing-guide.md

@@ -230,7 +230,7 @@ This prevents false positives from connection errors.
 **Problem**: Unreal Engine is not running or not accessible
 
 **Solutions**:
-1. Launch Unreal Engine 5.6
+1. Launch Unreal Engine 5.0-5.7
 2. Open your project
 3. Verify Unreal Engine is running with the MCP plugin enabled
 4. Check `DefaultEngine.ini` configuration
@@ -417,7 +417,7 @@ For issues with:
 ## Next Steps
 
 1. **Build the server**: `npm run build`
-2. **Start Unreal Engine 5.6**
+2. **Start Unreal Engine 5.0-5.7**
 3. **Run your first test**: `npm run test:system`
 4. **Review the report**: Check `tests/reports/` folder
 5. **Test other tools**: Run `npm run test:<toolname>` for each tool you use

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "unreal-engine-mcp-server",
-  "version": "0.5.0",
+  "version": "0.5.1",
   "mcpName": "io.github.ChiR24/unreal-engine-mcp",
   "description": "A comprehensive Model Context Protocol (MCP) server that enables AI assistants to control Unreal Engine via native automation bridge. Built with TypeScript and designed for game development automation.",
   "type": "module",
@@ -26,6 +26,9 @@
     "automation:sync": "node scripts/sync-mcp-plugin.js",
     "clean:tmp": "node scripts/clean-tmp.js",
     "test": "node scripts/run-all-tests.mjs",
+    "test:unit": "vitest run",
+    "test:unit:watch": "vitest",
+    "test:unit:coverage": "vitest run --coverage",
     "test:all": "node scripts/run-all-tests.mjs",
     "test:manage_asset": "node tests/test-manage-asset.mjs",
     "test:plugin-handshake": "node tests/test-plugin-handshake.mjs",
@@ -43,12 +46,15 @@
     "test:console_command": "node tests/test-console-command.mjs",
     "test:inspect": "node tests/test-inspect.mjs",
     "test:asset_advanced": "node tests/test-asset-advanced.mjs",
-    "test:render": "node tests/test-render.mjs",
     "test:world_partition": "node tests/test-world-partition.mjs",
     "test:no-inline-python": "node tests/test-no-inline-python.mjs",
     "test:graphql": "node tests/test-graphql.mjs",
     "test:audio": "node tests/test-audio.mjs",
     "test:behavior_tree": "node tests/test-behavior-tree.mjs",
+    "test:lighting": "node tests/test-lighting.mjs",
+    "test:performance": "node tests/test-performance.mjs",
+    "test:input": "node tests/test-input.mjs",
+    "test:asset_graph": "node tests/test-asset-graph.mjs",
     "test:wasm": "node tests/test-wasm.mjs",
     "build:wasm": "echo 'Building WebAssembly module...' && cd wasm && wasm-pack build --target web --out-dir ../src/wasm/pkg && cd .. && node scripts/patch-wasm.js",
     "test:wasm:all": "npm run build:core && npm run build:wasm && node tests/test-wasm.mjs",
@@ -76,13 +82,11 @@
     "@graphql-tools/utils": "^10.11.0",
     "@modelcontextprotocol/sdk": "^1.25.0",
     "ajv": "^8.17.1",
-    "axios": "^1.13.2",
+    "dataloader": "^2.2.3",
     "dotenv": "^17.2.3",
     "graphql": "^16.12.0",
     "graphql-yoga": "^5.17.1",
-    "json5": "^2.2.3",
     "ws": "^8.18.3",
-    "yargs": "^18.0.0",
     "zod": "^4.2.1"
   },
   "devDependencies": {
@@ -91,9 +95,11 @@
     "@types/ws": "^8.18.1",
     "@typescript-eslint/eslint-plugin": "^8.50.0",
     "@typescript-eslint/parser": "^8.49.0",
+    "@vitest/coverage-v8": "^4.0.16",
     "eslint": "^9.39.2",
     "rimraf": "^6.1.2",
     "ts-node": "^10.9.2",
-    "typescript": "^5.9.3"
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.16"
   }
 }

package/scripts/run-all-tests.mjs

@@ -2,27 +2,32 @@
 import { spawn } from 'node:child_process';
 
 const tests = [
-  'test:control_actor', // Pass
-  'test:control_editor', // Pass
-  'test:manage_level', // Pass
-  'test:animation', // Pass
-  'test:materials', // Pass
-  'test:niagara', // Pass
-  'test:landscape', // Pass
-  'test:sequence', // Pass
-  'test:system', // Pass
-  'test:console_command', // Pass
-  'test:inspect', // Pass
-  'test:manage_asset', // Pass
-  'test:blueprint', // Pass
-  'test:blueprint_graph', // Pass
-  // 'test:graphql', // Pass
-  'test:wasm:all', // Pass
+  'test:control_actor', // 1
+  'test:control_editor', // 1
+  'test:manage_level', // crashed 1
+  'test:animation',
+  'test:materials',
+  'test:niagara',
+  'test:landscape',
+  'test:sequence', // crashed 1
+  'test:system',
+  'test:console_command',
+  'test:inspect',
+  'test:manage_asset',
+  'test:blueprint',
+  'test:blueprint_graph',
+  'test:audio',
+  'test:behavior_tree',
+  'test:lighting',
+  'test:performance',
+  'test:input',
+  'test:asset_graph',
+  'test:graphql',
+  'test:wasm:all',
   'test:no-inline-python',
-  'test:plugin-handshake', // Pass
-  'test:asset_advanced', // Pass
-  'test:render', // Pass
-  'test:world_partition' // Pass
+  'test:plugin-handshake',
+  'test:asset_advanced',
+  'test:world_partition'
 ];
 
 const isWindows = process.platform === 'win32';

package/server.json

@@ -1,13 +1,14 @@
 {
+  "$schema": "https://raw.githubusercontent.com/modelcontextprotocol/registry/main/schema.json",
   "name": "io.github.ChiR24/unreal-engine-mcp",
   "description": "MCP server for Unreal Engine 5 with 17 tools for game development automation.",
-  "version": "0.5.0",
+  "version": "0.5.1",
   "packages": [
     {
       "registryType": "npm",
       "registryBaseUrl": "https://registry.npmjs.org",
       "identifier": "unreal-engine-mcp-server",
-      "version": "0.5.0",
+      "version": "0.5.1",
       "transport": {
         "type": "stdio"
       },

package/src/config.ts

@@ -40,7 +40,7 @@ export const EnvSchema = z.object({
   // Unreal Settings
   UE_PROJECT_PATH: z.string().optional(),
   UE_EDITOR_EXE: z.string().optional(),
-  UE_SCREENSHOT_DIR: z.string().optional(),
+
 
   // Connection Settings
   MCP_AUTOMATION_PORT: z.preprocess((v) => stringToNumber(v, 8091), z.number().default(8091)),

package/src/constants.ts

@@ -9,4 +9,11 @@ export const DEFAULT_MAX_PENDING_REQUESTS = 25;
 export const DEFAULT_TIME_OF_DAY = 9;
 export const DEFAULT_SUN_INTENSITY = 10000;
 export const DEFAULT_SKYLIGHT_INTENSITY = 1;
+
 export const DEFAULT_SCREENSHOT_RESOLUTION = '1920x1080';
+
+// Operation Timeouts
+export const DEFAULT_OPERATION_TIMEOUT_MS = 30000;
+export const DEFAULT_ASSET_OP_TIMEOUT_MS = 60000;
+export const EXTENDED_ASSET_OP_TIMEOUT_MS = 120000;
+export const LONG_RUNNING_OP_TIMEOUT_MS = 300000;

package/src/graphql/loaders.ts

@@ -0,0 +1,244 @@
+/**
+ * DataLoader instances for GraphQL N+1 query optimization
+ * 
+ * DataLoaders batch and cache requests within a single GraphQL request,
+ * preventing the N+1 query problem when resolving nested fields.
+ */
+
+import DataLoader from 'dataloader';
+import type { AutomationBridge } from '../automation/index.js';
+import { Logger } from '../utils/logger.js';
+
+const log = new Logger('GraphQL:Loaders');
+
+// ============================================================================
+// Types
+// ============================================================================
+
+export interface Actor {
+    name: string;
+    label?: string;
+    class?: string;
+    path?: string;
+    location?: { x: number; y: number; z: number };
+    rotation?: { pitch: number; yaw: number; roll: number };
+    scale?: { x: number; y: number; z: number };
+    tags?: string[];
+}
+
+export interface Asset {
+    name: string;
+    path: string;
+    class?: string;
+    packagePath?: string;
+    size?: number;
+}
+
+export interface Blueprint {
+    name: string;
+    path: string;
+    parentClass?: string;
+    variables?: Array<{ name: string; type: string; defaultValue?: unknown }>;
+    functions?: Array<{ name: string; parameters?: Array<{ name: string; type: string }> }>;
+    components?: Array<{ name: string; type: string }>;
+}
+
+// ============================================================================
+// Loader Factory
+// ============================================================================
+
+export interface GraphQLLoaders {
+    actorLoader: DataLoader<string, Actor | null>;
+    assetLoader: DataLoader<string, Asset | null>;
+    blueprintLoader: DataLoader<string, Blueprint | null>;
+    actorComponentsLoader: DataLoader<string, Array<{ name: string; type: string }> | null>;
+}
+
+/**
+ * Creates DataLoader instances for a GraphQL request context.
+ * 
+ * Each GraphQL request should have its own set of loaders to ensure
+ * proper request-scoped caching and batching.
+ */
+export function createLoaders(automationBridge: AutomationBridge): GraphQLLoaders {
+    return {
+        /**
+         * Batches actor fetches by name
+         */
+        actorLoader: new DataLoader<string, Actor | null>(
+            async (names: readonly string[]) => {
+                log.debug(`Batching actor fetch for ${names.length} actors`);
+
+                try {
+                    // Use batch fetch if available, otherwise fall back to individual fetches
+                    const result = await automationBridge.sendAutomationRequest<{
+                        success: boolean;
+                        actors?: Actor[];
+                    }>('control_actor', {
+                        action: 'batch_get',
+                        actorNames: [...names]
+                    });
+
+                    if (result.success && result.actors) {
+                        // Map results back to input order
+                        return names.map(name =>
+                            result.actors?.find(a => a.name === name || a.label === name) ?? null
+                        );
+                    }
+                } catch {
+                    log.debug('Batch fetch not supported, falling back to individual fetches');
+                }
+
+                // Fallback: fetch individually
+                const results = await Promise.all(
+                    names.map(async (name) => {
+                        try {
+                            const result = await automationBridge.sendAutomationRequest<{
+                                success: boolean;
+                                actor?: Actor;
+                            }>('control_actor', {
+                                action: 'find_by_name',
+                                actorName: name
+                            });
+                            return result.success ? (result.actor ?? null) : null;
+                        } catch {
+                            return null;
+                        }
+                    })
+                );
+                return results;
+            },
+            {
+                cache: true,
+                maxBatchSize: 50
+            }
+        ),
+
+        /**
+         * Batches asset fetches by path
+         */
+        assetLoader: new DataLoader<string, Asset | null>(
+            async (paths: readonly string[]) => {
+                log.debug(`Batching asset fetch for ${paths.length} assets`);
+
+                try {
+                    const result = await automationBridge.sendAutomationRequest<{
+                        success: boolean;
+                        assets?: Asset[];
+                    }>('manage_asset', {
+                        action: 'batch_get',
+                        assetPaths: [...paths]
+                    });
+
+                    if (result.success && result.assets) {
+                        return paths.map(path =>
+                            result.assets?.find(a => a.path === path) ?? null
+                        );
+                    }
+                } catch {
+                    log.debug('Batch asset fetch not supported');
+                }
+
+                // Fallback: check existence individually
+                const results = await Promise.all(
+                    paths.map(async (path) => {
+                        try {
+                            const result = await automationBridge.sendAutomationRequest<{
+                                success: boolean;
+                                exists?: boolean;
+                                asset?: Asset;
+                            }>('manage_asset', {
+                                action: 'exists',
+                                assetPath: path
+                            });
+
+                            if (result.success && result.exists) {
+                                return result.asset ?? { name: path.split('/').pop() || '', path };
+                            }
+                            return null;
+                        } catch {
+                            return null;
+                        }
+                    })
+                );
+                return results;
+            },
+            {
+                cache: true,
+                maxBatchSize: 100
+            }
+        ),
+
+        /**
+         * Batches blueprint fetches by path
+         */
+        blueprintLoader: new DataLoader<string, Blueprint | null>(
+            async (paths: readonly string[]) => {
+                log.debug(`Batching blueprint fetch for ${paths.length} blueprints`);
+
+                const results = await Promise.all(
+                    paths.map(async (path) => {
+                        try {
+                            const result = await automationBridge.sendAutomationRequest<{
+                                success: boolean;
+                                blueprint?: Blueprint;
+                            }>('manage_blueprint', {
+                                action: 'get_blueprint',
+                                blueprintPath: path
+                            });
+                            return result.success ? (result.blueprint ?? null) : null;
+                        } catch {
+                            return null;
+                        }
+                    })
+                );
+                return results;
+            },
+            {
+                cache: true,
+                maxBatchSize: 20
+            }
+        ),
+
+        /**
+         * Batches actor component fetches
+         */
+        actorComponentsLoader: new DataLoader<string, Array<{ name: string; type: string }> | null>(
+            async (actorNames: readonly string[]) => {
+                log.debug(`Batching component fetch for ${actorNames.length} actors`);
+
+                const results = await Promise.all(
+                    actorNames.map(async (actorName) => {
+                        try {
+                            const result = await automationBridge.sendAutomationRequest<{
+                                success: boolean;
+                                components?: Array<{ name: string; type: string }>;
+                            }>('control_actor', {
+                                action: 'get_components',
+                                actorName
+                            });
+                            return result.success ? (result.components ?? null) : null;
+                        } catch {
+                            return null;
+                        }
+                    })
+                );
+                return results;
+            },
+            {
+                cache: true,
+                maxBatchSize: 30
+            }
+        )
+    };
+}
+
+/**
+ * Clears all loader caches (useful between mutations)
+ */
+export function clearLoaders(loaders: GraphQLLoaders): void {
+    loaders.actorLoader.clearAll();
+    loaders.assetLoader.clearAll();
+    loaders.blueprintLoader.clearAll();
+    loaders.actorComponentsLoader.clearAll();
+}