@zackbart/connecta 0.24.3 → 0.25.0

package/dist/operator-ui/setup-commands.js

@@ -0,0 +1,53 @@
+/**
+ * Client setup snippets for one MCP endpoint: the deployment's `/mcp` or a
+ * `/mcp/<pool>`. Three formats and no more — Claude Code's CLI, Codex's CLI,
+ * and the `mcpServers` JSON most other clients read — because a longer list
+ * is a list to keep current.
+ *
+ * None of them carries a credential. A client authenticates through the
+ * deployment's inbound auth — OAuth discovery where that is configured — and
+ * a token pasted into a snippet on this page would be one rendered by it.
+ */
+/**
+ * The name a client files this server under. Derived from the deployment's
+ * configured server name, reduced to the characters every client CLI accepts
+ * unquoted, with the pool appended so two endpoints never collide.
+ */
+export function clientServerName(serverName, pool) {
+    const base = (serverName ?? "")
+        .toLowerCase()
+        .replace(/[^a-z0-9_-]+/g, "-")
+        .replace(/-{2,}/g, "-")
+        .replace(/^-+|-+$/g, "")
+        .slice(0, 48) || "connecta";
+    return pool ? `${base}-${pool}` : base;
+}
+/** The URL for a pool: `/mcp` plus its name, which config limits to `[a-z0-9_-]`. */
+export function poolEndpointUrl(mcpUrl, pool) {
+    return `${mcpUrl.replace(/\/+$/, "")}/${encodeURIComponent(pool)}`;
+}
+/** POSIX single-quoting, only when the value needs it. */
+function shellWord(value) {
+    return /^[A-Za-z0-9_./:@%+=,~-]+$/.test(value)
+        ? value
+        : `'${value.replace(/'/g, `'"'"'`)}'`;
+}
+export function clientSetupCommands(name, url) {
+    return [
+        {
+            id: "claude",
+            label: "Claude Code",
+            text: `claude mcp add --transport http ${shellWord(name)} ${shellWord(url)}`,
+        },
+        {
+            id: "codex",
+            label: "Codex",
+            text: `codex mcp add ${shellWord(name)} --url ${shellWord(url)}`,
+        },
+        {
+            id: "json",
+            label: "JSON config",
+            text: JSON.stringify({ mcpServers: { [name]: { type: "http", url } } }, null, 2),
+        },
+    ];
+}

package/dist/operator-ui/view.js

@@ -13,8 +13,8 @@ export function pageForPath(path) {
 export function info(message) {
     return { message, tone: "info" };
 }
-export function failure(message) {
-    return { message, tone: "error" };
+export function failure(message, fix) {
+    return fix ? { message, tone: "error", fix } : { message, tone: "error" };
 }
 export function initialState(page) {
     return {
@@ -97,6 +97,113 @@ export function connectorStatusLabel(status) {
 export function toolCountLabel(count) {
     return `${count} ${count === 1 ? "tool" : "tools"}`;
 }
+export function connectorStatusTone(status) {
+    if (status === "ok")
+        return "ok";
+    if (status === "auth_required")
+        return "warn";
+    if (status === "loading")
+        return "neutral";
+    return "danger";
+}
+export function summarizeConnectors(connectors) {
+    const summary = {
+        total: connectors.length,
+        connected: 0,
+        attention: 0,
+        unavailable: 0,
+        tools: 0,
+        drifting: 0,
+    };
+    for (const connector of connectors) {
+        if (connector.status === "ok")
+            summary.connected += 1;
+        else if (connector.status === "auth_required")
+            summary.attention += 1;
+        else if (connector.status !== "loading")
+            summary.unavailable += 1;
+        summary.tools += connector.toolCount || 0;
+        if (driftState(connector.catalogDrift) === "warning")
+            summary.drifting += 1;
+    }
+    return summary;
+}
+/**
+ * The one line above the list. Connected and tool counts are always present;
+ * the two counts an operator may have to act on appear only when they are not
+ * zero, so a healthy deployment stays short.
+ */
+export function connectorSummaryParts(summary) {
+    return [
+        { text: `${summary.connected} connected`, tone: "neutral" },
+        ...(summary.attention
+            ? [
+                {
+                    text: `${summary.attention} need${summary.attention === 1 ? "s" : ""} authorization`,
+                    tone: "warn",
+                },
+            ]
+            : []),
+        ...(summary.unavailable
+            ? [{ text: `${summary.unavailable} unavailable`, tone: "danger" }]
+            : []),
+        { text: toolCountLabel(summary.tools), tone: "neutral" },
+    ];
+}
+/**
+ * The badge for each call path, keyed by the server's classification so the
+ * planned third state is a row here rather than a new branch in a component.
+ */
+export const TOOL_SAFETY_BADGE = {
+    runs_in_programs: {
+        label: "runs in programs",
+        tone: "ok",
+        title: "Explicitly read-only: execute_code programs may call it without asking.",
+    },
+    needs_approval: {
+        label: "needs approval",
+        tone: "warn",
+        title: "Not explicitly read-only: calls cross call_destructive_tool, where the host asks first.",
+    },
+};
+/**
+ * What the page says about a connector that is not usable, one fixed sentence
+ * per problem kind the server classified. This is the only account of a
+ * failure the Connections page renders: a connector's status message can quote
+ * a downstream error body, and a downstream error body can quote the secret
+ * that was just rejected, so the raw text stays in the deployment's log and
+ * never reaches the payload or the DOM. The fix prompt beside it is keyed off
+ * the same kind.
+ */
+const PROBLEM_COPY = {
+    connector_unavailable: "Unavailable: its status check or catalog load failed, or did not finish in time. The deployment's log has the downstream error.",
+    oauth_required: "Needs OAuth authorization: no grant is stored, or the stored grant expired or was revoked.",
+    credential_required: "Needs a credential: nothing usable is stored in its credential slot.",
+    auth_required: "Needs authorization. Its secret lives in deployment configuration, not on this page.",
+    credential_mismatch: "The stored credential does not match the fields this connector declares, so it cannot be used.",
+    catalog_failed: "Connected, but its tool catalog could not be loaded, so none of its tools are served.",
+};
+export function problemCopy(problem) {
+    return problem ? PROBLEM_COPY[problem] ?? null : null;
+}
+/** Who owns this connector's downstream credentials, in two words. */
+export function authScopeLabel(scope) {
+    return scope === "personal" ? "personal auth" : "shared auth";
+}
+/**
+ * What this identity may do with a connector, in one line. Being able to use it
+ * is implied by seeing it at all, so the sentence covers authentication, which
+ * is the part that differs between operators.
+ */
+export function permissionLabel(connector) {
+    if (connector.permissions?.manageSharedAuth) {
+        return "You can manage shared authentication for this connection.";
+    }
+    if (connector.permissions?.connectPersonal) {
+        return "You can connect your own account to this connection.";
+    }
+    return "Authentication for this connection is managed by your deployment.";
+}
 /**
  * The four categories, in the order an operator should read them: what the
  * deployment refuses to call, what it can no longer call, what contradicts a

package/dist/program-source.js

@@ -0,0 +1,205 @@
+// Program source handling shared by every executor. Web-API only: execute_code
+// runs it before handing a program to QuickJS or a Dynamic Worker, and the
+// QuickJS normalizer runs it too for callers that drive that executor directly.
+/** A whole-program markdown fence, as QuickJS's normalizer recognizes one. */
+const FENCE = /^```[\w-]*\s*\n([\s\S]*?)\n?```$/;
+/** Leading whitespace and comments, which may precede the arrow expression. */
+const LEADING_TRIVIA = /^(?:\s+|\/\/[^\n]*|\/\*[\s\S]*?\*\/)+/;
+/** One character of an identifier, keyword, or number; `\\` for escapes. */
+const WORD = /[\w$\\\u0080-\uffff]/;
+/**
+ * Words after which a `/` begins a regular expression rather than dividing.
+ * Any other word is an identifier or a literal, which a `/` divides.
+ */
+const REGEX_AFTER_WORD = new Set([
+    "await", "case", "delete", "do", "else", "in", "instanceof", "new", "of",
+    "return", "throw", "typeof", "void", "yield",
+]);
+/**
+ * Remove the statement terminators after a program's arrow expression:
+ * `async () => { … };`, with any whitespace or comments around the trailing
+ * semicolons, becomes `async () => { … }` with those comments kept. Both
+ * executors evaluate a program as a parenthesized expression, where a
+ * terminator is a syntax error on QuickJS and, on a Dynamic Worker, either the
+ * same error or a program that silently returns `undefined`. Models often end
+ * a program with `};`, so P1 accepts it on both.
+ *
+ * Deliberately narrow, so it cannot broaden what a program is: only a program
+ * whose first token is `async` or `(` — what QuickJS treats as a function
+ * expression — and only when every semicolon at bracket depth zero trails it,
+ * with nothing but whitespace and comments after. `async () => 1; 2();` keeps
+ * both its semicolons, and a bare statement body is never touched, since its
+ * trailing `;` can be an empty loop body. A whole-program markdown fence is
+ * looked through, and dropped when a terminator came out from under it.
+ *
+ * A small lexer, not a parser: it skips strings, template literals (with
+ * `${}` nesting), comments, and regular expressions, telling a regex from a
+ * division by the token before it. Any source it cannot close — an
+ * unterminated string or comment, unbalanced brackets — comes back unchanged,
+ * so the executor reports the same error it always did.
+ */
+export function withoutProgramTerminator(code) {
+    const fenced = FENCE.exec(code.trim())?.[1];
+    const source = fenced === undefined ? code : fenced.trim();
+    const stripped = stripTerminators(source);
+    return stripped === source ? code : stripped;
+}
+function stripTerminators(source) {
+    const head = source.replace(LEADING_TRIVIA, "");
+    if (!/^async\b/.test(head) && !head.startsWith("("))
+        return source;
+    const n = source.length;
+    let depth = 0;
+    /** Bracket depth at which each open template substitution resumes its template. */
+    const substitutions = [];
+    /** Positions of the top-level semicolons, all of which must trail. */
+    const terminators = [];
+    /**
+     * The previous significant token: a punctuator character or a word, with a
+     * string, template, or regex literal recorded as `0` — a value, like a number.
+     */
+    let previous = "";
+    let i = 0;
+    /** Scan template text from `from` to its closing backtick or next `${`. */
+    const template = (from) => {
+        for (let j = from; j < n; j++) {
+            const c = source[j];
+            if (c === "\\") {
+                j++;
+            }
+            else if (c === "`") {
+                return j + 1;
+            }
+            else if (c === "$" && source[j + 1] === "{") {
+                substitutions.push(depth);
+                depth++;
+                return j + 2;
+            }
+        }
+        return undefined;
+    };
+    while (i < n) {
+        const c = source[i];
+        if (/\s/.test(c)) {
+            i++;
+            continue;
+        }
+        if (c === "/" && source[i + 1] === "/") {
+            const end = source.indexOf("\n", i);
+            i = end === -1 ? n : end;
+            continue;
+        }
+        if (c === "/" && source[i + 1] === "*") {
+            const end = source.indexOf("*/", i + 2);
+            if (end === -1)
+                return source;
+            i = end + 2;
+            continue;
+        }
+        if (c === ";") {
+            if (depth === 0)
+                terminators.push(i);
+            previous = ";";
+            i++;
+            continue;
+        }
+        // Code after a top-level semicolon means the program is more than one
+        // expression; that is for the executor to refuse, not for us to repair.
+        if (terminators.length > 0)
+            return source;
+        if (c === '"' || c === "'") {
+            let j = i + 1;
+            while (j < n && source[j] !== c) {
+                if (source[j] === "\n")
+                    return source;
+                j += source[j] === "\\" ? 2 : 1;
+            }
+            if (j >= n)
+                return source;
+            i = j + 1;
+            previous = "0";
+            continue;
+        }
+        if (c === "`") {
+            const end = template(i + 1);
+            if (end === undefined)
+                return source;
+            i = end;
+            previous = source[end - 1] === "`" ? "0" : "{";
+            continue;
+        }
+        if (c === "}" && substitutions.at(-1) === depth - 1) {
+            substitutions.pop();
+            depth--;
+            const end = template(i + 1);
+            if (end === undefined)
+                return source;
+            i = end;
+            previous = source[end - 1] === "`" ? "0" : "{";
+            continue;
+        }
+        if (c === "/" && startsRegex(previous)) {
+            let j = i + 1;
+            let inClass = false;
+            for (; j < n; j++) {
+                const r = source[j];
+                if (r === "\n")
+                    return source;
+                if (r === "\\")
+                    j++;
+                else if (r === "[")
+                    inClass = true;
+                else if (r === "]")
+                    inClass = false;
+                else if (r === "/" && !inClass)
+                    break;
+            }
+            if (j >= n)
+                return source;
+            i = j + 1;
+            while (i < n && /[\w$]/.test(source[i]))
+                i++;
+            previous = "0";
+            continue;
+        }
+        if (WORD.test(c)) {
+            let j = i + 1;
+            while (j < n && WORD.test(source[j]))
+                j++;
+            previous = source.slice(i, j);
+            i = j;
+            continue;
+        }
+        if (c === "(" || c === "[" || c === "{")
+            depth++;
+        else if (c === ")" || c === "]" || c === "}") {
+            if (depth === 0)
+                return source;
+            depth--;
+        }
+        previous = c;
+        i++;
+    }
+    if (depth !== 0 || substitutions.length > 0 || terminators.length === 0) {
+        return source;
+    }
+    let out = "";
+    let from = 0;
+    for (const at of terminators) {
+        out += source.slice(from, at);
+        from = at + 1;
+    }
+    return out + source.slice(from);
+}
+/** Whether a `/` after `previous` opens a regular expression. */
+function startsRegex(previous) {
+    if (previous === "")
+        return true;
+    if (WORD.test(previous[0])) {
+        // A number or an identifier divides; a keyword introduces an operand.
+        return REGEX_AFTER_WORD.has(previous);
+    }
+    // After a closing bracket a value precedes; after any other punctuator
+    // an operand is expected.
+    return previous !== ")" && previous !== "]" && previous !== "}";
+}

package/dist/providers/cloudflare.d.ts

@@ -6,9 +6,21 @@ export declare const CLOUDFLARE_API_BASE = "https://api.cloudflare.com/client/v4
 export declare const CLOUDFLARE_MCP_ENDPOINT = "https://mcp.cloudflare.com/mcp";
 /** Authentication schemes accepted by Cloudflare's v4 API. */
 export type CloudflareAuthentication = "apiToken" | "globalApiKey";
-/** See documentation/cloudflare.md#dns-record-types. */
+/**
+ * The 21 record types Cloudflare accepts. Eight carry a single `content`
+ * string; the other thirteen carry a per-type structured `data` object.
+ * `list_dns_records` filters on all 21 because reading them costs nothing.
+ */
 export declare const CLOUDFLARE_DNS_RECORD_TYPES: readonly ["A", "AAAA", "CAA", "CERT", "CNAME", "DNSKEY", "DS", "HTTPS", "LOC", "MX", "NAPTR", "NS", "OPENPGPKEY", "PTR", "SMIMEA", "SRV", "SSHFP", "SVCB", "TLSA", "TXT", "URI"];
-/** Content-valued types only; see documentation/cloudflare.md#dns-record-types. */
+/**
+ * Content-valued types only, and the only types `create_dns_record` and
+ * `update_dns_record` accept. Covering the thirteen structured-`data` types
+ * would mean either a free-form `data` passthrough — the untyped body this
+ * connection exists to avoid — or thirteen more hand-written schemas for record
+ * types that are rare in day-to-day zone administration. They stay fully
+ * readable; writing one goes through the approval-gated raw mutation tool with
+ * Cloudflare's documented per-type `data` body.
+ */
 export declare const CLOUDFLARE_CONTENT_DNS_RECORD_TYPES: readonly ["A", "AAAA", "CNAME", "MX", "NS", "OPENPGPKEY", "PTR", "TXT"];
 interface CloudflareCommonOptions {
     /** Human-readable display name; defaults identify the selected interface. */

package/dist/providers/cloudflare.js

@@ -1,4 +1,14 @@
-/** See documentation/cloudflare.md#no-sdk-on-purpose. */
+/**
+ * No official `cloudflare` SDK on purpose. What the SDK sells — typed request
+ * wrappers and pagination helpers — is what this connection replaces: an agent
+ * gets a projected result and a `page.hasMore` boolean, so the SDK's types
+ * would be re-projected away at the boundary, and the dependency would cost an
+ * optional peer, an install step, and an import that never belongs in the root
+ * graph. Cloudflare's v4 API is authenticated `fetch` over a uniform
+ * `{ success, errors, messages, result, result_info }` envelope, so Web APIs
+ * alone keep this provider Workers-clean. `test/package-surface.test.ts` pins
+ * it: no `cloudflare` package in any dependency field, every import relative.
+ */
 import { api, defined } from "../connectors/api.js";
 import { remoteMcp, withCredentialDefaults, } from "../connectors/remote-mcp.js";
 import { vettedCatalog, withVettedCatalog } from "../catalog-drift.js";
@@ -8,7 +18,11 @@ import { ConnectorCallError } from "../errors.js";
 export const CLOUDFLARE_API_BASE = "https://api.cloudflare.com/client/v4";
 /** Cloudflare's official whole-API hosted MCP endpoint. */
 export const CLOUDFLARE_MCP_ENDPOINT = "https://mcp.cloudflare.com/mcp";
-/** See documentation/cloudflare.md#dns-record-types. */
+/**
+ * The 21 record types Cloudflare accepts. Eight carry a single `content`
+ * string; the other thirteen carry a per-type structured `data` object.
+ * `list_dns_records` filters on all 21 because reading them costs nothing.
+ */
 export const CLOUDFLARE_DNS_RECORD_TYPES = [
     "A",
     "AAAA",
@@ -32,7 +46,15 @@ export const CLOUDFLARE_DNS_RECORD_TYPES = [
     "TXT",
     "URI",
 ];
-/** Content-valued types only; see documentation/cloudflare.md#dns-record-types. */
+/**
+ * Content-valued types only, and the only types `create_dns_record` and
+ * `update_dns_record` accept. Covering the thirteen structured-`data` types
+ * would mean either a free-form `data` passthrough — the untyped body this
+ * connection exists to avoid — or thirteen more hand-written schemas for record
+ * types that are rare in day-to-day zone administration. They stay fully
+ * readable; writing one goes through the approval-gated raw mutation tool with
+ * Cloudflare's documented per-type `data` body.
+ */
 export const CLOUDFLARE_CONTENT_DNS_RECORD_TYPES = [
     "A",
     "AAAA",
@@ -43,7 +65,17 @@ export const CLOUDFLARE_CONTENT_DNS_RECORD_TYPES = [
     "PTR",
     "TXT",
 ];
-/** See documentation/cloudflare.md#rate-limits. */
+/**
+ * Cloudflare documents a global limit of 1,200 requests per five minutes per
+ * user, counted cumulatively across the dashboard, API keys, and API tokens
+ * (developers.cloudflare.com/fundamentals/api/reference/limits/). The matching
+ * rolling window here is a best-effort approximation, not an enforcement: each
+ * runtime keeps its own counter, so N isolates or processes can each admit
+ * 1,200, and a human's dashboard traffic counts for Cloudflare but not for us.
+ * `maxConcurrency` is the bound that actually protects a shared credential,
+ * because one `execute_code` program can fan out faster than the window
+ * notices.
+ */
 function admissionPolicy(maxConcurrency) {
     return {
         rules: [
@@ -155,7 +187,17 @@ function errorCodes(errors) {
  * would risk telling an agent its token was broken when its arguments were.
  * Genuine 10000 auth failures arrive with 401 or 403 and are caught by status.
  *
- * See documentation/cloudflare.md#typed-failures for provenance and routing.
+ * Provenance worth knowing before editing this set: Cloudflare publishes no
+ * official table mapping error codes to causes, so these six — and the 10000
+ * observation above — come from community reports and probing rather than
+ * documentation. They are well-supported readings Cloudflare could invalidate
+ * without notice; prefer `verify_api_token` or `verify_global_api_key` when a
+ * diagnosis actually matters.
+ *
+ * Cloudflare also rate-limits authentication failures separately from the
+ * global limit: a few requests with a bad token return 429 with code 10502.
+ * That is one more reason to diagnose a broken token once with a verify tool
+ * rather than by retrying real calls.
  */
 const AUTH_ERROR_CODES = new Set([1001, 6003, 6111, 9103, 9106, 9107]);
 /**
@@ -169,7 +211,9 @@ const AUTH_ERROR_CODES = new Set([1001, 6003, 6111, 9103, 9106, 9107]);
 function failureFor(status, headers, errors) {
     const detail = describeErrors(errors);
     const codes = errorCodes(errors);
-    // Ordering rationale: documentation/cloudflare.md#typed-failures.
+    // 429 is checked before the authentication codes on purpose: Cloudflare
+    // reuses the generic 10000 code on throttled responses, and reading a rate
+    // limit as an auth failure would tell an agent to stop when it should wait.
     if (status === 429) {
         const wait = retryAfterMs(headers);
         return new ConnectorCallError("rate_limited", `Cloudflare rate limit reached (HTTP 429). ${detail} The documented limit is 1,200 requests per five minutes per user, counted across the dashboard and every token.`, 
@@ -184,7 +228,10 @@ function failureFor(status, headers, errors) {
     if (status === 400 || status === 409 || status === 422) {
         return new ConnectorCallError("invalid_args", `Cloudflare rejected the request (HTTP ${status}). ${detail}`);
     }
-    // 404 rationale: documentation/cloudflare.md#typed-failures.
+    // Cloudflare refuses a token that may not touch a resource with 401 or 403,
+    // so a 404 here is a real absence rather than a permission gap wearing a
+    // miss — the unambiguous case `not_found` exists for, and something an agent
+    // can act on by re-running discovery for the id.
     if (status === 404) {
         return new ConnectorCallError("not_found", `Cloudflare found no such resource (HTTP 404). ${detail} Confirm the zone or account id with list_zones or list_accounts.`);
     }
@@ -576,7 +623,17 @@ const RAW_INPUT_PROPERTY = {
     type: "boolean",
     description: "Return Cloudflare's unprojected result instead of the lean shape. Use only when a field the projection drops is genuinely needed; the raw shape is much larger.",
 };
-/** Bound provenance: documentation/cloudflare.md#where-the-perpage-bounds-come-from. */
+/**
+ * Local enforcement of a `perPage` range is only a favor when the bound is
+ * really Cloudflare's, so `bounds` decides what the description admits to.
+ * `list_accounts`/`list_zones` (5–50) and `list_kv_namespaces` (1–1000) are
+ * Cloudflare's documented bounds. `list_dns_records` takes Cloudflare's
+ * minimum but is `clamped` at 1,000: Cloudflare's schema documents `per_page`
+ * on `/zones/{id}/dns_records` up to 5,000,000, a nominal ceiling no listing
+ * will honor, and a local cap an agent is told about beats a page size that
+ * fails somewhere inside Cloudflare. `list_pages_projects` is `undocumented` —
+ * Cloudflare publishes no bounds and no default for it, so 1–100 is ours.
+ */
 function pagingInputProperties(minPerPage, maxPerPage, options = {}) {
     const { defaultPerPage, bounds = "cloudflare" } = options;
     const defaultNote = defaultPerPage === undefined
@@ -601,7 +658,12 @@ function pagingInputProperties(minPerPage, maxPerPage, options = {}) {
         },
     };
 }
-/** Cursor convention: documentation/cloudflare.md#results. */
+/**
+ * Four endpoints — `list_zone_rulesets`, `list_r2_buckets`, `list_r2_objects`,
+ * `list_kv_keys` — page by cursor and get no `page` object. Both the argument
+ * and the result say so, so the loop condition is legible from either end of
+ * one tool rather than only to a reader who compared all of them.
+ */
 const CURSOR_INPUT_PROPERTY = {
     type: "string",
     description: "Opaque cursor from a previous call's nextCursor. This endpoint pages by cursor, not page number.",
@@ -1013,7 +1075,12 @@ const QUERY_INPUT_PROPERTY = {
         additionalProperties: false,
     },
 };
-// Header boundary: documentation/cloudflare.md#the-whole-v4-escape-hatch.
+// Connector-owned and refused: Authorization, Cookie, Host, Content-Length,
+// Content-Type, Transfer-Encoding — authentication, host selection, content
+// type, and request framing are not the caller's to set. That list stays out of
+// this description on purpose: the compact renderer inlines a shared property
+// description once per tool, and spelling the six out three times pushed
+// cloudflare_api_upload's compact input past the 1,024-byte discovery budget.
 const HEADERS_INPUT_PROPERTY = {
     type: "array",
     description: "Endpoint headers as name/value pairs, e.g. cf-r2-jurisdiction or Range. Connector-owned headers are refused.",
@@ -1412,7 +1479,11 @@ function buildTools(scope, authentication) {
                 path: "/zones",
                 query: {
                     name: optionalString(args, "name"),
-                    // Undefaulted on purpose — see documentation/cloudflare.md#scoping.
+                    // Undefaulted on purpose: list_zones is the discovery step,
+                    // and quietly filtering it by a configured accountId would
+                    // be a restriction in all but name — one with no argument
+                    // that escapes it, since an empty accountId would fall back
+                    // to the default again.
                     "account.id": optionalString(args, "accountId"),
                     status: optionalString(args, "status"),
                     page: optionalNumber(args, "page"),
@@ -1424,7 +1495,13 @@ function buildTools(scope, authentication) {
         cfTool("get_zone", "Fetch one zone's settings summary by id: status, plan, name servers, and owning account.", readOnly, "zoneId", scope.zoneId, {
             raw: RAW_INPUT_PROPERTY
         }, [], ZONE_SCHEMA, getResult(send, (args) => ({ method: "GET", path: `/zones/${encodeURIComponent(zoneArg(args))}` }), (result, args) => args["raw"] === true ? result : projectZone(result))),
-        // Removed tools: documentation/cloudflare.md#what-the-named-surface-deliberately-leaves-out.
+        // No bulk `list_zone_settings` on purpose (#361): Cloudflare's published
+        // document marks GET /zones/{zoneId}/settings and its PATCH sibling
+        // deprecated with no bulk replacement, and the tool projected nothing while
+        // *growing* the payload 22.7% by wrapping an unpaginated settings array in a
+        // page object. Read one setting here; an operator who genuinely wants the
+        // whole set names /zones/{zoneId}/settings through cloudflare_api_get, at
+        // the caller's risk rather than promised by connecta's catalog.
         cfTool("get_zone_setting", "Get one zone setting by its Cloudflare setting id, such as ssl, always_use_https, min_tls_version, brotli, or development_mode.", readOnly, "zoneId", scope.zoneId, {
             settingId: SETTING_ID_PROPERTY,
             raw: RAW_INPUT_PROPERTY
@@ -2019,8 +2096,18 @@ function buildTools(scope, authentication) {
             path: `/accounts/${encodeURIComponent(accountArg(args))}/r2/buckets/${encodeURIComponent(requireString(args, "bucketName"))}/objects/${encodeObjectKey(objectKey)}`,
             headers: r2Headers(args),
         }))),
-        // No `get_r2_metrics`, `set_r2_cors`, or `delete_r2_cors` on purpose (#350) —
-        // see documentation/cloudflare.md#what-the-named-surface-deliberately-leaves-out.
+        // No `get_r2_metrics`, `set_r2_cors`, or `delete_r2_cors` on purpose (#350).
+        // A named tool is a permanent line item in every deployment's catalog, and
+        // these lost the comparison against the escape hatches: `get_r2_metrics`
+        // took an account id, put it in a path, and returned the response untouched,
+        // which `cloudflare_api_get` at /accounts/{accountId}/r2/metrics already
+        // does. `set_r2_cors` declared its rule list as free-form objects — the
+        // untyped body refused everywhere else — and returned Cloudflare's response
+        // unprojected, so it beat the raw route on nothing. `delete_r2_cors`
+        // validated fine and went anyway, because naming only the delete would mean
+        // one CORS policy is set through the raw route and cleared through a named
+        // tool. Read with `get_r2_cors`; write with `cloudflare_api_mutate` at
+        // PUT/DELETE /accounts/{accountId}/r2/buckets/{bucketName}/cors.
         cfTool("get_r2_cors", "Get the browser CORS rules configured on an R2 bucket.", readOnly, "accountId", scope.accountId, {
             bucketName: R2_BUCKET_NAME_PROPERTY,
             jurisdiction: R2_JURISDICTION_PROPERTY
@@ -2342,8 +2429,12 @@ function buildTools(scope, authentication) {
             const zoneId = zoneArg(args);
             const targeted = ["files", "tags", "hosts", "prefixes"].filter((key) => Array.isArray(args[key]) && args[key].length > 0);
             const everything = args["everything"] === true;
-            // Cloudflare's purge body accepts exactly one variant. Refusing here
-            // turns a confusing provider 400 into a schema-shaped failure.
+            // One variant per call is this connection's contract, not a
+            // documented API restriction: Cloudflare's schema models the body as
+            // `anyOf`, which does not forbid combining. Refusing locally gives an
+            // agent `invalid_args` naming the conflict instead of a purge whose
+            // actual scope is ambiguous. Combined purging would be a deliberate
+            // change here.
             if (everything && targeted.length > 0) {
                 throw new ConnectorCallError("invalid_args", "purge_cache takes either everything: true or one targeted list, never both.", {
                     validation: {

package/dist/providers/linear.d.ts

@@ -19,18 +19,40 @@ export interface LinearOptions {
     authScope?: "shared" | "personal";
     /** Which workspace this is and what decisions it answers. */
     purpose: string;
-    /** Required endpoint selection; see `documentation/linear.md`. */
+    /**
+     * Endpoint selection, required with no default. Linear's read-only endpoint
+     * advertises the `read` scope alone, so its token cannot reach the write APIs
+     * — a stronger guarantee than any annotation. Neither default is safe:
+     * read-write hands out access nobody asked for, and read-only breaks a
+     * writing deployment at runtime, where no agent can repair it.
+     */
     access: LinearAccess;
-    /** OAuth or a personal API key; see `documentation/linear.md`. */
+    /**
+     * OAuth 2.1 with dynamic client registration by default. Linear's MCP server
+     * also accepts a personal API key in `Authorization: Bearer` — note this is
+     * the MCP endpoint's own documented contract, not the GraphQL API convention.
+     * A personal key carries the acting user's full permissions, so pair it with
+     * `access: "read-only"` unless the deployment genuinely writes.
+     */
     auth?: RemoteMcpAuth;
     /** Workspace-specific conventions appended to the maintained provider guide. */
     instructions?: string;
     /** Connector-specific inline result limit; omit to inherit the deployment. */
     maxResultBytes?: number;
-    /** Optional per-runtime policy; see `documentation/linear.md#rate-limits`. */
+    /**
+     * Optional per-runtime policy. There is no default: Linear documents no
+     * MCP-specific limit, the GraphQL limits it rides are metered per user per
+     * hour (and its own page disagrees with itself on the API-key figure), and
+     * Connecta's counter is per runtime. Only the operator knows the workspace.
+     */
     callAdmission?: ConnectorCallAdmissionPolicy;
 }
-/** Release-reviewed manifest; see provider conventions P5 and P13. */
+/**
+ * One release-reviewed manifest, used both to classify a live tool and as the
+ * baseline the drift check compares against, so the annotation a caller gets
+ * and the verdict a check reads can never disagree. Drift must surface as an
+ * unclassified tool on the approval path (P5), never a quiet re-guess.
+ */
 export declare const LINEAR_VETTED_CATALOG: import("../catalog-drift.js").VettedCatalog;
 /** A maintained Linear hosted-MCP connection. */
 export declare function linear(id: string, options: LinearOptions): Connector;