@aprovan/mcp-app-server 0.1.0-dev.4d82df8

package/src/runtime/main.ts

@@ -0,0 +1,164 @@
+/**
+ * Patchwork widget runtime host.
+ *
+ * Runs inside the nested, CSP-free iframe embedded by the MCP App shell. It
+ * fetches a saved widget's raw source and compiles + mounts it in the browser
+ * using the shared `@aprovan/patchwork-compiler` runtime (esbuild-wasm) — the
+ * same path the chat app uses.
+ *
+ * The widget is selected via query params written by the shell:
+ *   /runtime/?widget=<name>/<hash>&inputs=<urlencoded-json>
+ *
+ * Service / live-update / context calls made by the widget go through the
+ * bridge shim (window.patchwork.* and namespace.*), which forwards them to the
+ * parent shell over postMessage; the shell relays to the MCP host.
+ */
+import {
+  createCompiler,
+  createProjectFromFiles,
+  type Compiler,
+  type Manifest,
+  type VirtualFile,
+} from "@aprovan/patchwork-compiler";
+import { generateBridgeShim } from "../shim.js";
+
+const CDN_BASE = "https://esm.sh";
+
+interface WidgetRef {
+  name: string;
+  hash: string;
+}
+
+interface WidgetFilesResponse {
+  files: VirtualFile[];
+  entry: string;
+  manifest: Manifest;
+}
+
+const statusEl = document.getElementById("pw-status");
+
+function setStatus(message: string, isError = false): void {
+  if (!statusEl) return;
+  statusEl.textContent = message;
+  if (isError) statusEl.setAttribute("data-error", "true");
+  else statusEl.removeAttribute("data-error");
+  statusEl.style.display = message ? "block" : "none";
+}
+
+/**
+ * Execute the bridge shim in this window so `window.patchwork` and the service
+ * namespace proxies exist before the widget mounts. Imported as a blob module so
+ * execution completes before we continue.
+ */
+async function runShim(code: string): Promise<void> {
+  if (!code.trim()) return;
+  const blob = new Blob([code], { type: "application/javascript" });
+  const url = URL.createObjectURL(blob);
+  try {
+    await import(/* @vite-ignore */ url);
+  } catch (err) {
+    console.warn("[patchwork-runtime] bridge shim failed to load:", err);
+  } finally {
+    URL.revokeObjectURL(url);
+  }
+}
+
+/** Report content height to the parent shell so it can size the iframe. */
+function reportSize(): void {
+  const height = Math.ceil(document.documentElement.getBoundingClientRect().height);
+  window.parent.postMessage({ source: "patchwork", kind: "size", height }, "*");
+}
+
+let started = false;
+const compilerCache = new Map<string, Promise<Compiler>>();
+
+function getCompiler(image: string): Promise<Compiler> {
+  let cached = compilerCache.get(image);
+  if (!cached) {
+    cached = createCompiler({
+      image,
+      // Services are bridged to the MCP host via the shim, not an HTTP proxy.
+      proxyUrl: "",
+      cdnBaseUrl: CDN_BASE,
+      widgetCdnBaseUrl: CDN_BASE,
+    });
+    compilerCache.set(image, cached);
+  }
+  return cached;
+}
+
+async function render(widget: WidgetRef, inputs: Record<string, unknown>): Promise<void> {
+  if (started) return;
+  started = true;
+
+  try {
+    setStatus("Loading widget source…");
+    const res = await fetch(
+      `/widget/${encodeURIComponent(widget.name)}/${encodeURIComponent(widget.hash)}/files`,
+    );
+    if (!res.ok) throw new Error(`Failed to load widget files (${res.status})`);
+    const { files, entry, manifest } = (await res.json()) as WidgetFilesResponse;
+
+    const services = manifest.services ?? [];
+
+    // Wire window.patchwork + service namespaces (forwarded to the host shell)
+    // before mounting so the widget's calls resolve.
+    await runShim(generateBridgeShim({ namespaces: services }));
+
+    setStatus("Compiling widget…");
+    const compiler = await getCompiler(manifest.image);
+
+    const project = createProjectFromFiles(files, widget.name);
+    if (entry) project.entry = entry;
+
+    // Strip services from the manifest passed to the compiler so its built-in
+    // HTTP-proxy namespace globals don't clobber the bridge shim's proxies.
+    const compileManifest: Manifest = { ...manifest, services: undefined };
+    const compiled = await compiler.compile(project, compileManifest);
+
+    const root = document.getElementById("root");
+    if (!root) throw new Error("Missing #root element");
+
+    setStatus("");
+    await compiler.mount(compiled, { target: root, mode: "embedded", inputs });
+
+    // Report size now and on any subsequent layout change.
+    reportSize();
+    const ro = new ResizeObserver(() => reportSize());
+    ro.observe(document.body);
+  } catch (err) {
+    started = false;
+    console.error("[patchwork-runtime] render failed", err);
+    const message = err instanceof Error ? err.message : String(err);
+    setStatus(`Failed to render widget:\n${message}`, true);
+    window.parent.postMessage({ source: "patchwork", kind: "error", error: message }, "*");
+  }
+}
+
+// Render from query params: /runtime/?widget=<name>/<hash>&inputs=<json>
+function renderFromQuery(): void {
+  const params = new URLSearchParams(window.location.search);
+  const widgetParam = params.get("widget");
+  if (!widgetParam) {
+    setStatus("No widget specified.", true);
+    return;
+  }
+  const [name, hash] = widgetParam.split("/");
+  if (!name || !hash) {
+    setStatus("Invalid widget reference.", true);
+    return;
+  }
+
+  let inputs: Record<string, unknown> = {};
+  const inputsParam = params.get("inputs");
+  if (inputsParam) {
+    try {
+      inputs = JSON.parse(inputsParam) as Record<string, unknown>;
+    } catch {
+      /* ignore malformed inputs */
+    }
+  }
+  void render({ name, hash }, inputs);
+}
+
+renderFromQuery();

package/src/scripts/export-artifacts.ts

@@ -0,0 +1,51 @@
+import { mkdir, writeFile } from "node:fs/promises";
+import { join, resolve, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import type { Manifest, VirtualFile } from "@aprovan/patchwork-compiler";
+import {
+  REFERENCE_WIDGET_FILES,
+  REFERENCE_WIDGET_MANIFEST,
+} from "../reference-widgets/live-dashboard.js";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const ARTIFACTS_DIR = resolve(__dirname, "../../../../.artifacts/widgets");
+
+const WIDGETS: Array<{ manifest: Manifest; files: VirtualFile[] }> = [
+  { manifest: REFERENCE_WIDGET_MANIFEST, files: REFERENCE_WIDGET_FILES },
+];
+
+/**
+ * Export the raw source of each reference widget to .artifacts/widgets/<name>/.
+ *
+ * Widgets are no longer compiled on the server — they are saved as raw source
+ * and compiled in the browser by the shared runtime. This script just dumps the
+ * raw files (plus manifest.json) for inspection.
+ */
+async function main(): Promise<void> {
+  console.log("Exporting raw widget source artifacts...\n");
+
+  for (const { manifest, files } of WIDGETS) {
+    const widgetDir = join(ARTIFACTS_DIR, manifest.name);
+    await mkdir(widgetDir, { recursive: true });
+
+    for (const file of files) {
+      const outPath = join(widgetDir, file.path);
+      await mkdir(dirname(outPath), { recursive: true });
+      await writeFile(outPath, file.content, "utf-8");
+    }
+    await writeFile(
+      join(widgetDir, "manifest.json"),
+      JSON.stringify(manifest, null, 2),
+      "utf-8",
+    );
+
+    console.log(`  ${manifest.name} → ${widgetDir} (${files.length} files)`);
+  }
+
+  console.log("\nDone. Render widgets via the runtime host to see them compiled.");
+}
+
+main().catch((err) => {
+  console.error("Export failed:", err);
+  process.exit(1);
+});

package/src/server.ts

@@ -0,0 +1,398 @@
+import { randomUUID } from "node:crypto";
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+import express from "express";
+import { createMcpExpressApp } from "@modelcontextprotocol/sdk/server/express.js";
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import cors from "cors";
+import { registerSession, unregisterSession } from "./live-update.js";
+import { log, error } from "./logger.js";
+import { createRegistryBackend, type RegistryBackend } from "./registry-backend.js";
+import { createMcpAppServer, type McpAppServerOptions } from "./index.js";
+import { getWidgetStore } from "./widget-store/index.js";
+import { startTunnel, stopTunnel } from "./tunnel.js";
+import type { Request, Response } from "express";
+
+const PORT = Number(process.env["PORT"] ?? 3000);
+const WIDGET_PORT = Number(process.env["WIDGET_PORT"] ?? 3002);
+const HOST = process.env["HOST"] ?? "0.0.0.0";
+const TRANSPORT = process.env["TRANSPORT"] ?? (process.argv.includes("--stdio") ? "stdio" : "http");
+const WIDGET_TUNNEL = process.env["WIDGET_TUNNEL"] === "true" || process.argv.includes("--tunnel");
+
+type SessionEntry = {
+  server: ReturnType<typeof createMcpAppServer>;
+  transport: StreamableHTTPServerTransport;
+};
+
+/**
+ * Cross-process coordination for the shared widget host.
+ *
+ * Every stdio spawn of this server (Claude Desktop respawns it freely) would
+ * otherwise start its own widget server and its own cloudflared quick tunnel.
+ * Only one can bind {@link WIDGET_PORT}; the rest orphan extra tunnels and, worse,
+ * each render returns a *different* hostname — and any instance whose ephemeral
+ * tunnel has dropped serves a dead URL (Cloudflare 1033) into the widget HTML.
+ *
+ * We elect a single owner via the port bind: whoever binds the port establishes
+ * (and verifies) the tunnel and publishes its base URL to a temp file keyed by
+ * port; every other instance reuses that URL instead of starting a tunnel.
+ */
+interface WidgetHostState {
+  baseUrl: string;
+  pid: number;
+  updatedAt: number;
+}
+
+const WIDGET_STATE_FILE = join(tmpdir(), `patchwork-widget-${WIDGET_PORT}.json`);
+
+function readWidgetHostState(): WidgetHostState | null {
+  try {
+    return JSON.parse(readFileSync(WIDGET_STATE_FILE, "utf8")) as WidgetHostState;
+  } catch {
+    return null;
+  }
+}
+
+function publishWidgetHostState(baseUrl: string): void {
+  try {
+    const state: WidgetHostState = { baseUrl, pid: process.pid, updatedAt: Date.now() };
+    writeFileSync(WIDGET_STATE_FILE, JSON.stringify(state));
+  } catch (err) {
+    error("mcp-app-server", "Failed to publish widget host state:", err);
+  }
+}
+
+function isProcessAlive(pid: number): boolean {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (err) {
+    // ESRCH = no such process; EPERM = exists but not ours (still alive).
+    return (err as NodeJS.ErrnoException).code === "EPERM";
+  }
+}
+
+/**
+ * Wait for the owning instance to publish its (verified) base URL. Only adopt
+ * state whose owning pid is still alive, so a non-owner never reuses a dead
+ * previous owner's (now-1033) hostname.
+ */
+async function awaitPublishedWidgetBaseUrl(timeoutMs = 35000): Promise<string | null> {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    const state = readWidgetHostState();
+    if (state?.baseUrl && isProcessAlive(state.pid)) return state.baseUrl;
+    await new Promise((r) => setTimeout(r, 500));
+  }
+  return null;
+}
+
+/** Locate a built browser bundle dir (dist/<name>) from either dist or src. */
+function resolveDistDir(name: string): string {
+  const candidates = [
+    fileURLToPath(new URL(`./${name}`, import.meta.url)), // built: dist/<name>
+    fileURLToPath(new URL(`../dist/${name}`, import.meta.url)), // dev via tsx: src → dist
+  ];
+  return candidates.find((dir) => existsSync(dir)) ?? candidates[0]!;
+}
+
+/** Locate the built runtime bundle (dist/runtime). */
+export function resolveRuntimeDir(): string {
+  return resolveDistDir("runtime");
+}
+
+/** Locate the built MCP App shell bundle (dist/shell). */
+export function resolveShellDir(): string {
+  return resolveDistDir("shell");
+}
+
+async function setupRegistryBackend(): Promise<{
+  registryBackend: RegistryBackend | null;
+  serverOptions: McpAppServerOptions;
+}> {
+  const REGISTRY_PROVIDERS = process.env["REGISTRY_PROVIDERS"];
+
+  if (!REGISTRY_PROVIDERS) {
+    return { registryBackend: null, serverOptions: {} };
+  }
+
+  const command = process.env["REGISTRY_COMMAND"] ?? "npx";
+  const extraArgs = process.env["REGISTRY_ARGS"]?.split(" ").filter(Boolean) ?? [];
+  const args = ["@utdk/mcp", ...extraArgs];
+
+  log("mcp-app-server", `Connecting to Registry MCP server (providers: ${REGISTRY_PROVIDERS})...`);
+
+  try {
+    const registryBackend = await createRegistryBackend({
+      command,
+      args,
+      providers: REGISTRY_PROVIDERS,
+    });
+
+    const toolInfos = registryBackend.getToolInfos();
+    const namespaces = [...new Set(toolInfos.map((t) => t.namespace))];
+    log(
+      "mcp-app-server",
+      `Registry ready: ${toolInfos.length} tools across namespaces: ${namespaces.join(", ")}`
+    );
+
+    return {
+      registryBackend,
+      serverOptions: {
+        services: {
+          backend: registryBackend,
+          tools: toolInfos,
+        },
+      },
+    };
+  } catch (err) {
+    error("mcp-app-server", "Failed to connect to Registry MCP server:", err);
+    error("mcp-app-server", "Starting without Registry service backend.");
+    return { registryBackend: null, serverOptions: {} };
+  }
+}
+
+function handleExistingSession(existing: SessionEntry, req: Request, res: Response): void {
+  try {
+    existing.transport.handleRequest(req, res, req.body);
+  } catch (err) {
+    error("mcp", "session request error", err);
+    if (!res.headersSent) {
+      res.status(500).json({ error: "Internal server error" });
+    }
+  }
+}
+
+async function createNewSession(
+  serverOptions: McpAppServerOptions,
+  sessionStore: Map<string, SessionEntry>,
+  req: Request,
+  res: Response
+): Promise<void> {
+  const mcpServer = createMcpAppServer(serverOptions);
+  const transport = new StreamableHTTPServerTransport({
+    sessionIdGenerator: () => randomUUID(),
+    onsessioninitialized: (id) => {
+      sessionStore.set(id, { server: mcpServer, transport });
+      registerSession(id, mcpServer);
+    },
+    onsessionclosed: (id) => {
+      sessionStore.delete(id);
+      unregisterSession(id);
+    },
+  });
+
+  res.on("close", () => {
+    const id = transport.sessionId;
+    if (id && !sessionStore.has(id)) {
+      void mcpServer.close();
+    }
+  });
+
+  try {
+    await mcpServer.connect(transport);
+    await transport.handleRequest(req, res, req.body);
+  } catch (err) {
+    error("mcp", "new session error", err);
+    if (!res.headersSent) {
+      res.status(500).json({ error: "Internal server error" });
+    }
+  }
+}
+
+function registerMcpEndpoint(
+  app: ReturnType<typeof createMcpExpressApp>,
+  serverOptions: McpAppServerOptions
+): Map<string, SessionEntry> {
+  const sessionStore = new Map<string, SessionEntry>();
+
+  app.all("/mcp", async (req, res) => {
+    const sessionId = req.headers["mcp-session-id"] as string | undefined;
+
+    if (sessionId) {
+      const existing = sessionStore.get(sessionId);
+      if (existing) {
+        handleExistingSession(existing, req, res);
+        return;
+      }
+    }
+
+    await createNewSession(serverOptions, sessionStore, req, res);
+  });
+
+  return sessionStore;
+}
+
+function registerShutdownHandlers(registryBackend: RegistryBackend | null): void {
+  const shutdown = () => {
+    if (registryBackend) {
+      registryBackend.close().catch(() => {
+        /* ignore close errors on exit */
+      });
+    }
+    process.exit(0);
+  };
+  process.on("SIGTERM", shutdown);
+  process.on("SIGINT", shutdown);
+}
+
+async function startServer(): Promise<void> {
+  const { registryBackend, serverOptions } = await setupRegistryBackend();
+
+  const app = createMcpExpressApp({ host: HOST });
+  app.use(cors());
+
+  registerMcpEndpoint(app, serverOptions);
+
+  app.get("/health", (_req, res) => {
+    res.json({ status: "ok", service: "patchwork-mcp-app-server" });
+  });
+
+  app.listen(PORT, HOST, () => {
+    log("mcp-app-server", `MCP App Server listening on http://${HOST}:${PORT}`);
+    log("mcp-app-server", `  POST /mcp    — MCP Streamable HTTP endpoint (stateful sessions)`);
+    log("mcp-app-server", `  GET  /health — health check`);
+    log("mcp-app-server", "");
+    log("mcp-app-server", "To expose locally via cloudflared:");
+    log("mcp-app-server", `  cloudflared tunnel --url http://localhost:${PORT}`);
+  });
+
+  registerShutdownHandlers(registryBackend);
+}
+
+async function startWidgetServer(): Promise<string> {
+  const widgetApp = express();
+  widgetApp.use(cors());
+
+  const store = getWidgetStore();
+
+  // Serve the MCP App shell (resource document's external script) and the shared
+  // browser runtime bundle (compiles widgets in-browser). Both resolve to dist
+  // whether running built (dist/server.js) or via tsx (src).
+  widgetApp.use("/shell", express.static(resolveShellDir()));
+  widgetApp.use("/runtime", express.static(resolveRuntimeDir()));
+
+  // Raw widget source files — fetched by the runtime and compiled in-browser.
+  widgetApp.get("/widget/:name/:hash/files", async (req, res) => {
+    const { name, hash } = req.params;
+    try {
+      const widget = await store.getWidget(name, hash);
+      if (!widget) {
+        res.status(404).json({ error: "Widget not found" });
+        return;
+      }
+      res.json({ files: widget.files, entry: widget.entry, manifest: widget.manifest });
+    } catch (err) {
+      error("widget-server", "Error serving widget files:", err);
+      res.status(500).json({ error: "Internal server error" });
+    }
+  });
+
+  // Convenience redirect: /widget/:name/:hash → runtime host with the widget preselected.
+  widgetApp.get("/widget/:name/:hash", (req, res) => {
+    const { name, hash } = req.params;
+    res.redirect(
+      302,
+      `/runtime/?widget=${encodeURIComponent(name)}/${encodeURIComponent(hash)}`,
+    );
+  });
+
+  widgetApp.get("/health", (_req, res) => {
+    res.json({ status: "ok", service: "patchwork-widget-server" });
+  });
+
+  // Elect the widget-host owner via the port bind. A failed bind (EADDRINUSE)
+  // means another instance already owns the widget server + tunnel.
+  const isOwner = await new Promise<boolean>((resolve) => {
+    const httpServer = widgetApp.listen(WIDGET_PORT, HOST, () => {
+      log("mcp-app-server", `Widget server listening on http://${HOST}:${WIDGET_PORT}`);
+      resolve(true);
+    });
+    httpServer.on("error", (err: NodeJS.ErrnoException) => {
+      if (err.code === "EADDRINUSE") {
+        log(
+          "mcp-app-server",
+          `Widget port ${WIDGET_PORT} already owned by another instance; reusing its widget host.`,
+        );
+      } else {
+        error("mcp-app-server", "Widget server failed to bind:", err);
+      }
+      resolve(false);
+    });
+  });
+
+  if (!isOwner) {
+    // Reuse the owner's verified, published base URL so every instance hands out
+    // the same live hostname instead of orphaning another (possibly dead) tunnel.
+    const shared = await awaitPublishedWidgetBaseUrl();
+    if (shared) {
+      log("mcp-app-server", `Reusing shared widget host: ${shared}`);
+      return shared;
+    }
+    error(
+      "mcp-app-server",
+      "Owner instance never published a base URL; falling back to localhost (widgets may not load in remote hosts).",
+    );
+    return `http://localhost:${WIDGET_PORT}`;
+  }
+
+  // We own the widget server. Establish (and verify) the tunnel, then publish
+  // the base URL for sibling instances.
+  let widgetBaseUrl = `http://localhost:${WIDGET_PORT}`;
+
+  if (WIDGET_TUNNEL) {
+    try {
+      widgetBaseUrl = await startTunnel(WIDGET_PORT);
+      log("mcp-app-server", `Widgets accessible at: ${widgetBaseUrl}`);
+    } catch (err) {
+      error("mcp-app-server", "Failed to start tunnel, using localhost:", err);
+    }
+  }
+
+  publishWidgetHostState(widgetBaseUrl);
+  return widgetBaseUrl;
+}
+
+async function startStdioServer(): Promise<void> {
+  const { registryBackend, serverOptions } = await setupRegistryBackend();
+
+  log("mcp-app-server", "Starting MCP App Server in stdio mode...");
+
+  // Start widget server and optionally tunnel
+  const widgetBaseUrl = await startWidgetServer();
+
+  // Create MCP server with widget base URL
+  const mcpServer = createMcpAppServer({
+    ...serverOptions,
+    widgetBaseUrl,
+  });
+  const transport = new StdioServerTransport();
+
+  await mcpServer.connect(transport);
+
+  const shutdown = () => {
+    stopTunnel();
+    if (registryBackend) {
+      registryBackend.close().catch(() => {});
+    }
+    process.exit(0);
+  };
+  process.on("SIGTERM", shutdown);
+  process.on("SIGINT", shutdown);
+}
+
+async function main(): Promise<void> {
+  if (TRANSPORT === "stdio") {
+    await startStdioServer();
+  } else {
+    await startServer();
+  }
+}
+
+main().catch((err: unknown) => {
+  error("mcp-app-server", "Fatal startup error:", err);
+  process.exit(1);
+});