unreal-engine-mcp-server 0.3.1 → 0.4.3

package/src/utils/python-output.ts

@@ -0,0 +1,351 @@
+import JSON5 from 'json5';
+
+export interface PythonOutput {
+  raw: unknown;
+  text: string;
+}
+
+export interface TaggedJsonResult<T> extends PythonOutput {
+  data: T | null;
+}
+
+export interface StandardResultPayload {
+  success?: boolean;
+  message?: string;
+  error?: string;
+  [key: string]: unknown;
+}
+
+function escapeRegExp(value: string): string {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+function stringifyAny(value: unknown): string {
+  if (typeof value === 'string') {
+    return value;
+  }
+  try {
+    return JSON.stringify(value ?? '');
+  } catch {
+    return String(value);
+  }
+}
+
+function isTaggedResultLine(line: unknown, tag = 'RESULT:'): boolean {
+  if (typeof line !== 'string') {
+    return false;
+  }
+  return line.includes(tag);
+}
+
+function collectLogOutput(logs: unknown): string | undefined {
+  if (!Array.isArray(logs)) return undefined;
+  let buffer = '';
+  for (const entry of logs) {
+    if (!entry) continue;
+    if (typeof entry === 'string') {
+      buffer += entry.endsWith('\n') ? entry : `${entry}\n`;
+      continue;
+    }
+    const output = (entry as any).Output ?? (entry as any).output ?? (entry as any).Message;
+    if (typeof output === 'string') {
+      buffer += output.endsWith('\n') ? output : `${output}\n`;
+    }
+  }
+  return buffer || undefined;
+}
+
+export function toPythonOutput(response: unknown): PythonOutput {
+  if (typeof response === 'string') {
+    return { raw: response, text: response };
+  }
+
+  if (response == null) {
+    return { raw: response, text: '' };
+  }
+
+  if (Array.isArray(response)) {
+    const lines = response.map(item => stringifyAny(item));
+    return { raw: response, text: lines.join('\n') };
+  }
+
+  if (typeof response === 'object') {
+    const obj = response as Record<string, unknown>;
+
+    const logOutput = collectLogOutput(obj.LogOutput ?? obj.logOutput ?? obj.logs);
+    if (logOutput) {
+      return { raw: response, text: logOutput };
+    }
+
+    if (typeof obj.result === 'string') {
+      return { raw: response, text: obj.result };
+    }
+
+    if (typeof obj.ReturnValue === 'string') {
+      return { raw: response, text: obj.ReturnValue };
+    }
+
+    if (obj.result !== undefined) {
+      return { raw: response, text: stringifyAny(obj.result) };
+    }
+
+    if (obj.ReturnValue !== undefined) {
+      return { raw: response, text: stringifyAny(obj.ReturnValue) };
+    }
+
+    return { raw: response, text: stringifyAny(obj) };
+  }
+
+  return { raw: response, text: String(response) };
+}
+
+function tryParseJson<T>(candidate: string): T | null {
+  try {
+    return JSON.parse(candidate) as T;
+  } catch {
+    try {
+      return JSON5.parse(candidate) as T;
+    } catch {
+      try {
+        const normalized = normalizeLegacyJson(candidate);
+        return JSON5.parse(normalized) as T;
+      } catch {
+        return null;
+      }
+    }
+  }
+}
+
+function normalizeLegacyJson(candidate: string): string {
+  return candidate.replace(/\b(True|False|None)\b/g, (match) => {
+    switch (match) {
+      case 'True': return 'true';
+      case 'False': return 'false';
+      case 'None': return 'null';
+      default: return match;
+    }
+  });
+}
+
+function findJsonBlock(text: string, startIndex: number): string | null {
+  const length = text.length;
+  let index = startIndex;
+
+  while (index < length) {
+    const currentChar = text[index];
+    if (!currentChar || !/\s/.test(currentChar)) {
+      break;
+    }
+    index += 1;
+  }
+
+  if (index >= length) {
+    return null;
+  }
+
+  const opening = text[index];
+  if (!opening) {
+    return null;
+  }
+  let closing: string | null = null;
+  if (opening === '{') {
+    closing = '}';
+  } else if (opening === '[') {
+    closing = ']';
+  }
+
+  if (!closing) {
+    return null;
+  }
+
+  let depth = 0;
+  let inString = false;
+  let stringQuote: string | null = null;
+  let escaped = false;
+
+  for (let i = index; i < length; i++) {
+    const char = text[i];
+    if (!char) {
+      break;
+    }
+
+    if (inString) {
+      if (escaped) {
+        escaped = false;
+        continue;
+      }
+
+      if (char === '\\') {
+        escaped = true;
+        continue;
+      }
+
+      if (char === stringQuote) {
+        inString = false;
+        stringQuote = null;
+      }
+      continue;
+    }
+
+    if (char === '"' || char === '\'') {
+      inString = true;
+      stringQuote = char;
+      escaped = false;
+      continue;
+    }
+
+    if (char === opening) {
+      depth += 1;
+    } else if (char === closing) {
+      depth -= 1;
+      if (depth === 0) {
+        return text.slice(index, i + 1);
+      }
+    }
+  }
+
+  return null;
+}
+
+function extractTaggedJson<T = unknown>(response: unknown, tag = 'RESULT:'): TaggedJsonResult<T> {
+  const output = toPythonOutput(response);
+  const pattern = escapeRegExp(tag);
+
+  let data: T | null = null;
+
+  const directMatch = output.text.match(new RegExp(`${pattern}\\s*(.+)$`, 'm'));
+  if (directMatch) {
+    const parsed = tryParseJson<T>(directMatch[1]);
+    if (parsed !== null) {
+      data = parsed;
+    }
+  }
+
+  if (data === null) {
+    const tagIndex = output.text.indexOf(tag);
+    if (tagIndex >= 0) {
+      const jsonBlock = findJsonBlock(output.text, tagIndex + tag.length);
+      if (jsonBlock) {
+        const parsed = tryParseJson<T>(jsonBlock);
+        if (parsed !== null) {
+          data = parsed;
+        }
+      }
+    }
+  }
+
+  const sanitizedText = stripTaggedResultLines(output.text, tag);
+  const sanitizedRaw = sanitizePythonRaw(output.raw, tag);
+  return { raw: sanitizedRaw, text: sanitizedText, data };
+}
+
+export function parseStandardResult(response: unknown, tag = 'RESULT:'): TaggedJsonResult<StandardResultPayload> {
+  return extractTaggedJson<StandardResultPayload>(response, tag);
+}
+
+export function stripTaggedResultLines(text: string, tag = 'RESULT:'): string {
+  if (!text || !text.includes(tag)) {
+    return text;
+  }
+
+  const lines = text.split(/\r?\n/);
+  const cleaned = lines.filter(line => !isTaggedResultLine(line, tag));
+  const collapsed = cleaned.join('\n');
+  return collapsed.replace(/\n{3,}/g, '\n\n');
+}
+
+export function extractTaggedLine(output: string | PythonOutput, prefix: string): string | null {
+  const text = typeof output === 'string' ? output : output.text;
+  const pattern = new RegExp(`^${escapeRegExp(prefix)}\\s*(.+)$`, 'm');
+  const match = text.match(pattern);
+  return match ? match[1].trim() : null;
+}
+
+function sanitizePythonRaw(raw: unknown, tag = 'RESULT:'): unknown {
+  if (raw == null) {
+    return raw;
+  }
+
+  if (typeof raw === 'string') {
+    return stripTaggedResultLines(raw, tag);
+  }
+
+  if (Array.isArray(raw)) {
+    const sanitized = raw
+      .map(item => sanitizePythonRaw(item, tag))
+      .filter(item => {
+        if (typeof item === 'string') {
+          return item.length > 0 && !isTaggedResultLine(item, tag);
+        }
+        return item !== undefined;
+      });
+    return sanitized;
+  }
+
+  if (typeof raw === 'object') {
+    const obj = raw as Record<string, unknown>;
+    let mutated = false;
+    const clone: Record<string, unknown> = { ...obj };
+
+    const sanitizeLogArray = (value: unknown[]): unknown[] => {
+      const filtered = value.filter(entry => {
+        if (entry == null) {
+          return false;
+        }
+        if (typeof entry === 'string') {
+          return !isTaggedResultLine(entry, tag);
+        }
+        const output = (entry as any).Output ?? (entry as any).output ?? (entry as any).Message;
+        if (typeof output === 'string' && isTaggedResultLine(output, tag)) {
+          return false;
+        }
+        return true;
+      });
+      return filtered;
+    };
+
+    if (Array.isArray(obj.LogOutput)) {
+      const originalArray = obj.LogOutput as unknown[];
+      const sanitizedLog = sanitizeLogArray(originalArray);
+      if (
+        sanitizedLog.length !== originalArray.length ||
+        sanitizedLog.some((entry: unknown, idx: number) => entry !== originalArray[idx])
+      ) {
+        clone.LogOutput = sanitizedLog;
+        mutated = true;
+      }
+    }
+
+    if (Array.isArray(obj.logs)) {
+      const originalLogs = obj.logs as unknown[];
+      const sanitizedLogs = sanitizeLogArray(originalLogs);
+      if (
+        sanitizedLogs.length !== originalLogs.length ||
+        sanitizedLogs.some((entry: unknown, idx: number) => entry !== originalLogs[idx])
+      ) {
+        clone.logs = sanitizedLogs;
+        mutated = true;
+      }
+    }
+
+    if (typeof obj.Output === 'string') {
+      const stripped = stripTaggedResultLines(obj.Output, tag);
+      if (stripped !== obj.Output) {
+        clone.Output = stripped;
+        mutated = true;
+      }
+    }
+
+    if (typeof obj.result === 'string') {
+      const strippedResult = stripTaggedResultLines(obj.result, tag);
+      if (strippedResult !== obj.result) {
+        clone.result = strippedResult;
+        mutated = true;
+      }
+    }
+
+    return mutated ? clone : raw;
+  }
+
+  return raw;
+}

package/src/utils/python.ts

@@ -0,0 +1,3 @@
+export function escapePythonString(value: string): string {
+  return value.replace(/\\/g, '\\\\').replace(/"/g, '\\"');
+}

package/src/utils/response-validator.ts

@@ -95,40 +95,91 @@ export class ResponseValidator {
   }
 
   /**
-   * Wrap a tool response with validation
+   * 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.
    */
   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);
     }
-    
+
+    // 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 = this.validateResponse(toolName, response);
-    
-    // Add validation metadata
+    const structuredPayload = validation.structuredContent;
+
     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
-        };
+    }
+
+    // If it's already MCP-shaped, return as-is (optionally append validation meta)
+    if (alreadyMcpShaped) {
+      if (structuredPayload !== undefined && response && typeof response === 'object' && response.structuredContent === undefined) {
+        try {
+          (response as any).structuredContent = structuredPayload && typeof structuredPayload === 'object'
+            ? cleanObject(structuredPayload)
+            : structuredPayload;
+        } catch {}
+      }
+      if (!validation.valid) {
+        try {
+          (response as any)._validation = { valid: false, errors: validation.errors };
+        } catch {}
       }
+      return response;
     }
 
-    // Don't add structuredContent to the response - it's for internal validation only
-    // Adding it can cause circular references
-    
-    return response;
+    // Otherwise, wrap structured result into MCP content
+    let text: string;
+    try {
+      // Pretty-print small objects for readability
+      text = typeof response === 'string'
+        ? response
+        : JSON.stringify(response ?? { success: true }, null, 2);
+    } catch (_e) {
+      text = String(response);
+    }
+
+    const wrapped = {
+      content: [
+        { type: 'text', text }
+      ]
+    } as any;
+
+    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;
+      }
+    }
+
+    if (!validation.valid) {
+      wrapped._validation = { valid: false, errors: validation.errors };
+    }
+
+    return wrapped;
   }
 
   /**

package/src/utils/result-helpers.ts

@@ -0,0 +1,193 @@
+import { parseStandardResult, StandardResultPayload, stripTaggedResultLines } from './python-output.js';
+
+export interface InterpretedStandardResult {
+  success: boolean;
+  message: string;
+  error?: string;
+  warnings?: string[];
+  details?: string[];
+  payload: StandardResultPayload & Record<string, unknown>;
+  cleanText?: string;
+  rawText: string;
+  raw: unknown;
+}
+
+export function interpretStandardResult(
+  response: unknown,
+  defaults: { successMessage: string; failureMessage: string }
+): InterpretedStandardResult {
+  const parsed = parseStandardResult(response);
+  const payload = (parsed.data ?? {}) as StandardResultPayload & Record<string, unknown>;
+  const success = payload.success === true;
+  const rawText = typeof parsed.text === 'string' ? parsed.text : String(parsed.text ?? '');
+  const cleanedText = cleanResultText(rawText, { fallback: undefined });
+
+  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: cleanedText,
+    rawText,
+    raw: parsed.raw
+  };
+}
+
+export function cleanResultText(
+  text: string | undefined,
+  options: { tag?: string; fallback?: string } = {}
+): string | undefined {
+  const { tag = 'RESULT:', fallback } = options;
+  if (!text) {
+    return fallback;
+  }
+
+  const cleaned = stripTaggedResultLines(text, tag).trim();
+  if (cleaned.length > 0) {
+    return cleaned;
+  }
+
+  return fallback;
+}
+
+export function bestEffortInterpretedText(
+  interpreted: Pick<InterpretedStandardResult, 'cleanText' | 'rawText'>,
+  fallback?: string
+): string | undefined {
+  const cleaned = interpreted.cleanText?.trim();
+  if (cleaned) {
+    return cleaned;
+  }
+
+  const raw = interpreted.rawText?.trim?.();
+  if (raw && !raw.startsWith('RESULT:')) {
+    return raw;
+  }
+
+  return fallback;
+}
+
+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, fallback?: 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 fallback;
+}
+
+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.ts

@@ -1,53 +1,3 @@
-// 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();