unreal-engine-mcp-server 0.5.4 → 0.5.5

package/src/utils/response-validator.ts

@@ -1,395 +0,0 @@
-import Ajv, { ValidateFunction } from 'ajv';
-import { Logger } from './logger.js';
-import { cleanObject } from './safe-json.js';
-import { wasmIntegration } from '../wasm/index.js';
-
-const log = new Logger('ResponseValidator');
-
-function isRecord(value: unknown): value is Record<string, unknown> {
-  return !!value && typeof value === 'object' && !Array.isArray(value);
-}
-
-function normalizeText(text: string): string {
-  return text.replace(/\s+/g, ' ').trim();
-}
-
-function buildSummaryText(toolName: string, payload: unknown): string {
-  if (typeof payload === 'string') {
-    const normalized = payload.trim();
-    return normalized || `${toolName} responded`;
-  }
-
-  if (typeof payload === 'number' || typeof payload === 'bigint' || typeof payload === 'boolean') {
-    return `${toolName} responded: ${payload}`;
-  }
-
-  if (!isRecord(payload)) {
-    return `${toolName} responded`;
-  }
-
-  // Recursively flatten data/result wrappers into effective payload
-  const effectivePayload: Record<string, any> = { ...(payload as object) };
-
-  const flattenWrappers = (obj: Record<string, any>, depth = 0): void => {
-    if (depth > 5) return; // Prevent infinite loops
-    if (isRecord(obj.data)) {
-      Object.assign(obj, obj.data);
-      delete obj.data;
-      flattenWrappers(obj, depth + 1);
-    }
-    if (isRecord(obj.result)) {
-      Object.assign(obj, obj.result);
-      delete obj.result;
-      flattenWrappers(obj, depth + 1);
-    }
-  };
-  flattenWrappers(effectivePayload);
-
-  const parts: string[] = [];
-  const addedKeys = new Set<string>();
-
-  // Keys to skip (internal/redundant)
-  const skipKeys = new Set(['requestId', 'type', 'data', 'result', 'warnings']);
-
-  // Helper to format a value for display
-  const formatValue = (val: unknown): string => {
-    if (val === null || val === undefined) return '';
-    if (typeof val === 'string') return val.length > 150 ? val.slice(0, 150) + '...' : val;
-    if (typeof val === 'number' || typeof val === 'boolean') return String(val);
-
-    // Handle arrays - show items with names/paths
-    if (Array.isArray(val)) {
-      if (val.length === 0) return '[] (0)';
-      const items = val.slice(0, 30).map(v => {
-        if (isRecord(v)) {
-          // Try common identifier fields
-          return v.name || v.path || v.id || v.nodeId || v.nodeName || v.className ||
-            v.displayName || v.type || v.assetPath || v.objectPath ||
-            JSON.stringify(v).slice(0, 50);
-        }
-        return String(v);
-      });
-      const suffix = val.length > 30 ? `, ... (+${val.length - 30} more)` : '';
-      return `[${items.join(', ')}${suffix}] (${val.length})`;
-    }
-
-    // Handle transform-like objects (location/rotation/scale)
-    if (isRecord(val)) {
-      const keys = Object.keys(val);
-      // Check if it looks like a 3D vector/transform
-      if (keys.some(k => ['x', 'y', 'z', 'pitch', 'yaw', 'roll'].includes(k))) {
-        const x = val.x ?? val.pitch ?? 0;
-        const y = val.y ?? val.yaw ?? 0;
-        const z = val.z ?? val.roll ?? 0;
-        return `[${x}, ${y}, ${z}]`;
-      }
-      // Generic object - show key=value pairs
-      const entries = Object.entries(val).slice(0, 8);
-      const formatted = entries.map(([k, v]) => {
-        const vStr = typeof v === 'object' ? JSON.stringify(v).slice(0, 40) : String(v);
-        return `${k}=${vStr}`;
-      });
-      return `{ ${formatted.join(', ')}${keys.length > 8 ? ' ...' : ''} }`;
-    }
-
-    return String(val);
-  };
-
-  // Process all keys in priority order
-  // 1. First add 'success' and 'error' at the start
-  for (const key of ['success', 'error']) {
-    if (effectivePayload[key] !== undefined && !addedKeys.has(key)) {
-      const formatted = formatValue(effectivePayload[key]);
-      if (formatted) {
-        parts.push(`${key}: ${formatted}`);
-        addedKeys.add(key);
-      }
-    }
-  }
-
-  // 2. Then add ALL other keys dynamically
-  let hasArrays = false;
-  for (const [key, val] of Object.entries(effectivePayload)) {
-    if (addedKeys.has(key)) continue;
-    if (skipKeys.has(key)) continue;
-    if (val === undefined || val === null) continue;
-    if (typeof val === 'string' && val.trim() === '') continue;
-
-    // Skip 'message' for now - handle later to avoid duplication
-    if (key === 'message') continue;
-
-    // Track if we have arrays (to skip duplicate count/totalCount later)
-    if (Array.isArray(val) && val.length > 0) hasArrays = true;
-
-    // Skip count/totalCount if we already have arrays showing counts
-    if ((key === 'count' || key === 'totalCount') && hasArrays) continue;
-
-    const formatted = formatValue(val);
-    if (formatted) {
-      parts.push(`${key}: ${formatted}`);
-      addedKeys.add(key);
-    }
-  }
-
-  // 3. Handle message last - but skip if it duplicates existing info
-  const message = typeof effectivePayload.message === 'string' ? normalizeText(effectivePayload.message) : '';
-  if (message && message.toLowerCase() !== 'success') {
-    // Skip if message duplicates count info
-    const isDuplicateInfo = /^(found|listed|retrieved|got|loaded|created|deleted|saved|spawned)\s+\d+/i.test(message) ||
-      /Folders:\s*\[/.test(message) ||
-      /\d+\s+(assets?|folders?|items?|actors?|components?)\s+(and|in|at)/i.test(message);
-
-    // Also skip if message content is already represented in parts
-    const messageInParts = parts.some(p => p.toLowerCase().includes(message.toLowerCase().slice(0, 30)));
-
-    if (!isDuplicateInfo && !messageInParts) {
-      parts.push(message);
-    }
-  }
-
-  // 4. Warnings at end
-  const warnings = Array.isArray(effectivePayload.warnings) ? effectivePayload.warnings : [];
-  if (warnings.length > 0) {
-    parts.push(`Warnings: ${warnings.map((w: any) => typeof w === 'string' ? w : JSON.stringify(w)).join('; ')}`);
-  }
-
-  return parts.length > 0 ? parts.join(' | ') : `${toolName} responded`;
-}
-
-/**
- * Response Validator for MCP Tool Outputs
- * Validates tool responses against their defined output schemas
- */
-export class ResponseValidator {
-  // Ajv instance - using Ajv.default for ESM/CJS interop
-  private ajv: Ajv.default;
-  private validators: Map<string, ValidateFunction> = new Map();
-
-  constructor() {
-    // Ajv exports differ between ESM and CJS - handle both patterns
-    const AjvClass = (Ajv as unknown as { default: typeof Ajv.default }).default ?? Ajv.default;
-    this.ajv = new AjvClass({
-      allErrors: true,
-      verbose: true,
-      strict: true // Enforce strict schema validation
-    });
-  }
-
-  /**
-   * 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);
-      // Demote per-tool schema registration to debug to reduce log noise
-      log.debug(`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
-   */
-  async validateResponse(toolName: string, response: any): Promise<{
-    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) {
-        const rawText = String(textContent.text);
-        const trimmed = rawText.trim();
-        const looksLikeJson = trimmed.startsWith('{') || trimmed.startsWith('[');
-
-        if (looksLikeJson) {
-          try {
-            // Check if text is JSON - use WASM for high-performance parsing (5-8x faster)
-            structuredContent = await wasmIntegration.parseProperties(rawText);
-          } catch {
-            // If JSON parsing fails, fall back to using the full response without
-            // emitting noisy parse errors for plain-text messages.
-            structuredContent = response;
-          }
-        } else {
-          // Plain-text summary or error message; keep the original structured
-          // response object instead of attempting JSON parsing.
-          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 and MCP-compliant content shape.
-   *
-   * MCP tools/call responses must contain a `content` array. Many internal
-   * handlers return structured JSON objects (e.g., { success, message, ... }).
-   * This wrapper serializes such objects into a single text block while keeping
-   * existing `content` responses intact.
-   */
-  async wrapResponse(toolName: string, response: any): Promise<any> {
-    // Ensure response is safe to serialize first
-    try {
-      if (response && typeof response === 'object') {
-        JSON.stringify(response);
-      }
-    } catch (_error) {
-      log.error(`Response for ${toolName} contains circular references, cleaning...`);
-      response = cleanObject(response);
-    }
-
-    // If handler already returned MCP content, keep it as-is (still validate)
-    const alreadyMcpShaped = response && typeof response === 'object' && Array.isArray(response.content);
-
-    // Choose the payload to validate: if already MCP-shaped, validate the
-    // structured content extracted from text; otherwise validate the object directly.
-    const validation = await this.validateResponse(toolName, response);
-    const structuredPayload = validation.structuredContent;
-
-    if (!validation.valid) {
-      log.warn(`Tool ${toolName} response validation failed:`, validation.errors);
-    }
-
-    // If it's already MCP-shaped, return as-is (optionally append validation meta)
-    if (alreadyMcpShaped) {
-      if (structuredPayload !== undefined && response && typeof response === 'object' && (response as any).structuredContent === undefined) {
-        try {
-          (response as any).structuredContent = structuredPayload && typeof structuredPayload === 'object'
-            ? cleanObject(structuredPayload)
-            : structuredPayload;
-        } catch { }
-      }
-      // Promote failure semantics to top-level isError when obvious
-      try {
-        const sc: any = (response as any).structuredContent || structuredPayload || {};
-        const hasExplicitFailure = (typeof sc.success === 'boolean' && sc.success === false) || (typeof sc.error === 'string' && sc.error.length > 0);
-        if (hasExplicitFailure && (response as any).isError !== true) {
-          (response as any).isError = true;
-        }
-      } catch { }
-      if (!validation.valid) {
-        try {
-          (response as any)._validation = { valid: false, errors: validation.errors };
-        } catch { }
-      }
-      return response;
-    }
-
-    // Otherwise, wrap structured result into MCP content
-    const summarySource = structuredPayload !== undefined ? structuredPayload : response;
-    let text = buildSummaryText(toolName, summarySource);
-    if (!text || !text.trim()) {
-      text = buildSummaryText(toolName, response);
-    }
-
-    const wrapped = {
-      content: [
-        { type: 'text', text }
-      ]
-    } as any;
-
-    // Surface a top-level success flag when available so clients and test
-    // harnesses do not have to infer success from the absence of isError.
-    try {
-      if (structuredPayload && typeof (structuredPayload as any).success === 'boolean') {
-        (wrapped as any).success = Boolean((structuredPayload as any).success);
-      } else if (response && typeof (response as any).success === 'boolean') {
-        (wrapped as any).success = Boolean((response as any).success);
-      }
-    } catch { }
-
-    if (structuredPayload !== undefined) {
-      try {
-        wrapped.structuredContent = structuredPayload && typeof structuredPayload === 'object'
-          ? cleanObject(structuredPayload)
-          : structuredPayload;
-      } catch {
-        wrapped.structuredContent = structuredPayload;
-      }
-    } else if (response && typeof response === 'object') {
-      try {
-        wrapped.structuredContent = cleanObject(response);
-      } catch {
-        wrapped.structuredContent = response;
-      }
-    }
-
-    // Promote failure semantics to top-level isError when obvious
-    try {
-      const sc: any = wrapped.structuredContent || {};
-      const hasExplicitFailure = (typeof sc.success === 'boolean' && sc.success === false) || (typeof sc.error === 'string' && sc.error.length > 0);
-      if (hasExplicitFailure) {
-        wrapped.isError = true;
-      }
-    } catch { }
-
-    if (!validation.valid) {
-      wrapped._validation = { valid: false, errors: validation.errors };
-    }
-
-    // Mark explicit error when success is false to avoid false positives in
-    // clients that check only for the absence of isError.
-    try {
-      const s = (wrapped as any).success;
-      if (typeof s === 'boolean' && s === false) {
-        (wrapped as any).isError = true;
-      }
-    } catch { }
-
-    return wrapped;
-  }
-
-  /**
-   * 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/result-helpers.ts

@@ -1,195 +0,0 @@
-// Generic result interpretation for automation bridge responses
-export interface InterpretedStandardResult {
-  success: boolean;
-  message: string;
-  error?: string;
-  warnings?: string[];
-  details?: string[];
-  payload: Record<string, unknown>;
-  cleanText?: string;
-  rawText: string;
-  raw: unknown;
-}
-
-/** Interprets automation bridge responses into a standard format */
-export function interpretStandardResult(
-  response: unknown,
-  defaults: { successMessage: string; failureMessage: string }
-): InterpretedStandardResult {
-  // Handle automation bridge response format
-  const payload = (response && typeof response === 'object' ? response : {}) as Record<string, unknown>;
-  const success = payload.success === true;
-  const rawText = typeof payload.message === 'string' ? payload.message : 
-                  typeof payload.output === 'string' ? payload.output :
-                  String(payload.result ?? '');
-
-  const messageFromPayload = typeof payload.message === 'string' ? payload.message.trim() : '';
-  const errorFromPayload = typeof payload.error === 'string' ? payload.error.trim() : '';
-
-  const message = messageFromPayload || (success ? defaults.successMessage : defaults.failureMessage);
-  const error = success ? undefined : errorFromPayload || messageFromPayload || defaults.failureMessage;
-
-  return {
-    success,
-    message,
-    error,
-    warnings: coerceStringArray(payload.warnings),
-    details: coerceStringArray(payload.details),
-    payload,
-    cleanText: rawText || undefined,
-    rawText,
-    raw: response
-  };
-}
-
-/** Cleans result text by removing tags */
-export function cleanResultText(
-  text: string | undefined,
-  options: { tag?: string; defaultValue?: string } = {}
-): string | undefined {
-  const { defaultValue } = options;
-  if (!text) {
-    return defaultValue;
-  }
-
-  const cleaned = text.trim();
-  if (cleaned.length > 0) {
-    return cleaned;
-  }
-
-  return defaultValue;
-}
-
-export function bestEffortInterpretedText(
-  interpreted: Pick<InterpretedStandardResult, 'cleanText' | 'rawText'>,
-  defaultValue?: string
-): string | undefined {
-  const cleaned = interpreted.cleanText?.trim();
-  if (cleaned) {
-    return cleaned;
-  }
-
-  const raw = interpreted.rawText?.trim?.();
-  if (raw) {
-    return raw;
-  }
-
-  return defaultValue;
-}
-
-export function coerceString(value: unknown): string | undefined {
-  if (typeof value === 'string') {
-    const trimmed = value.trim();
-    return trimmed.length > 0 ? trimmed : undefined;
-  }
-  return undefined;
-}
-
-export function coerceStringArray(value: unknown): string[] | undefined {
-  if (!Array.isArray(value)) {
-    return undefined;
-  }
-
-  const items: string[] = [];
-  for (const entry of value) {
-    if (typeof entry !== 'string') {
-      continue;
-    }
-    const trimmed = entry.trim();
-    if (!trimmed) {
-      continue;
-    }
-    items.push(trimmed);
-  }
-
-  return items.length > 0 ? items : undefined;
-}
-
-export function coerceBoolean(value: unknown, defaultValue?: boolean): boolean | undefined {
-  if (typeof value === 'boolean') {
-    return value;
-  }
-
-  if (typeof value === 'string') {
-    const normalized = value.trim().toLowerCase();
-    if (['true', '1', 'yes', 'on'].includes(normalized)) {
-      return true;
-    }
-    if (['false', '0', 'no', 'off'].includes(normalized)) {
-      return false;
-    }
-  }
-
-  if (typeof value === 'number') {
-    if (value === 1) {
-      return true;
-    }
-    if (value === 0) {
-      return false;
-    }
-  }
-
-  return defaultValue;
-}
-
-export function coerceNumber(value: unknown): number | undefined {
-  if (typeof value === 'number' && Number.isFinite(value)) {
-    return value;
-  }
-
-  if (typeof value === 'string') {
-    const parsed = Number(value);
-    if (Number.isFinite(parsed)) {
-      return parsed;
-    }
-  }
-
-  return undefined;
-}
-
-export function coerceVector3(value: unknown): [number, number, number] | undefined {
-  const toNumber = (entry: unknown): number | undefined => {
-    if (typeof entry === 'number' && Number.isFinite(entry)) {
-      return entry;
-    }
-    if (typeof entry === 'string') {
-      const parsed = Number(entry.trim());
-      if (Number.isFinite(parsed)) {
-        return parsed;
-      }
-    }
-    return undefined;
-  };
-
-  const fromArray = (arr: unknown[]): [number, number, number] | undefined => {
-    if (arr.length !== 3) {
-      return undefined;
-    }
-    const mapped = arr.map(toNumber);
-    if (mapped.every((entry): entry is number => typeof entry === 'number')) {
-      return mapped as [number, number, number];
-    }
-    return undefined;
-  };
-
-  if (Array.isArray(value)) {
-    const parsed = fromArray(value);
-    if (parsed) {
-      return parsed;
-    }
-  }
-
-  if (value && typeof value === 'object') {
-    const obj = value as Record<string, unknown>;
-    const candidate = fromArray([obj.x, obj.y, obj.z]);
-    if (candidate) {
-      return candidate;
-    }
-    const alternate = fromArray([obj.pitch, obj.yaw, obj.roll]);
-    if (alternate) {
-      return alternate;
-    }
-  }
-
-  return undefined;
-}

package/src/utils/safe-json.test.ts

@@ -1,90 +0,0 @@
-/**
- * Unit tests for safe-json utility
- */
-import { describe, it, expect } from 'vitest';
-import { cleanObject } from './safe-json.js';
-
-describe('cleanObject', () => {
-    it('removes undefined values', () => {
-        const input = { a: 1, b: undefined, c: 3 };
-        const result = cleanObject(input);
-        expect(result).toEqual({ a: 1, c: 3 });
-        expect('b' in result).toBe(false);
-    });
-
-    it('preserves null values (only removes undefined)', () => {
-        const input = { a: 1, b: null, c: 3 };
-        const result = cleanObject(input);
-        // cleanObject preserves null, only removes undefined
-        expect(result).toEqual({ a: 1, b: null, c: 3 });
-    });
-
-    it('handles nested objects', () => {
-        const input = { a: 1, nested: { b: 2, c: undefined } };
-        const result = cleanObject(input);
-        expect(result.nested).toEqual({ b: 2 });
-    });
-
-    it('handles arrays with undefined (preserves null)', () => {
-        const input = { arr: [1, undefined, 3, null] };
-        const result = cleanObject(input);
-        // Arrays preserve their structure, undefined becomes undefined in array
-        expect(result.arr).toEqual([1, undefined, 3, null]);
-    });
-
-    it('preserves falsy values that are not null/undefined', () => {
-        const input = { a: 0, b: '', c: false };
-        const result = cleanObject(input);
-        expect(result).toEqual({ a: 0, b: '', c: false });
-    });
-
-    it('handles empty objects', () => {
-        expect(cleanObject({})).toEqual({});
-    });
-
-    it('handles primitive inputs', () => {
-        expect(cleanObject('string')).toBe('string');
-        expect(cleanObject(42)).toBe(42);
-        expect(cleanObject(true)).toBe(true);
-    });
-
-    it('respects max depth limit', () => {
-        // Create deeply nested object
-        let deep: any = { value: 'deep' };
-        for (let i = 0; i < 15; i++) {
-            deep = { nested: deep };
-        }
-
-        // Should not throw when hitting depth limit
-        expect(() => cleanObject(deep, 10)).not.toThrow();
-    });
-
-    it('handles circular reference prevention at max depth', () => {
-        const obj: any = { a: 1 };
-        obj.self = obj; // circular reference
-
-        // Should not throw - depth limiting should prevent infinite recursion
-        expect(() => cleanObject(obj, 5)).not.toThrow();
-    });
-
-    it('handles Date objects (converts to empty object)', () => {
-        const date = new Date('2024-01-01');
-        const input = { created: date };
-        const result = cleanObject(input);
-        // Date objects are processed as objects using Object.keys, which returns []
-        expect(result.created).toEqual({});
-    });
-
-    it('handles empty arrays', () => {
-        const input = { arr: [] };
-        const result = cleanObject(input);
-        expect(result.arr).toEqual([]);
-    });
-
-    it('handles NaN values', () => {
-        const input = { a: 1, b: NaN };
-        const result = cleanObject(input);
-        // NaN handling depends on implementation
-        expect(result.a).toBe(1);
-    });
-});