@aprovan/patchwork-mcp 0.1.0-dev.030eb3d

package/src/shell/main.ts

@@ -0,0 +1,172 @@
+/**
+ * Patchwork MCP App "shell".
+ *
+ * This is the document Claude loads as the MCP App resource. Per the MCP Apps
+ * protocol the resource document itself must be the app that connects to the
+ * host (`App.connect()` → `window.parent`); it runs under a strict CSP with no
+ * `unsafe-eval`, so it cannot run the esbuild-wasm compiler.
+ *
+ * So the shell stays light: it runs the ext-apps {@link App} (handshake + sizing
+ * + host bridge) and embeds the Patchwork runtime in a nested, CSP-free iframe
+ * served from the widget host. The runtime compiles the widget in the browser
+ * and mounts it; the widget's `window.patchwork.*` / service-namespace calls are
+ * forwarded up here over postMessage and relayed to the host:
+ *
+ *   widget (runtime iframe) ──postMessage──▶ shell (App) ──ext-apps──▶ host
+ */
+import { App } from "@modelcontextprotocol/ext-apps";
+
+interface ShellConfig {
+  /** Base URL of the runtime host page, e.g. https://host/runtime/ */
+  runtime: string;
+  /** "<name>/<hash>" of the saved widget to render. */
+  widget: string;
+  /** Startup props passed to the widget. */
+  inputs: Record<string, unknown>;
+}
+
+// Minimal MCP tool-result shape (avoids depending on SDK types in the bundle).
+interface ToolResult {
+  isError?: boolean;
+  content?: Array<{ type: string; text?: string }>;
+}
+
+function readConfig(): ShellConfig {
+  const el = document.currentScript as HTMLScriptElement | null;
+  const raw = el?.dataset["config"] ?? "";
+  try {
+    const json = decodeURIComponent(escape(atob(raw)));
+    return JSON.parse(json) as ShellConfig;
+  } catch {
+    return { runtime: "", widget: "", inputs: {} };
+  }
+}
+
+function parseResult(result: ToolResult): unknown {
+  const textBlock = result?.content?.find((c) => c.type === "text");
+  if (textBlock?.text !== undefined) {
+    try {
+      return JSON.parse(textBlock.text);
+    } catch {
+      return textBlock.text;
+    }
+  }
+  return result;
+}
+
+function boot(): void {
+  const config = readConfig();
+
+  const app = new App({ name: "patchwork-widget", version: "0.1.0" });
+
+  // Nested, CSP-free runtime iframe (compiles + mounts the widget in-browser).
+  const iframe = document.createElement("iframe");
+  iframe.style.cssText = "width:100%;border:none;display:block;";
+  iframe.setAttribute("sandbox", "allow-scripts allow-same-origin");
+  const query = new URLSearchParams({
+    widget: config.widget,
+    inputs: JSON.stringify(config.inputs ?? {}),
+  });
+  iframe.src = `${config.runtime}?${query.toString()}`;
+  (document.getElementById("pw-root") ?? document.body).appendChild(iframe);
+
+  const post = (msg: Record<string, unknown>): void => {
+    iframe.contentWindow?.postMessage({ source: "patchwork-host", ...msg }, "*");
+  };
+
+  // Per-stream cursor for live updates.
+  const streams = new Map<string, number>();
+
+  const pollStream = async (stream: string): Promise<void> => {
+    const afterSeq = streams.get(stream) ?? 0;
+    try {
+      const res = (await app.callServerTool({
+        name: "poll_updates",
+        arguments: { stream, after_seq: afterSeq },
+      })) as ToolResult;
+      const parsed = parseResult(res) as { events?: Array<{ seq: number; data: unknown }> };
+      if (!parsed?.events?.length) return;
+      for (const ev of parsed.events) {
+        if (ev.seq > (streams.get(stream) ?? 0)) streams.set(stream, ev.seq);
+        post({ kind: "stream-event", stream, data: ev.data, seq: ev.seq });
+      }
+    } catch (err) {
+      console.warn("[patchwork-shell] poll_updates failed:", err);
+    }
+  };
+
+  const callTool = async (id: string, name: string, args: unknown): Promise<void> => {
+    try {
+      const res = (await app.callServerTool({
+        name,
+        arguments: (args as Record<string, unknown>) ?? {},
+      })) as ToolResult;
+      if (res.isError) {
+        const text = res.content?.find((c) => c.type === "text")?.text;
+        post({ kind: "result", id, ok: false, error: text ?? `Tool call failed: ${name}` });
+      } else {
+        post({ kind: "result", id, ok: true, value: parseResult(res) });
+      }
+    } catch (err) {
+      post({ kind: "result", id, ok: false, error: err instanceof Error ? err.message : String(err) });
+    }
+  };
+
+  window.addEventListener("message", (event: MessageEvent) => {
+    if (event.source !== iframe.contentWindow) return;
+    const m = event.data as Record<string, unknown> | undefined;
+    if (!m || m["source"] !== "patchwork") return;
+
+    switch (m["kind"]) {
+      case "size": {
+        const h = m["height"];
+        if (typeof h === "number" && h > 0) iframe.style.height = `${h}px`;
+        break;
+      }
+      case "service":
+        void callTool(m["id"] as string, `${m["namespace"]}__${m["procedure"]}`, m["args"]);
+        break;
+      case "fire":
+        void callTool(m["id"] as string, m["toolName"] as string, m["args"]);
+        break;
+      case "subscribe": {
+        const stream = m["stream"] as string;
+        if (streams.has(stream)) break;
+        streams.set(stream, 0);
+        void app
+          .callServerTool({ name: "subscribe_stream", arguments: { stream } })
+          .then((res) => {
+            const parsed = parseResult(res as ToolResult) as { seq?: number };
+            if (typeof parsed?.seq === "number") streams.set(stream, parsed.seq);
+          })
+          .catch((err) => console.warn("[patchwork-shell] subscribe_stream failed:", err));
+        break;
+      }
+      case "context": {
+        const content = m["content"];
+        const params =
+          typeof content === "string"
+            ? { content: [{ type: "text", text: content }] }
+            : Array.isArray(content)
+              ? { content }
+              : { structuredContent: content as Record<string, unknown> };
+        void app.updateModelContext(params).catch(() => {});
+        break;
+      }
+    }
+  });
+
+  // When the server signals new data (notifications/tools/list_changed), poll
+  // every subscribed stream and forward fresh events down to the widget.
+  app.fallbackNotificationHandler = async (notification: { method: string }) => {
+    if (notification.method === "notifications/tools/list_changed") {
+      for (const stream of streams.keys()) await pollStream(stream);
+    }
+  };
+
+  app.connect().catch((err) => {
+    console.error("[patchwork-shell] failed to connect to host:", err);
+  });
+}
+
+boot();

package/src/shim.ts

@@ -0,0 +1,106 @@
+export interface BridgeShimOptions {
+  /** Service namespaces the widget calls (e.g. ["weather", "stripe"]). */
+  namespaces: string[];
+}
+
+/**
+ * Generate the runtime-side bridge shim.
+ *
+ * This runs inside the CSP-free runtime iframe (the nested frame that compiles
+ * and mounts the widget). It exposes `window.patchwork` and a proxy per service
+ * namespace, but instead of talking to the MCP host directly — the runtime
+ * iframe is one level removed from the host and can't — it forwards every call
+ * to the parent shell over `postMessage`. The shell holds the ext-apps `App`
+ * and relays to the host:
+ *
+ *   widget → window.patchwork.* / namespace.* → postMessage(parent) → shell → host
+ *
+ * Messages sent to the parent: `{ source: 'patchwork', kind, ... }`.
+ * Messages received from the parent: `{ source: 'patchwork-host', kind, ... }`.
+ */
+export function generateBridgeShim(options: BridgeShimOptions): string {
+  const namespacesJson = JSON.stringify(options.namespaces ?? []);
+
+  return `
+(function () {
+  if (window.patchwork) return; // guard against double-injection
+
+  var __pending = {};
+  var __seq = 0;
+  var __streams = {};
+
+  function __post(msg) {
+    msg.source = 'patchwork';
+    window.parent.postMessage(msg, '*');
+  }
+
+  function __request(payload) {
+    return new Promise(function (resolve, reject) {
+      var id = 'r' + (++__seq);
+      __pending[id] = { resolve: resolve, reject: reject };
+      payload.id = id;
+      __post(payload);
+    });
+  }
+
+  window.addEventListener('message', function (e) {
+    var m = e.data;
+    if (!m || m.source !== 'patchwork-host') return;
+    if (m.kind === 'result' && m.id && __pending[m.id]) {
+      var p = __pending[m.id];
+      delete __pending[m.id];
+      if (m.ok) p.resolve(m.value);
+      else p.reject(new Error(m.error || 'Service call failed'));
+    } else if (m.kind === 'stream-event') {
+      var cbs = __streams[m.stream];
+      if (cbs) {
+        for (var i = 0; i < cbs.length; i++) {
+          try { cbs[i](m.data, m.seq, m.stream); }
+          catch (err) { console.error('[patchwork] subscribe callback error:', err); }
+        }
+      }
+    }
+  });
+
+  window.patchwork = {
+    /** Subscribe to a named server data stream. Returns an unsubscribe fn. */
+    subscribe: function (stream, cb) {
+      if (!__streams[stream]) {
+        __streams[stream] = [];
+        __post({ kind: 'subscribe', stream: stream });
+      }
+      __streams[stream].push(cb);
+      return function () {
+        var a = __streams[stream];
+        if (!a) return;
+        var i = a.indexOf(cb);
+        if (i !== -1) a.splice(i, 1);
+      };
+    },
+    /** Push widget state into the conversation context. */
+    updateContext: function (content) {
+      __post({ kind: 'context', content: content });
+      return Promise.resolve();
+    },
+    /** Fire a client event as an MCP tool call and await its result. */
+    fireEvent: function (toolName, args) {
+      return __request({ kind: 'fire', toolName: toolName, args: args || {} });
+    }
+  };
+
+  var __namespaces = ${namespacesJson};
+  for (var __i = 0; __i < __namespaces.length; __i++) {
+    (function (ns) {
+      window[ns] = new Proxy({}, {
+        get: function (target, prop) {
+          if (typeof prop !== 'string') return undefined;
+          return function (args) {
+            return __request({ kind: 'service', namespace: ns, procedure: prop, args: args || {} });
+          };
+        }
+      });
+    })(__namespaces[__i]);
+  }
+})();
+`;
+}

package/src/tunnel.ts

@@ -0,0 +1,123 @@
+import { spawn, type ChildProcess } from "node:child_process";
+import { log, error } from "./logger.js";
+
+let tunnelProcess: ChildProcess | null = null;
+let tunnelUrl: string | null = null;
+
+/**
+ * Poll the tunnel's public `/health` endpoint until it returns 200.
+ *
+ * cloudflared prints the `*.trycloudflare.com` URL as soon as the process
+ * registers, but the edge route is frequently not live yet — requests in that
+ * window return Cloudflare error 1033 ("unable to resolve"). Publishing the URL
+ * before it's actually reachable bakes a dead host into rendered widgets, so we
+ * verify reachability before adopting it.
+ */
+async function waitForTunnelLive(url: string, timeoutMs = 30000): Promise<boolean> {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    try {
+      const res = await fetch(`${url}/health`, { signal: AbortSignal.timeout(5000) });
+      if (res.ok) return true;
+    } catch {
+      // not reachable yet — keep polling
+    }
+    await new Promise((r) => setTimeout(r, 1000));
+  }
+  return false;
+}
+
+/**
+ * Start a cloudflare tunnel to expose a local port publicly.
+ * Returns the public URL once the tunnel is established AND verified reachable.
+ */
+export async function startTunnel(port: number): Promise<string> {
+  if (tunnelUrl) return tunnelUrl;
+
+  const detectedUrl = await new Promise<string>((resolve, reject) => {
+    const args = ["tunnel", "--url", `http://localhost:${port}`];
+
+    log("tunnel", `Starting cloudflared tunnel for port ${port}...`);
+
+    tunnelProcess = spawn("cloudflared", args, {
+      stdio: ["ignore", "pipe", "pipe"],
+    });
+
+    let resolved = false;
+    const timeout = setTimeout(() => {
+      if (!resolved) {
+        resolved = true;
+        reject(new Error("Tunnel startup timed out after 30s"));
+      }
+    }, 30000);
+
+    const handleOutput = (data: Buffer) => {
+      const text = data.toString();
+
+      // Look for the tunnel URL in the output
+      // cloudflared outputs: "https://xxx.trycloudflare.com"
+      const urlMatch = text.match(/https:\/\/[^\s]+\.trycloudflare\.com\/?/);
+      if (urlMatch && !resolved) {
+        resolved = true;
+        clearTimeout(timeout);
+        resolve(urlMatch[0].replace(/\/$/, ""));
+      }
+    };
+
+    tunnelProcess.stdout?.on("data", handleOutput);
+    tunnelProcess.stderr?.on("data", handleOutput);
+
+    tunnelProcess.on("error", (err) => {
+      if (!resolved) {
+        resolved = true;
+        clearTimeout(timeout);
+        error("tunnel", "Failed to start cloudflared:", err);
+        reject(err);
+      }
+    });
+
+    tunnelProcess.on("exit", (code) => {
+      if (!resolved) {
+        resolved = true;
+        clearTimeout(timeout);
+        reject(new Error(`cloudflared exited with code ${code}`));
+      }
+      tunnelProcess = null;
+      tunnelUrl = null;
+    });
+  });
+
+  // Verify-then-publish: don't adopt the hostname until the edge route is live,
+  // otherwise rendered widgets reference a host that returns Cloudflare 1033.
+  log("tunnel", `Tunnel hostname detected (${detectedUrl}); verifying reachability...`);
+  const live = await waitForTunnelLive(detectedUrl);
+  if (!live) {
+    error(
+      "tunnel",
+      `Tunnel ${detectedUrl} did not become reachable within 30s — publishing anyway, but widgets may fail to load until the edge route propagates.`,
+    );
+  } else {
+    log("tunnel", `Tunnel verified reachable: ${detectedUrl}`);
+  }
+
+  tunnelUrl = detectedUrl;
+  return tunnelUrl;
+}
+
+/**
+ * Stop the cloudflare tunnel if running.
+ */
+export function stopTunnel(): void {
+  if (tunnelProcess) {
+    tunnelProcess.kill();
+    tunnelProcess = null;
+    tunnelUrl = null;
+  }
+}
+
+/**
+ * Get the current tunnel URL if available.
+ */
+export function getTunnelUrl(): string | null {
+  return tunnelUrl;
+}

package/src/widget-store/index.ts

@@ -0,0 +1,10 @@
+export { WidgetStore, getWidgetStore, resetWidgetStore } from "./store.js";
+export { LocalFileBackend } from "./local-backend.js";
+export type {
+  FSProvider,
+  FileStats,
+  DirEntry,
+  StoredWidget,
+  StoredWidgetInfo,
+  WidgetStoreOptions,
+} from "./types.js";

package/src/widget-store/local-backend.ts

@@ -0,0 +1,77 @@
+import { readFile, writeFile, unlink, stat, mkdir, readdir, rm, access } from "node:fs/promises";
+import { join, dirname, normalize } from "node:path";
+import type { DirEntry, FileStats, FSProvider } from "./types.js";
+
+function createDirEntry(name: string, isDir: boolean): DirEntry {
+  return {
+    name,
+    isFile: () => !isDir,
+    isDirectory: () => isDir,
+  };
+}
+
+function createFileStats(size: number, mtime: Date, isDir: boolean): FileStats {
+  return {
+    size,
+    mtime,
+    isFile: () => !isDir,
+    isDirectory: () => isDir,
+  };
+}
+
+export class LocalFileBackend implements FSProvider {
+  constructor(private basePath: string) {}
+
+  private resolve(path: string): string {
+    return join(this.basePath, normalize(path));
+  }
+
+  async readFile(path: string): Promise<string> {
+    return readFile(this.resolve(path), "utf-8");
+  }
+
+  async writeFile(path: string, content: string): Promise<void> {
+    const fullPath = this.resolve(path);
+    await mkdir(dirname(fullPath), { recursive: true });
+    await writeFile(fullPath, content, "utf-8");
+  }
+
+  async unlink(path: string): Promise<void> {
+    await unlink(this.resolve(path));
+  }
+
+  async stat(path: string): Promise<FileStats> {
+    const fullPath = this.resolve(path);
+    const s = await stat(fullPath);
+    return createFileStats(s.size, s.mtime, s.isDirectory());
+  }
+
+  async mkdir(path: string, options?: { recursive?: boolean }): Promise<void> {
+    await mkdir(this.resolve(path), options);
+  }
+
+  async readdir(path: string): Promise<DirEntry[]> {
+    const fullPath = this.resolve(path);
+    const entries = await readdir(fullPath, { withFileTypes: true });
+    return entries.map((e) =>
+      createDirEntry(e.name, e.isDirectory()),
+    );
+  }
+
+  async rmdir(path: string, options?: { recursive?: boolean }): Promise<void> {
+    if (options?.recursive) {
+      await rm(this.resolve(path), { recursive: true, force: true });
+    } else {
+      await rm(this.resolve(path), { force: true });
+    }
+  }
+
+  async exists(path: string): Promise<boolean> {
+    try {
+      await access(this.resolve(path));
+      return true;
+    } catch {
+      return false;
+    }
+  }
+}