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

package/src/live-update.ts

@@ -0,0 +1,150 @@
+import { type McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { warn } from "./logger.js";
+
+/**
+ * A single buffered event for a data stream.
+ */
+export interface StreamEvent {
+  seq: number;
+  data: unknown;
+  timestamp: number;
+}
+
+const RING_BUFFER_MAX = 100;
+
+/**
+ * Process-level ring buffer for each named stream.
+ * Shared across all sessions so any request can read from it.
+ */
+const streamBuffers = new Map<string, StreamEvent[]>();
+let globalSeq = 0;
+
+function getOrCreateBuffer(stream: string): StreamEvent[] {
+  let buf = streamBuffers.get(stream);
+  if (!buf) {
+    buf = [];
+    streamBuffers.set(stream, buf);
+  }
+  return buf;
+}
+
+/**
+ * Retrieve buffered events for a stream with sequence numbers > afterSeq.
+ */
+export function getEvents(stream: string, afterSeq: number): StreamEvent[] {
+  const buf = streamBuffers.get(stream);
+  if (!buf) return [];
+  return buf.filter((e) => e.seq > afterSeq);
+}
+
+/**
+ * Write an event into the ring buffer for a stream.
+ * Evicts the oldest entry when the buffer is full.
+ */
+export function appendEvent(stream: string, data: unknown): StreamEvent {
+  const buf = getOrCreateBuffer(stream);
+  const event: StreamEvent = {
+    seq: ++globalSeq,
+    data,
+    timestamp: Date.now(),
+  };
+  buf.push(event);
+  if (buf.length > RING_BUFFER_MAX) {
+    buf.shift();
+  }
+  return event;
+}
+
+/**
+ * Per-session subscription tracking.
+ * A session is keyed by the MCP session ID; its McpServer is used to send
+ * `notifications/tools/list_changed` as a push signal when stream events arrive.
+ */
+interface SessionEntry {
+  server: McpServer;
+  streams: Set<string>;
+}
+
+const sessions = new Map<string, SessionEntry>();
+
+/**
+ * Register a live MCP session so it can receive push notifications.
+ */
+export function registerSession(sessionId: string, server: McpServer): void {
+  if (!sessions.has(sessionId)) {
+    sessions.set(sessionId, { server, streams: new Set() });
+  }
+}
+
+/**
+ * Unregister a session (e.g. on transport close or DELETE).
+ */
+export function unregisterSession(sessionId: string): void {
+  sessions.delete(sessionId);
+}
+
+/**
+ * Subscribe a session to a named stream.
+ */
+export function subscribeSession(sessionId: string, stream: string): void {
+  const entry = sessions.get(sessionId);
+  if (entry) {
+    entry.streams.add(stream);
+  }
+}
+
+/**
+ * Unsubscribe a session from a named stream.
+ */
+export function unsubscribeSession(sessionId: string, stream: string): void {
+  const entry = sessions.get(sessionId);
+  if (entry) {
+    entry.streams.delete(stream);
+  }
+}
+
+/**
+ * Push a data update to all sessions that have subscribed to `stream`.
+ *
+ * The event is appended to the ring buffer. Each subscribed session's McpServer
+ * then sends a `notifications/tools/list_changed` notification to the host.
+ * The host forwards this to the widget, which uses it as a signal to call
+ * `poll_updates` and retrieve the buffered data.
+ *
+ * @returns The new sequence number assigned to this event.
+ */
+export async function pushStreamUpdate(
+  stream: string,
+  data: unknown,
+): Promise<number> {
+  const event = appendEvent(stream, data);
+
+  const pushPromises: Promise<void>[] = [];
+  for (const [, entry] of sessions) {
+    if (entry.streams.has(stream)) {
+      const notifyPromise = entry.server.server
+        .notification({ method: "notifications/tools/list_changed" })
+        .catch((err: unknown) => {
+          warn("live-update", "Failed to notify session:", err);
+        });
+      pushPromises.push(notifyPromise);
+    }
+  }
+
+  await Promise.all(pushPromises);
+  return event.seq;
+}
+
+/**
+ * Return the current highest sequence number (useful for initial subscribe).
+ */
+export function currentSeq(): number {
+  return globalSeq;
+}
+
+/** Clears all buffers and sessions — for testing only. */
+export function _resetForTests(): void {
+  streamBuffers.clear();
+  sessions.clear();
+  globalSeq = 0;
+}

package/src/logger.ts

@@ -0,0 +1,44 @@
+type LogLevel = 'debug' | 'info' | 'warn' | 'error';
+
+const CURRENT_LEVEL: LogLevel =
+  (process.env['LOG_LEVEL'] as LogLevel | undefined) ?? 'info';
+
+const LEVEL_RANK: Record<LogLevel, number> = {
+  debug: 0,
+  info: 1,
+  warn: 2,
+  error: 3,
+};
+
+function shouldLog(level: LogLevel): boolean {
+  return LEVEL_RANK[level] >= LEVEL_RANK[CURRENT_LEVEL];
+}
+
+function formatMessage(tag: string, ...args: unknown[]): unknown[] {
+  return [`[${tag}]`, ...args];
+}
+
+// All logging goes to stderr to avoid interfering with MCP stdio protocol on stdout
+export function debug(tag: string, ...args: unknown[]): void {
+  if (shouldLog('debug')) {
+    console.error(...formatMessage(tag, ...args));
+  }
+}
+
+export function log(tag: string, ...args: unknown[]): void {
+  if (shouldLog('info')) {
+    console.error(...formatMessage(tag, ...args));
+  }
+}
+
+export function warn(tag: string, ...args: unknown[]): void {
+  if (shouldLog('warn')) {
+    console.error(...formatMessage(tag, ...args));
+  }
+}
+
+export function error(tag: string, ...args: unknown[]): void {
+  if (shouldLog('error')) {
+    console.error(...formatMessage(tag, ...args));
+  }
+}

package/src/reference-widgets/live-dashboard.ts

@@ -0,0 +1,162 @@
+import type { VirtualFile } from "@aprovan/patchwork-compiler";
+
+const DASHBOARD_MAIN = `import { useState, useEffect } from 'react';
+import { PriceCard } from './price-card';
+import { StatusPanel } from './status-panel';
+import { ActionBar } from './action-bar';
+
+export default function LiveDashboard() {
+  const [prices, setPrices] = useState<Record<string, { price: number; change: number }>>({});
+  const [statuses, setStatuses] = useState<Record<string, string>>({});
+  const [lastUpdate, setLastUpdate] = useState<number>(Date.now());
+
+  useEffect(() => {
+    const unsub1 = window.patchwork.subscribe('price_feed', (data: any, seq: number) => {
+      setPrices(prev => ({ ...prev, ...data }));
+      setLastUpdate(Date.now());
+    });
+
+    const unsub2 = window.patchwork.subscribe('system_status', (data: any, seq: number) => {
+      setStatuses(prev => ({ ...prev, ...data }));
+      setLastUpdate(Date.now());
+    });
+
+    return () => { unsub1(); unsub2(); };
+  }, []);
+
+  const handleRefresh = () => {
+    window.patchwork.fireEvent('push_update', {
+      stream: 'price_feed',
+      data: { tick: true },
+    });
+  };
+
+  const handleContextUpdate = () => {
+    const summary = Object.entries(prices)
+      .map(([sym, p]) => \`\${sym}: $\${p.price.toFixed(2)} (\${p.change >= 0 ? '+' : ''}\${p.change.toFixed(2)}%)\`)
+      .join('; ');
+    window.patchwork.updateContext(\`Dashboard state: \${summary}\`);
+  };
+
+  const priceEntries = Object.entries(prices);
+  const statusEntries = Object.entries(statuses);
+
+  return (
+    <div className="p-6 max-w-2xl mx-auto bg-white rounded-xl shadow-lg space-y-6">
+      <div className="flex items-center justify-between border-b pb-3">
+        <h1 className="text-xl font-bold text-gray-900">Live Data Dashboard</h1>
+        <span className="text-xs text-gray-400">
+          Updated {new Date(lastUpdate).toLocaleTimeString()}
+        </span>
+      </div>
+
+      {priceEntries.length > 0 && (
+        <section>
+          <h2 className="text-sm font-semibold text-gray-600 uppercase tracking-wide mb-2">
+            Price Feed
+          </h2>
+          <div className="grid grid-cols-2 gap-3">
+            {priceEntries.map(([symbol, p]) => (
+              <PriceCard key={symbol} symbol={symbol} price={p.price} change={p.change} />
+            ))}
+          </div>
+        </section>
+      )}
+
+      {statusEntries.length > 0 && (
+        <section>
+          <h2 className="text-sm font-semibold text-gray-600 uppercase tracking-wide mb-2">
+            System Status
+          </h2>
+          <StatusPanel statuses={statuses} />
+        </section>
+      )}
+
+      <ActionBar onRefresh={handleRefresh} onContextUpdate={handleContextUpdate} />
+
+      {priceEntries.length === 0 && statusEntries.length === 0 && (
+        <div className="text-center py-8 text-gray-400">
+          <p>Waiting for live data...</p>
+          <p className="text-xs mt-1">Use push_update or subscribe to streams to see data here.</p>
+        </div>
+      )}
+    </div>
+  );
+}
+`;
+
+const PRICE_CARD = `export function PriceCard({ symbol, price, change }: { symbol: string; price: number; change: number }) {
+  const isPositive = change >= 0;
+  return (
+    <div className="p-3 rounded-lg border bg-gray-50">
+      <div className="text-xs font-medium text-gray-500 uppercase">{symbol}</div>
+      <div className="text-lg font-bold text-gray-900">\${price.toFixed(2)}</div>
+      <div className={\`text-sm font-medium \${isPositive ? 'text-green-600' : 'text-red-600'}\`}>
+        {isPositive ? '+' : ''}{change.toFixed(2)}%
+      </div>
+    </div>
+  );
+}
+`;
+
+const STATUS_PANEL = `export function StatusPanel({ statuses }: { statuses: Record<string, string> }) {
+  const colorMap: Record<string, string> = {
+    ok: 'bg-green-100 text-green-800',
+    healthy: 'bg-green-100 text-green-800',
+    warning: 'bg-yellow-100 text-yellow-800',
+    degraded: 'bg-yellow-100 text-yellow-800',
+    error: 'bg-red-100 text-red-800',
+    down: 'bg-red-100 text-red-800',
+  };
+
+  return (
+    <div className="space-y-2">
+      {Object.entries(statuses).map(([service, status]) => {
+        const color = colorMap[status.toLowerCase()] ?? 'bg-gray-100 text-gray-800';
+        return (
+          <div key={service} className="flex items-center justify-between p-2 rounded border bg-gray-50">
+            <span className="text-sm font-medium text-gray-700">{service}</span>
+            <span className={\`text-xs font-semibold px-2 py-0.5 rounded \${color}\`}>{status}</span>
+          </div>
+        );
+      })}
+    </div>
+  );
+}
+`;
+
+const ACTION_BAR = `export function ActionBar({ onRefresh, onContextUpdate }: { onRefresh: () => void; onContextUpdate: () => void }) {
+  return (
+    <div className="flex gap-3 pt-2">
+      <button
+        onClick={onRefresh}
+        className="px-4 py-2 text-sm font-medium text-white bg-blue-600 rounded-lg hover:bg-blue-700 transition-colors"
+      >
+        Refresh Data
+      </button>
+      <button
+        onClick={onContextUpdate}
+        className="px-4 py-2 text-sm font-medium text-blue-600 bg-blue-50 rounded-lg hover:bg-blue-100 transition-colors"
+      >
+        Send Context
+      </button>
+    </div>
+  );
+}
+`;
+
+export const REFERENCE_WIDGET_FILES: VirtualFile[] = [
+  { path: "main.tsx", content: DASHBOARD_MAIN },
+  { path: "price-card.tsx", content: PRICE_CARD },
+  { path: "status-panel.tsx", content: STATUS_PANEL },
+  { path: "action-bar.tsx", content: ACTION_BAR },
+];
+
+export const REFERENCE_WIDGET_MANIFEST = {
+  name: "live-dashboard",
+  version: "0.1.0",
+  platform: "browser" as const,
+  image: "@aprovan/patchwork-image-shadcn",
+  description: "Live data dashboard with price feed, system status, and context feedback",
+  services: ["weather"],
+};

package/src/registry-backend.ts

@@ -0,0 +1,47 @@
+import {
+  PatchworkMcpClient,
+  type McpServerConfig,
+  type PatchworkTool,
+} from "@aprovan/patchwork";
+import type { ServiceBackend, ServiceToolInfo } from "./services.js";
+
+export type RegistryBackendOptions = Omit<McpServerConfig, "mode">;
+
+export interface RegistryBackend extends ServiceBackend {
+  getToolInfos(): ServiceToolInfo[];
+  readArtifact(uri: string): Promise<unknown>;
+  close(): Promise<void>;
+}
+
+function splitTool(tool: PatchworkTool): ServiceToolInfo {
+  const separator = tool.name.indexOf(".");
+  return {
+    name: tool.name,
+    namespace: separator < 0 ? tool.name : tool.name.slice(0, separator),
+    procedure: separator < 0 ? tool.name : tool.name.slice(separator + 1),
+    description: tool.description,
+    parameters:
+      tool.inputSchema && typeof tool.inputSchema === "object"
+        ? (tool.inputSchema as Record<string, unknown>)
+        : undefined,
+  };
+}
+
+export async function createRegistryBackend(
+  options: RegistryBackendOptions,
+): Promise<RegistryBackend> {
+  const client = new PatchworkMcpClient({ ...options, mode: "toolbox" });
+  await client.connect();
+  const tools = (await client.listTools()).map(splitTool);
+  return {
+    call(namespace, procedure, args) {
+      return client.callTool(
+        `${namespace}.${procedure}`,
+        (args[0] as Record<string, unknown> | undefined) ?? {},
+      );
+    },
+    getToolInfos: () => tools,
+    readArtifact: (uri) => client.readResource(uri),
+    close: () => client.close(),
+  };
+}

package/src/runtime/index.html

@@ -0,0 +1,38 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>Patchwork Widget Runtime</title>
+    <style>
+      * {
+        margin: 0;
+        padding: 0;
+        box-sizing: border-box;
+      }
+      html,
+      body {
+        width: 100%;
+        min-height: 100%;
+        font-family: system-ui, -apple-system, sans-serif;
+      }
+      #root {
+        width: 100%;
+      }
+      #pw-status {
+        padding: 12px 16px;
+        font-size: 13px;
+        color: #6b7280;
+      }
+      #pw-status[data-error] {
+        color: #dc2626;
+        white-space: pre-wrap;
+      }
+    </style>
+  </head>
+  <body>
+    <div id="pw-status">Loading runtime…</div>
+    <div id="root"></div>
+    <script type="module" src="./main.ts"></script>
+  </body>
+</html>

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 {
+  REFERENCE_WIDGET_FILES,
+  REFERENCE_WIDGET_MANIFEST,
+} from "../reference-widgets/live-dashboard.js";
+import type { Manifest, VirtualFile } from "@aprovan/patchwork-compiler";
+
+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);
+});