unreal-engine-mcp-server 0.3.1 → 0.4.3

package/dist/utils/python-output.js

@@ -0,0 +1,290 @@
+import JSON5 from 'json5';
+function escapeRegExp(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+function stringifyAny(value) {
+    if (typeof value === 'string') {
+        return value;
+    }
+    try {
+        return JSON.stringify(value ?? '');
+    }
+    catch {
+        return String(value);
+    }
+}
+function isTaggedResultLine(line, tag = 'RESULT:') {
+    if (typeof line !== 'string') {
+        return false;
+    }
+    return line.includes(tag);
+}
+function collectLogOutput(logs) {
+    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.Output ?? entry.output ?? entry.Message;
+        if (typeof output === 'string') {
+            buffer += output.endsWith('\n') ? output : `${output}\n`;
+        }
+    }
+    return buffer || undefined;
+}
+export function toPythonOutput(response) {
+    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;
+        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(candidate) {
+    try {
+        return JSON.parse(candidate);
+    }
+    catch {
+        try {
+            return JSON5.parse(candidate);
+        }
+        catch {
+            try {
+                const normalized = normalizeLegacyJson(candidate);
+                return JSON5.parse(normalized);
+            }
+            catch {
+                return null;
+            }
+        }
+    }
+}
+function normalizeLegacyJson(candidate) {
+    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, startIndex) {
+    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 = null;
+    if (opening === '{') {
+        closing = '}';
+    }
+    else if (opening === '[') {
+        closing = ']';
+    }
+    if (!closing) {
+        return null;
+    }
+    let depth = 0;
+    let inString = false;
+    let stringQuote = 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(response, tag = 'RESULT:') {
+    const output = toPythonOutput(response);
+    const pattern = escapeRegExp(tag);
+    let data = null;
+    const directMatch = output.text.match(new RegExp(`${pattern}\\s*(.+)$`, 'm'));
+    if (directMatch) {
+        const parsed = tryParseJson(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(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, tag = 'RESULT:') {
+    return extractTaggedJson(response, tag);
+}
+export function stripTaggedResultLines(text, tag = 'RESULT:') {
+    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, prefix) {
+    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, tag = 'RESULT:') {
+    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;
+        let mutated = false;
+        const clone = { ...obj };
+        const sanitizeLogArray = (value) => {
+            const filtered = value.filter(entry => {
+                if (entry == null) {
+                    return false;
+                }
+                if (typeof entry === 'string') {
+                    return !isTaggedResultLine(entry, tag);
+                }
+                const output = entry.Output ?? entry.output ?? entry.Message;
+                if (typeof output === 'string' && isTaggedResultLine(output, tag)) {
+                    return false;
+                }
+                return true;
+            });
+            return filtered;
+        };
+        if (Array.isArray(obj.LogOutput)) {
+            const originalArray = obj.LogOutput;
+            const sanitizedLog = sanitizeLogArray(originalArray);
+            if (sanitizedLog.length !== originalArray.length ||
+                sanitizedLog.some((entry, idx) => entry !== originalArray[idx])) {
+                clone.LogOutput = sanitizedLog;
+                mutated = true;
+            }
+        }
+        if (Array.isArray(obj.logs)) {
+            const originalLogs = obj.logs;
+            const sanitizedLogs = sanitizeLogArray(originalLogs);
+            if (sanitizedLogs.length !== originalLogs.length ||
+                sanitizedLogs.some((entry, idx) => 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;
+}
+//# sourceMappingURL=python-output.js.map

package/dist/utils/python.d.ts

@@ -0,0 +1,2 @@
+export declare function escapePythonString(value: string): string;
+//# sourceMappingURL=python.d.ts.map

package/dist/utils/python.js

@@ -0,0 +1,4 @@
+export function escapePythonString(value) {
+    return value.replace(/\\/g, '\\\\').replace(/"/g, '\\"');
+}
+//# sourceMappingURL=python.js.map

package/dist/utils/response-validator.d.ts

@@ -19,7 +19,12 @@ export declare class ResponseValidator {
         structuredContent?: any;
     };
     /**
-     * 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;
     /**

package/dist/utils/response-validator.js

@@ -76,14 +76,17 @@ 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, response) {
         // 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);
             }
         }
@@ -91,21 +94,71 @@ export class ResponseValidator {
             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.structuredContent = structuredPayload && typeof structuredPayload === 'object'
+                        ? cleanObject(structuredPayload)
+                        : structuredPayload;
+                }
+                catch { }
+            }
+            if (!validation.valid) {
+                try {
+                    response._validation = { valid: false, errors: validation.errors };
+                }
+                catch { }
             }
+            return response;
+        }
+        // Otherwise, wrap structured result into MCP content
+        let text;
+        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 }
+            ]
+        };
+        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 };
         }
-        // Don't add structuredContent to the response - it's for internal validation only
-        // Adding it can cause circular references
-        return response;
+        return wrapped;
     }
     /**
      * Get validation statistics

package/dist/utils/result-helpers.d.ts

@@ -0,0 +1,27 @@
+import { StandardResultPayload } 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 declare function interpretStandardResult(response: unknown, defaults: {
+    successMessage: string;
+    failureMessage: string;
+}): InterpretedStandardResult;
+export declare function cleanResultText(text: string | undefined, options?: {
+    tag?: string;
+    fallback?: string;
+}): string | undefined;
+export declare function bestEffortInterpretedText(interpreted: Pick<InterpretedStandardResult, 'cleanText' | 'rawText'>, fallback?: string): string | undefined;
+export declare function coerceString(value: unknown): string | undefined;
+export declare function coerceStringArray(value: unknown): string[] | undefined;
+export declare function coerceBoolean(value: unknown, fallback?: boolean): boolean | undefined;
+export declare function coerceNumber(value: unknown): number | undefined;
+export declare function coerceVector3(value: unknown): [number, number, number] | undefined;
+//# sourceMappingURL=result-helpers.d.ts.map

package/dist/utils/result-helpers.js

@@ -0,0 +1,147 @@
+import { parseStandardResult, stripTaggedResultLines } from './python-output.js';
+export function interpretStandardResult(response, defaults) {
+    const parsed = parseStandardResult(response);
+    const payload = (parsed.data ?? {});
+    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, options = {}) {
+    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, fallback) {
+    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) {
+    if (typeof value === 'string') {
+        const trimmed = value.trim();
+        return trimmed.length > 0 ? trimmed : undefined;
+    }
+    return undefined;
+}
+export function coerceStringArray(value) {
+    if (!Array.isArray(value)) {
+        return undefined;
+    }
+    const items = [];
+    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, fallback) {
+    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) {
+    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) {
+    const toNumber = (entry) => {
+        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) => {
+        if (arr.length !== 3) {
+            return undefined;
+        }
+        const mapped = arr.map(toNumber);
+        if (mapped.every((entry) => typeof entry === 'number')) {
+            return mapped;
+        }
+        return undefined;
+    };
+    if (Array.isArray(value)) {
+        const parsed = fromArray(value);
+        if (parsed) {
+            return parsed;
+        }
+    }
+    if (value && typeof value === 'object') {
+        const obj = value;
+        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;
+}
+//# sourceMappingURL=result-helpers.js.map

package/dist/utils/safe-json.d.ts

@@ -1,4 +1,2 @@
-export declare function safeStringify(obj: any, space?: number): string;
-export declare function sanitizeResponse(response: any): any;
 export declare function cleanObject(obj: any, maxDepth?: number): any;
 //# sourceMappingURL=safe-json.d.ts.map

package/dist/utils/safe-json.js

@@ -1,46 +1,3 @@
-// Utility to safely serialize objects with circular references
-export function safeStringify(obj, space) {
-    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) {
-    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, maxDepth = 10) {
     const seen = new WeakSet();

package/dist/utils/validation.d.ts

@@ -47,4 +47,20 @@ export declare function resolveSkeletalMeshPath(input: string): string | null;
  * @param ms Milliseconds to delay
  */
 export declare function concurrencyDelay(ms?: number): Promise<void>;
+/**
+ * Ensure the provided value is a finite number within optional bounds.
+ * @throws if the value is not a finite number or violates bounds
+ */
+export declare function validateNumber(value: unknown, label: string, { min, max, allowZero }?: {
+    min?: number;
+    max?: number;
+    allowZero?: boolean;
+}): number;
+/**
+ * Validate an array (tuple) of finite numbers, preserving the original shape.
+ * @throws if the tuple has the wrong length or contains invalid values
+ */
+export declare function ensureVector3(value: unknown, label: string): [number, number, number];
+export declare function ensureColorRGB(value: unknown, label: string): [number, number, number];
+export declare function ensureRotation(value: unknown, label: string): [number, number, number];
 //# sourceMappingURL=validation.d.ts.map