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

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,306 @@
+/**
+ * Registry MCP backend for the Patchwork MCP App Server.
+ *
+ * Spawns (or connects to) the Aprovan Registry MCP server via stdio and bridges
+ * its tools into the Patchwork ServiceBridge. Widgets can then call any Registry-
+ * backed service (e.g. `github.repos_list()`, `stripe.charges_list()`) via the
+ * standard Patchwork service proxy shim.
+ *
+ * Usage (in server.ts or programmatically):
+ *
+ *   const backend = await createRegistryBackend({
+ *     command: "npx",
+ *     args: ["@utdk/mcp"],
+ *     providers: "github,slack,stripe",
+ *   });
+ *
+ *   const bridge = new ServiceBridge({
+ *     backend,
+ *     tools: backend.getToolInfos(),
+ *   });
+ */
+
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
+import { log, warn } from "./logger.js";
+import type { ServiceBackend, ServiceToolInfo } from "./services.js";
+
+// ---------------------------------------------------------------------------
+// Minimal type alias for MCP callTool responses
+// ---------------------------------------------------------------------------
+
+/** Subset of the MCP CallToolResult used in this module. */
+interface McpToolResult {
+  isError?: boolean;
+  content: Array<{ type: string; text?: string; [k: string]: unknown }>;
+}
+
+// ---------------------------------------------------------------------------
+// Public types
+// ---------------------------------------------------------------------------
+
+export interface RegistryBackendOptions {
+  /** Executable to start the Registry MCP server (e.g. "npx" or an absolute path). */
+  command: string;
+  /** Arguments passed to the command (e.g. ["@utdk/mcp"]). */
+  args?: string[];
+  /**
+   * Additional environment variables for the Registry process.
+   * Merged on top of the current process.env, so provider credentials already
+   * present in the environment are forwarded automatically.
+   */
+  env?: Record<string, string>;
+  /**
+   * Comma-separated list of `@utdk` providers to load, e.g. "github,slack,stripe".
+   * Passed as UTDK_PROVIDERS to the Registry server.
+   */
+  providers: string;
+}
+
+export interface RegistryBackend extends ServiceBackend {
+  /** All service tool infos loaded from the Registry, ready for ServiceBridgeConfig. */
+  getToolInfos(): ServiceToolInfo[];
+  /** Close the underlying MCP client / Registry child process. */
+  close(): Promise<void>;
+}
+
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Split a Registry MCP tool name (e.g. "github__repos_list") into its
+ * namespace ("github") and procedure ("repos_list") parts.
+ *
+ * The Registry convention is:
+ *   <provider>__<operation>   (double underscore as separator)
+ *
+ * Everything before the first "__" is the namespace; the remainder is the
+ * procedure (which may itself contain single underscores).
+ */
+export function parseRegistryToolName(mcpName: string): {
+  namespace: string;
+  procedure: string;
+} {
+  const idx = mcpName.indexOf("__");
+  if (idx === -1) {
+    // No separator — treat the whole name as a single-part namespace
+    return { namespace: mcpName, procedure: "call" };
+  }
+  return {
+    namespace: mcpName.slice(0, idx),
+    procedure: mcpName.slice(idx + 2),
+  };
+}
+
+/**
+ * Fetch all tool metadata from the Registry via its `list_tools` / `tool_info`
+ * meta-tools and convert to the `ServiceToolInfo` shape expected by ServiceBridge.
+ */
+async function loadRegistryToolInfos(client: Client): Promise<ServiceToolInfo[]> {
+  // list_tools returns a flat JSON array of MCP tool names when no group_by is given.
+  const listResult = (await client.callTool({
+    name: "list_tools",
+    arguments: {},
+  })) as McpToolResult;
+
+  const listText = listResult.content
+    .filter((c): c is { type: "text"; text: string } => c.type === "text")
+    .map((c) => c.text)
+    .join("");
+
+  let toolNames: unknown;
+  try {
+    toolNames = JSON.parse(listText);
+  } catch {
+    warn("registry-backend", "Failed to parse tool list response from Registry");
+    return [];
+  }
+
+  if (!Array.isArray(toolNames)) {
+    warn("registry-backend", "Unexpected tool list format from Registry (expected array)");
+    return [];
+  }
+
+  const mcpNames = toolNames.filter((n): n is string => typeof n === "string");
+
+  // Fetch full schema for each tool in parallel, chunked to avoid flooding the process.
+  const CHUNK_SIZE = 20;
+  const toolInfos: ServiceToolInfo[] = [];
+
+  for (let i = 0; i < mcpNames.length; i += CHUNK_SIZE) {
+    const chunk = mcpNames.slice(i, i + CHUNK_SIZE);
+    const results = await Promise.all(
+      chunk.map(async (mcpName): Promise<ServiceToolInfo | null> => {
+        try {
+          const infoResult = (await client.callTool({
+            name: "tool_info",
+            arguments: { tool_name: mcpName },
+          })) as McpToolResult;
+
+          const infoText = infoResult.content
+            .filter((c): c is { type: "text"; text: string } => c.type === "text")
+            .map((c) => c.text)
+            .join("");
+
+          const raw = JSON.parse(infoText) as {
+            name?: string;
+            description?: string;
+            inputSchema?: Record<string, unknown>;
+          };
+
+          const { namespace, procedure } = parseRegistryToolName(mcpName);
+
+          return {
+            name: `${namespace}.${procedure}`,
+            namespace,
+            procedure,
+            description: raw.description ?? `Call ${namespace}.${procedure}`,
+            parameters: raw.inputSchema as Record<string, unknown> | undefined,
+          };
+        } catch (err) {
+          warn("registry-backend", `Failed to fetch tool info for '${mcpName}': ${err}`);
+          return null;
+        }
+      }),
+    );
+
+    for (const info of results) {
+      if (info !== null) {
+        toolInfos.push(info);
+      }
+    }
+  }
+
+  const providerCount = new Set(toolInfos.map((t) => t.namespace)).size;
+  log(
+    "registry-backend",
+    `Loaded ${toolInfos.length} tools from ${providerCount} provider(s)`,
+  );
+
+  return toolInfos;
+}
+
+// ---------------------------------------------------------------------------
+// Public factory
+// ---------------------------------------------------------------------------
+
+/**
+ * Create a `RegistryBackend` that routes widget service calls through the
+ * Aprovan Registry MCP server.
+ *
+ * The Registry server is spawned as a child process via stdio. All current
+ * `process.env` variables (including provider credentials such as `GITHUB_TOKEN`)
+ * are forwarded to the child process, with `UTDK_PROVIDERS` set to the given
+ * providers list. Additional overrides can be passed via `options.env`.
+ *
+ * @example
+ * ```ts
+ * const backend = await createRegistryBackend({
+ *   command: "npx",
+ *   args: ["@utdk/mcp"],
+ *   providers: "github,stripe",
+ * });
+ *
+ * const bridge = new ServiceBridge({
+ *   backend,
+ *   tools: backend.getToolInfos(),
+ * });
+ * ```
+ */
+export async function createRegistryBackend(
+  options: RegistryBackendOptions,
+): Promise<RegistryBackend> {
+  // Forward the current environment so provider API keys are available in the
+  // spawned process. UTDK_PROVIDERS is the only variable that must be set here.
+  const inheritedEnv: Record<string, string> = {};
+  for (const [k, v] of Object.entries(process.env)) {
+    if (v !== undefined) inheritedEnv[k] = v;
+  }
+
+  const env: Record<string, string> = {
+    ...inheritedEnv,
+    UTDK_PROVIDERS: options.providers,
+    ...options.env,
+  };
+
+  const transport = new StdioClientTransport({
+    command: options.command,
+    args: options.args ?? [],
+    env,
+    // Route Registry stderr to the parent so operators can see provider logs.
+    stderr: "inherit",
+  });
+
+  const client = new Client({
+    name: "patchwork-mcp-app-server",
+    version: "0.1.0",
+  });
+
+  await client.connect(transport);
+
+  // Pre-load all tool metadata so ServiceBridge can be constructed synchronously.
+  const toolInfos = await loadRegistryToolInfos(client);
+
+  const backend: RegistryBackend = {
+    /**
+     * Execute a Registry-backed service tool.
+     *
+     * The call is forwarded as a Registry `call_tool` meta-tool invocation:
+     *   namespace + "__" + procedure → Registry MCP tool name
+     *
+     * The first element of `args` is treated as the tool's argument object.
+     */
+    async call(
+      namespace: string,
+      procedure: string,
+      args: unknown[],
+    ): Promise<unknown> {
+      const toolName = `${namespace}__${procedure}`;
+      const toolArgs = (typeof args[0] === "object" && args[0] !== null ? args[0] : {}) as Record<
+        string,
+        unknown
+      >;
+
+      const result = (await client.callTool({
+        name: "call_tool",
+        arguments: {
+          tool_name: toolName,
+          arguments: toolArgs,
+        },
+      })) as McpToolResult;
+
+      if (result.isError) {
+        const message = result.content
+          .filter((c): c is { type: "text"; text: string } => c.type === "text")
+          .map((c) => c.text)
+          .join("\n");
+        throw new Error(message || `Registry call failed for '${toolName}'`);
+      }
+
+      // Return parsed JSON when the response looks like JSON, else return raw text.
+      const textContent = result.content.find(
+        (c): c is { type: "text"; text: string } => c.type === "text",
+      );
+      if (textContent) {
+        try {
+          return JSON.parse(textContent.text) as unknown;
+        } catch {
+          return textContent.text;
+        }
+      }
+
+      return result;
+    },
+
+    getToolInfos(): ServiceToolInfo[] {
+      return toolInfos;
+    },
+
+    async close(): Promise<void> {
+      await client.close();
+    },
+  };
+
+  return backend;
+}

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>