unreal-mcp-proxy 0.1.0

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "unreal-mcp-proxy",
+  "version": "0.1.0",
+  "description": "Session recorder, offline flight viewer, and agent skillset for Epic's Unreal MCP (UE 5.8+).",
+  "type": "module",
+  "license": "MIT",
+  "author": "HyunJin Yoo",
+  "repository": { "type": "git", "url": "git+https://github.com/rapina/unreal-mcp-proxy.git" },
+  "bin": { "unreal-mcp-proxy": "dist/cli.js" },
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": { ".": { "types": "./dist/index.d.ts", "default": "./dist/index.js" } },
+  "files": ["dist", "skills", "README.md", "LICENSE"],
+  "scripts": {
+    "build": "tsc -p tsconfig.json && node viewer/build.mjs",
+    "typecheck": "tsc -p tsconfig.json && tsc -p viewer/tsconfig.json && tsc -p tsconfig.test.json",
+    "test": "npm run build && node --test \"test/*.test.ts\"",
+    "start": "npm run build && node dist/cli.js",
+    "prepublishOnly": "npm run typecheck && npm test"
+  },
+  "engines": { "node": ">=20" },
+  "keywords": ["unreal", "unreal-engine", "ue5", "mcp", "model-context-protocol", "proxy", "observability", "session-recording", "claude", "ai-agent"],
+  "devDependencies": {
+    "@types/node": "^24.0.0",
+    "esbuild": "^0.28.1",
+    "typescript": "^7.0.0"
+  }
+}

package/skills/unreal-mcp-observer/SKILL.md

@@ -0,0 +1,88 @@
+---
+name: unreal-mcp-observer
+description: Query and operate the Unreal MCP session recorder (unreal-mcp-proxy). Use when an Unreal MCP tool call fails (check for past similar failures and their fixes first), when a call seems unusually slow, when the user asks what happened in an Unreal editor automation session, or when you need to share a deep link to a specific call, check recorder status, or start a fresh observation session. After diagnosing a failure, record the conclusion as an annotation so future sessions can recall it.
+---
+
+# Unreal MCP Observer
+
+Your Unreal MCP traffic is being recorded by [unreal-mcp-proxy](https://github.com/rapina/unreal-mcp-proxy).
+This skill lets you query that history: past failures and how they were resolved, per-tool
+latency baselines, and full request/response bodies of any call.
+
+All commands print JSON. Run them with node (no dependencies):
+
+```bash
+node <skill-dir>/scripts/query.mjs <command> [args]
+```
+
+Set `UNREAL_MCP_PROXY_DATA_DIR` if the proxy's data directory is not `./data`
+(it is printed at proxy startup). `UNREAL_MCP_PROXY_URL` defaults to `http://127.0.0.1:35100`.
+
+## Workflow
+
+1. **An Unreal MCP tool call failed?** Before retrying or guessing, check history:
+
+   ```bash
+   node scripts/query.mjs similar-failures "Cannot remove file as it is read only"
+   ```
+
+   Matches include any annotations left by previous sessions - a past agent may have
+   already recorded the root cause and the fix (e.g. Unreal + Git LFS file locking
+   makes assets read-only until `git lfs lock`).
+
+2. **A call seems slow?** Compare against the recorded baseline:
+
+   ```bash
+   node scripts/query.mjs tool-stats save_assets
+   ```
+
+3. **Need the exact request/response of a call?**
+
+   ```bash
+   node scripts/query.mjs call-detail <callId-prefix>
+   ```
+
+4. **Diagnosed something non-obvious?** Record it for future sessions (yours and others'):
+
+   ```bash
+   node scripts/query.mjs annotate <callId> --severity error \
+     --title "Asset save fails under LFS locking" \
+     --summary "save_assets fails because .uasset files are checked out read-only" \
+     --suggestion "run git lfs lock <path> before saving, unlock after push"
+   ```
+
+   Annotations appear in the session viewer next to the call, and are returned by
+   `similar-failures` forever after. This is the memory loop: record once, recall always.
+
+5. **Reporting a finding to the user?** Hand them a deep link instead of describing the
+   call - they will see the exact request/response and your annotation in the viewer:
+
+   ```bash
+   node scripts/query.mjs link <callId>
+   ```
+
+6. **Starting a distinct piece of work** (and the user asked for a fresh recording)?
+
+   ```bash
+   node scripts/query.mjs clear
+   ```
+
+## Commands
+
+| Command | Purpose |
+| --- | --- |
+| `status` | Proxy health, active session + URL, and how many sessions/calls/failures are recorded |
+| `sessions [--limit N]` | Recorded sessions with call/failure counts and viewer URLs, newest first |
+| `link <callId>` | Deep link for one call - share it with a human (callId prefix is enough) |
+| `clear` | Roll over to a new observation session (history is kept; requires the proxy running) |
+| `recent-failures [--limit N]` | Latest failed calls with error text, across all recorded sessions |
+| `similar-failures <text> [--limit N]` | Past failures matching an error message (paths/ids/numbers are masked before matching) + their annotations |
+| `call-detail <callId>` | One call with full request/response bodies (callId prefix is enough) |
+| `tool-stats [tool]` | Per-tool call count, failure rate, p50/p95 duration |
+| `annotate <callId> --title --summary [...]` | Attach a diagnosis to a call (requires the proxy to be running) |
+
+Notes:
+- Query results are advisory context. If a query fails (proxy not running, no data dir),
+  continue your task without it.
+- Session viewer for humans: open a session at `http://127.0.0.1:35100/sessions/<id>`,
+  or open the standalone `viewer.html` and drop a `data/sessions/*.jsonl` file into it.

package/skills/unreal-mcp-observer/scripts/query.mjs

@@ -0,0 +1,225 @@
+#!/usr/bin/env node
+// Zero-dependency query CLI over recorded unreal-mcp-proxy sessions.
+// Usage: node query.mjs <recent-failures|similar-failures|call-detail|tool-stats|annotate> [args]
+// Env:   UNREAL_MCP_PROXY_DATA_DIR (default ./data), UNREAL_MCP_PROXY_URL (default http://127.0.0.1:35100)
+
+import { readdir, readFile } from "node:fs/promises";
+import path from "node:path";
+
+const dataDir = path.resolve(process.env.UNREAL_MCP_PROXY_DATA_DIR ?? "./data");
+const proxyUrl = (process.env.UNREAL_MCP_PROXY_URL ?? "http://127.0.0.1:35100").replace(/\/$/, "");
+const [command, ...rest] = process.argv.slice(2);
+
+const flags = {};
+const positional = [];
+for (let index = 0; index < rest.length; index += 1) {
+  const arg = rest[index];
+  if (arg.startsWith("--")) { flags[arg.slice(2)] = rest[index + 1]; index += 1; }
+  else positional.push(arg);
+}
+
+async function loadSessions() {
+  const sessionsDir = path.join(dataDir, "sessions");
+  let files = [];
+  try { files = (await readdir(sessionsDir)).filter((name) => name.endsWith(".jsonl")); }
+  catch { fail(`no sessions directory at ${sessionsDir} (set UNREAL_MCP_PROXY_DATA_DIR)`); }
+  const sessions = [];
+  for (const file of files) {
+    const text = await readFile(path.join(sessionsDir, file), "utf8");
+    const events = text.split("\n").filter(Boolean).map((line) => JSON.parse(line));
+    sessions.push({ sessionId: file.replace(/\.jsonl$/, ""), events });
+  }
+  return sessions;
+}
+
+function toolOf(startedEvent) {
+  const body = startedEvent?.body;
+  const params = body?.params;
+  if (body?.method !== "tools/call") return { tool: body?.method ?? "mcp", toolset: null, args: null };
+  if (params?.name === "call_tool") {
+    return {
+      tool: params.arguments?.tool_name ?? "unknown",
+      toolset: params.arguments?.toolset_name ?? null,
+      args: params.arguments?.arguments ?? null
+    };
+  }
+  return { tool: params?.name ?? "unknown", toolset: null, args: params?.arguments ?? null };
+}
+
+function errorOf(event) {
+  if (event.type === "mcp_request_failed") return event.error ?? "connection failed";
+  if ((event.status ?? 0) >= 400) return `HTTP ${event.status}`;
+  const messages = event.body?.transport === "sse" ? event.body.events ?? [] : [event.body];
+  for (const message of messages) {
+    if (message?.error) return message.error.message ?? "MCP error";
+    if (message?.result?.isError) {
+      const text = (message.result.content ?? []).map((item) => item?.text ?? "").join("\n").trim();
+      return text.slice(0, 500) || "tool returned isError";
+    }
+  }
+  return null;
+}
+
+function buildCalls(sessions) {
+  const calls = [];
+  for (const { sessionId, events } of sessions) {
+    const started = new Map();
+    const annotations = events.filter((event) => event.type === "ai_annotation");
+    for (const event of events) {
+      if (event.type === "mcp_request_started") started.set(event.callId, event);
+      if (event.type === "mcp_request_completed" || event.type === "mcp_request_failed") {
+        const begin = started.get(event.callId);
+        const { tool, toolset, args } = toolOf(begin);
+        calls.push({
+          callId: event.callId, sessionId, tool, toolset, arguments: args,
+          startedAt: begin?.timestamp ?? event.timestamp, durationMs: event.durationMs ?? null,
+          status: event.type === "mcp_request_failed" ? "failed" : "completed",
+          error: errorOf(event),
+          request: begin?.body ?? null, response: event.body ?? null,
+          annotations: annotations.filter((note) => note.callId === event.callId)
+            .map(({ severity, title, summary, cause, suggestion, author }) => ({ severity, title, summary, cause, suggestion, author }))
+        });
+      }
+    }
+  }
+  return calls.sort((a, b) => new Date(b.startedAt) - new Date(a.startedAt));
+}
+
+function normalize(text) {
+  return (text ?? "").toLowerCase()
+    .replace(/[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}/g, "<uuid>")
+    .replace(/[a-z]:\\[^\s"'`]+/g, "<path>")
+    .replace(/(?:\/[\w.-]+){2,}/g, "<path>")
+    .replace(/0x[0-9a-f]+/g, "<hex>")
+    .replace(/\d+/g, "<n>")
+    .replace(/\s+/g, " ").trim();
+}
+
+function similarity(a, b) {
+  const tokens = (text) => new Set(text.split(/[^a-z<>]+/).filter((token) => token.length > 2));
+  const setA = tokens(a), setB = tokens(b);
+  if (!setA.size || !setB.size) return 0;
+  let shared = 0;
+  for (const token of setA) if (setB.has(token)) shared += 1;
+  return (2 * shared) / (setA.size + setB.size);
+}
+
+const out = (value) => console.log(JSON.stringify(value, null, 1));
+const fail = (message) => { console.error(message); process.exit(1); };
+const limit = Number(flags.limit ?? 10);
+
+switch (command) {
+  case "recent-failures": {
+    const calls = buildCalls(await loadSessions());
+    out(calls.filter((call) => call.error)
+      .slice(0, limit)
+      .map(({ request, response, arguments: _args, ...call }) => call));
+    break;
+  }
+  case "similar-failures": {
+    const query = positional.join(" ");
+    if (!query) fail("usage: similar-failures <error text>");
+    const norm = normalize(query);
+    const calls = buildCalls(await loadSessions()).filter((call) => call.error);
+    const matches = calls
+      .map((call) => ({ score: similarity(norm, normalize(call.error)), call }))
+      .filter((match) => match.score > 0.3)
+      .sort((a, b) => b.score - a.score)
+      .slice(0, limit)
+      .map(({ score, call: { request, response, arguments: _args, ...call } }) => ({ similarity: Math.round(score * 100) / 100, ...call }));
+    out(matches);
+    break;
+  }
+  case "call-detail": {
+    const callId = positional[0];
+    if (!callId) fail("usage: call-detail <callId>");
+    const call = buildCalls(await loadSessions()).find((item) => item.callId.startsWith(callId));
+    out(call ?? { error: "not_found" });
+    break;
+  }
+  case "tool-stats": {
+    const filterTool = positional[0];
+    const calls = buildCalls(await loadSessions()).filter((call) => !filterTool || call.tool === filterTool);
+    const byTool = new Map();
+    for (const call of calls) {
+      const stats = byTool.get(call.tool) ?? { tool: call.tool, toolset: call.toolset, calls: 0, failed: 0, durations: [] };
+      stats.calls += 1;
+      if (call.error) stats.failed += 1;
+      if (call.durationMs != null) stats.durations.push(call.durationMs);
+      byTool.set(call.tool, stats);
+    }
+    out([...byTool.values()]
+      .sort((a, b) => b.calls - a.calls)
+      .map(({ durations, ...stats }) => {
+        const sorted = [...durations].sort((a, b) => a - b);
+        const at = (q) => sorted.length ? Math.round(sorted[Math.min(sorted.length - 1, Math.floor(q * sorted.length))]) : null;
+        return { ...stats, failureRate: stats.calls ? Math.round((stats.failed / stats.calls) * 1000) / 1000 : 0, p50: at(0.5), p95: at(0.95) };
+      }));
+    break;
+  }
+  case "status": {
+    // Proxy health + active session + how much history is on disk.
+    let proxy = null;
+    try { proxy = await (await fetch(`${proxyUrl}/health`)).json(); } catch { /* proxy down */ }
+    let recorded = { sessions: 0, calls: 0, failures: 0 };
+    try {
+      const calls = buildCalls(await loadSessions());
+      recorded = {
+        sessions: new Set(calls.map((call) => call.sessionId)).size,
+        calls: calls.length,
+        failures: calls.filter((call) => call.error).length
+      };
+    } catch { /* no data dir yet */ }
+    out({ proxy: proxy ?? { ok: false, error: `proxy not reachable at ${proxyUrl}` }, recorded, dataDir });
+    break;
+  }
+  case "sessions": {
+    const sessions = await loadSessions();
+    out(sessions.map(({ sessionId, events }) => {
+      const calls = buildCalls([{ sessionId, events }]);
+      return {
+        sessionId,
+        startedAt: events[0]?.timestamp ?? null,
+        lastEventAt: events.at(-1)?.timestamp ?? null,
+        calls: calls.length,
+        failures: calls.filter((call) => call.error).length,
+        url: `${proxyUrl}/sessions/${sessionId}`
+      };
+    }).sort((a, b) => new Date(b.lastEventAt ?? 0) - new Date(a.lastEventAt ?? 0)).slice(0, limit));
+    break;
+  }
+  case "link": {
+    // Deep link for a call - hand it to a human, they see the same call in the viewer.
+    const prefix = positional[0];
+    if (!prefix) fail("usage: link <callId>");
+    const call = buildCalls(await loadSessions()).find((item) => item.callId.startsWith(prefix));
+    if (!call) { out({ error: "not_found" }); break; }
+    out({ callId: call.callId, tool: call.tool, url: `${proxyUrl}/sessions/${call.sessionId}?call=${call.callId}` });
+    break;
+  }
+  case "clear": {
+    // Start a new observation session (history is kept on disk).
+    const response = await fetch(`${proxyUrl}/api/session/clear`, { method: "POST" });
+    out(await response.json());
+    break;
+  }
+  case "annotate": {
+    const callId = positional[0];
+    if (!callId || !flags.title || !flags.summary) {
+      fail("usage: annotate <callId> --title <t> --summary <s> [--severity info|warn|error] [--cause <c>] [--suggestion <s>] [--author <a>]");
+    }
+    const session = await (await fetch(`${proxyUrl}/api/session`)).json();
+    const response = await fetch(`${proxyUrl}/api/sessions/${session.id}/annotations`, {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({
+        callId, severity: flags.severity ?? "info", title: flags.title, summary: flags.summary,
+        cause: flags.cause, suggestion: flags.suggestion, author: flags.author ?? "agent"
+      })
+    });
+    out({ status: response.status, ...(await response.json()) });
+    break;
+  }
+  default:
+    fail("usage: query.mjs <status|sessions|link|clear|recent-failures|similar-failures|call-detail|tool-stats|annotate> [args] [--limit N]");
+}