@zackbart/connecta 0.10.6 → 0.12.0

package/examples/worker/src/index.ts

@@ -3,8 +3,8 @@
  *
  * One MCP endpoint aggregating a downstream remote MCP and an HTTP API, guarded
  * by Clerk OAuth *and* a static bearer token, with OAuth/cache state in a KV
- * namespace. Add the optional Worker Loader binding in wrangler.jsonc for the
- * seven-tool code-first surface; without it this serves the nine classic tools.
+ * namespace. The required Worker Loader binding in wrangler.jsonc backs the
+ * seven-tool surface.
  *
  * Setup (this example has no package.json of its own — it self-references the
  * installed `@zackbart/connecta` package):
@@ -19,8 +19,7 @@
  *      and CLERK_PUBLISHABLE_KEY + PUBLIC_URL as plain vars in wrangler.jsonc.
  *   4. Enable Dynamic Client Registration in the Clerk dashboard
  *        (OAuth Applications -> DCR toggle) so Claude/Cursor can self-register.
- *   5. Optional paid code mode: add the documented `worker_loaders` binding to
- *      wrangler.jsonc. Binding presence enables execute_code automatically.
+ *   5. Use the Workers Paid plan required by the `worker_loaders` binding.
  *   6. `wrangler deploy` from this folder (examples/worker), where wrangler.jsonc
  *      lives. Point your MCP client at `<PUBLIC_URL>/mcp`.
  */
@@ -46,23 +45,16 @@ interface Env {
   PUBLIC_URL: string;
   /**
    * Worker Loader binding (wrangler.jsonc `worker_loaders`) powering
-   * execute_code and, with it, the code-first surface. Dynamic Workers require
-   * the Workers Paid plan; leave the binding absent for the nine classic
-   * meta-tools on either plan.
+   * execute_code. Dynamic Workers require the Workers Paid plan.
    */
-  LOADER?: WorkerLoader;
+  LOADER: WorkerLoader;
 }
 
 function build(env: Env) {
   return createConnecta({
     publicUrl: env.PUBLIC_URL,
     storage: cloudflareKvStorage(env.CONNECTA_KV),
-    // Binding-as-switch: adding worker_loaders in wrangler.jsonc enables code
-    // mode and the seven-tool code-first surface with it; leaving it absent
-    // keeps this deployment free-tier compatible on the classic surface.
-    ...(env.LOADER
-      ? { executor: new DynamicWorkerExecutor({ loader: env.LOADER }) }
-      : {}),
+    executor: new DynamicWorkerExecutor({ loader: env.LOADER }),
     auth: [
       // Multiple credentials may identify callers in one deployment. Every
       // admitted caller reaches this deployment's deliberate connector set.

package/examples/worker/wrangler.jsonc

@@ -16,11 +16,8 @@
   // Create with `wrangler kv namespace create CONNECTA_KV` and paste the id.
   "kv_namespaces": [
     { "binding": "CONNECTA_KV", "id": "replace-with-kv-namespace-id" }
-  ]
+  ],
 
-  // Optional paid code mode: add a comma above, then uncomment this binding.
-  // Its presence is the entire switch — src/index.ts detects env.LOADER and
-  // serves the seven-tool code-first surface. Leave it absent for a free-tier
-  // deployment with the nine classic meta-tools.
-  // "worker_loaders": [{ "binding": "LOADER" }]
+  // Required by execute_code; Dynamic Workers use the Workers Paid plan.
+  "worker_loaders": [{ "binding": "LOADER" }]
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zackbart/connecta",
-  "version": "0.10.6",
+  "version": "0.12.0",
   "type": "module",
   "sideEffects": false,
   "description": "One MCP to rule them all — a single MCP endpoint aggregating many downstream connectors behind a code-first surface of seven meta-tools.",

package/src/activity.ts

@@ -23,6 +23,11 @@ const MAX_ACTIVITY_ADDRESS_BYTES = MAX_ACTIVITY_NAME_BYTES * 2 + 1;
 export type ActivityCallSource =
   | "call_tool"
   | "call_destructive_tool"
+  // Read-only history. Nothing emits `batch_call` since issue #273 removed the
+  // tool, but activity storage is append-only: rows written by older
+  // deployments are still read back — the D1 example maps a stored row straight
+  // into this type — and an operator's timeline should not have to lie about
+  // where a call came from. Never widen this member back into a live source.
   | "batch_call"
   | "execute_code";
 

package/src/apps-shell.ts

@@ -0,0 +1,179 @@
+/**
+ * The one MCP Apps template connecta serves (`U5`, `U6`).
+ *
+ * A build-time string constant, not a file read at startup: the core is
+ * Web-API-only so it runs unchanged on Workers, and the same bytes have to
+ * serve everywhere. The shell is display-only — it renders whatever HTML a
+ * program handed `connecta.ui` inside a nested `srcdoc` frame and forwards no
+ * channel back from that frame to the host, so program-authored markup is
+ * inert beyond its own pixels.
+ *
+ * The address carries a version segment because hosts are permitted to
+ * prefetch and cache templates by URI: change these bytes, bump `v1`.
+ */
+
+/** The only `ui://` URI in the system. No program input reaches it. */
+export const PROGRAM_UI_RESOURCE_URI = "ui://connecta/program-ui/v1";
+
+/** The mimeType the Apps spec requires of an HTML template. */
+export const PROGRAM_UI_MIME_TYPE = "text/html;profile=mcp-app";
+
+/**
+ * The result `_meta` key carrying the payload (`U3`). A plain single-label
+ * prefix rather than the reverse-DNS form MCP's SHOULD prefers: connecta has
+ * no domain to reverse, and fabricating one to satisfy a SHOULD is a worse
+ * answer than the shape the key format's MUST already permits.
+ */
+export const PROGRAM_UI_META_KEY = "connecta/ui";
+
+/** The one extension identifier connecta advertises (`U11`). */
+export const MCP_APPS_EXTENSION = "io.modelcontextprotocol/ui";
+
+/**
+ * The shell document. Dependency-free and deliberately small: it speaks the
+ * Apps postMessage dialect (`ui/initialize`, `ui/notifications/initialized`,
+ * `ui/notifications/tool-result`, `ui/notifications/size-changed`,
+ * `ui/resource-teardown`), lifts `_meta["connecta/ui"].html` out of the
+ * delivered tool result, and puts it in a frame. It declares no CSP domains,
+ * so the host applies its restrictive default and the `srcdoc` frame inherits
+ * `default-src 'none'` — the payload gets scripts and local interactivity,
+ * and no network.
+ */
+export const PROGRAM_UI_SHELL_HTML = `<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>connecta program view</title>
+    <style>
+      html,
+      body {
+        margin: 0;
+        padding: 0;
+        background: transparent;
+      }
+      #program-view {
+        display: block;
+        width: 100%;
+        min-height: 480px;
+        border: 0;
+      }
+    </style>
+  </head>
+  <body>
+    <iframe
+      id="program-view"
+      title="Program-rendered view"
+      sandbox="allow-scripts"
+      srcdoc=""
+    ></iframe>
+    <script>
+      (function () {
+        "use strict";
+        // The host frame is the only peer this shell speaks to, in either
+        // direction. The payload frame below is sandboxed to scripts alone,
+        // with no same-origin escape, and is never handed a reply path:
+        // anything it posts fails the source check and is dropped. There is
+        // no bridge from program HTML to the host, by construction rather
+        // than by validation.
+        var host = window.parent;
+        var view = document.getElementById("program-view");
+        var initializeId = "connecta-ui-initialize";
+        var lastWidth = 0;
+        var lastHeight = 0;
+
+        function send(message) {
+          if (!host || host === window) return;
+          host.postMessage(message, "*");
+        }
+
+        function notify(method, params) {
+          send({ jsonrpc: "2.0", method: method, params: params });
+        }
+
+        // Program views are fixed-height by construction. The shell has no
+        // bridge to the payload frame — that is the security posture, not an
+        // omission — so it can never learn the payload's content height, and
+        // what it reports here is its own box: the min-height above, unless
+        // the host has given it more. Taller content scrolls inside the inner
+        // frame rather than growing the view. Raising the min-height is the
+        // only lever; a content-height signal would cost the isolation.
+        function reportSize() {
+          var width = Math.ceil(document.documentElement.clientWidth);
+          var height = Math.ceil(document.documentElement.scrollHeight);
+          if (width === lastWidth && height === lastHeight) return;
+          lastWidth = width;
+          lastHeight = height;
+          notify("ui/notifications/size-changed", {
+            width: width,
+            height: height
+          });
+        }
+
+        function payloadHtml(result) {
+          if (!result || typeof result !== "object") return null;
+          var meta = result._meta;
+          if (!meta || typeof meta !== "object") return null;
+          var payload = meta["connecta/ui"];
+          if (!payload || typeof payload !== "object") return null;
+          var html = payload.html;
+          return typeof html === "string" && html.length > 0 ? html : null;
+        }
+
+        function render(params) {
+          var html =
+            payloadHtml(params) ||
+            payloadHtml(params && params.result) ||
+            payloadHtml(params && params.toolResult);
+          if (html === null) return;
+          view.srcdoc = html;
+          reportSize();
+        }
+
+        window.addEventListener("message", function (event) {
+          if (event.source !== host) return;
+          var message = event.data;
+          if (!message || message.jsonrpc !== "2.0") return;
+          if (message.method === "ui/notifications/tool-result") {
+            render(message.params);
+            return;
+          }
+          if (message.method === "ui/resource-teardown") {
+            // A host->view request, not a notification: the host waits for
+            // this reply before it tears the view down. There is nothing to
+            // release, so answer immediately rather than make it time out.
+            if (message.id !== undefined && message.id !== null) {
+              send({ jsonrpc: "2.0", id: message.id, result: {} });
+            }
+            return;
+          }
+          // Only a completed handshake earns "initialized". A JSON-RPC error
+          // response carries the same id, and announcing initialization on one
+          // would assert a handshake that never happened.
+          if (message.id === initializeId && message.result !== undefined) {
+            notify("ui/notifications/initialized", {});
+          }
+        });
+
+        window.addEventListener("resize", reportSize);
+        view.addEventListener("load", reportSize);
+
+        // Every field here is required by the Apps initialize schema, and a
+        // conforming host rejects the request outright when one is missing —
+        // which would strand the shell before any tool result arrives.
+        send({
+          jsonrpc: "2.0",
+          id: initializeId,
+          method: "ui/initialize",
+          params: {
+            appInfo: { name: "connecta program view", version: "1" },
+            appCapabilities: {},
+            protocolVersion: "2026-01-26"
+          }
+        });
+        reportSize();
+      })();
+    </script>
+  </body>
+</html>
+`;

package/src/catalog-service.ts

@@ -48,23 +48,10 @@ const MAX_QUERY_ANALYSIS_TERM_LENGTH = 64;
 
 const encoder = new TextEncoder();
 
-/**
- * The tool a describe-path error should name when it tells a caller to retry.
- * This is the route the *caller* took, not the deployment's advertised surface:
- * a classic deployment with an executor serves `describe_tools` at top level
- * while every in-program describe still arrives through `connecta.describe`, so
- * one CatalogService cannot infer the answer from `surface` alone. Callers pass
- * the route they own.
- */
-export type DescribeRoute = "describe_tools" | "connecta.describe";
-
 /**
  * The discovery route a routing failure should send a caller back through. Same
- * rule as {@link DescribeRoute} — the route the *caller* took, not the
- * deployment's advertised surface — with one difference worth keeping the two
- * options separate for: `search_tools` exists on both advertised surfaces, so a
- * top-level handler never has to derive this one, while an in-program caller
- * still has to be told about `connecta.search` because it cannot call a tool.
+ * catalog logic serves both the top-level `search_tools` path and the
+ * in-program `connecta.search` path, so callers pass the route they own.
  */
 export type SearchRoute = "search_tools" | "connecta.search";
 
@@ -96,10 +83,7 @@ function discoverySearchLimit(value: unknown): number {
 }
 
 /** Normalize the single-address convenience form, then validate the bounded list. */
-function discoveryAddresses(
-  args: CatalogDescribeArgs,
-  describeRoute: DescribeRoute,
-): unknown[] {
+function discoveryAddresses(args: CatalogDescribeArgs): unknown[] {
   if (args.address !== undefined && args.addresses !== undefined) {
     throw new DiscoveryPolicyError(
       "invalid_args",
@@ -121,7 +105,7 @@ function discoveryAddresses(
   if (value.length > MAX_DESCRIBE_ADDRESSES) {
     throw new DiscoveryPolicyError(
       "invalid_args",
-      `addresses must contain at most ${MAX_DESCRIBE_ADDRESSES} entries. Split a larger list across ${describeRoute} calls.`,
+      `addresses must contain at most ${MAX_DESCRIBE_ADDRESSES} entries. Split a larger list across connecta.describe calls.`,
     );
   }
   return value;
@@ -327,7 +311,6 @@ export class CatalogService {
   readonly requestScope: object;
   private readonly probeTimeoutMs: number;
   private readonly concurrency: number;
-  private readonly describeRoute: DescribeRoute;
   private readonly searchRoute: SearchRoute;
   private readonly loaded = new Map<string, ToolDef[]>();
   private readonly loading = new Map<string, Promise<ToolDef[]>>();
@@ -339,8 +322,6 @@ export class CatalogService {
       requestScope?: object;
       probeTimeoutMs?: number;
       concurrency?: number;
-      /** The tool describe-path errors name. Default `describe_tools`. */
-      describeRoute?: DescribeRoute;
       /** The discovery route recovery records name. Default `search_tools`. */
       searchRoute?: SearchRoute;
     } = {},
@@ -349,7 +330,6 @@ export class CatalogService {
     this.probeTimeoutMs =
       normalizeTimeoutMs(options.probeTimeoutMs) ?? DEFAULT_PROBE_TIMEOUT_MS;
     this.concurrency = resolveDiscoveryConcurrency(options.concurrency);
-    this.describeRoute = options.describeRoute ?? "describe_tools";
     this.searchRoute = options.searchRoute ?? "search_tools";
   }
 
@@ -817,7 +797,7 @@ export class CatalogService {
   }
 
   async describe(args: CatalogDescribeArgs): Promise<CatalogDescription[]> {
-    const addresses = discoveryAddresses(args, this.describeRoute);
+    const addresses = discoveryAddresses(args);
     const format = args.format ?? "compact";
     const resolved = addresses.map((rawAddress) => {
       const address = String(rawAddress);
@@ -834,7 +814,7 @@ export class CatalogService {
       connectorIds,
       this.concurrency,
       (id) =>
-        this.loadForDiscovery(id, `${this.describeRoute} probe of "${id}"`),
+        this.loadForDiscovery(id, `connecta.describe probe of "${id}"`),
     );
     const catalogs = new Map<string, ToolDef[] | Error>();
     loaded.forEach((result, index) => {

package/src/connectors/api.ts

@@ -20,7 +20,7 @@ export interface ApiTool {
   outputSchema?: JsonSchema;
   /**
    * Standard MCP-style behavior hints. Only an explicit readOnlyHint: true
-   * admits the tool to call_tool, batch_call, and execute_code.
+   * admits the tool to call_tool and execute_code.
    */
   annotations?: ToolAnnotations;
   handler: (args: any, ctx: ConnectorContext) => Promise<unknown> | unknown;
@@ -32,7 +32,7 @@ export interface ApiOptions {
   description?: string;
   /**
    * Max inline result size (bytes) for this connector's tools before
-   * call_tool/batch_call truncate and stash the full text for get_result
+   * call_tool truncates and stashes the full text for get_result
    * paging. Overrides the deployment's `calls.maxResultBytes`; omit to inherit
    * it. Must be a whole number of bytes >= 1; anything else warns at startup
    * and is ignored.

package/src/connectors/remote-mcp.ts

@@ -38,7 +38,7 @@ export interface RemoteMcpOptions {
   description?: string;
   /**
    * Max inline result size (bytes) for this connector's tools before
-   * call_tool/batch_call truncate and stash the full text for get_result
+   * call_tool truncates and stashes the full text for get_result
    * paging. Overrides the deployment's `calls.maxResultBytes`; omit to inherit
    * it. Must be a whole number of bytes >= 1; anything else warns at startup
    * and is ignored.

package/src/errors.ts

@@ -221,7 +221,7 @@ export class ConnectorCallError extends Error {
   }
 }
 
-/** The `error` object surfaced in call_tool/batch_call value-mode results. */
+/** The `error` object surfaced in value-mode call results and connecta.batch entries. */
 export interface CallErrorDetails {
   code: string;
   message: string;
@@ -322,7 +322,7 @@ const RETRYABLE_MESSAGE_RE =
 const TIMEOUT_MESSAGE_RE = /timed out|timeout/i;
 
 /** Message-text fallback used when an error carries no typed classification. */
-export function messageLooksRetryable(message: string): boolean {
+function messageLooksRetryable(message: string): boolean {
   return RETRYABLE_MESSAGE_RE.test(message);
 }