unreal-engine-mcp-server 0.5.3 → 0.5.4

package/src/automation/bridge.ts

@@ -6,7 +6,9 @@ import {
     DEFAULT_AUTOMATION_PORT,
     DEFAULT_NEGOTIATED_PROTOCOLS,
     DEFAULT_HEARTBEAT_INTERVAL_MS,
-    DEFAULT_MAX_PENDING_REQUESTS
+    DEFAULT_MAX_PENDING_REQUESTS,
+    DEFAULT_MAX_QUEUED_REQUESTS,
+    MAX_WS_MESSAGE_SIZE_BYTES
 } from '../constants.js';
 import { createRequire } from 'node:module';
 import {
@@ -45,6 +47,7 @@ export class AutomationBridge extends EventEmitter {
     private readonly clientPort: number;
     private readonly serverLegacyEnabled: boolean;
     private readonly maxConcurrentConnections: number;
+    private readonly maxQueuedRequests: number;
 
     private connectionManager: ConnectionManager;
     private requestTracker: RequestTracker;
@@ -131,6 +134,7 @@ export class AutomationBridge extends EventEmitter {
 
         const maxPendingRequests = Math.max(1, options.maxPendingRequests ?? DEFAULT_MAX_PENDING_REQUESTS);
         const maxConcurrentConnections = Math.max(1, options.maxConcurrentConnections ?? 10);
+        this.maxQueuedRequests = Math.max(0, options.maxQueuedRequests ?? DEFAULT_MAX_QUEUED_REQUESTS);
 
         this.clientHost = options.clientHost ?? process.env.MCP_AUTOMATION_CLIENT_HOST ?? DEFAULT_AUTOMATION_HOST;
         this.clientPort = options.clientPort ?? sanitizePort(process.env.MCP_AUTOMATION_CLIENT_PORT) ?? DEFAULT_AUTOMATION_PORT;
@@ -185,13 +189,21 @@ export class AutomationBridge extends EventEmitter {
 
             this.log.debug(`Negotiated protocols: ${JSON.stringify(this.negotiatedProtocols)}`);
 
-            // Compatibility fix: If only one protocol, pass as string to ensure ws/plugin compatibility
-            const protocols = 'mcp-automation';
+            const protocols = this.negotiatedProtocols.length === 1
+                ? this.negotiatedProtocols[0]
+                : this.negotiatedProtocols;
 
             this.log.debug(`Using WebSocket protocols arg: ${JSON.stringify(protocols)}`);
 
+            const headers: Record<string, string> | undefined = this.capabilityToken
+                ? {
+                    'X-MCP-Capability': this.capabilityToken,
+                    'X-MCP-Capability-Token': this.capabilityToken
+                  }
+                : undefined;
+
             const socket = new WebSocket(url, protocols, {
-                headers: this.capabilityToken ? { 'X-MCP-Capability': this.capabilityToken } : undefined,
+                headers,
                 perMessageDeflate: false
             });
 
@@ -233,10 +245,69 @@ export class AutomationBridge extends EventEmitter {
                     protocol: socket.protocol || null
                 });
 
-                // Set up message handling for the authenticated socket
+                const getRawDataByteLength = (data: unknown): number => {
+                    if (typeof data === 'string') {
+                        return Buffer.byteLength(data, 'utf8');
+                    }
+
+                    if (Buffer.isBuffer(data)) {
+                        return data.length;
+                    }
+
+                    if (Array.isArray(data)) {
+                        return data.reduce((total, item) => total + (Buffer.isBuffer(item) ? item.length : 0), 0);
+                    }
+
+                    if (data instanceof ArrayBuffer) {
+                        return data.byteLength;
+                    }
+
+                    if (ArrayBuffer.isView(data)) {
+                        return data.byteLength;
+                    }
+
+                    return 0;
+                };
+
+                const rawDataToUtf8String = (data: unknown, byteLengthHint?: number): string => {
+                    if (typeof data === 'string') {
+                        return data;
+                    }
+
+                    if (Buffer.isBuffer(data)) {
+                        return data.toString('utf8');
+                    }
+
+                    if (Array.isArray(data)) {
+                        const buffers = data.filter((item): item is Buffer => Buffer.isBuffer(item));
+                        const totalLength = typeof byteLengthHint === 'number'
+                            ? byteLengthHint
+                            : buffers.reduce((total, item) => total + item.length, 0);
+                        return Buffer.concat(buffers, totalLength).toString('utf8');
+                    }
+
+                    if (data instanceof ArrayBuffer) {
+                        return Buffer.from(data).toString('utf8');
+                    }
+
+                    if (ArrayBuffer.isView(data)) {
+                        return Buffer.from(data.buffer, data.byteOffset, data.byteLength).toString('utf8');
+                    }
+
+                    return '';
+                };
+
                 socket.on('message', (data) => {
                     try {
-                        const text = typeof data === 'string' ? data : data.toString('utf8');
+                        const byteLength = getRawDataByteLength(data);
+                        if (byteLength > MAX_WS_MESSAGE_SIZE_BYTES) {
+                            this.log.error(
+                                `Received oversized message (${byteLength} bytes, max: ${MAX_WS_MESSAGE_SIZE_BYTES}). Dropping.`
+                            );
+                            return;
+                        }
+
+                        const text = rawDataToUtf8String(data, byteLength);
                         this.log.debug(`[AutomationBridge Client] Received message: ${text.substring(0, 1000)}`);
                         const parsed = JSON.parse(text) as AutomationBridgeMessage;
                         this.connectionManager.updateLastMessageTime();
@@ -431,11 +502,10 @@ export class AutomationBridge extends EventEmitter {
             throw new Error('Automation bridge not connected');
         }
 
-        // Check if we need to queue (unless it's a priority request which standard ones are not)
-        // We use requestTracker directly to check limit as it's the source of truth
-        // Note: requestTracker exposes maxPendingRequests via constructor but generic check logic isn't public
-        // We assumed getPendingCount() is available
         if (this.requestTracker.getPendingCount() >= this.requestTracker.getMaxPendingRequests()) {
+            if (this.queuedRequestItems.length >= this.maxQueuedRequests) {
+                throw new Error(`Automation bridge request queue is full (max: ${this.maxQueuedRequests}). Please retry later.`);
+            }
             return new Promise<T>((resolve, reject) => {
                 this.queuedRequestItems.push({
                     resolve,

package/src/automation/types.ts

@@ -12,6 +12,7 @@ export interface AutomationBridgeOptions {
     heartbeatIntervalMs?: number;
     maxPendingRequests?: number;
     maxConcurrentConnections?: number;
+    maxQueuedRequests?: number;
     clientMode?: boolean;
     clientHost?: string;
     clientPort?: number;

package/src/constants.ts

@@ -6,6 +6,7 @@ export const DEFAULT_NEGOTIATED_PROTOCOLS = ['mcp-automation'];
 export const DEFAULT_HEARTBEAT_INTERVAL_MS = 10000;
 export const DEFAULT_HANDSHAKE_TIMEOUT_MS = 5000;
 export const DEFAULT_MAX_PENDING_REQUESTS = 25;
+export const DEFAULT_MAX_QUEUED_REQUESTS = 100;
 export const DEFAULT_TIME_OF_DAY = 9;
 export const DEFAULT_SUN_INTENSITY = 10000;
 export const DEFAULT_SKYLIGHT_INTENSITY = 1;
@@ -22,3 +23,7 @@ export const LONG_RUNNING_OP_TIMEOUT_MS = 300000;
 export const CONSOLE_COMMAND_TIMEOUT_MS = 30000;
 export const ENGINE_QUERY_TIMEOUT_MS = 15000;
 export const CONNECTION_TIMEOUT_MS = 15000;
+
+// Message size limits
+export const MAX_WS_MESSAGE_SIZE_BYTES = 5 * 1024 * 1024;
+

package/src/graphql/server.ts

@@ -50,11 +50,32 @@ export class GraphQLServer {
       return;
     }
 
+    const isLoopback = this.config.host === '127.0.0.1' ||
+                        this.config.host === '::1' ||
+                        this.config.host.toLowerCase() === 'localhost';
+
+    const allowRemote = process.env.GRAPHQL_ALLOW_REMOTE === 'true';
+
+    if (!isLoopback && !allowRemote) {
+      this.log.warn(
+        `GraphQL server is configured to bind to non-loopback host '${this.config.host}'. GraphQL is for local debugging only. ` +
+          'To allow remote binding, set GRAPHQL_ALLOW_REMOTE=true. Aborting start.'
+      );
+      return;
+    }
+
+    if (!isLoopback && allowRemote) {
+      if (this.config.cors.origin === '*') {
+        this.log.warn(
+          "GraphQL server is binding to a remote host with permissive CORS origin '*'. " +
+            'Set GRAPHQL_CORS_ORIGIN to specific origins for production. Using permissive CORS for now.'
+        );
+      }
+    }
+
     try {
-      // Create GraphQL schema
       const schema = createGraphQLSchema(this.bridge, this.automationBridge);
 
-      // Create Yoga server
       const yoga = createYoga({
         schema,
         graphqlEndpoint: this.config.path,
@@ -77,12 +98,10 @@ export class GraphQLServer {
         }
       });
 
-      // Create HTTP server with Yoga's request handler
       this.server = createServer(
         yoga as any
       );
 
-      // Start server
       await new Promise<void>((resolve, reject) => {
         if (!this.server) {
           reject(new Error('Server not initialized'));
@@ -102,9 +121,6 @@ export class GraphQLServer {
           resolve();
         });
       });
-
-      // Setup graceful shutdown
-      this.setupShutdown();
     } catch (error) {
       this.log.error('Failed to start GraphQL server:', error);
       throw error;
@@ -130,22 +146,6 @@ export class GraphQLServer {
     });
   }
 
-  private setupShutdown(): void {
-    const gracefulShutdown = async (signal: string) => {
-      this.log.info(`Received ${signal}, shutting down GraphQL server...`);
-      try {
-        await this.stop();
-        process.exit(0);
-      } catch (error) {
-        this.log.error('Error during GraphQL server shutdown:', error);
-        process.exit(1);
-      }
-    };
-
-    process.on('SIGINT', () => gracefulShutdown('SIGINT'));
-    process.on('SIGTERM', () => gracefulShutdown('SIGTERM'));
-  }
-
   getConfig() {
     return this.config;
   }

package/src/index.ts

@@ -30,7 +30,7 @@ const DEFAULT_SERVER_NAME = typeof packageInfo.name === 'string' && packageInfo.
   : 'unreal-engine-mcp';
 const DEFAULT_SERVER_VERSION = typeof packageInfo.version === 'string' && packageInfo.version.trim().length > 0
   ? packageInfo.version
-  : '0.5.3';
+  : '0.5.4';
 
 function routeStdoutLogsToStderr(): void {
   if (!config.MCP_ROUTE_STDOUT_LOGS) {

package/src/services/metrics-server.ts

@@ -3,7 +3,6 @@ import { HealthMonitor } from './health-monitor.js';
 import { AutomationBridge } from '../automation/index.js';
 import { Logger } from '../utils/logger.js';
 import { wasmIntegration } from '../wasm/index.js';
-import { DEFAULT_AUTOMATION_HOST } from '../constants.js';
 
 interface MetricsServerOptions {
   healthMonitor: HealthMonitor;
@@ -96,6 +95,8 @@ export function startMetricsServer(options: MetricsServerOptions): http.Server |
     return null;
   }
 
+  const host = process.env.MCP_METRICS_HOST || '127.0.0.1';
+
   // Simple rate limiting: max 60 requests per minute per IP
   const RATE_LIMIT_WINDOW_MS = 60000;
   const RATE_LIMIT_MAX_REQUESTS = 60;
@@ -139,7 +140,6 @@ export function startMetricsServer(options: MetricsServerOptions): http.Server |
         return;
       }
 
-      // Apply rate limiting
       const clientIp = req.socket.remoteAddress || 'unknown';
       if (!checkRateLimit(clientIp)) {
         res.statusCode = 429;
@@ -160,8 +160,8 @@ export function startMetricsServer(options: MetricsServerOptions): http.Server |
       }
     });
 
-    server.listen(port, () => {
-      logger.info(`Prometheus metrics server listening on http://${DEFAULT_AUTOMATION_HOST}:${port}/metrics`);
+    server.listen(port, host, () => {
+      logger.info(`Prometheus metrics server listening on http://${host}:${port}/metrics`);
     });
 
     server.on('error', (err) => {

package/src/tools/handlers/pipeline-handlers.ts

@@ -6,6 +6,67 @@ import { spawn } from 'child_process';
 import path from 'path';
 import fs from 'fs';
 
+function validateUbtArgumentsString(extraArgs: string): void {
+  if (!extraArgs || typeof extraArgs !== 'string') {
+    return;
+  }
+
+  const forbiddenChars = ['\n', '\r', ';', '|', '`', '&&', '||', '>', '<'];
+  for (const char of forbiddenChars) {
+    if (extraArgs.includes(char)) {
+      throw new Error(
+        `UBT arguments contain forbidden character(s) and are blocked for safety. Blocked: ${JSON.stringify(char)}.`
+      );
+    }
+  }
+}
+
+function tokenizeArgs(extraArgs: string): string[] {
+  if (!extraArgs) {
+    return [];
+  }
+
+  const args: string[] = [];
+  let current = '';
+  let inQuotes = false;
+  let escapeNext = false;
+
+  for (let i = 0; i < extraArgs.length; i++) {
+    const ch = extraArgs[i];
+
+    if (escapeNext) {
+      current += ch;
+      escapeNext = false;
+      continue;
+    }
+
+    if (ch === '\\') {
+      escapeNext = true;
+      continue;
+    }
+
+    if (ch === '"') {
+      inQuotes = !inQuotes;
+      continue;
+    }
+
+    if (!inQuotes && /\s/.test(ch)) {
+      if (current.length > 0) {
+        args.push(current);
+        current = '';
+      }
+    } else {
+      current += ch;
+    }
+  }
+
+  if (current.length > 0) {
+    args.push(current);
+  }
+
+  return args;
+}
+
 export async function handlePipelineTools(action: string, args: PipelineArgs, tools: ITools) {
   switch (action) {
     case 'run_ubt': {
@@ -18,8 +79,9 @@ export async function handlePipelineTools(action: string, args: PipelineArgs, to
         throw new Error('Target is required for run_ubt');
       }
 
-      // Try to find UnrealBuildTool
-      let ubtPath = 'UnrealBuildTool'; // Assume in PATH by default
+      validateUbtArgumentsString(extraArgs);
+
+      let ubtPath = 'UnrealBuildTool';
       const enginePath = process.env.UE_ENGINE_PATH || process.env.UNREAL_ENGINE_PATH;
 
       if (enginePath) {
@@ -38,10 +100,8 @@ export async function handlePipelineTools(action: string, args: PipelineArgs, to
         throw new Error('UE_PROJECT_PATH environment variable is not set and no projectPath argument was provided.');
       }
 
-      // If projectPath points to a .uproject file, use it. If it's a directory, look for a .uproject file.
       let uprojectFile = projectPath;
       if (!uprojectFile.endsWith('.uproject')) {
-        // Find first .uproject in the directory
         try {
           const files = fs.readdirSync(projectPath);
           const found = files.find(f => f.endsWith('.uproject'));
@@ -53,16 +113,19 @@ export async function handlePipelineTools(action: string, args: PipelineArgs, to
         }
       }
 
+      const projectArg = `-Project="${uprojectFile}"`;
+      const extraTokens = tokenizeArgs(extraArgs);
+
       const cmdArgs = [
         target,
         platform,
         configuration,
-        `-Project="${uprojectFile}"`,
-        extraArgs
-      ].filter(Boolean);
+        projectArg,
+        ...extraTokens
+      ];
 
       return new Promise((resolve) => {
-        const child = spawn(ubtPath, cmdArgs, { shell: true });
+        const child = spawn(ubtPath, cmdArgs, { shell: false });
 
         const MAX_OUTPUT_SIZE = 20 * 1024; // 20KB cap
         let stdout = '';
@@ -91,12 +154,14 @@ export async function handlePipelineTools(action: string, args: PipelineArgs, to
             ? '\n[Output truncated for response payload]'
             : '';
 
+          const quotedArgs = cmdArgs.map(arg => arg.includes(' ') ? `"${arg}"` : arg);
+
           if (code === 0) {
             resolve({
               success: true,
               message: 'UnrealBuildTool finished successfully',
               output: stdout + truncatedNote,
-              command: `${ubtPath} ${cmdArgs.join(' ')}`
+              command: `${ubtPath} ${quotedArgs.join(' ')}`
             });
           } else {
             resolve({
@@ -105,23 +170,24 @@ export async function handlePipelineTools(action: string, args: PipelineArgs, to
               message: `UnrealBuildTool failed with code ${code}`,
               output: stdout + truncatedNote,
               errorOutput: stderr + truncatedNote,
-              command: `${ubtPath} ${cmdArgs.join(' ')}`
+              command: `${ubtPath} ${quotedArgs.join(' ')}`
             });
           }
         });
 
         child.on('error', (err) => {
+          const quotedArgs = cmdArgs.map(arg => arg.includes(' ') ? `"${arg}"` : arg);
+
           resolve({
             success: false,
             error: 'SPAWN_FAILED',
             message: `Failed to spawn UnrealBuildTool: ${err.message}`,
-            command: `${ubtPath} ${cmdArgs.join(' ')}`
+            command: `${ubtPath} ${quotedArgs.join(' ')}`
           });
         });
       });
     }
     default:
-      // Fallback to automation bridge if we add more actions later that are bridge-supported
       const res = await executeAutomationRequest(tools, 'manage_pipeline', { ...args, subAction: action }, 'Automation bridge not available for manage_pipeline');
       return cleanObject(res);
   }

package/src/utils/validation.test.ts

@@ -59,9 +59,9 @@ describe('sanitizePath', () => {
     });
 
     it('sanitizes path segments with dots', () => {
-        const result = sanitizePath('/Game/../MyAsset');
-        // Each segment is sanitized, .. becomes a segment that gets sanitized
-        expect(result).toContain('/');
+        expect(() => sanitizePath('/Game/../MyAsset')).toThrow(
+            'Path traversal (..) is not allowed'
+        );
     });
 });
 

package/tests/test-console-command.mjs

@@ -43,7 +43,7 @@ const testCases = [
     scenario: "Edge: Very long safe command",
     toolName: "system_control",
     arguments: { action: "console_command", command: "stat fps; stat gpu; stat memory" },
-    expected: "success"
+    expected: "blocked|command_blocked|blocked for safety"
   },
   {
     scenario: "Warning: Unknown command",

package/tests/test-runner.mjs

@@ -20,6 +20,66 @@ let serverArgs = process.env.UNREAL_MCP_SERVER_ARGS ? process.env.UNREAL_MCP_SER
 const serverCwd = process.env.UNREAL_MCP_SERVER_CWD ?? repoRoot;
 const serverEnv = Object.assign({}, process.env);
 
+const DEFAULT_RESPONSE_LOG_MAX_CHARS = 6000; // default max chars
+const RESPONSE_LOGGING_ENABLED = process.env.UNREAL_MCP_TEST_LOG_RESPONSES !== '0';
+
+function clampString(value, maxChars) {
+  if (typeof value !== 'string') return '';
+  if (value.length <= maxChars) return value;
+  return value.slice(0, maxChars) + `\n... (truncated, ${value.length - maxChars} chars omitted)`;
+}
+
+function tryParseJson(text) {
+  if (typeof text !== 'string') return null;
+  try {
+    return JSON.parse(text);
+  } catch {
+    return null;
+  }
+}
+
+export function normalizeMcpResponse(response) {
+  const normalized = {
+    isError: Boolean(response?.isError),
+    structuredContent: response?.structuredContent ?? null,
+    contentText: '',
+    content: response?.content ?? undefined
+  };
+
+  if (normalized.structuredContent === null && Array.isArray(response?.content)) {
+    for (const entry of response.content) {
+      if (entry?.type !== 'text' || typeof entry.text !== 'string') continue;
+      const parsed = tryParseJson(entry.text);
+      if (parsed !== null) {
+        normalized.structuredContent = parsed;
+        break;
+      }
+    }
+  }
+
+  if (Array.isArray(response?.content) && response.content.length > 0) {
+    normalized.contentText = response.content
+      .map((entry) => (entry && typeof entry.text === 'string' ? entry.text : ''))
+      .filter((text) => text.length > 0)
+      .join('\n');
+  }
+
+  return normalized;
+}
+
+function logMcpResponse(toolName, normalizedResponse) {
+  const maxChars = Number(process.env.UNREAL_MCP_TEST_RESPONSE_MAX_CHARS ?? DEFAULT_RESPONSE_LOG_MAX_CHARS);
+  const payload = {
+    isError: normalizedResponse.isError,
+    structuredContent: normalizedResponse.structuredContent,
+    contentText: normalizedResponse.contentText,
+    content: normalizedResponse.content
+  };
+  const json = JSON.stringify(payload, null, 2);
+  console.log(`[MCP RESPONSE] ${toolName}:`);
+  console.log(clampString(json, Number.isFinite(maxChars) && maxChars > 0 ? maxChars : DEFAULT_RESPONSE_LOG_MAX_CHARS));
+}
+
 function formatResultLine(testCase, status, detail, durationMs) {
   const durationText = typeof durationMs === 'number' ? ` (${durationMs.toFixed(1)} ms)` : '';
   return `[${status.toUpperCase()}] ${testCase.scenario}${durationText}${detail ? ` => ${detail}` : ''}`;
@@ -515,13 +575,13 @@ export async function runToolTests(toolName, testCases) {
           }
         }
         const normalizedResponse = { ...response, structuredContent };
+        if (RESPONSE_LOGGING_ENABLED) {
+          logMcpResponse(testCase.toolName + " :: " + testCase.scenario, normalizeMcpResponse(normalizedResponse));
+        }
         const { passed, reason } = evaluateExpectation(testCase, normalizedResponse);
 
         if (!passed) {
           console.log(`[FAILED] ${testCase.scenario} (${durationMs.toFixed(1)} ms) => ${reason}`);
-          if (normalizedResponse) {
-            console.log(`[DEBUG] Full response for ${testCase.scenario}:`, JSON.stringify(normalizedResponse, null, 2));
-          }
           results.push({
             scenario: testCase.scenario,
             toolName: testCase.toolName,