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

package/src/services.ts

@@ -0,0 +1,307 @@
+import { type McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+
+export interface ServiceBackend {
+  call(namespace: string, procedure: string, args: unknown[]): Promise<unknown>;
+}
+
+export interface ServiceToolInfo {
+  name: string;
+  namespace: string;
+  procedure: string;
+  description?: string;
+  parameters?: Record<string, unknown>;
+}
+
+export interface ServiceBridgeConfig {
+  backend: ServiceBackend;
+  tools: ServiceToolInfo[];
+}
+
+const TOOL_SEPARATOR = "__";
+
+function toMcpToolName(namespace: string, procedure: string): string {
+  return `${namespace}${TOOL_SEPARATOR}${procedure}`;
+}
+
+function jsonSchemaToZodShape(schema?: Record<string, unknown>): Record<string, z.ZodTypeAny> {
+  const properties = (schema?.["properties"] ?? {}) as Record<
+    string,
+    { type?: string; description?: string }
+  >;
+  const required = new Set((schema?.["required"] ?? []) as string[]);
+
+  const shape: Record<string, z.ZodTypeAny> = {};
+  for (const [key, prop] of Object.entries(properties)) {
+    let field: z.ZodTypeAny;
+    switch (prop.type) {
+      case "number":
+      case "integer":
+        field = z.number();
+        break;
+      case "boolean":
+        field = z.boolean();
+        break;
+      case "array":
+        field = z.array(z.unknown());
+        break;
+      case "object":
+        field = z.record(z.unknown());
+        break;
+      default:
+        field = z.string();
+        break;
+    }
+    if (prop.description) {
+      field = field.describe(prop.description);
+    }
+    if (!required.has(key)) {
+      field = field.optional();
+    }
+    shape[key] = field;
+  }
+
+  return shape;
+}
+
+export class ServiceBridge {
+  private backend: ServiceBackend;
+  private tools: Map<string, ServiceToolInfo> = new Map();
+
+  constructor(config: ServiceBridgeConfig) {
+    this.backend = config.backend;
+    for (const tool of config.tools) {
+      this.tools.set(tool.name, tool);
+    }
+  }
+
+  registerTools(server: McpServer): void {
+    for (const [, info] of this.tools) {
+      const mcpToolName = toMcpToolName(info.namespace, info.procedure);
+      const inputShape = jsonSchemaToZodShape(info.parameters);
+
+      server.registerTool(
+        mcpToolName,
+        {
+          description: info.description ?? `Call ${info.namespace}.${info.procedure}`,
+          inputSchema: inputShape,
+        },
+        async (args) => {
+          try {
+            const result = await this.backend.call(info.namespace, info.procedure, [args ?? {}]);
+            return {
+              content: [
+                {
+                  type: "text" as const,
+                  text: typeof result === "string" ? result : JSON.stringify(result),
+                },
+              ],
+            };
+          } catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            return {
+              content: [
+                {
+                  type: "text" as const,
+                  text: `Service call failed: ${message}`,
+                },
+              ],
+              isError: true,
+            };
+          }
+        }
+      );
+    }
+  }
+
+  registerSearchServices(server: McpServer): void {
+    server.registerTool(
+      "search_services",
+      {
+        description:
+          "Search for available service tools that widgets can call. " +
+          "Returns matching services with their namespaces, procedures, and parameter schemas.",
+        inputSchema: {
+          query: z
+            .string()
+            .optional()
+            .describe(
+              'Natural language description of what you want to do (e.g., "get weather forecast")'
+            ),
+          namespace: z
+            .string()
+            .optional()
+            .describe('Filter results to a specific service namespace (e.g., "weather")'),
+          tool_name: z
+            .string()
+            .optional()
+            .describe("Get detailed info about a specific tool by name"),
+          limit: z.number().optional().describe("Maximum number of results to return"),
+        },
+      },
+      async (args) => {
+        const query = args?.["query"] as string | undefined;
+        const namespace = args?.["namespace"] as string | undefined;
+        const toolName = args?.["tool_name"] as string | undefined;
+        const limit = (args?.["limit"] as number) ?? 10;
+
+        if (toolName) {
+          const dotName = toolName.replace(/__/g, ".");
+          const info = this.tools.get(toolName) ?? this.tools.get(dotName);
+          if (!info) {
+            return {
+              content: [
+                {
+                  type: "text" as const,
+                  text: JSON.stringify({
+                    success: false,
+                    error: `Tool '${toolName}' not found`,
+                  }),
+                },
+              ],
+            };
+          }
+          return {
+            content: [
+              {
+                type: "text" as const,
+                text: JSON.stringify({ success: true, tool: info }),
+              },
+            ],
+          };
+        }
+
+        let results = Array.from(this.tools.values());
+
+        if (namespace) {
+          results = results.filter((info) => info.namespace === namespace);
+        }
+
+        if (query) {
+          const queryLower = query.toLowerCase();
+          const keywords = queryLower.split(/\s+/).filter(Boolean);
+          results = results
+            .map((info) => {
+              const searchText =
+                `${info.name} ${info.namespace} ${info.procedure} ${info.description ?? ""}`.toLowerCase();
+              const matchCount = keywords.filter((kw) => searchText.includes(kw)).length;
+              return { info, score: matchCount / keywords.length };
+            })
+            .filter(({ score }) => score > 0)
+            .sort((a, b) => b.score - a.score)
+            .map(({ info }) => info);
+        }
+
+        results = results.slice(0, limit);
+
+        return {
+          content: [
+            {
+              type: "text" as const,
+              text: JSON.stringify({
+                success: true,
+                count: results.length,
+                tools: results,
+                namespaces: this.getNamespaces(),
+              }),
+            },
+          ],
+        };
+      }
+    );
+
+    // call_service: Execute any service by namespace/procedure
+    server.registerTool(
+      "call_service",
+      {
+        description:
+          "Call a service tool by namespace and procedure. Use search_services to discover available tools first.",
+        inputSchema: {
+          namespace: z.string().describe('Service namespace (e.g., "github", "stripe")'),
+          procedure: z.string().describe('Procedure name (e.g., "repos_list", "customers_create")'),
+          args: z.record(z.unknown()).optional().describe("Arguments to pass to the procedure"),
+        },
+      },
+      async (params) => {
+        const namespace = params?.["namespace"] as string;
+        const procedure = params?.["procedure"] as string;
+        const args = (params?.["args"] ?? {}) as Record<string, unknown>;
+
+        if (!namespace || !procedure) {
+          return {
+            content: [
+              {
+                type: "text" as const,
+                text: JSON.stringify({
+                  success: false,
+                  error: "namespace and procedure are required",
+                }),
+              },
+            ],
+            isError: true,
+          };
+        }
+
+        // Look up tool info for validation
+        const toolKey = `${namespace}.${procedure}`;
+        const info = this.tools.get(toolKey);
+        if (!info) {
+          return {
+            content: [
+              {
+                type: "text" as const,
+                text: JSON.stringify({
+                  success: false,
+                  error: `Tool '${namespace}.${procedure}' not found. Use search_services to discover available tools.`,
+                }),
+              },
+            ],
+            isError: true,
+          };
+        }
+
+        try {
+          const result = await this.backend.call(namespace, procedure, [args]);
+          return {
+            content: [
+              {
+                type: "text" as const,
+                text: typeof result === "string" ? result : JSON.stringify(result),
+              },
+            ],
+          };
+        } catch (error) {
+          const message = error instanceof Error ? error.message : String(error);
+          return {
+            content: [
+              {
+                type: "text" as const,
+                text: JSON.stringify({
+                  success: false,
+                  error: `Service call failed: ${message}`,
+                }),
+              },
+            ],
+            isError: true,
+          };
+        }
+      }
+    );
+  }
+
+  getNamespaces(): string[] {
+    const namespaces = new Set<string>();
+    for (const info of this.tools.values()) {
+      namespaces.add(info.namespace);
+    }
+    return Array.from(namespaces);
+  }
+
+  getToolInfos(): ServiceToolInfo[] {
+    return Array.from(this.tools.values());
+  }
+
+  has(namespace: string, procedure: string): boolean {
+    return this.tools.has(`${namespace}.${procedure}`);
+  }
+}

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;
+}