@zackbart/connecta 0.10.1 → 0.10.2

package/examples/worker/README.md

@@ -0,0 +1,160 @@
+# connecta — Cloudflare Worker example
+
+A deployable Worker that aggregates a downstream remote MCP and an in-code HTTP
+API connector, guarded by Clerk OAuth *and* a static bearer token, with state in
+a KV namespace. One Wrangler binding turns on paid code mode, which is also what
+selects the seven-tool code-first surface; the checked-in configuration deploys
+without it, serving the nine classic meta-tools on the Workers Free plan.
+
+This is also the **starting template for a deployment**: a real deployment
+should be its own repository that pins an exact `@zackbart/connecta` version and
+owns only its connector configuration, auth policy, domain, bindings,
+migrations, and secrets. See [deployment architecture](../../documentation/operations.md).
+
+## Files
+
+| File | What it is |
+| --- | --- |
+| `src/index.ts` | the Worker entrypoint — connector and auth configuration |
+| `src/cloudflare-kv.ts` | `KVStorage` over Workers KV (deployment-owned, not a package export) |
+| `src/d1-activity.ts` | `ActivityStore` over D1 (deployment-owned; see below) |
+| `wrangler.jsonc` | Worker name, vars, bindings, `compatibility_flags` |
+
+`cloudflare-kv.ts` and `d1-activity.ts` deliberately live here rather than in
+the package: storage backends are deployment-owned, so the package ships only
+the generic `KVStorage` and `ActivityStore` contracts. Workers KV is eventually
+consistent across locations; use a strongly consistent `KVStorage` adapter when
+OAuth disconnect, credential rotation, or access-token issuance/revocation must
+become globally visible immediately.
+
+## Deploy
+
+This example has no `package.json` of its own — it resolves the installed
+package from the repository root.
+
+```sh
+npm install                                    # from the package root
+
+wrangler kv namespace create CONNECTA_KV       # paste the id into wrangler.jsonc
+
+cd examples/worker
+wrangler secret put SUPPORT_TOKEN                # one headless client
+wrangler secret put EXEC_TOKEN                   # another headless client
+wrangler secret put CLERK_SECRET_KEY
+wrangler secret put DOWNSTREAM_TOKEN
+wrangler deploy
+```
+
+`PUBLIC_URL` and `CLERK_PUBLISHABLE_KEY` are plain vars in `wrangler.jsonc`.
+Enable Dynamic Client Registration on the Clerk instance (OAuth Applications →
+DCR) so Claude/Cursor can self-register — full walkthrough in
+[setting up Clerk](../../documentation/auth.md).
+
+Then point an MCP client at `<PUBLIC_URL>/mcp`, and open `<PUBLIC_URL>/` for
+Connections. Credentials is at `/credentials`, named MCP access tokens are at
+`/tokens`, Activity is at `/activity`, and legacy `/ui` redirects to `/`.
+
+## Code mode
+
+Code mode is a deploy-time opt-in because its Dynamic Worker sandbox requires
+the [Workers Paid plan](https://developers.cloudflare.com/dynamic-workers/pricing/).
+The Worker Loader binding is the switch; no TypeScript change or separate
+environment variable is needed. Add this block to `wrangler.jsonc` (and a comma
+after the preceding property):
+
+```jsonc
+"worker_loaders": [{ "binding": "LOADER" }]
+```
+
+`src/index.ts` detects `env.LOADER`, constructs `DynamicWorkerExecutor`, and
+serves the seven-tool code-first surface. Leave the binding absent — as it is in
+the checked-in config — to deploy the same source on the Workers Free plan with
+the nine classic meta-tools. A deployment copied into its own repository must
+also install the executor package before enabling the binding:
+
+```sh
+npm install @cloudflare/codemode
+```
+
+## Activity history (optional)
+
+`src/d1-activity.ts` is a complete `ActivityStore` over D1 — keyset paging on
+`(occurred_at_ms, id)` plus a batched retention pass — but it is **not wired
+into `src/index.ts`**, so the example deploys without a database. To enable it:
+
+1. Create the database and bind it in `wrangler.jsonc`:
+
+   ```sh
+   wrangler d1 create connecta-activity
+   ```
+
+   ```jsonc
+   "d1_databases": [
+     { "binding": "ACTIVITY_DB", "database_name": "connecta-activity", "database_id": "…" }
+   ]
+   ```
+
+2. Apply the schema (keep it in a deployment-owned `migrations/` directory):
+
+   ```sql
+   CREATE TABLE IF NOT EXISTS tool_call_activity (
+     id             TEXT PRIMARY KEY,
+     occurred_at_ms INTEGER NOT NULL,
+     request_id     TEXT NOT NULL,
+     actor_kind     TEXT NOT NULL,
+     actor_id       TEXT,
+     actor_namespace TEXT,
+     connector_id   TEXT NOT NULL,
+     tool_name      TEXT NOT NULL,
+     source         TEXT NOT NULL,
+     outcome        TEXT NOT NULL,
+     duration_ms    INTEGER NOT NULL,
+     attempts       INTEGER NOT NULL,
+     error_code     TEXT,
+     server_name    TEXT NOT NULL,
+     server_version TEXT NOT NULL,
+     deployment_id  TEXT
+   );
+
+   CREATE INDEX IF NOT EXISTS tool_call_activity_recent
+     ON tool_call_activity (occurred_at_ms DESC, id DESC);
+   ```
+
+   **Already have this table?** `actor_namespace` was added after the original
+   example, and `CREATE TABLE IF NOT EXISTS` will not add it to a table that
+   already exists. Add it as a migration:
+
+   ```sql
+   ALTER TABLE tool_call_activity ADD COLUMN actor_namespace TEXT;
+   ```
+
+   Do this **before** deploying the updated `d1-activity.ts`: its `INSERT`
+   names the column, so against an un-migrated table every write fails with
+   `no such column`. Activity writes are best-effort by design — connecta logs
+   the failure and returns the tool result unharmed — so the symptom is not an
+   error your agent sees, it is an activity log that quietly stops recording.
+
+3. Pass the store to `createConnecta`:
+
+   ```ts
+   import { d1ActivityStore } from "./d1-activity.js";
+
+   createConnecta({
+     // …
+     activity: {
+       store: d1ActivityStore(env.ACTIVITY_DB),
+       deploymentId: "production",
+     },
+   });
+   ```
+
+Events carry no arguments, results, generated code, or raw error messages — see
+[activity history](../../documentation/operator-ui.md).
+The Worker entrypoint already forwards `ctx` to `connecta.fetch`, which lets
+async activity writes settle on `waitUntil`.
+
+For retention, add a
+[Cron Trigger](https://developers.cloudflare.com/workers/configuration/cron-triggers/)
+(`triggers.crons` in `wrangler.jsonc` plus a `scheduled` handler — this example
+no longer ships one) and call `pruneActivity(env.ACTIVITY_DB, retentionDays)`
+from it.

package/examples/worker/src/cloudflare-kv.ts

@@ -0,0 +1,43 @@
+import type { KVStorage } from "@zackbart/connecta";
+
+/**
+ * KVStorage backed by a Cloudflare Workers KV namespace binding.
+ * Note: Workers KV enforces a 60s minimum TTL; shorter TTLs are dropped
+ * (stored without expiry) rather than rejected.
+ *
+ * Workers KV is eventually consistent across locations. It is suitable for
+ * this example's durable state, but cannot promise immediate global OAuth
+ * disconnect, credential rotation, or access-token issuance/revocation; use a
+ * strongly consistent adapter when that is required.
+ */
+export function cloudflareKvStorage(namespace: KVNamespace): KVStorage {
+  return {
+    async get(key) {
+      return namespace.get(key);
+    },
+    async set(key, value, opts) {
+      const ttl = opts?.ttlSeconds;
+      await namespace.put(
+        key,
+        value,
+        ttl && ttl >= 60 ? { expirationTtl: ttl } : undefined,
+      );
+    },
+    async delete(key) {
+      await namespace.delete(key);
+    },
+    async list(prefix) {
+      const keys: string[] = [];
+      let cursor: string | undefined;
+      do {
+        const page = await namespace.list({
+          prefix,
+          ...(cursor ? { cursor } : {}),
+        });
+        keys.push(...page.keys.map((key) => key.name));
+        cursor = page.list_complete ? undefined : page.cursor;
+      } while (cursor);
+      return keys.sort();
+    },
+  };
+}

package/examples/worker/src/d1-activity-row.ts

@@ -0,0 +1,100 @@
+// Keep this pure mapping module dependency-free so the repository's tests can
+// exercise the example before the package's dist/ entrypoint has been built.
+// The public adapter in d1-activity.ts remains checked against ActivityStore.
+export interface ActivityEvent {
+  schemaVersion: 1;
+  id: string;
+  occurredAt: string;
+  requestId: string;
+  actor: {
+    kind: string;
+    id?: string;
+    namespace?: string;
+  };
+  connectorId: string;
+  toolName: string;
+  address: string;
+  source:
+    | "call_tool"
+    | "call_destructive_tool"
+    | "batch_call"
+    | "execute_code";
+  outcome: "success" | "error" | "timeout" | "cancelled";
+  durationMs: number;
+  attempts: number;
+  errorCode?: string;
+  serverName: string;
+  serverVersion: string;
+  deploymentId?: string;
+}
+
+export interface ActivityRow {
+  id: string;
+  occurred_at_ms: number;
+  request_id: string;
+  actor_kind: string;
+  actor_id: string | null;
+  actor_namespace: string | null;
+  connector_id: string;
+  tool_name: string;
+  source: ActivityEvent["source"];
+  outcome: ActivityEvent["outcome"];
+  duration_ms: number;
+  attempts: number;
+  error_code: string | null;
+  server_name: string;
+  server_version: string;
+  deployment_id: string | null;
+}
+
+export function activityEventToRow(
+  event: ActivityEvent,
+): ActivityRow {
+  return {
+    id: event.id,
+    occurred_at_ms: Date.parse(event.occurredAt),
+    request_id: event.requestId,
+    actor_kind: event.actor.kind,
+    actor_id: event.actor.id ?? null,
+    actor_namespace: event.actor.namespace ?? null,
+    connector_id: event.connectorId,
+    tool_name: event.toolName,
+    source: event.source,
+    outcome: event.outcome,
+    duration_ms: event.durationMs,
+    attempts: event.attempts,
+    error_code: event.errorCode ?? null,
+    server_name: event.serverName,
+    server_version: event.serverVersion,
+    deployment_id: event.deploymentId ?? null,
+  };
+}
+
+export function activityRowToEvent(
+  row: ActivityRow,
+): ActivityEvent {
+  return {
+    schemaVersion: 1,
+    id: row.id,
+    occurredAt: new Date(row.occurred_at_ms).toISOString(),
+    requestId: row.request_id,
+    actor: {
+      kind: row.actor_kind,
+      ...(row.actor_id ? { id: row.actor_id } : {}),
+      ...(row.actor_namespace ? { namespace: row.actor_namespace } : {}),
+    },
+    connectorId: row.connector_id,
+    toolName: row.tool_name,
+    address: `${row.connector_id}.${row.tool_name}`,
+    source: row.source,
+    outcome: row.outcome,
+    durationMs: row.duration_ms,
+    attempts: row.attempts,
+    ...(row.error_code ? { errorCode: row.error_code } : {}),
+    serverName: row.server_name,
+    serverVersion: row.server_version,
+    ...(row.deployment_id
+      ? { deploymentId: row.deployment_id }
+      : {}),
+  };
+}

package/examples/worker/src/d1-activity.ts

@@ -0,0 +1,144 @@
+import type {
+  ActivityPage,
+  ActivityStore,
+} from "@zackbart/connecta";
+import { InvalidActivityCursorError } from "@zackbart/connecta";
+import {
+  activityEventToRow,
+  activityRowToEvent,
+  type ActivityRow,
+} from "./d1-activity-row.js";
+
+interface Cursor {
+  occurredAtMs: number;
+  id: string;
+}
+
+function encodeCursor(row: ActivityRow): string {
+  return btoa(`${row.occurred_at_ms}:${row.id}`);
+}
+
+function decodeCursor(value: string): Cursor {
+  let decoded: string;
+  try {
+    decoded = atob(value);
+  } catch {
+    throw new InvalidActivityCursorError();
+  }
+  const separator = decoded.indexOf(":");
+  const occurredAtMs = Number(decoded.slice(0, separator));
+  const id = decoded.slice(separator + 1);
+  if (
+    separator < 1 ||
+    !Number.isSafeInteger(occurredAtMs) ||
+    occurredAtMs < 0 ||
+    !/^[0-9a-f-]{36}$/i.test(id)
+  ) {
+    throw new InvalidActivityCursorError();
+  }
+  return { occurredAtMs, id };
+}
+
+/** One append-only row per completed downstream call; no arguments or results. */
+export function d1ActivityStore(db: D1Database): ActivityStore {
+  return {
+    async record(event) {
+      const row = activityEventToRow(event);
+      await db
+        .prepare(
+          `INSERT INTO tool_call_activity (
+            id, occurred_at_ms, request_id, actor_kind, actor_id,
+            actor_namespace,
+            connector_id, tool_name, source, outcome, duration_ms, attempts,
+            error_code, server_name, server_version, deployment_id
+          ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+        )
+        .bind(
+          row.id,
+          row.occurred_at_ms,
+          row.request_id,
+          row.actor_kind,
+          row.actor_id,
+          row.actor_namespace,
+          row.connector_id,
+          row.tool_name,
+          row.source,
+          row.outcome,
+          row.duration_ms,
+          row.attempts,
+          row.error_code,
+          row.server_name,
+          row.server_version,
+          row.deployment_id,
+        )
+        .run();
+    },
+
+    async list({ cursor, limit }): Promise<ActivityPage> {
+      const boundedLimit = Math.min(100, Math.max(1, Math.trunc(limit)));
+      const pageSize = boundedLimit + 1;
+      const position = cursor ? decodeCursor(cursor) : undefined;
+      const statement = position
+        ? db
+            .prepare(
+              `SELECT * FROM tool_call_activity
+               WHERE occurred_at_ms < ?
+                  OR (occurred_at_ms = ? AND id < ?)
+               ORDER BY occurred_at_ms DESC, id DESC
+               LIMIT ?`,
+            )
+            .bind(
+              position.occurredAtMs,
+              position.occurredAtMs,
+              position.id,
+              pageSize,
+            )
+        : db
+            .prepare(
+              `SELECT * FROM tool_call_activity
+               ORDER BY occurred_at_ms DESC, id DESC
+               LIMIT ?`,
+            )
+            .bind(pageSize);
+      const result = await statement.all<ActivityRow>();
+      const rows = result.results ?? [];
+      const hasMore = rows.length > boundedLimit;
+      const visible = hasMore ? rows.slice(0, boundedLimit) : rows;
+      const last = visible.at(-1);
+      return {
+        events: visible.map(activityRowToEvent),
+        ...(hasMore && last ? { nextCursor: encodeCursor(last) } : {}),
+      };
+    },
+  };
+}
+
+/**
+ * Daily retention pass. Each statement is capped at 5,000 rows, then repeats
+ * up to a per-run ceiling so normal traffic catches up without allowing one
+ * scheduled invocation to consume unbounded queries.
+ */
+export async function pruneActivity(
+  db: D1Database,
+  retentionDays: number,
+  maxBatches = 20,
+): Promise<void> {
+  const cutoff = Date.now() -
+    Math.max(1, Math.trunc(retentionDays)) * 24 * 60 * 60 * 1_000;
+  const batchLimit = Math.max(1, Math.trunc(maxBatches));
+  for (let batch = 0; batch < batchLimit; batch++) {
+    const result = await db
+      .prepare(
+        `DELETE FROM tool_call_activity
+         WHERE id IN (
+           SELECT id FROM tool_call_activity
+           WHERE occurred_at_ms < ?
+           ORDER BY occurred_at_ms ASC
+           LIMIT 5000
+         )`,
+      )
+      .bind(cutoff)
+      .run();
+    if ((result.meta.changes ?? 0) < 5_000) return;
+  }
+}

package/examples/worker/src/index.ts

@@ -0,0 +1,136 @@
+/**
+ * connecta on Cloudflare Workers.
+ *
+ * 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.
+ *
+ * Setup (this example has no package.json of its own — it self-references the
+ * installed `@zackbart/connecta` package):
+ *   1. `npm install` in the connecta package root (../../ from here) so the
+ *      package import and wrangler resolve.
+ *   2. Create a KV namespace and put its id in wrangler.jsonc under `kv_namespaces`.
+ *   3. Set secrets:
+ *        wrangler secret put SUPPORT_TOKEN
+ *        wrangler secret put EXEC_TOKEN
+ *        wrangler secret put CLERK_SECRET_KEY
+ *        wrangler secret put DOWNSTREAM_TOKEN
+ *      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.
+ *   6. `wrangler deploy` from this folder (examples/worker), where wrangler.jsonc
+ *      lives. Point your MCP client at `<PUBLIC_URL>/mcp`.
+ */
+import { DynamicWorkerExecutor } from "@cloudflare/codemode";
+import {
+  api,
+  bearerToken,
+  createConnecta,
+  remoteMcp,
+} from "@zackbart/connecta";
+import { clerkAuth } from "@zackbart/connecta/auth/clerk";
+import { cloudflareKvStorage } from "./cloudflare-kv.js";
+
+interface Env {
+  CONNECTA_KV: KVNamespace;
+  /** Bearer token for one headless client in this deployment's audience. */
+  SUPPORT_TOKEN: string;
+  /** Bearer token for another headless client in the same audience. */
+  EXEC_TOKEN: string;
+  CLERK_PUBLISHABLE_KEY: string;
+  CLERK_SECRET_KEY: string;
+  DOWNSTREAM_TOKEN: string;
+  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.
+   */
+  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 }) }
+      : {}),
+    auth: [
+      // Multiple credentials may identify callers in one deployment. Every
+      // admitted caller reaches this deployment's deliberate connector set.
+      bearerToken(env.SUPPORT_TOKEN, {
+        subjectId: "support-team",
+      }),
+      bearerToken(env.EXEC_TOKEN, {
+        subjectId: "exec-team",
+      }),
+      // The operator signs in with Clerk. Restrict who may sign in with
+      // `allowedDomains` (or a `gate`, for anything a domain cannot express).
+      clerkAuth({
+        publishableKey: env.CLERK_PUBLISHABLE_KEY,
+        secretKey: env.CLERK_SECRET_KEY,
+        publicUrl: env.PUBLIC_URL,
+        // allowedDomains: ["acme.com"],
+      }),
+    ],
+    // Eligible Clerk operators can create named, revocable MCP Bearer tokens
+    // at /tokens. Secrets are shown once; only their hashes enter KV.
+    accessTokens: {},
+    connectors: [
+      remoteMcp("notion", {
+        url: "https://mcp.notion.com/mcp",
+        description: "Notion — pages, databases, comments (static token)",
+        auth: {
+          type: "headers",
+          headers: { Authorization: `Bearer ${env.DOWNSTREAM_TOKEN}` },
+        },
+      }),
+      api("echo", {
+        description: "Echo — text transforms",
+        tools: [
+          {
+            name: "shout",
+            description: "Uppercase the given text.",
+            inputSchema: {
+              type: "object",
+              properties: {
+                text: { type: "string", description: "Text to uppercase." },
+              },
+              required: ["text"],
+            },
+            annotations: { readOnlyHint: true },
+            handler: async (args: { text: string }) => ({
+              shouted: args.text.toUpperCase(),
+            }),
+          },
+        ],
+      }),
+    ],
+  });
+}
+
+// Lazy per-isolate singleton: reuses the plain-data tool cache. Downstream MCP
+// clients are request-scoped internally so Worker I/O never crosses requests.
+let connecta: ReturnType<typeof build> | undefined;
+
+export default {
+  // Pass `ctx` through: connecta hands deferred work (activity sinks) to
+  // ctx.waitUntil so it settles after the response is returned instead of
+  // being cancelled with the request.
+  async fetch(
+    request: Request,
+    env: Env,
+    ctx: ExecutionContext,
+  ): Promise<Response> {
+    connecta ??= build(env);
+    return connecta.fetch(request, env, ctx);
+  },
+};

package/examples/worker/wrangler.jsonc

@@ -0,0 +1,26 @@
+{
+  "$schema": "node_modules/wrangler/config-schema.json",
+  "name": "connecta-example",
+  "main": "src/index.ts",
+  "compatibility_date": "2025-01-01",
+  "compatibility_flags": ["nodejs_compat"],
+  "observability": { "enabled": true },
+
+  // Plain vars. Secrets (SUPPORT_TOKEN, EXEC_TOKEN, CLERK_SECRET_KEY,
+  // DOWNSTREAM_TOKEN) are set with `wrangler secret put <NAME>`, not here.
+  "vars": {
+    "PUBLIC_URL": "https://connecta.example.workers.dev",
+    "CLERK_PUBLISHABLE_KEY": "pk_test_replace-me"
+  },
+
+  // 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" }]
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zackbart/connecta",
-  "version": "0.10.1",
+  "version": "0.10.2",
   "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.",
@@ -11,6 +11,9 @@
   "publishConfig": {
     "access": "public"
   },
+  "bin": {
+    "connecta": "./bin/connecta.mjs"
+  },
   "repository": {
     "type": "git",
     "url": "git+https://github.com/zackbart/connecta.git"
@@ -26,9 +29,16 @@
     "connectors"
   ],
   "files": [
+    "bin",
     "dist",
     "src",
     "assets",
+    "documentation",
+    "examples/node",
+    "examples/worker",
+    "templates",
+    "AGENTS.md",
+    "ethos.md",
     "README.md",
     "CHANGELOG.md",
     "SECURITY.md",