ultimate-unreal-engine-mcp 0.1.0

package/dist/parsers/ini-parser.js

@@ -0,0 +1,216 @@
+// UE-aware INI parser — standalone pure string-processing module.
+// No fs imports — all I/O is the caller's responsibility.
+// No console.log — pure transform, no side effects.
+//
+// Handles all five UE INI operators:
+//   plain =   scalar assignment; last occurrence wins
+//   +         append if not already present (no duplicates)
+//   .         append always (duplicates allowed)
+//   -         remove exact match
+//   !         clear all values for key (value after = is ignored)
+//
+// Values are always stored as string[] (scalars as single-element arrays).
+// Section names and key names are case-sensitive per UE requirements.
+// Indexed-array syntax (MyArray[0]=val) is stored with the bracket index
+// as part of the literal key name — no special flattening.
+// Struct/compound values (parens) are treated as opaque strings.
+// Only lines where ; is the first non-whitespace char are treated as comments;
+// mid-line semicolons are preserved verbatim in the value.
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+const OPERATORS = new Set(['+', '-', '.', '!']);
+/**
+ * Strips the UE operator prefix (+ - . !) from a raw key token and
+ * returns { operator, key }.
+ * If the first character is not an operator, operator is '' (plain =).
+ */
+function splitOperator(rawKey) {
+    const first = rawKey[0] ?? '';
+    if (OPERATORS.has(first)) {
+        return { operator: first, key: rawKey.slice(1) };
+    }
+    return { operator: '', key: rawKey };
+}
+// ---------------------------------------------------------------------------
+// parseIni
+// ---------------------------------------------------------------------------
+/**
+ * Parse a full INI file content string into a structured map.
+ * Handles all five UE operators: plain =, +, -, ., !
+ * Section names are case-sensitive (UE requirement).
+ */
+export function parseIni(content) {
+    const result = {};
+    let currentSection = '';
+    for (const rawLine of content.split(/\r?\n/)) {
+        const line = rawLine.trim();
+        // Skip blank lines
+        if (!line)
+            continue;
+        // Skip comment lines (first non-whitespace char is ;)
+        if (line.startsWith(';'))
+            continue;
+        // Section header: [SectionName]
+        if (line.startsWith('[') && line.endsWith(']')) {
+            currentSection = line.slice(1, -1);
+            if (!result[currentSection]) {
+                result[currentSection] = {};
+            }
+            continue;
+        }
+        // Key=Value line — must have an = sign
+        const eqIdx = line.indexOf('=');
+        if (eqIdx === -1)
+            continue; // malformed line — skip silently
+        const rawKey = line.slice(0, eqIdx).trim();
+        // Preserve value verbatim after the = (no trimming — spaces and semicolons kept)
+        const value = line.slice(eqIdx + 1);
+        const { operator, key } = splitOperator(rawKey);
+        // Ensure section exists (handles key lines before any section header)
+        if (!result[currentSection]) {
+            result[currentSection] = {};
+        }
+        const section = result[currentSection];
+        switch (operator) {
+            case '!':
+                // Clear all accumulated values for this key
+                section[key] = [];
+                break;
+            case '-':
+                // Remove exact match from array
+                section[key] = (section[key] ?? []).filter((v) => v !== value);
+                break;
+            case '+':
+                // Append only if value not already present
+                if (!(section[key] ?? []).includes(value)) {
+                    section[key] = [...(section[key] ?? []), value];
+                }
+                break;
+            case '.':
+                // Append unconditionally (duplicates allowed)
+                section[key] = [...(section[key] ?? []), value];
+                break;
+            default:
+                // Plain = : last occurrence wins — store as single-element array
+                section[key] = [value];
+                break;
+        }
+    }
+    return result;
+}
+// ---------------------------------------------------------------------------
+// setIniValue
+// ---------------------------------------------------------------------------
+/**
+ * Write/update a single key in a section (plain = operator).
+ * Returns the new file content string — does not write to disk.
+ *
+ * Behaviour:
+ * - If the key exists in the target section (with any operator prefix),
+ *   replaces the FIRST matching line with "key=value" and drops all
+ *   subsequent lines for that key.
+ * - If the key is not found but the section exists, appends "key=value"
+ *   at the end of the section block (before the next [Section] header).
+ * - If the section does not exist at all, appends an empty line, the
+ *   section header, and "key=value" at the end of the file.
+ *
+ * Output uses \n line endings regardless of input style.
+ */
+export function setIniValue(content, section, key, value) {
+    const lines = content.split(/\r?\n/);
+    let inTargetSection = false;
+    let sectionFound = false;
+    let keyReplaced = false;
+    const output = [];
+    for (const line of lines) {
+        const trimmed = line.trim();
+        // Detect section headers
+        if (trimmed.startsWith('[') && trimmed.endsWith(']')) {
+            // Leaving a section — if we were in target section and haven't placed
+            // the key yet, inject it before moving to the new section
+            if (inTargetSection && !keyReplaced) {
+                output.push(`${key}=${value}`);
+                keyReplaced = true;
+            }
+            inTargetSection = trimmed.slice(1, -1) === section;
+            if (inTargetSection)
+                sectionFound = true;
+            output.push(line);
+            continue;
+        }
+        // Within target section: look for lines whose bare key matches
+        if (inTargetSection && !keyReplaced) {
+            const eqIdx = trimmed.indexOf('=');
+            if (eqIdx !== -1) {
+                const rawKey = trimmed.slice(0, eqIdx).trim();
+                const { key: bareKey } = splitOperator(rawKey);
+                if (bareKey === key) {
+                    // Replace this line with the new key=value
+                    output.push(`${key}=${value}`);
+                    keyReplaced = true;
+                    continue; // drop the original line
+                }
+            }
+        }
+        else if (inTargetSection && keyReplaced) {
+            // Key already replaced — drop any further lines for the same key
+            const eqIdx = trimmed.indexOf('=');
+            if (eqIdx !== -1) {
+                const rawKey = trimmed.slice(0, eqIdx).trim();
+                const { key: bareKey } = splitOperator(rawKey);
+                if (bareKey === key) {
+                    continue; // skip duplicate key lines
+                }
+            }
+        }
+        output.push(line);
+    }
+    // After loop: section was found but key never appeared — append at end
+    if (inTargetSection && !keyReplaced) {
+        output.push(`${key}=${value}`);
+    }
+    // Section was not in the file at all — append section + key at end
+    if (!sectionFound) {
+        output.push('', `[${section}]`, `${key}=${value}`);
+    }
+    return output.join('\n');
+}
+// ---------------------------------------------------------------------------
+// writeIniRemoveKey
+// ---------------------------------------------------------------------------
+/**
+ * Remove all lines for a key from a specified section (all operator prefixes).
+ * Returns the new file content string — does not write to disk.
+ *
+ * - Removes lines whose bare key (operator prefix stripped) matches target key.
+ * - No-op if section or key does not exist (returns content unchanged).
+ * - Output uses \n line endings regardless of input style.
+ */
+export function writeIniRemoveKey(content, section, key) {
+    const lines = content.split(/\r?\n/);
+    let inTargetSection = false;
+    const output = [];
+    for (const line of lines) {
+        const trimmed = line.trim();
+        // Detect section headers
+        if (trimmed.startsWith('[') && trimmed.endsWith(']')) {
+            inTargetSection = trimmed.slice(1, -1) === section;
+            output.push(line);
+            continue;
+        }
+        // Within target section: skip lines whose bare key matches
+        if (inTargetSection) {
+            const eqIdx = trimmed.indexOf('=');
+            if (eqIdx !== -1) {
+                const rawKey = trimmed.slice(0, eqIdx).trim();
+                const { key: bareKey } = splitOperator(rawKey);
+                if (bareKey === key) {
+                    continue; // remove this line
+                }
+            }
+        }
+        output.push(line);
+    }
+    return output.join('\n');
+}

package/dist/parsers/uproject-parser.js

@@ -0,0 +1,130 @@
+// src/parsers/uproject-parser.ts
+// Zod-validated parsers for .uproject and .uplugin JSON descriptor files.
+//
+// These files are standard JSON — JSON.parse with Zod schema validation is sufficient.
+// Both parsers return a discriminated union (ParseResult) and never throw.
+//
+// References:
+//   https://github.com/starkat99/unreal-schema/blob/main/uproject.schema.json
+//   https://github.com/starkat99/unreal-schema/blob/main/uplugin.schema.json
+import { z } from 'zod';
+// ---------------------------------------------------------------------------
+// .uproject schemas
+// ---------------------------------------------------------------------------
+export const UProjectModuleSchema = z.object({
+    Name: z.string(),
+    Type: z.string(),
+    LoadingPhase: z.string().optional(),
+    PlatformAllowList: z.array(z.string()).optional(),
+    PlatformDenyList: z.array(z.string()).optional(),
+    TargetAllowList: z.array(z.string()).optional(),
+    TargetDenyList: z.array(z.string()).optional(),
+    TargetConfigurationAllowList: z.array(z.string()).optional(),
+    TargetConfigurationDenyList: z.array(z.string()).optional(),
+});
+export const UProjectPluginEntrySchema = z.object({
+    Name: z.string(),
+    Enabled: z.boolean(),
+    Optional: z.boolean().optional(),
+    Description: z.string().optional(),
+    MarketplaceURL: z.string().optional(),
+    PlatformAllowList: z.array(z.string()).optional(),
+    SupportedTargetPlatforms: z.array(z.string()).optional(),
+});
+export const UProjectSchema = z.object({
+    FileVersion: z.number().int().min(1).max(3),
+    EngineAssociation: z.string().optional(),
+    Category: z.string().optional(),
+    Description: z.string().optional(),
+    Enterprise: z.boolean().optional(),
+    DisableEnginePluginsByDefault: z.boolean().optional(),
+    Modules: z.array(UProjectModuleSchema).optional(),
+    Plugins: z.array(UProjectPluginEntrySchema).optional(),
+    AdditionalPluginDirectories: z.array(z.string()).optional(),
+    AdditionalRootDirectories: z.array(z.string()).optional(),
+    TargetPlatforms: z.array(z.string()).optional(),
+});
+// ---------------------------------------------------------------------------
+// .uplugin schemas
+// ---------------------------------------------------------------------------
+export const UPluginModuleSchema = z.object({
+    Name: z.string(),
+    Type: z.string(),
+    LoadingPhase: z.string().optional(),
+    PlatformAllowList: z.array(z.string()).optional(),
+    PlatformDenyList: z.array(z.string()).optional(),
+});
+export const UPluginDependencySchema = z.object({
+    Name: z.string(),
+    Enabled: z.boolean(),
+    Optional: z.boolean().optional(),
+    PlatformAllowList: z.array(z.string()).optional(),
+});
+export const UPluginSchema = z.object({
+    FileVersion: z.number().int().min(1).max(3),
+    Version: z.number().optional(),
+    VersionName: z.string().optional(),
+    FriendlyName: z.string().optional(),
+    Description: z.string().optional(),
+    Category: z.string().optional(),
+    CreatedBy: z.string().optional(),
+    EngineVersion: z.string().optional(),
+    SupportedTargetPlatforms: z.array(z.string()).optional(),
+    Modules: z.array(UPluginModuleSchema).optional(),
+    Plugins: z.array(UPluginDependencySchema).optional(),
+    EnabledByDefault: z.boolean().optional(),
+    CanContainContent: z.boolean().optional(),
+    IsBetaVersion: z.boolean().optional(),
+    IsExperimentalVersion: z.boolean().optional(),
+});
+// ---------------------------------------------------------------------------
+// Parse functions
+// ---------------------------------------------------------------------------
+/**
+ * Parse a raw JSON string from a .uproject file.
+ * Returns ParseResult<UProjectDescriptor> — never throws.
+ *
+ * Threat T-02-03: JSON.parse is wrapped in try/catch; SyntaxError is never propagated.
+ */
+export function parseUproject(jsonContent) {
+    let parsed;
+    try {
+        parsed = JSON.parse(jsonContent);
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        return { success: false, error: `Invalid JSON: ${msg}` };
+    }
+    const result = UProjectSchema.safeParse(parsed);
+    if (result.success) {
+        return { success: true, data: result.data };
+    }
+    return {
+        success: false,
+        error: result.error.issues.map((i) => i.message).join('; '),
+    };
+}
+/**
+ * Parse a raw JSON string from a .uplugin file.
+ * Returns ParseResult<UPluginDescriptor> — never throws.
+ *
+ * Threat T-02-03: JSON.parse is wrapped in try/catch; SyntaxError is never propagated.
+ */
+export function parseUplugin(jsonContent) {
+    let parsed;
+    try {
+        parsed = JSON.parse(jsonContent);
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        return { success: false, error: `Invalid JSON: ${msg}` };
+    }
+    const result = UPluginSchema.safeParse(parsed);
+    if (result.success) {
+        return { success: true, data: result.data };
+    }
+    return {
+        success: false,
+        error: result.error.issues.map((i) => i.message).join('; '),
+    };
+}

package/dist/plugin-bridge/client.js

@@ -0,0 +1,217 @@
+// TCP client connecting to the UE Editor plugin on PLUGIN_PORT.
+// Returns structured plugin_not_connected errors when the editor is not running.
+// Reconnects automatically with ExponentialBackoff — never floods logs (Pitfall 3).
+// JSON-newline framing with correlationId-based request/response matching (Phase 7).
+import * as net from 'net';
+import { ExponentialBackoff } from './retry.js';
+import { PLUGIN_PORT } from '../config.js';
+/**
+ * Thrown by sendCommand() when no connection to the UE Editor plugin exists.
+ * Catch this to surface a structured error to the MCP client instead of crashing.
+ */
+export class PluginNotConnectedError extends Error {
+    bridgeError;
+    constructor(bridgeError) {
+        super(bridgeError.message);
+        this.name = 'PluginNotConnectedError';
+        this.bridgeError = bridgeError;
+    }
+}
+// ---------------------------------------------------------------------------
+// PluginBridgeClient
+// ---------------------------------------------------------------------------
+/**
+ * TCP client that connects to the UE Editor MCPBridge plugin (port 55557 by default).
+ *
+ * Connection lifecycle:
+ *  - Constructor starts scheduleReconnect() immediately (first attempt after 1s).
+ *  - On connect: socket is set, backoff is reset.
+ *  - On error/close: socket is cleared, next reconnect is scheduled.
+ *  - Only logs on first failure and on state changes (never on every retry).
+ *
+ * Graceful degradation:
+ *  - isConnected() returns false when no socket is active — never throws.
+ *  - getDisconnectedError() returns the exact MCPBridgeError shape.
+ *  - sendCommand() throws PluginNotConnectedError when disconnected.
+ *
+ * Protocol (JSON-newline framing with correlationId):
+ *  - sendCommand() generates a UUID correlationId, writes JSON+\n to the socket.
+ *  - The socket 'data' listener accumulates receiveBuffer, splits on \n, and
+ *    resolves the matching pending promise by correlationId.
+ *  - 10-second timeout rejects the promise if no response arrives.
+ *  - destroy() rejects all pending commands to prevent leaks.
+ */
+export class PluginBridgeClient {
+    socket = null;
+    port;
+    backoff;
+    reconnectTimer = null;
+    /** Log first failure only; suppress subsequent retries until state changes. */
+    hasLoggedFirstFailure = false;
+    /** Accumulates partial data received from the TCP socket between newlines. */
+    receiveBuffer = '';
+    /**
+     * Maps correlationId to resolve/reject callbacks for in-flight sendCommand() calls.
+     * Entries are added before socket.write() and removed on response or timeout.
+     */
+    pendingCommands = new Map();
+    constructor(port = PLUGIN_PORT) {
+        this.port = port;
+        this.backoff = new ExponentialBackoff();
+        this.scheduleReconnect();
+    }
+    /** Returns true only when a live (non-destroyed) socket exists. */
+    isConnected() {
+        return this.socket !== null && !this.socket.destroyed;
+    }
+    /**
+     * Returns the exact error object shape required by CONTEXT.md locked decision.
+     * Callers should include this object in their MCP tool response (isError: true).
+     */
+    getDisconnectedError() {
+        return {
+            error: 'plugin_not_connected',
+            message: 'This tool requires the UE Editor plugin. Start the editor with the MCPBridge plugin enabled.',
+            required_plugin: true,
+        };
+    }
+    /**
+     * Sends a command to the UE Editor plugin and waits for a correlated response.
+     *
+     * - Throws PluginNotConnectedError immediately if not connected.
+     * - Generates a crypto.randomUUID() correlationId (overwrites any caller-supplied value).
+     * - Writes JSON-newline framed message: JSON.stringify(cmd) + '\n'.
+     * - Resolves when the matching correlationId response arrives from the plugin.
+     * - Rejects with a timeout Error after 10 seconds if no response arrives.
+     * - Rejects immediately on socket write error.
+     *
+     * Threat T-07-11 mitigation: 10-second timeout clears Map entry on expiry;
+     * destroy() clears all remaining entries.
+     */
+    async sendCommand(cmd) {
+        if (!this.isConnected()) {
+            throw new PluginNotConnectedError(this.getDisconnectedError());
+        }
+        // Generate a unique correlationId for this request — overwrites any caller value.
+        // crypto.randomUUID() is available globally in Node 19+ (Node 22 used here).
+        const correlationId = crypto.randomUUID();
+        const cmdWithId = { ...cmd, correlationId };
+        return new Promise((resolve, reject) => {
+            this.pendingCommands.set(correlationId, { resolve, reject });
+            // 10-second timeout — T-07-11 mitigation
+            const timeoutHandle = setTimeout(() => {
+                if (this.pendingCommands.has(correlationId)) {
+                    this.pendingCommands.delete(correlationId);
+                    reject(new Error(`MCP command '${cmd.type}' timed out after 10 seconds`));
+                }
+            }, 10_000);
+            // Write JSON-newline framed message to the socket.
+            // The write callback fires on flush; reject immediately on error.
+            this.socket.write(JSON.stringify(cmdWithId) + '\n', 'utf8', (err) => {
+                if (err) {
+                    clearTimeout(timeoutHandle);
+                    this.pendingCommands.delete(correlationId);
+                    reject(err);
+                }
+            });
+        });
+    }
+    /**
+     * Cancel the pending reconnect timer, reject all in-flight commands, and close the socket.
+     * Call this in tests or during graceful shutdown.
+     */
+    destroy() {
+        if (this.reconnectTimer !== null) {
+            clearTimeout(this.reconnectTimer);
+            this.reconnectTimer = null;
+        }
+        if (this.socket !== null) {
+            this.socket.destroy();
+            this.socket = null;
+        }
+        // Reject all pending commands to prevent leaks (T-07-11 mitigation).
+        for (const [, pending] of this.pendingCommands) {
+            pending.reject(new Error('PluginBridgeClient destroyed'));
+        }
+        this.pendingCommands.clear();
+        this.receiveBuffer = '';
+    }
+    // ---------------------------------------------------------------------------
+    // Private: reconnect loop
+    // ---------------------------------------------------------------------------
+    scheduleReconnect() {
+        const delay = this.backoff.nextDelay();
+        this.reconnectTimer = setTimeout(() => {
+            this.reconnectTimer = null;
+            if (this.isConnected()) {
+                // Already connected — reset backoff and continue monitoring
+                this.backoff.reset();
+                this.scheduleReconnect();
+                return;
+            }
+            this.connect().then(() => {
+                // Connection succeeded
+                this.backoff.reset();
+                this.hasLoggedFirstFailure = false;
+                console.error('[UE MCP] Connected to UE Editor plugin on port', this.port);
+                this.scheduleReconnect();
+            }).catch(() => {
+                // Connection failed — log only on first failure or after reconnection
+                if (!this.hasLoggedFirstFailure) {
+                    console.error(`[UE MCP] Cannot reach UE Editor plugin on port ${this.port}. Retrying with backoff...`);
+                    this.hasLoggedFirstFailure = true;
+                }
+                this.scheduleReconnect();
+            });
+        }, delay);
+    }
+    connect() {
+        return new Promise((resolve, reject) => {
+            const socket = net.createConnection({ port: this.port, host: '127.0.0.1' });
+            // JSON-newline response parser — accumulates partial chunks, splits on \n,
+            // and resolves the correlated pending promise.
+            // Threat T-07-09 mitigation: try/catch around JSON.parse; unknown correlationId
+            // is silently dropped — no state corruption.
+            socket.on('data', (chunk) => {
+                this.receiveBuffer += chunk.toString('utf8');
+                let newlineIdx;
+                while ((newlineIdx = this.receiveBuffer.indexOf('\n')) !== -1) {
+                    const line = this.receiveBuffer.slice(0, newlineIdx).trim();
+                    this.receiveBuffer = this.receiveBuffer.slice(newlineIdx + 1);
+                    if (line.length === 0) {
+                        continue;
+                    }
+                    try {
+                        const response = JSON.parse(line);
+                        const pending = this.pendingCommands.get(response.correlationId);
+                        if (pending) {
+                            this.pendingCommands.delete(response.correlationId);
+                            pending.resolve(response);
+                        }
+                        // Unknown correlationId — silently drop (T-07-09 mitigation)
+                    }
+                    catch {
+                        // Non-JSON line — ignore (T-07-09 mitigation)
+                    }
+                }
+            });
+            socket.once('connect', () => {
+                this.socket = socket;
+                resolve();
+            });
+            socket.once('error', (err) => {
+                socket.destroy();
+                reject(err);
+            });
+            socket.once('close', () => {
+                if (this.socket === socket) {
+                    this.socket = null;
+                    // Log disconnection only if we were previously connected
+                    console.error('[UE MCP] Lost connection to UE Editor plugin. Reconnecting...');
+                    this.hasLoggedFirstFailure = false;
+                    this.scheduleReconnect();
+                }
+            });
+        });
+    }
+}

package/dist/plugin-bridge/protocol.js

@@ -0,0 +1,6 @@
+// JSON-newline framing types for communication with the UE C++ plugin.
+// The UE plugin (Phase 7) runs a TCP server on PLUGIN_PORT that speaks this protocol:
+//   - Each message is a JSON object followed by a newline character (\n)
+//   - Client sends MCPCommand, server responds with MCPResponse
+//   - correlationId is generated by the client, echoed by the server for matching
+export {};

package/dist/plugin-bridge/retry.js

@@ -0,0 +1,23 @@
+// Exponential backoff for TCP reconnection to the UE Editor plugin.
+// Delay doubles from 1s initial, capped at 30s to avoid reconnect storms.
+// See: RESEARCH.md Pitfall 3 — TCP Reconnect Storm on Plugin Not Running
+export class ExponentialBackoff {
+    delay = 1000;
+    maxDelay = 30000;
+    /**
+     * Returns the current delay in milliseconds, then doubles it for next call.
+     * Delay is capped at maxDelay (30000ms).
+     */
+    nextDelay() {
+        const current = this.delay;
+        this.delay = Math.min(this.delay * 2, this.maxDelay);
+        return current;
+    }
+    /**
+     * Resets delay back to the initial value (1000ms).
+     * Call this when a connection succeeds.
+     */
+    reset() {
+        this.delay = 1000;
+    }
+}