@capacms/mcp 0.2.0

package/lib/client.mjs

@@ -0,0 +1,512 @@
+/**
+ * client.mjs — the HTTP client every tool goes through.
+ *
+ * Zero dependencies, matching @capa/config-guard and the Circular MCP server:
+ * a server an agent runs on its own machine should not drag a dependency tree
+ * along with it, and this one only needs `fetch`.
+ *
+ * AUTH IS NO LONGER READ-ONLY, AND THE COLUMN IS NOW A CONTROL
+ *
+ * This file used to say there was "no write verb behind an API key anywhere in
+ * the codebase". That was true when it was measured (2026-08-21) and is not
+ * true now. Two things changed it:
+ *
+ *   - THE AGENT SURFACE (#383 / ZVN-5741) mounted `/v2/agent/models` and
+ *     `/v2/agent/model-instances` behind `verifyApiKey`, and
+ *     ADMIN_UI_OVERHAUL 0h.4b added `/v2/agent/workspaces`. These are the same
+ *     handlers the admin uses, with the key authenticator instead of the
+ *     session one.
+ *   - `tenant_api_keys.permission` STOPPED BEING DECORATION (#4646).
+ *     `requireApiKeyPermission` reads it through the same `can()` every
+ *     session route asks, so `read`, `write`, `delete` and `agent` now grant
+ *     genuinely different things. The old note here said the column was "read
+ *     by nothing" — do not restore that claim.
+ *
+ * So a write tool CAN be built, and the workspace tools below are. What a key
+ * may actually do is its bundle's business: a `read` key gets 403 on every
+ * write, and this client surfaces the API's own message rather than guessing.
+ *
+ * Still true, and still the reason most tools here are reads: the CONTENT write
+ * surface an agent would want (edit an entry, publish it) is behind
+ * `/v2/agent/model-instances`, and the tools for it are a separate piece of
+ * work. Absent rather than stubbed — a tool that always fails teaches an agent
+ * to stop trying.
+ */
+
+export class CapaApiError extends Error {
+  /**
+   * `envelope` is the `error` object of an `/api/` failure, when there was one.
+   * The legacy surface answers `{ error: "<string>" }` and has no such object,
+   * so the three legacy functions never pass it and `code`/`hint` stay null.
+   */
+  constructor(status, path, body, envelope) {
+    super(
+      envelope && envelope.code
+        ? `Capa API ${status} on ${path}: ${envelope.code}: ${envelope.message ?? ""}`.trimEnd()
+        : `Capa API ${status} on ${path}${body ? `: ${body.slice(0, 200)}` : ""}`,
+    );
+    this.name = "CapaApiError";
+    this.status = status;
+    this.path = path;
+    /**
+     * The response body, whole and unsliced.
+     *
+     * The message carries only the first 200 characters, which is right for a
+     * log line and wrong for a caller that has to ACT on the body. A 400 from
+     * `PUT /v2/models/:id/layout` is `{ error, path }` where `path` names the
+     * node to fix (ADMIN_UI_OVERHAUL 0m.4), and an agent can only fix it if the
+     * tool can read it back out.
+     */
+    this.body = body ?? "";
+    /**
+     * The `/api/` envelope's two act-on-it fields.
+     *
+     * `code` is the exact reason (`page_not_found`, `scope_missing`), which is
+     * what a caller branches on: the STATUS is also produced by things that are
+     * not the API, so a tool that switches on 404 alone is switching on
+     * something a proxy can author. `hint` names the fix in this deployment's
+     * own values, which is the only part of an error a model can act on without
+     * guessing. Null for the legacy surface, which carries neither.
+     */
+    this.code = envelope?.code ?? null;
+    this.hint = envelope?.hint ?? null;
+  }
+}
+
+/**
+ * The dated `/api/` platform version this package asks for when the
+ * environment names none.
+ *
+ * A COPY, and deliberately so: this package has no dependencies and cannot
+ * import from the api. The source of truth is the registry in
+ * `apps/api/src/api-next/versions.ts`, whose newest date this is; a date added
+ * there moves this constant and the README row with it. A date the deployment
+ * does not know answers `400 invalid_version` with a hint listing the dates it
+ * does, so a stale copy here fails loudly rather than quietly serving a shape
+ * nobody asked for.
+ */
+export const DEFAULT_API_VERSION = "2026-10-01";
+
+/**
+ * Which family a key belongs to, from its prefix and nothing else.
+ *
+ * `cap_` keys are hashed at rest and accepted on `/api/` ONLY: the legacy
+ * middleware refuses the prefix before it looks anything up. Every other key
+ * is legacy: `pk_`, `sk_` and the unprefixed keys older tenants hold are
+ * plaintext and reach both surfaces. That one fact is what decides which
+ * tools this server registers, so it is read once here rather than sniffed
+ * per call.
+ *
+ * Case-sensitive, matching the api: `CAP_live_…` is not a key this system
+ * mints, and a lookup path chosen by a header's capitalisation is a bug.
+ * `@capacms/sdk` applies the same rule; both packages are tested against
+ * `packages/sdk/test/fixtures/key-family.json`.
+ */
+export function keyFamily(apiKey) {
+  return String(apiKey ?? "").startsWith("cap_") ? "cap" : "legacy";
+}
+
+/**
+ * Read config from the environment, failing with a message that names the fix.
+ *
+ * ONE PAIR OF NAMES FOR THE WHOLE PRODUCT: `CAPA_API_URL` and `CAPA_KEY`, the
+ * names `@capacms/sdk/nextjs`, `capa-codegen`, the SDK snippets these tools
+ * write and every curl example in docs/api read, so one
+ * `.env` serves a site and this server. `CAPA_BASE_URL` and `CAPA_API_KEY`,
+ * this package's first names, still work as aliases; the new name wins when
+ * both are set.
+ *
+ * NOTE ON THE ENV INVENTORY. `gen-env-template.mjs` scans for the literal
+ * `process.env.X` form, and the `env = process.env` parameter here (which
+ * exists so this is testable) hides every name below from it. The names reach
+ * .env.next.template anyway, because `packages/sdk`'s codegen bin reads them
+ * in the literal form; their notes in scripts/env-notes.json say this package
+ * shares them. CAPA_API_VERSION is read HERE and nowhere else, so it is listed
+ * in that file's `unread` block instead, which is the generator's second
+ * source for exactly this case.
+ */
+export function loadConfig(env = process.env) {
+  // Trimmed: a key pasted with a space or a newline around it is still the key,
+  // and its prefix decides the family below.
+  const baseUrl = (env.CAPA_API_URL || env.CAPA_BASE_URL || "").trim().replace(/\/+$/, "");
+  const apiKey = (env.CAPA_KEY || env.CAPA_API_KEY || "").trim();
+  const tenantId = (env.CAPA_TENANT_ID || "").trim();
+  // Optional, and the only one of the four that is. An agent that never sets it
+  // gets today's shape; one pinning an older date gets the shape it was written
+  // against, which is the whole point of a dated surface.
+  const apiVersion = (env.CAPA_API_VERSION || "").trim() || DEFAULT_API_VERSION;
+  const family = keyFamily(apiKey);
+
+  const missing = [];
+  if (!baseUrl) missing.push("CAPA_API_URL");
+  if (!apiKey) missing.push("CAPA_KEY");
+  // REQUIRED FOR A LEGACY KEY ONLY, and that is not a convenience.
+  //
+  // `X-Tenant-Key` is read by the `/v2` and `/v3` mounts, which is where every
+  // legacy tool calls, so a legacy key without it gets a refusal on the
+  // first call. A `cap_` key reaches `/api/` and nothing else: that surface
+  // resolves the tenant from the key itself and never reads the header, and
+  // the registry gives a `cap_` key no legacy tool to call. Demanding it would
+  // be demanding a value nothing this process can reach will read, and refusing
+  // to start without one would refuse to start over a value that does not
+  // matter.
+  //
+  // It is therefore EMPTY STRING in the returned config for a `cap_` key. No
+  // tool can send it, because no tool that would is registered.
+  // Only a legacy key that was given is missing its tenant: with no key yet,
+  // nothing says one is needed, and a cap_ key never needs it.
+  if (!tenantId && apiKey && family === "legacy") missing.push("CAPA_TENANT_ID");
+
+  if (missing.length) {
+    // Each line says which key needs it, so a cap_ key's reader never goes
+    // hunting for a tenant id that changes nothing.
+    const keyLine = !apiKey
+      ? `  CAPA_KEY          a cap_ key from Developers > Keys, or a legacy key\n` +
+        `                    (or CAPA_API_KEY)\n`
+      : family === "cap"
+        ? `  CAPA_KEY          a cap_ key (or CAPA_API_KEY). Its scopes decide which tools register;\n` +
+          `                    the page tools need instance:read\n`
+        : `  CAPA_KEY          a tenant API key, or CAPA_API_KEY (read scope for the read tools;\n` +
+          `                    the workspace write tools need a key with write permission)\n`;
+    const tenantLine =
+      family === "cap" && apiKey
+        ? `  CAPA_TENANT_ID    not needed for a cap_ key: /api/ resolves the tenant\n` +
+          `                    from the key, and no legacy tool is registered\n`
+        : `  CAPA_TENANT_ID    legacy keys only (pk_, sk_ or unprefixed): the tenant the key belongs to\n`;
+    throw new Error(
+      `capa-mcp: missing ${missing.join(", ")}.\n` +
+        `  CAPA_API_URL      the API, e.g. https://api.capacms.com (or CAPA_BASE_URL)\n` +
+        keyLine +
+        tenantLine +
+        `  CAPA_API_VERSION  optional; the dated /api/ version, default ${DEFAULT_API_VERSION}`
+    );
+  }
+  const route = routeIn(baseUrl);
+  if (route) {
+    throw new Error(
+      `capa-mcp: CAPA_API_URL is the API's address with no route, e.g. https://api.capacms.com: drop ${route}.\n` +
+        "  Every tool adds the route it calls (/api/graphql, /api/entries), so a URL ending in one calls it twice.",
+    );
+  }
+  return { baseUrl, apiKey, tenantId, apiVersion, family };
+}
+
+/**
+ * The API route an address ends in, pasted with it: `/api`, `/api/graphql`,
+ * `/v2/api`. A path before the routes (a proxy's `/capa`) is the address.
+ */
+function routeIn(baseUrl) {
+  let path;
+  try {
+    path = new URL(baseUrl).pathname;
+  } catch {
+    return null;
+  }
+  const at = path.search(/\/(?:api|v2|v3)(?:\/|$)/);
+  return at === -1 ? null : path.slice(at);
+}
+
+/**
+ * How long one request may take, response body included, on every surface.
+ * `fetch` has no timeout of its own (undici gives up after about five
+ * minutes), and a tool call held open that long stalls the agent's whole
+ * turn. The API's own statement timeout is 5 seconds by default, so 25 leaves
+ * room for a slow network without letting a silent host hold the call.
+ * `config.requestTimeoutMs` overrides it (tests use a few hundred ms).
+ */
+export const REQUEST_TIMEOUT_MS = 25_000;
+
+/**
+ * What to do when Capa never answered, in the words every such error ends
+ * with: this client's own, and capa_explain_error's for one pasted from a
+ * site's log (error-guide.mjs).
+ */
+export const UNREACHABLE_NEXT =
+  "check that CAPA_API_URL is right and that the API is running and reachable from this machine, then retry.";
+export const TIMEOUT_NEXT =
+  "retry once, narrower if you can (fewer fields, a smaller first); if it times out again, the API at CAPA_API_URL is down or unreachable.";
+
+/**
+ * A request that never got an answer from Capa: the host refused the
+ * connection, its name did not resolve, TLS failed, or the connection closed
+ * mid-answer. `fetch` reports every one of those as a bare "fetch failed" and
+ * keeps the reason in `cause`, which is the part a person can act on, so the
+ * message names the host, that reason and the next step.
+ *
+ * `origin` is CAPA_API_URL's scheme, host and port, never its path or any
+ * credentials written into it.
+ */
+export class CapaUnreachable extends Error {
+  constructor({ method, path, origin, reason, midAnswer }) {
+    super(
+      midAnswer
+        ? `Capa at ${origin} closed the connection before ${method} ${path} finished (${reason}). ` +
+            "Next: retry once; if it happens again, the API at CAPA_API_URL is failing mid-answer."
+        : `Could not reach Capa at ${origin} for ${method} ${path} (${reason}). Next: ${UNREACHABLE_NEXT}`,
+    );
+    this.name = "CapaUnreachable";
+    this.origin = origin;
+    this.reason = reason;
+  }
+}
+
+/**
+ * What went wrong under `fetch`'s "fetch failed": the system code
+ * (ECONNREFUSED, ENOTFOUND, a TLS code) when there is one. A URL carrying a
+ * user name or password is refused by `fetch` before any connection, in a
+ * message that quotes the URL whole, so that case is named here instead.
+ */
+function transportReason(error, url) {
+  if (url.username || url.password) {
+    return "CAPA_API_URL carries a user name or password, which fetch refuses to send; remove them, the key goes in CAPA_KEY";
+  }
+  const cause = error?.cause;
+  return cause?.code ?? cause?.message ?? error?.message ?? String(error);
+}
+
+/**
+ * `fetch` plus reading the body as text, bounded by the request timeout, by
+ * `signal` when the caller has its own (the startup `/api/me` call does), and
+ * by `config.signal`, the tool call's, which the client aborts when it
+ * cancels the call. A caller's own abort surfaces as it was raised, so the
+ * caller can tell it apart; this file's timeout and a failed connection
+ * become errors naming the next step.
+ */
+async function boundedFetch(config, method, path, url, init) {
+  const timeoutMs = config.requestTimeoutMs ?? REQUEST_TIMEOUT_MS;
+  const timeout = AbortSignal.timeout(timeoutMs);
+  const own = [init.signal, config.signal].filter(Boolean);
+  const failed = (error, midAnswer) => {
+    if (own.some((signal) => signal.aborted)) return error;
+    if (timeout.aborted) {
+      return new Error(
+        `Capa did not answer ${method} ${path} within ${timeoutMs >= 1000 ? `${Math.round(timeoutMs / 1000)} seconds` : `${timeoutMs} ms`}. Next: ${TIMEOUT_NEXT}`,
+      );
+    }
+    const parsed = new URL(url);
+    return new CapaUnreachable({ method, path, origin: parsed.origin, reason: transportReason(error, parsed), midAnswer });
+  };
+  let res;
+  try {
+    res = await fetch(url, {
+      ...init,
+      method,
+      signal: own.length ? AbortSignal.any([...own, timeout]) : timeout,
+    });
+  } catch (error) {
+    throw failed(error, false);
+  }
+  try {
+    return { res, text: await res.text() };
+  } catch (error) {
+    throw failed(error, true);
+  }
+}
+
+/** Build the request URL + headers once, for both the JSON and text readers. */
+function prepare(config, path, query) {
+  const url = new URL(config.baseUrl + path);
+  for (const [k, v] of Object.entries(query)) {
+    if (v === undefined || v === null || v === "") continue;
+    url.searchParams.set(k, String(v));
+  }
+  return url;
+}
+
+/**
+ * GET an endpoint that returns text rather than JSON.
+ *
+ * /v2/schema/types serves `text/plain` — generated TypeScript source, not a
+ * JSON document — so apiGet's JSON.parse would reject a perfectly good
+ * response. Kept as a separate function rather than a flag on apiGet so the
+ * caller states which it expects and a content-type change surfaces as a
+ * failing test instead of a silent shape change.
+ */
+export async function apiGetText(config, path, query = {}) {
+  const url = prepare(config, path, query);
+  const { res, text } = await boundedFetch(config, "GET", path, url, {
+    headers: {
+      "x-api-key": config.apiKey,
+      "X-Tenant-Key": config.tenantId,
+      Accept: "text/plain, */*",
+    },
+  });
+  if (!res.ok) throw new CapaApiError(res.status, path, text);
+  return text;
+}
+
+export async function apiGet(config, path, query = {}) {
+  const url = prepare(config, path, query);
+  const { res, text } = await boundedFetch(config, "GET", path, url, {
+    headers: {
+      "x-api-key": config.apiKey,
+      "X-Tenant-Key": config.tenantId,
+      Accept: "application/json",
+    },
+  });
+  if (!res.ok) throw new CapaApiError(res.status, path, text);
+  try {
+    return JSON.parse(text);
+  } catch {
+    throw new CapaApiError(res.status, path, `response was not JSON: ${text.slice(0, 200)}`);
+  }
+}
+
+/**
+ * GET a route on the `/api/` surface — a SECOND request path, not a flag on
+ * `apiGet`, because the two surfaces differ in three ways a caller has to see.
+ *
+ *   NO `X-Tenant-Key`. `/api/` resolves the tenant from the key itself, so the
+ *   header is not merely unnecessary, it is a value this surface never reads.
+ *   Sending it would teach the next reader that a tenant id is part of an
+ *   `/api/` request, and it is not.
+ *
+ *   `Capa-Version`. Every `/api/` response is shaped by a dated version. Not
+ *   sending one means the key's stored pin decides, which makes the shape a
+ *   property of when the key was minted rather than of what this code expects.
+ *   One date from every environment is the point of the header.
+ *
+ *   `{ data, meta, page }`, not a bare body. `meta` carries the counters a
+ *   list's row array cannot hold (the window it measured, the cap, whether the
+ *   cap cut anything), and `page` an entry list's cursors, so every part comes
+ *   back rather than the caller being handed `data` and told the rest did not
+ *   exist.
+ *
+ * Errors are the `/api/` envelope, `{ error: { type, code, message, param,
+ * hint, docs } }`, and `code` plus `hint` are lifted onto `CapaApiError` so a
+ * tool can branch on the reason and hand the model the fix in one step.
+ */
+export async function apiNextGet(config, path, query = {}, init = {}) {
+  const url = prepare(config, path, query);
+  const { res, text } = await boundedFetch(config, "GET", path, url, {
+    headers: {
+      "x-api-key": config.apiKey,
+      "Capa-Version": config.apiVersion || DEFAULT_API_VERSION,
+      Accept: "application/json",
+    },
+    // `init.signal` is how the startup call bounds itself more tightly than
+    // the request timeout: it runs before the first client message is read.
+    signal: init.signal,
+  });
+  let body = null;
+  try {
+    body = text ? JSON.parse(text) : null;
+  } catch {
+    body = null;
+  }
+  if (!res.ok) {
+    const envelope = body && typeof body === "object" ? body.error : null;
+    // A non-object `error` is the LEGACY body shape (`{ error: "<string>" }`),
+    // which reaches here when a request lands on a stack that does not serve
+    // `/api/` at all. It has no code and no hint, and pretending otherwise
+    // would invent both.
+    throw new CapaApiError(
+      res.status,
+      path,
+      text,
+      envelope && typeof envelope === "object" ? envelope : undefined,
+    );
+  }
+  if (!body || typeof body !== "object") {
+    throw new CapaApiError(res.status, path, `response was not JSON: ${text.slice(0, 200)}`);
+  }
+  return { data: body.data, meta: body.meta ?? null, page: body.page ?? null };
+}
+
+/**
+ * A write verb behind the API key — POST, PUT, PATCH or DELETE.
+ *
+ * Deliberately a separate function from `apiGet` rather than a `method` flag on
+ * it: the two have different failure modes an agent has to distinguish. A 403
+ * here means "this key may read but not write", which is a fixable
+ * configuration fact, and the caller has to be able to say so without parsing a
+ * shared error message.
+ *
+ * The API's OWN message is preserved rather than replaced. `CapaApiError`
+ * carries the body, so `capa_set_workspace` can hand the model back exactly
+ * what the server said about the grant it lacked.
+ */
+export async function apiWrite(config, method, path, body) {
+  const url = new URL(config.baseUrl + path);
+  const { res, text } = await boundedFetch(config, method, path, url, {
+    headers: {
+      "x-api-key": config.apiKey,
+      "X-Tenant-Key": config.tenantId,
+      Accept: "application/json",
+      "Content-Type": "application/json",
+    },
+    body: body === undefined ? undefined : JSON.stringify(body),
+  });
+  if (!res.ok) throw new CapaApiError(res.status, path, text);
+  if (!text) return null;
+  try {
+    return JSON.parse(text);
+  } catch {
+    throw new CapaApiError(res.status, path, `response was not JSON: ${text.slice(0, 200)}`);
+  }
+}
+
+/**
+ * The status of a GraphQL request the API refused as a whole, however it was
+ * sent. GraphQL over HTTP answers the refusal 200 on `application/json`, which
+ * this client asks for, and 4xx on `application/graphql-response+json`
+ * (decision of 2026-09-25); every refusal it moves to a 200 is a 400 in the
+ * API's error table, so both read the same.
+ */
+export const REFUSED_STATUS = 400;
+
+/** GraphQL over HTTP: a refused request has `errors` and no `data` entry; a body with `data`, null included, ran. */
+function refusedWhole(body) {
+  return Array.isArray(body?.errors) && body.errors.length > 0 && !Object.hasOwn(body, "data");
+}
+
+/**
+ * POST JSON to the `/api/` surface: today only `/api/graphql`.
+ *
+ * The same three rules as `apiNextGet` (no `X-Tenant-Key`, `Capa-Version` on
+ * every call, the envelope's `code` and `hint` lifted onto the error), plus
+ * the one GraphQL adds: a request the API ran is an answer even when it
+ * carries `errors`, because the root fields that worked still carry data. So
+ * this returns the whole parsed body when the API ran the request, and throws
+ * `CapaApiError` when it refused it: any status but 2xx, or a 200 with
+ * `errors` and no `data`, which throws as the 400 it is on
+ * `application/graphql-response+json`.
+ *
+ * A refused GraphQL request answers `{ errors: [...] }` rather than the REST
+ * `{ error }` object, so the envelope is read from `errors[0].extensions` when
+ * that is what came back. `body` keeps every error for a caller that wants
+ * them all.
+ */
+export async function apiNextPost(config, path, payload, init = {}) {
+  const url = new URL(config.baseUrl + path);
+  const { res, text } = await boundedFetch(config, "POST", path, url, {
+    headers: {
+      "x-api-key": config.apiKey,
+      "Capa-Version": config.apiVersion || DEFAULT_API_VERSION,
+      Accept: "application/json",
+      "Content-Type": "application/json",
+    },
+    body: JSON.stringify(payload),
+    signal: init.signal,
+  });
+  let body = null;
+  try {
+    body = text ? JSON.parse(text) : null;
+  } catch {
+    body = null;
+  }
+  const refused = res.ok && refusedWhole(body);
+  if (!res.ok || refused) {
+    const first = Array.isArray(body?.errors) ? body.errors[0] : null;
+    const envelope = first
+      ? { code: first.extensions?.code, message: first.message, hint: first.extensions?.hint }
+      : body && typeof body.error === "object"
+        ? body.error
+        : undefined;
+    throw new CapaApiError(refused ? REFUSED_STATUS : res.status, path, text, envelope);
+  }
+  if (!body || typeof body !== "object") {
+    throw new CapaApiError(res.status, path, `response was not JSON: ${text.slice(0, 200)}`);
+  }
+  return body;
+}