unreal-engine-mcp-server 0.4.7 → 0.5.1

package/src/utils/command-validator.ts

@@ -0,0 +1,76 @@
+export class CommandValidator {
+    private static readonly DANGEROUS_COMMANDS = [
+        'quit', 'exit', 'delete', 'destroy', 'kill', 'crash',
+        'viewmode visualizebuffer basecolor',
+        'viewmode visualizebuffer worldnormal',
+        'r.gpucrash',
+        'buildpaths', // Can cause access violation if nav system not initialized
+        'rebuildnavigation', // Can also crash without proper nav setup
+        'obj garbage', 'obj list', 'memreport' // Heavy debug commands that can stall
+    ];
+
+    private static readonly 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(', 'write(', 'read('
+    ];
+
+    private static readonly INVALID_PATTERNS = [
+        /^\d+$/,  // Just numbers
+        /^invalid_command/i,
+        /^this_is_not_a_valid/i,
+    ];
+
+    static validate(command: string): void {
+        if (!command || typeof command !== 'string') {
+            throw new Error('Invalid command: must be a non-empty string');
+        }
+
+        const cmdTrimmed = command.trim();
+        if (cmdTrimmed.length === 0) {
+            return; // Empty commands are technically valid (no-op)
+        }
+
+        if (cmdTrimmed.includes('\n') || cmdTrimmed.includes('\r')) {
+            throw new Error('Multi-line console commands are not allowed. Send one command per call.');
+        }
+
+        const cmdLower = cmdTrimmed.toLowerCase();
+
+        if (cmdLower === 'py' || cmdLower.startsWith('py ')) {
+            throw new Error('Python console commands are blocked from external calls for safety.');
+        }
+
+        if (this.DANGEROUS_COMMANDS.some(dangerous => cmdLower.includes(dangerous))) {
+            throw new Error(`Dangerous command blocked: ${command}`);
+        }
+
+        if (cmdLower.includes('&&') || cmdLower.includes('||')) {
+            throw new Error('Command chaining with && or || is blocked for safety.');
+        }
+
+        if (this.FORBIDDEN_TOKENS.some(token => cmdLower.includes(token))) {
+            throw new Error(`Command contains unsafe token and was blocked: ${command}`);
+        }
+    }
+
+    static isLikelyInvalid(command: string): boolean {
+        const cmdTrimmed = command.trim();
+        return this.INVALID_PATTERNS.some(pattern => pattern.test(cmdTrimmed));
+    }
+
+    static getPriority(command: string): number {
+        if (command.includes('BuildLighting') || command.includes('BuildPaths')) {
+            return 1; // Heavy operation
+        } else if (command.includes('summon') || command.includes('spawn')) {
+            return 5; // Medium operation
+        } else if (command.startsWith('stat')) {
+            return 8; // Dedicated throttling for stat commands
+        } else if (command.startsWith('show')) {
+            return 9; // Light operation
+        }
+        return 7; // Default priority
+    }
+}

package/src/utils/elicitation.ts

@@ -2,7 +2,7 @@ import type { Server } from '@modelcontextprotocol/sdk/server/index.js';
 import { Logger } from './logger.js';
 
 // Minimal helper to opportunistically use MCP Elicitation when available.
-// Safe across clients: validates schema shape, handles timeouts and -32601 fallbacks.
+// Safe across clients: validates schema shape and handles timeouts and -32601 errors.
 export type PrimitiveSchema =
   | { type: 'string'; title?: string; description?: string; minLength?: number; maxLength?: number; pattern?: string; format?: 'email'|'uri'|'date'|'date-time'; default?: string }
   | { type: 'number'|'integer'; title?: string; description?: string; minimum?: number; maximum?: number; default?: number }
@@ -17,7 +17,9 @@ export interface ElicitSchema {
 
 export interface ElicitOptions {
   timeoutMs?: number;
-  fallback?: () => Promise<{ ok: boolean; value?: any; error?: string }>;
+  // Handler invoked when elicitation cannot be performed; previously named
+  // Handler invoked when elicitation cannot be performed.
+  alternate?: () => Promise<{ ok: boolean; value?: any; error?: string }>;
 }
 
 export function createElicitationHelper(server: Server, log: Logger) {
@@ -77,7 +79,7 @@ export function createElicitationHelper(server: Server, log: Logger) {
 
   async function elicit(message: string, requestedSchema: ElicitSchema, opts: ElicitOptions = {}) {
     if (!supported || !isSafeSchema(requestedSchema)) {
-      if (opts.fallback) return opts.fallback();
+      if (opts.alternate) return opts.alternate();
       return { ok: false, error: 'elicitation-unsupported' };
     }
 
@@ -98,10 +100,10 @@ export function createElicitationHelper(server: Server, log: Logger) {
 
       if (action === 'accept') return { ok: true, value: content };
       if (action === 'decline' || action === 'cancel') {
-        if (opts.fallback) return opts.fallback();
+        if (opts.alternate) return opts.alternate();
         return { ok: false, error: action };
       }
-      if (opts.fallback) return opts.fallback();
+      if (opts.alternate) return opts.alternate();
       return { ok: false, error: 'unexpected-response' };
     } catch (e: any) {
       const msg = String(e?.message || e);
@@ -115,8 +117,9 @@ export function createElicitationHelper(server: Server, log: Logger) {
       ) {
         supported = false;
       }
-      log.debug('Elicitation failed; falling back', { error: msg, code });
-      if (opts.fallback) return opts.fallback();
+  // Use an alternate handler if provided when elicitation fails.
+  log.debug('Elicitation failed; using alternate handler', { error: msg, code });
+      if (opts.alternate) return opts.alternate();
       return { ok: false, error: msg.includes('timeout') ? 'timeout' : 'rpc-failed' };
     }
   }

package/src/utils/error-handler.ts

@@ -95,7 +95,7 @@ export class ErrorHandler {
     // Unreal Engine specific errors
     if (
       errorMessage.includes('unreal') ||
-      errorMessage.includes('remote control') ||
+      errorMessage.includes('connection failed') ||
       errorMessage.includes('blueprint') ||
       errorMessage.includes('actor') ||
       errorMessage.includes('asset')
@@ -128,7 +128,7 @@ export class ErrorHandler {
 
     switch (type) {
       case ErrorType.CONNECTION:
-        return 'Failed to connect to Unreal Engine. Please ensure Remote Control is enabled and the engine is running.';
+        return 'Failed to connect to Unreal Engine. Please ensure the Automation Bridge plugin is active and the editor is running.';
       
       case ErrorType.VALIDATION:
         return `Invalid input: ${originalMessage}`;
@@ -164,114 +164,38 @@ export class ErrorHandler {
   }
 
   /**
-   * Retry an async operation with exponential backoff
-   * Best practice from TypeScript async programming patterns
-   * @param operation - Async operation to retry
-   * @param options - Retry configuration
-   * @returns Result of the operation
+   * Retry a function with exponential backoff
    */
   static async retryWithBackoff<T>(
-    operation: () => Promise<T>,
+    fn: () => Promise<T>,
     options: {
       maxRetries?: number;
       initialDelay?: number;
       maxDelay?: number;
       backoffMultiplier?: number;
-      shouldRetry?: (error: unknown) => boolean;
+      shouldRetry?: (error: any) => boolean;
     } = {}
   ): Promise<T> {
-    const {
-      maxRetries = 3,
-      initialDelay = 100,
-      maxDelay = 10000,
-      backoffMultiplier = 2,
-      shouldRetry = (error) => this.isRetriable(error)
-    } = options;
+    const maxRetries = options.maxRetries ?? 3;
+    const initialDelay = options.initialDelay ?? 1000;
+    const maxDelay = options.maxDelay ?? 10000;
+    const multiplier = options.backoffMultiplier ?? 2;
+    const shouldRetry = options.shouldRetry ?? ((err) => this.isRetriable(err));
 
-    let lastError: unknown;
     let delay = initialDelay;
 
     for (let attempt = 0; attempt <= maxRetries; attempt++) {
       try {
-        return await operation();
+        return await fn();
       } catch (error) {
-        lastError = error;
-
         if (attempt === maxRetries || !shouldRetry(error)) {
           throw error;
         }
-
-        log.debug(`Retry attempt ${attempt + 1}/${maxRetries} after ${delay}ms`);
+        
         await new Promise(resolve => setTimeout(resolve, delay));
-
-        delay = Math.min(delay * backoffMultiplier, maxDelay);
+        delay = Math.min(delay * multiplier, maxDelay);
       }
     }
-
-    throw lastError;
-  }
-
-  /**
-   * Add timeout to any promise
-   * @param promise - Promise to add timeout to
-   * @param timeoutMs - Timeout in milliseconds
-   * @param errorMessage - Custom error message for timeout
-   * @returns Promise that rejects on timeout
-   */
-  static async withTimeout<T>(
-    promise: Promise<T>,
-    timeoutMs: number,
-    errorMessage = 'Operation timed out'
-  ): Promise<T> {
-    let timeoutHandle: NodeJS.Timeout | undefined;
-
-    const timeoutPromise = new Promise<never>((_, reject) => {
-      timeoutHandle = setTimeout(() => {
-        reject(new Error(errorMessage));
-      }, timeoutMs);
-    });
-
-    try {
-      return await Promise.race([promise, timeoutPromise]);
-    } finally {
-      if (timeoutHandle !== undefined) {
-        clearTimeout(timeoutHandle);
-      }
-    }
-  }
-
-  /**
-   * Execute multiple operations with Promise.allSettled for better error handling
-   * Returns detailed results for each operation, including failures
-   * @param operations - Array of async operations to execute
-   * @returns Object with successful and failed operations separated
-   */
-  static async batchExecute<T>(
-    operations: Array<() => Promise<T>>
-  ): Promise<{
-    successful: Array<{ index: number; value: T }>;
-    failed: Array<{ index: number; reason: unknown }>;
-    successCount: number;
-    failureCount: number;
-  }> {
-    const results = await Promise.allSettled(operations.map(op => op()));
-
-    const successful: Array<{ index: number; value: T }> = [];
-    const failed: Array<{ index: number; reason: unknown }> = [];
-
-    results.forEach((result, index) => {
-      if (result.status === 'fulfilled') {
-        successful.push({ index, value: result.value });
-      } else {
-        failed.push({ index, reason: result.reason });
-      }
-    });
-
-    return {
-      successful,
-      failed,
-      successCount: successful.length,
-      failureCount: failed.length
-    };
+    throw new Error('Max retries exceeded');
   }
 }

package/src/utils/ini-reader.ts

@@ -0,0 +1,86 @@
+import fs from 'fs/promises';
+import path from 'path';
+
+export async function readIniFile(filePath: string): Promise<Record<string, Record<string, string>>> {
+  try {
+    const content = await fs.readFile(filePath, 'utf-8');
+    const result: Record<string, Record<string, string>> = {};
+    let currentSection = '';
+
+    const lines = content.split(/\r?\n/);
+    for (const line of lines) {
+      const trimmed = line.trim();
+      if (!trimmed || trimmed.startsWith(';') || trimmed.startsWith('#')) {
+        continue;
+      }
+
+      if (trimmed.startsWith('[') && trimmed.endsWith(']')) {
+        currentSection = trimmed.substring(1, trimmed.length - 1);
+        result[currentSection] = {};
+      } else if (currentSection) {
+        const parts = trimmed.split('=');
+        if (parts.length >= 2) {
+          const key = parts[0].trim();
+          const value = parts.slice(1).join('=').trim();
+          result[currentSection][key] = value;
+        }
+      }
+    }
+
+    return result;
+  } catch (error) {
+    throw new Error(`Failed to read INI file at ${filePath}: ${error instanceof Error ? error.message : String(error)}`);
+  }
+}
+
+export async function getProjectSetting(projectPath: string, category: string, sectionName: string, key?: string): Promise<any> {
+    // Normalize project path to directory
+    let dirPath = projectPath;
+    if (dirPath.toLowerCase().endsWith('.uproject')) {
+        dirPath = path.dirname(dirPath);
+    }
+
+    // Possible file names/locations in order of preference (Config/DefaultX.ini, Saved/Config/WindowsEditor/X.ini)
+    // category is usually 'Project', 'Engine', 'Game', 'Input', etc.
+    const cleanCategory = category.replace(/^Default/, ''); // If caller passed 'DefaultEngine', normalize to 'Engine'
+    
+    const candidates = [
+        path.join(dirPath, 'Config', `Default${cleanCategory}.ini`),
+        path.join(dirPath, 'Saved', 'Config', 'WindowsEditor', `${cleanCategory}.ini`),
+        path.join(dirPath, 'Saved', 'Config', 'Windows', `${cleanCategory}.ini`),
+        path.join(dirPath, 'Saved', 'Config', 'Mac', `${cleanCategory}.ini`),
+        path.join(dirPath, 'Saved', 'Config', 'Linux', `${cleanCategory}.ini`)
+    ];
+
+    for (const configPath of candidates) {
+        try {
+            const iniData = await readIniFile(configPath);
+            // If we successfully read the file, check for the section
+            if (sectionName) {
+                const section = iniData[sectionName];
+                if (section) {
+                    if (key) {
+                        return section[key];
+                    }
+                    return section;
+                }
+                // If section not found in this file, continue to next candidate? 
+                // Usually we want the most authoritative, but if it's missing the section, maybe it's in another?
+                // For now, if we find the file, we return the data from it or null if section missing.
+                // Merging is complex without a proper config hierarchy implementation.
+                // We will assume if the file exists, it's the one we want, or if section is missing, we fail for this file.
+                // But 'Default' might lack user overrides.
+                // Given this is a simple reader, we'll return the first match that contains the section, 
+                // or if sectionName is empty, the first file found.
+            } else {
+                if (Object.keys(iniData).length > 0) {
+                    return iniData;
+                }
+            }
+        } catch (_e) {
+            // Continue to next candidate
+        }
+    }
+
+    return null;
+}

package/src/utils/logger.ts

@@ -16,13 +16,18 @@ export class Logger {
   }
 
   debug(...args: any[]) {
-    if (this.shouldLog('debug')) console.error(`[${this.scope}]`, ...args);
+    if (!this.shouldLog('debug')) return;
+    // Write to stderr to avoid corrupting MCP stdout stream
+    console.error(`[${this.scope}]`, ...args);
   }
   info(...args: any[]) {
-    if (this.shouldLog('info')) console.error(`[${this.scope}]`, ...args);
+    if (!this.shouldLog('info')) return;
+    // Write to stderr to avoid corrupting MCP stdout stream
+    console.error(`[${this.scope}]`, ...args);
   }
   warn(...args: any[]) {
-    if (this.shouldLog('warn')) console.error(`[${this.scope}]`, ...args);
+    if (!this.shouldLog('warn')) return;
+    console.warn(`[${this.scope}]`, ...args);
   }
   error(...args: any[]) {
     if (this.shouldLog('error')) console.error(`[${this.scope}]`, ...args);

package/src/utils/normalize.test.ts

@@ -0,0 +1,162 @@
+/**
+ * Unit tests for normalize utility functions
+ */
+import { describe, it, expect } from 'vitest';
+import {
+    toVec3Object,
+    toRotObject,
+    toVec3Tuple,
+    toRotTuple,
+    toFiniteNumber,
+    normalizePartialVector,
+    normalizeTransformInput
+} from './normalize.js';
+
+describe('toVec3Object', () => {
+    it('converts object input to Vector3', () => {
+        const result = toVec3Object({ x: 1, y: 2, z: 3 });
+        expect(result).toEqual({ x: 1, y: 2, z: 3 });
+    });
+
+    it('converts array input to Vector3', () => {
+        const result = toVec3Object([1, 2, 3]);
+        expect(result).toEqual({ x: 1, y: 2, z: 3 });
+    });
+
+    it('returns null for invalid input', () => {
+        expect(toVec3Object('invalid')).toBeNull();
+        expect(toVec3Object(null)).toBeNull();
+        expect(toVec3Object(undefined)).toBeNull();
+    });
+
+    it('returns null for incomplete object', () => {
+        expect(toVec3Object({ x: 1, y: 2 })).toBeNull();
+    });
+
+    it('handles zero values', () => {
+        const result = toVec3Object({ x: 0, y: 0, z: 0 });
+        expect(result).toEqual({ x: 0, y: 0, z: 0 });
+    });
+});
+
+describe('toRotObject', () => {
+    it('converts object input to Rotator', () => {
+        const result = toRotObject({ pitch: 10, yaw: 20, roll: 30 });
+        expect(result).toEqual({ pitch: 10, yaw: 20, roll: 30 });
+    });
+
+    it('converts array input to Rotator', () => {
+        const result = toRotObject([10, 20, 30]);
+        expect(result).toEqual({ pitch: 10, yaw: 20, roll: 30 });
+    });
+
+    it('returns null for invalid input', () => {
+        expect(toRotObject('invalid')).toBeNull();
+        expect(toRotObject(null)).toBeNull();
+    });
+});
+
+describe('toVec3Tuple', () => {
+    it('converts object to tuple', () => {
+        const result = toVec3Tuple({ x: 1, y: 2, z: 3 });
+        expect(result).toEqual([1, 2, 3]);
+    });
+
+    it('passes through valid array', () => {
+        const result = toVec3Tuple([1, 2, 3]);
+        expect(result).toEqual([1, 2, 3]);
+    });
+
+    it('returns null for invalid input', () => {
+        expect(toVec3Tuple([1, 2])).toBeNull();
+        expect(toVec3Tuple(null)).toBeNull();
+    });
+});
+
+describe('toRotTuple', () => {
+    it('converts object to tuple', () => {
+        const result = toRotTuple({ pitch: 10, yaw: 20, roll: 30 });
+        expect(result).toEqual([10, 20, 30]);
+    });
+
+    it('passes through valid array', () => {
+        const result = toRotTuple([10, 20, 30]);
+        expect(result).toEqual([10, 20, 30]);
+    });
+});
+
+describe('toFiniteNumber', () => {
+    it('accepts valid numbers', () => {
+        expect(toFiniteNumber(42)).toBe(42);
+        expect(toFiniteNumber(0)).toBe(0);
+        expect(toFiniteNumber(-5)).toBe(-5);
+        expect(toFiniteNumber(3.14)).toBe(3.14);
+    });
+
+    it('parses string numbers', () => {
+        expect(toFiniteNumber('42')).toBe(42);
+        expect(toFiniteNumber('3.14')).toBe(3.14);
+    });
+
+    it('returns undefined for invalid input', () => {
+        expect(toFiniteNumber('not a number')).toBeUndefined();
+        expect(toFiniteNumber(NaN)).toBeUndefined();
+        expect(toFiniteNumber(Infinity)).toBeUndefined();
+        expect(toFiniteNumber(null)).toBeUndefined();
+        expect(toFiniteNumber(undefined)).toBeUndefined();
+    });
+});
+
+describe('normalizePartialVector', () => {
+    it('normalizes complete vectors', () => {
+        const result = normalizePartialVector({ x: 1, y: 2, z: 3 });
+        expect(result).toEqual({ x: 1, y: 2, z: 3 });
+    });
+
+    it('handles partial vectors', () => {
+        const result = normalizePartialVector({ x: 1 });
+        expect(result).toBeDefined();
+        expect(result?.x).toBe(1);
+    });
+
+    it('uses alternate keys for reading input', () => {
+        const result = normalizePartialVector(
+            { pitch: 10, yaw: 20, roll: 30 },
+            ['pitch', 'yaw', 'roll']
+        );
+        // alternateKeys are used to READ from input, but output is still x/y/z
+        expect(result).toEqual({ x: 10, y: 20, z: 30 });
+    });
+
+    it('returns undefined for invalid input', () => {
+        expect(normalizePartialVector(null)).toBeUndefined();
+        expect(normalizePartialVector('string')).toBeUndefined();
+    });
+});
+
+describe('normalizeTransformInput', () => {
+    it('normalizes complete transform', () => {
+        const result = normalizeTransformInput({
+            location: { x: 0, y: 0, z: 100 },
+            rotation: { pitch: 0, yaw: 90, roll: 0 },
+            scale: { x: 1, y: 1, z: 1 }
+        });
+        expect(result).toBeDefined();
+        expect(result?.location).toBeDefined();
+        expect(result?.rotation).toBeDefined();
+        expect(result?.scale).toBeDefined();
+    });
+
+    it('handles partial transforms', () => {
+        const result = normalizeTransformInput({
+            location: { x: 100, y: 200, z: 300 }
+        });
+        expect(result).toBeDefined();
+        expect(result?.location).toBeDefined();
+    });
+
+    it('returns undefined for invalid input', () => {
+        expect(normalizeTransformInput(null)).toBeUndefined();
+        expect(normalizeTransformInput('invalid')).toBeUndefined();
+    });
+});

package/src/utils/normalize.ts

@@ -62,3 +62,63 @@ export function toRotTuple(input: any): Rot3Tuple | null {
   return [pitch, yaw, roll];
 }
 
+/**
+ * Parse a raw value into a finite number when possible.
+ * Accepts strings like "1.0" and returns number or undefined when invalid.
+ */
+export function toFiniteNumber(raw: unknown): number | undefined {
+  if (typeof raw === 'number' && Number.isFinite(raw)) return raw;
+  if (typeof raw === 'string') {
+    const trimmed = raw.trim();
+    if (trimmed.length === 0) return undefined;
+    const parsed = Number(trimmed);
+    if (Number.isFinite(parsed)) return parsed;
+  }
+  return undefined;
+}
+
+/**
+ * Normalize a partial vector input. Unlike toVec3Object, this accepts
+ * partial specifications and returns an object containing only present
+ * components (x/y/z) when any are provided; otherwise returns undefined.
+ */
+export function normalizePartialVector(value: any, alternateKeys: string[] = ['x', 'y', 'z']): Record<string, number> | undefined {
+  if (value === undefined || value === null) return undefined;
+  const result: Record<string, number> = {};
+  const assignIfPresent = (component: 'x' | 'y' | 'z', raw: unknown) => {
+    const num = toFiniteNumber(raw);
+    if (num !== undefined) result[component] = num;
+  };
+
+  if (Array.isArray(value)) {
+    if (value.length > 0) assignIfPresent('x', value[0]);
+    if (value.length > 1) assignIfPresent('y', value[1]);
+    if (value.length > 2) assignIfPresent('z', value[2]);
+  } else if (typeof value === 'object') {
+    const obj = value as Record<string, unknown>;
+    assignIfPresent('x', obj.x ?? obj[alternateKeys[0]]);
+    assignIfPresent('y', obj.y ?? obj[alternateKeys[1]]);
+    assignIfPresent('z', obj.z ?? obj[alternateKeys[2]]);
+  } else {
+    assignIfPresent('x', value);
+  }
+
+  return Object.keys(result).length > 0 ? result : undefined;
+}
+
+/**
+ * Normalize a transform-like input into a minimal object containing
+ * location/rotation/scale partial descriptors when present.
+ */
+export function normalizeTransformInput(transform: any): Record<string, unknown> | undefined {
+  if (!transform || typeof transform !== 'object') return undefined;
+  const result: Record<string, unknown> = {};
+  const location = normalizePartialVector(transform.location);
+  if (location) result.location = location;
+  const rotation = normalizePartialVector(transform.rotation, ['pitch', 'yaw', 'roll']);
+  if (rotation) result.rotation = rotation;
+  const scale = normalizePartialVector(transform.scale);
+  if (scale) result.scale = scale;
+  return Object.keys(result).length > 0 ? result : undefined;
+}
+

package/src/utils/path-security.ts

@@ -0,0 +1,43 @@
+export function sanitizePath(path: string, allowedRoots: string[] = ['/Game', '/Engine']): string {
+    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');
+    }
+
+    // Normalize separators
+    const normalized = trimmed.replace(/\\/g, '/');
+
+    // Prevent directory traversal
+    if (normalized.includes('..')) {
+        throw new Error('Invalid path: directory traversal (..) is not allowed');
+    }
+
+    // Ensure path starts with a valid root
+    // We check case-insensitive for the root prefix to be user-friendly, 
+    // but Unreal paths are typically case-insensitive anyway.
+    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(', ')}]`);
+    }
+
+    // Basic character validation (Unreal strictness)
+    // Blocks: < > : " | ? * (Windows reserved) and control characters
+    // allowing spaces, dots, underscores, dashes, slashes
+    // Note: Unreal allows spaces in some contexts but it's often safer to restrict them if strict mode is desired.
+    // For now, we block the definitely invalid ones.
+    // eslint-disable-next-line no-control-regex
+    const invalidChars = /[<>:"|?*\x00-\x1f]/;
+    if (invalidChars.test(normalized)) {
+        throw new Error('Invalid path: contains illegal characters');
+    }
+
+    return normalized;
+}