unreal-engine-mcp-server 0.2.1

package/src/utils/response-validator.ts

@@ -0,0 +1,145 @@
+import Ajv from 'ajv';
+import { Logger } from './logger.js';
+import { cleanObject } from './safe-json.js';
+
+const log = new Logger('ResponseValidator');
+
+/**
+ * Response Validator for MCP Tool Outputs
+ * Validates tool responses against their defined output schemas
+ */
+export class ResponseValidator {
+  private ajv: Ajv;
+  private validators: Map<string, any> = new Map();
+
+  constructor() {
+    this.ajv = new Ajv({
+      allErrors: true,
+      verbose: true,
+      strict: false // Allow additional properties for flexibility
+    });
+  }
+
+  /**
+   * Register a tool's output schema for validation
+   */
+  registerSchema(toolName: string, outputSchema: any) {
+    if (!outputSchema) {
+      log.warn(`No output schema defined for tool: ${toolName}`);
+      return;
+    }
+
+    try {
+      const validator = this.ajv.compile(outputSchema);
+      this.validators.set(toolName, validator);
+      log.info(`Registered output schema for tool: ${toolName}`);
+    } catch (error) {
+      log.error(`Failed to compile output schema for ${toolName}:`, error);
+    }
+  }
+
+  /**
+   * Validate a tool's response against its schema
+   */
+  validateResponse(toolName: string, response: any): { 
+    valid: boolean; 
+    errors?: string[];
+    structuredContent?: any;
+  } {
+    const validator = this.validators.get(toolName);
+    
+    if (!validator) {
+      log.debug(`No validator found for tool: ${toolName}`);
+      return { valid: true }; // Pass through if no schema defined
+    }
+
+    // Extract structured content from response
+    let structuredContent = response;
+    
+    // If response has MCP format with content array
+    if (response.content && Array.isArray(response.content)) {
+      // Try to extract structured data from text content
+      const textContent = response.content.find((c: any) => c.type === 'text');
+      if (textContent?.text) {
+        try {
+          // Check if text is JSON
+          structuredContent = JSON.parse(textContent.text);
+        } catch {
+          // Not JSON, use the full response
+          structuredContent = response;
+        }
+      }
+    }
+
+    const valid = validator(structuredContent);
+    
+    if (!valid) {
+      const errors = validator.errors?.map((err: any) => 
+        `${err.instancePath || 'root'}: ${err.message}`
+      );
+      
+      log.warn(`Response validation failed for ${toolName}:`, errors);
+      
+      return { 
+        valid: false, 
+        errors,
+        structuredContent 
+      };
+    }
+
+    return { 
+      valid: true,
+      structuredContent 
+    };
+  }
+
+  /**
+   * Wrap a tool response with validation
+   */
+  wrapResponse(toolName: string, response: any): any {
+    // Ensure response is safe to serialize first
+    try {
+      // The response should already be cleaned, but double-check
+      if (response && typeof response === 'object') {
+        // Make sure we can serialize it
+        JSON.stringify(response);
+      }
+    } catch (error) {
+      log.error(`Response for ${toolName} contains circular references, cleaning...`);
+      response = cleanObject(response);
+    }
+    
+    const validation = this.validateResponse(toolName, response);
+    
+    // Add validation metadata
+    if (!validation.valid) {
+      log.warn(`Tool ${toolName} response validation failed:`, validation.errors);
+      
+      // Add warning to response but don't fail
+      if (response && typeof response === 'object') {
+        response._validation = {
+          valid: false,
+          errors: validation.errors
+        };
+      }
+    }
+
+    // Don't add structuredContent to the response - it's for internal validation only
+    // Adding it can cause circular references
+    
+    return response;
+  }
+
+  /**
+   * Get validation statistics
+   */
+  getStats() {
+    return {
+      totalSchemas: this.validators.size,
+      tools: Array.from(this.validators.keys())
+    };
+  }
+}
+
+// Singleton instance
+export const responseValidator = new ResponseValidator();

package/src/utils/safe-json.ts

@@ -0,0 +1,112 @@
+// Utility to safely serialize objects with circular references
+export function safeStringify(obj: any, space?: number): string {
+  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: any): any {
+  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: any, maxDepth: number = 10): any {
+  const seen = new WeakSet();
+  
+  function clean(value: any, depth: number, path: string = 'root'): any {
+    // 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: any = {};
+    
+    // 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);
+}

package/src/utils/stdio-redirect.ts

@@ -0,0 +1,18 @@
+export function routeStdoutLogsToStderr(): void {
+  // 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) as (...args: any[]) => void;
+    // Route common stdout channels to stderr to keep stdout JSON-only for MCP
+    console.log = toErr as any;
+    console.info = toErr as any;
+    console.debug = toErr as any;
+    // Be explicit with trace as well
+    console.trace = toErr as any;
+  } catch {
+    // If overriding fails for any reason, just continue silently.
+  }
+}

package/src/utils/validation.ts

@@ -0,0 +1,212 @@
+/**
+ * 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: string): string {
+  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: string): string {
+  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: string): { valid: boolean; error?: string } {
+  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: {
+  name: string;
+  savePath?: string;
+  [key: string]: any;
+}): {
+  valid: boolean;
+  sanitized: typeof params;
+  error?: string;
+} {
+  // 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: string): string | null {
+  if (!input || typeof input !== 'string') {
+    return null;
+  }
+  
+  // Common skeleton to mesh mappings
+  const skeletonToMeshMap: { [key: string]: string } = {
+    '/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: number = 100): Promise<void> {
+  return new Promise(resolve => setTimeout(resolve, ms));
+}

package/tsconfig.json

@@ -0,0 +1,33 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ES2022",
+    "moduleResolution": "Bundler",
+    "outDir": "dist",
+    "rootDir": "src",
+    "strict": true,
+    "esModuleInterop": true,
+    "forceConsistentCasingInFileNames": true,
+    "skipLibCheck": true,
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "resolveJsonModule": true,
+    "incremental": true,
+    "tsBuildInfoFile": ".tsbuildinfo",
+    "noUnusedLocals": false,
+    "noUnusedParameters": false,
+    "noImplicitReturns": true,
+    "noFallthroughCasesInSwitch": true,
+    "allowUnreachableCode": false,
+    "types": ["node"]
+  },
+  "include": ["src/**/*"],
+  "exclude": [
+    "node_modules",
+    "dist",
+    "**/*.test.ts",
+    "**/*.spec.ts",
+    "src/tests/**/*"
+  ]
+}