@capacms/mcp 0.2.0 → 0.3.0

package/lib/client.mjs

@@ -87,11 +87,37 @@ export class CapaApiError extends Error {
  */
 export const DEFAULT_API_VERSION = "2026-10-01";
 
+/**
+ * The uploader Capa's hosted API pairs with: what the production admin uploads
+ * to (NEXT_PUBLIC_FILE_UPLOAD_SERVER_URL, infra/fly/fly.admin.toml and the
+ * live admin's bundle, 2026-10-03). It is the Fly app's own public address,
+ * as no capacms.com name points at the uploader yet.
+ *
+ * Used only when CAPA_API_URL is one of HOSTED_API_HOSTS over https and no
+ * CAPA_UPLOAD_URL is given. Any other API (local, self-hosted, a preview) gets
+ * no default, so a file is never sent to Capa's uploader with a ticket from
+ * somewhere else.
+ */
+export const HOSTED_UPLOAD_URL = "https://uploads.capacms.com";
+
+/** The hosts Capa's hosted API answers on (docs/LAUNCH.md), whose uploader is HOSTED_UPLOAD_URL. */
+export const HOSTED_API_HOSTS = ["api.capacms.com", "cdn.capacms.com", "capa-next-api.fly.dev", "capa-next-admin-api.fly.dev"];
+
+function hostedUploadUrl(baseUrl) {
+  try {
+    const url = new URL(baseUrl);
+    return url.protocol === "https:" && HOSTED_API_HOSTS.includes(url.hostname) ? HOSTED_UPLOAD_URL : "";
+  } catch {
+    return "";
+  }
+}
+
 /**
  * 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
+ * `cap_` keys are hashed at rest and accepted on `/api/`, and on `/v2/agent`
+ * only where the deployment says so in `GET /api/me`'s `surfaces`: every other
+ * legacy mount 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
@@ -144,15 +170,15 @@ export function loadConfig(env = process.env) {
   //
   // `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.
+  // first call. A `cap_` key reaches `/api/`, and `/v2/agent` where the
+  // deployment accepts it there: both resolve the tenant from the key itself
+  // and never read the header, and the registry gives a `cap_` key no tool on
+  // any other mount. 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.
+  // It is therefore EMPTY STRING in the returned config for a `cap_` key, and
+  // no request sends it for one whatever it holds (`tenantHeader` below).
   // 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");
@@ -175,7 +201,7 @@ export function loadConfig(env = process.env) {
         : `  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` +
+        `  CAPA_API_URL      the API, e.g. https://cdn.capacms.com (or CAPA_BASE_URL)\n` +
         keyLine +
         tenantLine +
         `  CAPA_API_VERSION  optional; the dated /api/ version, default ${DEFAULT_API_VERSION}`
@@ -184,11 +210,39 @@ export function loadConfig(env = process.env) {
   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` +
+      `capa-mcp: CAPA_API_URL is the API's address with no route, e.g. https://cdn.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 };
+  // Optional, both. Where files go (the uploader, a host of its own) and which
+  // folder the upload tool may read them from (media-tools.mjs). The first
+  // defaults to Capa's uploader for Capa's hosted API only; without one,
+  // capa_upload_media is not offered.
+  const uploadUrl = (env.CAPA_UPLOAD_URL || "").trim().replace(/\/+$/, "") || hostedUploadUrl(baseUrl);
+  if (uploadUrl && !/^https?:\/\/[^/]/.test(uploadUrl)) {
+    throw new Error(`capa-mcp: CAPA_UPLOAD_URL is the uploader's address, e.g. https://uploads.example.com; got ${uploadUrl}.`);
+  }
+  // The folder: CAPA_UPLOAD_ROOT when the person names one, else the project
+  // Claude Code names (CLAUDE_PROJECT_DIR), else the server's own folder.
+  // CAPA_UPLOAD_ALLOW names files the upload tool would otherwise refuse
+  // (hidden ones, keys and certificates), separated as PATH is.
+  const uploadRoot = (env.CAPA_UPLOAD_ROOT || "").trim();
+  const projectDir = (env.CLAUDE_PROJECT_DIR || "").trim();
+  const uploadAllow = String(env.CAPA_UPLOAD_ALLOW || "")
+    .split(process.platform === "win32" ? ";" : ":")
+    .map((entry) => entry.trim())
+    .filter(Boolean);
+  return {
+    baseUrl,
+    apiKey,
+    tenantId,
+    apiVersion,
+    family,
+    ...(uploadUrl ? { uploadUrl } : {}),
+    ...(uploadRoot ? { uploadRoot } : {}),
+    ...(projectDir ? { projectDir } : {}),
+    ...(uploadAllow.length ? { uploadAllow } : {}),
+  };
 }
 
 /**
@@ -250,6 +304,21 @@ export class CapaUnreachable extends Error {
   }
 }
 
+/**
+ * A request Capa did not answer within the request timeout. A class of its
+ * own, with the message every such error has always had, so a front end that
+ * sets an exit status (the `capa` CLI) can tell a silent host from a refusal
+ * without matching the words.
+ */
+export class CapaTimeout extends Error {
+  constructor({ method, path, timeoutMs }) {
+    super(
+      `Capa did not answer ${method} ${path} within ${timeoutMs >= 1000 ? `${Math.round(timeoutMs / 1000)} seconds` : `${timeoutMs} ms`}. Next: ${TIMEOUT_NEXT}`,
+    );
+    this.name = "CapaTimeout";
+  }
+}
+
 /**
  * What went wrong under `fetch`'s "fetch failed": the system code
  * (ECONNREFUSED, ENOTFOUND, a TLS code) when there is one. A URL carrying a
@@ -278,17 +347,17 @@ async function boundedFetch(config, method, path, url, init) {
   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}`,
-      );
-    }
+    if (timeout.aborted) return new CapaTimeout({ method, path, timeoutMs });
     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, {
+    // `config.fetch` is the hosted server's: it answers in-process, as the
+    // signed-in person (apps/api/src/hosted-mcp). Everything else is global
+    // `fetch`, which is what the stdio server always uses.
+    const send = config.fetch ?? fetch;
+    res = await send(url, {
       ...init,
       method,
       signal: own.length ? AbortSignal.any([...own, timeout]) : timeout,
@@ -303,6 +372,19 @@ async function boundedFetch(config, method, path, url, init) {
   }
 }
 
+/**
+ * `X-Tenant-Key`, for a legacy key only.
+ *
+ * The `/v2` and `/v3` mounts read it to find a legacy key's tenant. A `cap_`
+ * key reaches one of them, `/v2/agent`, where a deployment accepts it there
+ * (registry.mjs), and that mount resolves the tenant from the key's own row,
+ * as `/api/` does. So a `cap_` key never sends the header, even when
+ * CAPA_TENANT_ID happens to be set: a value the route does not read is not
+ * part of the request. A config with no family is a legacy one, as it was
+ * before the family existed.
+ */
+const tenantHeader = (config) => (config.family === "cap" ? {} : { "X-Tenant-Key": config.tenantId });
+
 /** 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);
@@ -327,7 +409,7 @@ export async function apiGetText(config, path, query = {}) {
   const { res, text } = await boundedFetch(config, "GET", path, url, {
     headers: {
       "x-api-key": config.apiKey,
-      "X-Tenant-Key": config.tenantId,
+      ...tenantHeader(config),
       Accept: "text/plain, */*",
     },
   });
@@ -340,7 +422,7 @@ export async function apiGet(config, path, query = {}) {
   const { res, text } = await boundedFetch(config, "GET", path, url, {
     headers: {
       "x-api-key": config.apiKey,
-      "X-Tenant-Key": config.tenantId,
+      ...tenantHeader(config),
       Accept: "application/json",
     },
   });
@@ -431,7 +513,7 @@ export async function apiWrite(config, method, path, body) {
   const { res, text } = await boundedFetch(config, method, path, url, {
     headers: {
       "x-api-key": config.apiKey,
-      "X-Tenant-Key": config.tenantId,
+      ...tenantHeader(config),
       Accept: "application/json",
       "Content-Type": "application/json",
     },

package/lib/connect.mjs

@@ -0,0 +1,67 @@
+/**
+ * connect.mjs — what the server learns before it reads a message, as one
+ * function every front end calls: the stdio bin, and the `capa` CLI, which
+ * runs these same tools as commands and `capa mcp`, which serves them.
+ *
+ * One `/api/me` call and three probes, before any client message is read.
+ * They are what turn the key's family and scopes, and the deployment's
+ * features, into the tool list (registry.mjs), and a client reads that list
+ * once at startup: deciding later would mean advertising tools and then
+ * changing our mind about them mid-session.
+ *
+ * `notes` are the lines the person running the server reads on stderr, in
+ * the order and the words the bin has always written them: why `/api/me` did
+ * not answer, which features the deployment does not serve, and which tools
+ * the key's scopes leave out. Returned rather than written, so a CLI can show
+ * them where its own errors go and a test can read them.
+ */
+import { agentSurface, loadMe, probeGraphQL, probePages, probeRestOnly, probeUploads, scopeNote, selectTools } from "./registry.mjs";
+
+/**
+ * `config` is `loadConfig()`'s. Returns `{ ctx, me, deployment, notes }`:
+ * `ctx` is what `dispatch`, `runTool` and `createSession` take; `me` is the
+ * `/api/me` body, or null when it did not answer; `deployment` is what the
+ * probes found.
+ */
+export async function connect(config) {
+  const [me, pages, graphql, restOnly, media] = await Promise.all([
+    loadMe(config),
+    probePages(config),
+    probeGraphQL(config),
+    probeRestOnly(config),
+    probeUploads(config),
+  ]);
+  const { uploads, mediaList } = media;
+  const notes = [];
+  // For a cap_ key the line also says the model and workspace tools are left out (registry.mjs loadMe).
+  if (!me.ok) notes.push(`capa-mcp: ${me.reason}`);
+  // Only an answering /api/ says anything about its features: without one, every /api/ tool registers and reports the real error.
+  const deployment = { pages: me.ok ? pages : null, graphql: me.ok ? graphql : null, restOnly, uploads, mediaList };
+  if (deployment.pages === false) {
+    notes.push("capa-mcp: this deployment does not serve /api/pages (CAPA_SITE_PREVIEW is off), so the page tools are not registered.");
+  }
+  // Said only where a cap_ key reaches /v2/agent: elsewhere no media tool was ever in reach.
+  if (uploads === false && me.ok && agentSurface(me.me) === true) {
+    notes.push(
+      "capa-mcp: this deployment does not take uploads with an API key (CAPA_AGENT_UPLOADS is off), so capa_list_media and capa_upload_media are not registered.",
+    );
+  }
+  if (uploads === true && mediaList === false && me.ok && agentSurface(me.me) === true) {
+    notes.push(
+      "capa-mcp: capa_list_media is not offered: this key reads published content only (a production key that may neither upload nor write entries), and the file list is for keys that can.",
+    );
+  }
+  const tools = selectTools(config, me.me, deployment);
+  // One line per reason: the key's scopes, and for a cap_ key a deployment that does not say it accepts one on /v2/agent.
+  const scoped = scopeNote(config, me.me, deployment);
+  if (scoped) notes.push(scoped);
+  if (deployment.graphql === false) {
+    const instead = tools.some((tool) => tool.name === "capa_read_entries") ? " capa_read_entries reads the same entries over REST instead." : "";
+    notes.push(`capa-mcp: this deployment does not serve /api/graphql (CAPA_API_GRAPHQL is off), so the GraphQL tools are not registered.${instead}`);
+  }
+  if (deployment.graphql !== false && restOnly.length && tools.some((tool) => tool.name === "capa_read_entries")) {
+    notes.push(`capa-mcp: GraphQL leaves out ${restOnly.join(", ")} (their type names collide), so capa_read_entries is registered to read them over REST.`);
+  }
+  const ctx = { config: me.apiMissing ? { ...config, apiMissing: true } : config, tools };
+  return { ctx, me: me.ok ? me.me : null, deployment, notes };
+}