unreal-mcp-proxy 0.1.0

package/dist/stdio-bridge.js

@@ -0,0 +1,137 @@
+import { spawn } from "node:child_process";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { createInterface } from "node:readline";
+/**
+ * stdio mode (`unreal-mcp-proxy --stdio`): lets an MCP client auto-start everything.
+ * Registered as a stdio server in the client config, this thin shim
+ *   1. ensures the HTTP proxy daemon is running (spawns it detached if the port is closed),
+ *   2. bridges newline-delimited JSON-RPC on stdio to the daemon's /mcp endpoint.
+ * The daemon owns recording and the viewer, and outlives the client session.
+ * All shim logging goes to stderr - stdout is the protocol channel.
+ */
+const log = (message) => void process.stderr.write(`[unreal-mcp-proxy] ${message}\n`);
+async function healthy(baseUrl) {
+    try {
+        const response = await fetch(`${baseUrl}/health`, { signal: AbortSignal.timeout(500) });
+        return response.ok;
+    }
+    catch {
+        return false;
+    }
+}
+export async function ensureDaemon(config) {
+    const baseUrl = `http://127.0.0.1:${config.listenPort}`;
+    if (await healthy(baseUrl))
+        return baseUrl;
+    const cliPath = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "cli.js");
+    log(`starting proxy daemon on port ${config.listenPort}`);
+    spawn(process.execPath, [cliPath], {
+        detached: true,
+        stdio: "ignore",
+        env: process.env,
+        windowsHide: true
+    }).unref();
+    for (let attempt = 0; attempt < 25; attempt += 1) {
+        await new Promise((resolve) => setTimeout(resolve, 200));
+        if (await healthy(baseUrl)) {
+            log(`daemon ready: ${baseUrl}`);
+            return baseUrl;
+        }
+    }
+    throw new Error(`proxy daemon did not become healthy on ${baseUrl}`);
+}
+export async function runStdioBridge(config) {
+    const baseUrl = await ensureDaemon(config);
+    const endpoint = `${baseUrl}/mcp`;
+    let mcpSessionId = null;
+    let notificationStreamStarted = false;
+    const writeOut = (payload) => void process.stdout.write(`${JSON.stringify(payload)}\n`);
+    /** Server→client notifications (e.g. tools/listChanged) arrive on a GET SSE stream. */
+    const startNotificationStream = async () => {
+        if (notificationStreamStarted || !mcpSessionId)
+            return;
+        notificationStreamStarted = true;
+        try {
+            const response = await fetch(endpoint, {
+                method: "GET",
+                headers: { accept: "text/event-stream", "mcp-session-id": mcpSessionId }
+            });
+            if (!response.ok || !response.body)
+                return;
+            let pending = "";
+            const decoder = new TextDecoder();
+            for await (const chunk of response.body) {
+                pending += decoder.decode(chunk, { stream: true });
+                const blocks = pending.split(/\r?\n\r?\n/);
+                pending = blocks.pop() ?? "";
+                for (const block of blocks)
+                    emitSseBlock(block, writeOut);
+            }
+        }
+        catch { /* optional channel - the editor may not support a standalone GET stream */ }
+    };
+    const rl = createInterface({ input: process.stdin, terminal: false });
+    for await (const line of rl) {
+        const trimmed = line.trim();
+        if (!trimmed)
+            continue;
+        let message;
+        try {
+            message = JSON.parse(trimmed);
+        }
+        catch {
+            continue;
+        }
+        try {
+            const response = await fetch(endpoint, {
+                method: "POST",
+                headers: {
+                    "content-type": "application/json",
+                    accept: "application/json, text/event-stream",
+                    ...(mcpSessionId ? { "mcp-session-id": mcpSessionId } : {})
+                },
+                body: trimmed
+            });
+            const sessionHeader = response.headers.get("mcp-session-id");
+            if (sessionHeader)
+                mcpSessionId = sessionHeader;
+            if (message.method === "initialize")
+                void startNotificationStream();
+            if (message.id === undefined) {
+                void response.arrayBuffer();
+                continue;
+            } // notification: no reply
+            const contentType = response.headers.get("content-type") ?? "";
+            const text = await response.text();
+            if (contentType.includes("text/event-stream")) {
+                for (const block of text.split(/\r?\n\r?\n/))
+                    emitSseBlock(block, writeOut);
+            }
+            else if (text.trim()) {
+                writeOut(JSON.parse(text));
+            }
+            else {
+                writeOut({ jsonrpc: "2.0", id: message.id, error: { code: -32603, message: `empty response (HTTP ${response.status})` } });
+            }
+        }
+        catch (error) {
+            if (message.id !== undefined) {
+                writeOut({ jsonrpc: "2.0", id: message.id, error: { code: -32603, message: error.message } });
+            }
+        }
+    }
+}
+function emitSseBlock(block, writeOut) {
+    const data = block.split(/\r?\n/)
+        .filter((line) => line.startsWith("data:"))
+        .map((line) => line.slice(5).trimStart())
+        .join("\n");
+    if (!data)
+        return;
+    try {
+        writeOut(JSON.parse(data));
+    }
+    catch { /* keep-alive or partial frame */ }
+}
+//# sourceMappingURL=stdio-bridge.js.map

package/dist/stdio-bridge.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stdio-bridge.js","sourceRoot":"","sources":["../src/stdio-bridge.ts"],"names":[],"mappings":"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"}

package/dist/types.d.ts

@@ -0,0 +1,124 @@
+/** Shared domain types for the proxy core, the viewer, and tests. */
+export type JsonValue = string | number | boolean | null | JsonValue[] | {
+    [key: string]: JsonValue;
+};
+export type JsonObject = Record<string, JsonValue | undefined>;
+/** One recorded event line in a session .jsonl file. */
+export interface SessionEvent {
+    schemaVersion: 2;
+    source: string;
+    sessionId: string;
+    sequence: number;
+    timestamp: string;
+    type: string;
+    /** Optional metadata tag (user/machine/project); null unless configured. */
+    identity: JsonObject | null;
+    [key: string]: unknown;
+}
+export interface ActiveSession {
+    id: string;
+    createdAt: string;
+    reason: string;
+    sequence: number;
+}
+/** Body summary produced by summarizeBody(): either parsed JSON, an SSE bundle, or an omission marker. */
+export type BodySummary = {
+    omitted: true;
+    reason: string;
+    size?: number;
+} | {
+    transport: "sse";
+    events: JsonValue[];
+} | JsonValue;
+export type CallOutcome = "success" | "error" | "running";
+export interface CallModel {
+    id: string;
+    sequence: number;
+    title: string;
+    subtitle?: string;
+    category: string;
+    toolName?: string;
+    toolsetName?: string;
+    arguments?: JsonObject;
+    startedAt: string;
+    completedAt: string | null;
+    durationMs: number | null;
+    statusCode: number | null;
+    outcome: CallOutcome;
+    error: string | null;
+    request: BodySummary | null;
+    response: BodySummary | null;
+    requestHeaders: JsonObject | null;
+    responseHeaders: JsonObject | null;
+    timing: CallTiming | null;
+    clientSource: string;
+    operationId?: string;
+    operationTitle?: string;
+    operationStep?: string;
+    deepLink: string;
+    annotations: AnnotationModel[];
+    isSystem: boolean;
+    performance?: CallPerformance;
+}
+export interface CallTiming {
+    requestToHeadersMs: number;
+    toolResultMs: number;
+    proxyFinalizeMs: number;
+    completionReason: string;
+}
+export interface CallPerformance {
+    sampleCount: number;
+    medianMs: number;
+    ratio: number;
+    classification: "slow" | "normal";
+}
+export interface AnnotationModel {
+    callId: string;
+    severity: string;
+    title: string;
+    summary: string;
+    cause?: string;
+    suggestion?: string;
+    author: string;
+    timestamp?: string;
+}
+export interface FlowNode {
+    id: string;
+    key: string;
+    label: string;
+    subtitle: string;
+    kind: "tool" | "target";
+    callIds: string[];
+}
+export interface FlowEdge {
+    id: string;
+    from: string;
+    to: string;
+    order: number;
+    callId: string;
+    durationMs: number;
+    outcome: CallOutcome;
+}
+export interface FlowGraph {
+    basis: string;
+    nodes: FlowNode[];
+    edges: FlowEdge[];
+}
+export interface SessionModel {
+    id: string;
+    startedAt: string | undefined;
+    lastEventAt: string | undefined;
+    summary: {
+        totalCalls: number;
+        successes: number;
+        errors: number;
+        running: number;
+        systemCalls: number;
+        averageDurationMs: number;
+        medianDurationMs: number;
+    };
+    graph: FlowGraph;
+    calls: CallModel[];
+    annotations: AnnotationModel[];
+    rawEventCount: number;
+}

package/dist/types.js

@@ -0,0 +1,3 @@
+/** Shared domain types for the proxy core, the viewer, and tests. */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,qEAAqE"}