@aprovan/mcp-app-server 0.1.0-dev.c1ac1dc

package/src/server.ts

@@ -0,0 +1,178 @@
+import { randomUUID } from 'node:crypto';
+import { createMcpExpressApp } from '@modelcontextprotocol/sdk/server/express.js';
+import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
+import cors from 'cors';
+import { registerSession, unregisterSession } from './live-update.js';
+import { createRegistryBackend, type RegistryBackend } from './registry-backend.js';
+import { createMcpAppServer, type McpAppServerOptions } from './index.js';
+
+const PORT = Number(process.env['PORT'] ?? 3000);
+const HOST = process.env['HOST'] ?? '0.0.0.0';
+
+async function startServer(): Promise<void> {
+  const serverOptions: McpAppServerOptions = {};
+
+  // ---------------------------------------------------------------------------
+  // Registry auto-configuration
+  //
+  // Set REGISTRY_PROVIDERS to a comma-separated list of @utdk providers
+  // (e.g. "github,slack,stripe") to automatically spawn the Registry MCP server
+  // and make all its tools available to widgets.
+  //
+  // The Registry process inherits all current environment variables, so provider
+  // credentials (GITHUB_TOKEN, STRIPE_SECRET_KEY, etc.) do not need to be
+  // duplicated — just set them once in this process's environment.
+  //
+  // Optional overrides:
+  //   REGISTRY_COMMAND   Executable to run (default: "npx")
+  //   REGISTRY_ARGS      Space-separated extra args appended after "@utdk/mcp-server"
+  // ---------------------------------------------------------------------------
+  const REGISTRY_PROVIDERS = process.env['REGISTRY_PROVIDERS'];
+
+  let registryBackend: RegistryBackend | null = null;
+
+  if (REGISTRY_PROVIDERS) {
+    const command = process.env['REGISTRY_COMMAND'] ?? 'npx';
+    const extraArgs = process.env['REGISTRY_ARGS']?.split(' ').filter(Boolean) ?? [];
+    const args = ['@utdk/mcp-server', ...extraArgs];
+
+    console.log(
+      `[mcp-app-server] Connecting to Registry MCP server (providers: ${REGISTRY_PROVIDERS})...`,
+    );
+
+    try {
+      registryBackend = await createRegistryBackend({
+        command,
+        args,
+        providers: REGISTRY_PROVIDERS,
+      });
+
+      const toolInfos = registryBackend.getToolInfos();
+      serverOptions.services = {
+        backend: registryBackend,
+        tools: toolInfos,
+      };
+
+      const namespaces = [...new Set(toolInfos.map((t) => t.namespace))];
+      console.log(
+        `[mcp-app-server] Registry ready: ${toolInfos.length} tools across namespaces: ${namespaces.join(', ')}`,
+      );
+    } catch (err) {
+      console.error('[mcp-app-server] Failed to connect to Registry MCP server:', err);
+      console.error('[mcp-app-server] Starting without Registry service backend.');
+    }
+  }
+
+  const app = createMcpExpressApp({ host: HOST });
+
+  // Allow cross-origin requests so Claude web (behind cloudflared) can reach the server
+  app.use(cors());
+
+  /**
+   * Session store for stateful MCP connections.
+   *
+   * Each MCP session gets its own McpServer + StreamableHTTPServerTransport pair.
+   * The session ID is minted on initialization and echoed in the Mcp-Session-Id
+   * response header so the host can route subsequent requests and the standalone
+   * GET SSE stream back to the correct server instance.
+   *
+   * Stateful sessions are required for server-initiated push: calling
+   * `mcpServer.server.notification(...)` on a live session delivers the
+   * message through the session's SSE stream to the host, which forwards it to
+   * the widget iframe.
+   */
+  const sessionStore = new Map<
+    string,
+    { server: ReturnType<typeof createMcpAppServer>; transport: StreamableHTTPServerTransport }
+  >();
+
+  /**
+   * MCP endpoint — stateful session mode.
+   *
+   * First request (no Mcp-Session-Id header): creates a new session.
+   * Subsequent requests carry the session ID and are routed to the existing
+   * server + transport pair.
+   */
+  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) {
+        try {
+          // eslint-disable-next-line @typescript-eslint/no-unsafe-argument
+          await existing.transport.handleRequest(req, res, req.body);
+        } catch (err) {
+          console.error('[mcp] session request error', err);
+          if (!res.headersSent) {
+            res.status(500).json({ error: 'Internal server error' });
+          }
+        }
+        return;
+      }
+      // Unknown session ID — fall through to create a fresh session.
+    }
+
+    // New session
+    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);
+      },
+    });
+
+    // Clean up when the response finishes (handles SSE streams that close early)
+    res.on('close', () => {
+      const id = transport.sessionId;
+      if (id && !sessionStore.has(id)) {
+        void mcpServer.close();
+      }
+    });
+
+    try {
+      await mcpServer.connect(transport);
+      // eslint-disable-next-line @typescript-eslint/no-unsafe-argument
+      await transport.handleRequest(req, res, req.body);
+    } catch (err) {
+      console.error('[mcp] new session error', err);
+      if (!res.headersSent) {
+        res.status(500).json({ error: 'Internal server error' });
+      }
+    }
+  });
+
+  /** Health-check endpoint — useful for cloudflared and load-balancer probes. */
+  app.get('/health', (_req, res) => {
+    res.json({ status: 'ok', service: 'patchwork-mcp-app-server' });
+  });
+
+  app.listen(PORT, HOST, () => {
+    console.log(`MCP App Server listening on http://${HOST}:${PORT}`);
+    console.log(`  POST /mcp    — MCP Streamable HTTP endpoint (stateful sessions)`);
+    console.log(`  GET  /health — health check`);
+    console.log();
+    console.log('To expose locally via cloudflared:');
+    console.log(`  cloudflared tunnel --url http://localhost:${PORT}`);
+  });
+
+  // Clean up the Registry child process on shutdown.
+  const shutdown = () => {
+    if (registryBackend) {
+      registryBackend.close().catch(() => {/* ignore close errors on exit */});
+    }
+    process.exit(0);
+  };
+  process.on('SIGTERM', shutdown);
+  process.on('SIGINT', shutdown);
+}
+
+startServer().catch((err: unknown) => {
+  console.error('[mcp-app-server] Fatal startup error:', err);
+  process.exit(1);
+});

package/src/services.ts

@@ -0,0 +1,251 @@
+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(),
+              }),
+            },
+          ],
+        };
+      },
+    );
+  }
+
+  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/shim.ts

@@ -0,0 +1,247 @@
+export interface ShimOptions {
+  namespaces: string[];
+  extAppsVersion?: string;
+}
+
+export interface LiveUpdateShimOptions {
+  /** @default "^1.7.3" */
+  extAppsVersion?: string;
+}
+
+const DEFAULT_EXT_APPS_VERSION = "^1.7.3";
+
+/**
+ * Generate the service-proxy shim that maps `namespace.procedure(args)` calls
+ * to `app.callServerTool({ name: "namespace__procedure", arguments: args })`.
+ *
+ * Returns an empty string when `namespaces` is empty (nothing to proxy).
+ */
+export function generateServiceShim(options: ShimOptions): string {
+  const {
+    namespaces,
+    extAppsVersion = DEFAULT_EXT_APPS_VERSION,
+  } = options;
+
+  if (namespaces.length === 0) return "";
+
+  const namespacesJson = JSON.stringify(namespaces);
+  const importUrl = `https://esm.sh/@modelcontextprotocol/ext-apps@${extAppsVersion}`;
+
+  return `
+import { App } from '${importUrl}';
+
+const __patchwork_app = new App({ name: 'patchwork-widget', version: '0.1.0' });
+const __patchwork_ready = __patchwork_app.connect().catch(function(err) {
+  console.error('[patchwork] Failed to connect to host:', err);
+});
+
+function __patchwork_createNamespaceProxy(namespace) {
+  return new Proxy({}, {
+    get: function(target, prop) {
+      if (typeof prop !== 'string') return undefined;
+      return function __patchwork_serviceCall(args) {
+        var toolName = namespace + '__' + prop;
+        return __patchwork_ready.then(function() {
+          return __patchwork_app.callServerTool({ name: toolName, arguments: args || {} });
+        }).then(function(result) {
+          if (result.isError) {
+            var errorMsg = result.content && result.content[0] && result.content[0].text
+              ? result.content[0].text
+              : 'Service call failed: ' + namespace + '.' + prop;
+            throw new Error(errorMsg);
+          }
+          var textContent = result.content && result.content.find(function(c) { return c.type === 'text'; });
+          if (textContent) {
+            try { return JSON.parse(textContent.text); }
+            catch (e) { return textContent.text; }
+          }
+          return result;
+        });
+      };
+    }
+  });
+}
+
+var __patchwork_namespaces = ${namespacesJson};
+for (var __i = 0; __i < __patchwork_namespaces.length; __i++) {
+  var __ns = __patchwork_namespaces[__i];
+  window[__ns] = __patchwork_createNamespaceProxy(__ns);
+}
+`;
+}
+
+/**
+ * Generate the live-update shim that wires up `window.patchwork`:
+ *
+ * - `patchwork.subscribe(stream, callback)` — subscribe to a named data
+ *   stream. Calls `subscribe_stream` on connect, then calls `callback(data)`
+ *   each time new events arrive via `poll_updates`.
+ * - `patchwork.updateContext(content)` — push widget state back to the model
+ *   via `app.updateModelContext()`.
+ * - `patchwork.fireEvent(toolName, args)` — convenience wrapper around
+ *   `app.callServerTool()` for user interaction events.
+ *
+ * The shim uses a single shared `App` instance (exposed as
+ * `window.__patchwork_app`) so it composes correctly with the service shim.
+ * If the service shim is also injected it must use the same variable name —
+ * both shims are concatenated in the compiler, and the first one to run
+ * initialises the App; the second one skips the initialisation guard.
+ */
+export function generateLiveUpdateShim(
+  options: LiveUpdateShimOptions = {},
+): string {
+  const { extAppsVersion = DEFAULT_EXT_APPS_VERSION } = options;
+  const importUrl = `https://esm.sh/@modelcontextprotocol/ext-apps@${extAppsVersion}`;
+
+  return `
+import { App } from '${importUrl}';
+
+// Shared App instance — the service shim may have already created this.
+if (!window.__patchwork_app) {
+  window.__patchwork_app = new App({ name: 'patchwork-widget', version: '0.1.0' });
+  window.__patchwork_ready = window.__patchwork_app.connect().catch(function(err) {
+    console.error('[patchwork] Failed to connect to host:', err);
+  });
+}
+
+(function() {
+  var __app = window.__patchwork_app;
+  var __ready = window.__patchwork_ready;
+
+  // Per-stream state: { seq, callbacks }
+  var __streams = {};
+  // MCP session ID captured after connect
+  var __sessionId = null;
+
+  function __parseResult(result) {
+    if (!result || !result.content) return result;
+    var textContent = result.content.find(function(c) { return c.type === 'text'; });
+    if (textContent) {
+      try { return JSON.parse(textContent.text); }
+      catch (e) { return textContent.text; }
+    }
+    return result;
+  }
+
+  function __pollStream(stream) {
+    var state = __streams[stream];
+    if (!state) return;
+    var afterSeq = state.seq;
+    __app.callServerTool({ name: 'poll_updates', arguments: { stream: stream, after_seq: afterSeq } })
+      .then(function(result) {
+        var parsed = __parseResult(result);
+        if (!parsed || !parsed.success || !parsed.events || !parsed.events.length) return;
+        var events = parsed.events;
+        for (var i = 0; i < events.length; i++) {
+          var ev = events[i];
+          if (ev.seq > state.seq) {
+            state.seq = ev.seq;
+          }
+          for (var j = 0; j < state.callbacks.length; j++) {
+            try { state.callbacks[j](ev.data, ev.seq, stream); }
+            catch (cbErr) { console.error('[patchwork] subscribe callback error:', cbErr); }
+          }
+        }
+      })
+      .catch(function(err) {
+        console.warn('[patchwork] poll_updates failed for stream ' + stream + ':', err);
+      });
+  }
+
+  // When tools/list_changed fires, poll all subscribed streams.
+  __app.setNotificationHandler(
+    { method: 'notifications/tools/list_changed', params: {} },
+    function() {
+      var streamNames = Object.keys(__streams);
+      for (var i = 0; i < streamNames.length; i++) {
+        __pollStream(streamNames[i]);
+      }
+      return Promise.resolve();
+    }
+  );
+
+  // Expose the public patchwork API on window.
+  window.patchwork = {
+    /**
+     * Subscribe to a named data stream.
+     *
+     * @param {string} stream - Stream name (e.g. "price_feed").
+     * @param {function} callback - Called with (data, seq, stream) for each event.
+     * @returns {function} Unsubscribe function.
+     */
+    subscribe: function(stream, callback) {
+      if (!__streams[stream]) {
+        __streams[stream] = { seq: 0, callbacks: [] };
+        // Tell the server about this subscription once the App is connected.
+        __ready.then(function() {
+          var args = { stream: stream };
+          if (__sessionId) args.session_id = __sessionId;
+          return __app.callServerTool({ name: 'subscribe_stream', arguments: args });
+        }).then(function(result) {
+          var parsed = __parseResult(result);
+          if (parsed && typeof parsed.seq === 'number') {
+            // Start polling from the server's current seq.
+            if (__streams[stream]) {
+              __streams[stream].seq = parsed.seq;
+            }
+          }
+        }).catch(function(err) {
+          console.warn('[patchwork] subscribe_stream failed:', err);
+        });
+      }
+      __streams[stream].callbacks.push(callback);
+      return function unsubscribe() {
+        if (!__streams[stream]) return;
+        var idx = __streams[stream].callbacks.indexOf(callback);
+        if (idx !== -1) __streams[stream].callbacks.splice(idx, 1);
+      };
+    },
+
+    /**
+     * Push the widget's current state into the conversation context.
+     * The model will include this in its next response.
+     *
+     * @param {string|Array} content - Text string or array of MCP ContentBlock objects.
+     */
+    updateContext: function(content) {
+      return __ready.then(function() {
+        var params;
+        if (typeof content === 'string') {
+          params = { content: [{ type: 'text', text: content }] };
+        } else if (Array.isArray(content)) {
+          params = { content: content };
+        } else if (content && typeof content === 'object') {
+          params = { structuredContent: content };
+        } else {
+          params = { content: [{ type: 'text', text: String(content) }] };
+        }
+        return __app.request({ method: 'ui/update-model-context', params: params }, {});
+      });
+    },
+
+    /**
+     * Fire a client event as an MCP tool call. Use this to surface user
+     * interactions so the LLM can observe and react to them.
+     *
+     * @param {string} toolName - MCP tool name on the server.
+     * @param {object} args - Tool arguments.
+     */
+    fireEvent: function(toolName, args) {
+      return __ready.then(function() {
+        return __app.callServerTool({ name: toolName, arguments: args || {} });
+      }).then(function(result) {
+        return __parseResult(result);
+      });
+    },
+  };
+
+  // Capture the session ID from the host context on connect.
+  __ready.then(function() {
+    // The host context is available via getHostContext(); we can't get the
+    // session ID directly, but it's passed in subscribe_stream args from
+    // user code. Expose a setter so widgets can supply it explicitly.
+    window.patchwork._setSessionId = function(id) { __sessionId = id; };
+  }).catch(function() {});
+})();
+`;
+}

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";