@capacms/mcp 0.2.1 → 0.3.0

package/lib/media-tools.mjs

@@ -0,0 +1,311 @@
+/**
+ * media-tools.mjs — a key's files: list them, and upload one from disk.
+ *
+ * NAMES, DESCRIPTIONS AND SCHEMAS ARE PROVISIONAL. The tool-calls lane owns
+ * them and may rename or reword them; the `capa` CLI reads them from here.
+ *
+ *   capa_list_media    GET /v2/agent/file-uploads (media:read)
+ *   capa_upload_media  POST /v2/agent/file-uploads/ticket (media:create),
+ *                      then the file to the uploader's /upload with the
+ *                      ticket as its bearer token. The key never goes to the
+ *                      uploader.
+ *
+ * Both are `capOnly` agent tools, offered only where the deployment SAYS it
+ * takes API key uploads (`onlyWhen`): the startup probe (registry.mjs
+ * `probeUploads`) asks the list route, which answers 404
+ * `agent_uploads_disabled` while `CAPA_AGENT_UPLOADS` is off. Unlike pages and
+ * GraphQL, an unsure probe leaves them out: a deployment older than the list
+ * route, or with the switch off (the default), would refuse every call. The
+ * list is also left out for a key the route refuses by its view: a
+ * production key that may neither upload nor write entries in every model
+ * gets the published view there (per surface since #366), and the file list
+ * has none. The upload also needs the uploader's address (the host the admin
+ * uploads to): CAPA_UPLOAD_URL, which Capa's hosted API defaults (client.mjs
+ * HOSTED_UPLOAD_URL). Without one the tool is left out and a line on stderr
+ * says so, rather than registering a tool that always fails. A production key
+ * holding `media:create` uploads like any other, as the API takes it since
+ * #349, and lists the files too since #366.
+ *
+ * A file row is the value an image, video or file field takes, whole, so both
+ * tools hand rows back as the API stores them and say so in `next`.
+ *
+ * WHICH FILES MAY BE UPLOADED. The server reads a path from the agent, so a
+ * prompt the agent read somewhere could ask for ~/.ssh/id_rsa. A path must
+ * resolve, symlinks followed, inside the upload folder: CAPA_UPLOAD_ROOT when
+ * the person sets it, else CLAUDE_PROJECT_DIR (the project Claude Code
+ * names), else the folder the server was started in. A folder nobody chose
+ * that is the home folder or holds it (/, /Users) is refused outright: an
+ * agent client started from there would put every file the person has in
+ * reach. Folders are compared by the name the disk gives them, so on a disk
+ * that does not tell cases apart (macOS, Windows) /users/me is still the home
+ * folder. Within the folder, no part of the path may start with a dot (.env,
+ * .git, .npmrc), and no file may be named like a private key or certificate
+ * (id_rsa*, *.pem, *.key, *.p12, *.pfx, *.ppk, *.p8, *.jks, *.keystore,
+ * *.gpg, and their backups such as server.pem.bak or privkey.pem~), unless
+ * CAPA_UPLOAD_ALLOW, which only the person sets, names it.
+ */
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { reads, writes } from "./annotations.mjs";
+import { apiGet, apiWrite, CapaApiError } from "./client.mjs";
+
+/** The uploader can take a while for a large file; the API's 25 seconds is for API calls. */
+const UPLOAD_TIMEOUT_MS = 5 * 60_000;
+
+const FIELD_NEXT =
+  "To use a file in an entry, put the whole file object in an image, video or file field: capa_update_entry { id, data: { <field>: <file> } }.";
+
+const TYPES = ["image", "video", "file", "audio", "document", "pdf"];
+
+const MIME = {
+  ".png": "image/png",
+  ".jpg": "image/jpeg",
+  ".jpeg": "image/jpeg",
+  ".gif": "image/gif",
+  ".webp": "image/webp",
+  ".avif": "image/avif",
+  ".svg": "image/svg+xml",
+  ".pdf": "application/pdf",
+  ".mp4": "video/mp4",
+  ".mov": "video/quicktime",
+  ".webm": "video/webm",
+  ".mp3": "audio/mpeg",
+  ".wav": "audio/wav",
+};
+
+/** The 403 a published-view key gets on an agent route with no published view (apps/api middleware/agentView.ts). */
+export const AGENT_ROUTE_NEEDS_DRAFT_ACCESS = "agent_route_needs_draft_access";
+
+/**
+ * Names a private key or certificate goes by, and their backups and editor
+ * copies (server.pem.bak, privkey.pem~, "key.pem " with a trailing space).
+ * Hidden ones (.npmrc, .env*) are refused as hidden.
+ */
+const KEY_FILE = /^id[-_](rsa|dsa|ecdsa|ed25519)|\.(pem|key|p12|pfx|ppk|p8|jks|keystore|gpg)(\.|~|\s|$)/i;
+
+function apiMessage(error) {
+  try {
+    const body = JSON.parse(error.body);
+    if (typeof body?.error === "string") return { error: body.error, code: body.code ?? null };
+  } catch {
+    // Not JSON: the status line is the message.
+  }
+  return { error: error.message, code: error.code ?? null };
+}
+
+/** Is `inner` the folder `outer`, or inside it? */
+const within = (inner, outer) => {
+  const relative = path.relative(outer, inner);
+  return relative === "" || (!relative.startsWith("..") && !path.isAbsolute(relative));
+};
+
+/**
+ * The path as the disk names it, symlinks followed. `.native` gives the case
+ * the disk stores: on a disk that does not tell cases apart, the JS
+ * `realpathSync` keeps the case it was typed in, and /users/me would not be
+ * the home folder /Users/me.
+ */
+const realOr = (file) => {
+  try {
+    return fs.realpathSync.native(path.resolve(file));
+  } catch {
+    return path.resolve(file);
+  }
+};
+
+/**
+ * The folder files are read from: `{ root }`, or `{ refusal }` when nobody
+ * chose it and it is the home folder or holds it. See WHICH FILES above.
+ */
+export function uploadFolder(config) {
+  if (config.uploadRoot) return { root: config.uploadRoot };
+  const root = config.projectDir || config.cwd || process.cwd();
+  const real = realOr(root);
+  const home = [config.home, os.homedir()].filter(Boolean).map(realOr).find((dir) => within(dir, real));
+  if (home) {
+    return {
+      refusal: {
+        error: `Files are read from ${real}, which ${real === home ? "is" : "holds"} the home folder ${home}, so none is uploaded: any of your files could be named.`,
+        hint: "Start the agent from the project's folder, or set CAPA_UPLOAD_ROOT to the folder files may be uploaded from.",
+      },
+    };
+  }
+  return { root };
+}
+
+/**
+ * The file at `given`, if the server may read it: `{ file, name }`, or
+ * `{ refusal }`. `allow` lists files the person named in CAPA_UPLOAD_ALLOW,
+ * which may be hidden or named like a key; they must still be in the folder.
+ */
+export function uploadable(given, root, allow = []) {
+  const base = fs.realpathSync.native(path.resolve(root));
+  let real;
+  try {
+    real = fs.realpathSync.native(path.resolve(base, given));
+  } catch {
+    return { refusal: { error: `No file at ${given}.`, hint: `Paths are read from ${base}.` } };
+  }
+  const relative = path.relative(base, real);
+  if (relative === "" || relative.startsWith("..") || path.isAbsolute(relative)) {
+    return {
+      refusal: {
+        error: `${given} is outside ${base}, the folder files are uploaded from.`,
+        hint: "Copy the file into the project first, or start the server with CAPA_UPLOAD_ROOT set to its folder.",
+      },
+    };
+  }
+  const named = allow.some((entry) => realOr(path.resolve(base, entry)) === real);
+  if (!named && relative.split(path.sep).some((part) => part.startsWith("."))) {
+    return {
+      refusal: {
+        error: `${given} is under a hidden name, which is never uploaded: hidden files and folders (.env, .git, .ssh) hold secrets.`,
+        hint: "To upload it anyway, the person running the agent names it in CAPA_UPLOAD_ALLOW.",
+      },
+    };
+  }
+  if (!named && KEY_FILE.test(path.basename(real))) {
+    return {
+      refusal: {
+        error: `${given} looks like a private key or certificate (id_rsa*, *.pem, *.key, *.p12, *.pfx, *.ppk, *.p8, *.jks, *.keystore, *.gpg, or a backup of one), so it is not uploaded.`,
+        hint: "To upload it anyway, the person running the agent names it in CAPA_UPLOAD_ALLOW.",
+      },
+    };
+  }
+  if (!fs.statSync(real).isFile()) return { refusal: { error: `${given} is not a file.` } };
+  return { file: real, name: path.basename(real) };
+}
+
+export const MEDIA_TOOLS = [
+  {
+    name: "capa_list_media",
+    ...reads("List media files"),
+    surface: "agent",
+    capOnly: true,
+    onlyWhen: "mediaList",
+    scope: "media:read",
+    cutHint: "Pass search, type or a smaller size, or the next page.",
+    description:
+      "The project's media files, newest first: images, videos, documents. Each file object is the value an image, " +
+      "video or file field takes, so pass one whole to capa_update_entry or capa_create_entry. search matches part " +
+      "of the file name; type narrows to image, video, file, audio, document (PDFs included) or pdf.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        search: { type: "string", description: "Part of the file name, any case." },
+        type: { type: "string", enum: TYPES, description: "One kind of file." },
+        folderId: { type: "string", description: "One media folder's files." },
+        page: { type: "integer", minimum: 1, description: "From 1." },
+        size: { type: "integer", minimum: 1, maximum: 100, description: "Files per page, 1 to 100. Default 25." },
+      },
+      additionalProperties: false,
+    },
+    handler: async (config, args) => {
+      try {
+        const res = await apiGet(config, "/v2/agent/file-uploads", {
+          search: args.search,
+          type: args.type,
+          folderId: args.folderId,
+          page: args.page,
+          size: args.size,
+        });
+        const pagination = res?.pagination ?? {};
+        return {
+          files: res?.data ?? [],
+          total: pagination.total ?? null,
+          page: pagination.currentPage ?? null,
+          hasNextPage: Boolean(pagination.hasNextPage),
+          next: FIELD_NEXT,
+        };
+      } catch (error) {
+        if (error instanceof CapaApiError && (error.status === 400 || error.status === 403 || error.status === 404)) {
+          const { error: message, code } = apiMessage(error);
+          const hint =
+            code === AGENT_ROUTE_NEEDS_DRAFT_ACCESS
+              ? "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: use a key that also holds media:create or can write entries in every model, or a development key."
+              : error.status === 403
+                ? "Listing files needs a key holding media:read."
+                : null;
+          return { error: message, ...(code ? { code } : {}), ...(hint ? { hint } : {}) };
+        }
+        throw error;
+      }
+    },
+  },
+
+  {
+    name: "capa_upload_media",
+    // Adds a file and replaces nothing: a second call makes a second file.
+    ...writes("Upload a media file", { idempotent: false, destructive: false }),
+    surface: "agent",
+    capOnly: true,
+    onlyWhen: "uploads",
+    requires: "uploadUrl",
+    scope: "media:create",
+    cutHint: "The file is uploaded; capa_list_media finds it by name.",
+    description:
+      "Upload one file from this machine to the project's media, and answer its file object, which is the value an " +
+      "image, video or file field takes. path is relative to the project folder, and must be inside it; hidden " +
+      "files and folders, and files named like a private key or certificate, are not read. The file gets every check an upload in the admin gets (type, size, " +
+      "the storage limit). WRITES: it needs a key holding media:create.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        path: { type: "string", description: "The file, relative to the project folder, e.g. public/hero.jpg." },
+        folderId: { type: "string", description: "A media folder to put it in." },
+        isPublic: { type: "boolean", description: "Mark the file public. Default false, as in the admin." },
+      },
+      required: ["path"],
+      additionalProperties: false,
+    },
+    handler: async (config, args) => {
+      const folder = uploadFolder(config);
+      if (folder.refusal) return { uploaded: false, ...folder.refusal };
+      const target = uploadable(args.path, folder.root, config.uploadAllow ?? []);
+      if (target.refusal) return { uploaded: false, ...target.refusal };
+      let ticket;
+      try {
+        ticket = await apiWrite(config, "POST", "/v2/agent/file-uploads/ticket", {});
+      } catch (error) {
+        if (error instanceof CapaApiError && (error.status === 403 || error.status === 404)) {
+          const { error: message, code } = apiMessage(error);
+          return { error: message, ...(code ? { code } : {}), uploaded: false };
+        }
+        throw error;
+      }
+      const form = new FormData();
+      const blob = await fs.openAsBlob(target.file, { type: MIME[path.extname(target.name).toLowerCase()] ?? "application/octet-stream" });
+      form.append("file", blob, target.name);
+      if (args.folderId) form.append("folderId", args.folderId);
+      if (args.isPublic !== undefined) form.append("isPublic", String(Boolean(args.isPublic)));
+      // `wait=true`: answer once the bytes are stored, so the URL works when the agent uses it.
+      const url = new URL(`${config.uploadUrl}${ticket?.uploadPath ?? "/upload"}`);
+      url.searchParams.set("wait", "true");
+      const res = await fetch(url, {
+        method: "POST",
+        headers: { authorization: `Bearer ${ticket.ticket}` },
+        body: form,
+        signal: AbortSignal.timeout(config.uploadTimeoutMs ?? UPLOAD_TIMEOUT_MS),
+      });
+      const text = await res.text();
+      let body = null;
+      try {
+        body = JSON.parse(text);
+      } catch {
+        body = null;
+      }
+      if (!res.ok) {
+        return {
+          uploaded: false,
+          error: typeof body?.error === "string" ? body.error : `The uploader answered ${res.status}.`,
+          ...(body?.code ? { code: body.code } : {}),
+          ...(body?.reason ? { reason: body.reason } : {}),
+        };
+      }
+      const file = Array.isArray(body?.data) ? body.data[0] : null;
+      if (!file) return { uploaded: false, error: "The uploader answered without a file." };
+      return { uploaded: true, file, next: FIELD_NEXT };
+    },
+  },
+];

package/lib/registry.mjs

@@ -10,17 +10,29 @@
  *
  * THE RULE, in one sentence per family:
  *
- *   cap_        `/api/` only. The legacy tools are not registered at all,
- *               because the surface they call refuses the prefix.
- *   pk_ / sk_   both. Every legacy tool registers as before, and the `/api/`
- *               tools register too, because `/api/` accepts a legacy key and
- *               derives its scope list from the key's bundle.
- *
- * Then the scope filter, which applies to `/api/` tools only: `GET /api/me`
- * reports the scopes a key holds, and a tool whose `scope` is not among them is
- * left out. A tool that is registered and always answers 403 teaches an agent
- * to stop trying, which is the same reasoning that keeps unbuilt write tools
- * absent rather than stubbed.
+ *   cap_        `/api/`, plus `/v2/agent` where `GET /api/me` lists it among
+ *               the key's `surfaces`. The tools that read `/v2/schema`,
+ *               `/v2/api` or `/v2/schema/types` are not registered at all,
+ *               because those mounts refuse the prefix on every deployment.
+ *   pk_ / sk_   all. Every legacy and agent tool registers as before, and the
+ *               `/api/` tools register too, because `/api/` accepts a legacy
+ *               key and derives its scope list from the key's bundle. The
+ *               exception is a `capOnly` agent tool (the entry writes, added
+ *               after 0.2.1): a legacy key's list stays the one it had.
+ *
+ * `/v2/agent` accepts a `cap_` key only on a deployment that switched that on,
+ * and `/api/me` is how this server learns it: `surfaces` holds "/v2/agent"
+ * there and not elsewhere. A deployment that lists no `surfaces` (it hides
+ * them, or predates them) says nothing, and nothing is not a yes, so the agent
+ * tools stay out for a `cap_` key until a deployment says so.
+ *
+ * Then the scope filter, for the `/api/` tools and for a `cap_` key's agent
+ * tools: `GET /api/me` reports the scopes a key holds, and a tool whose `scope`
+ * is not among them is left out. A tool that is registered and always answers
+ * 403 teaches an agent to stop trying, which is the same reasoning that keeps
+ * unbuilt write tools absent rather than stubbed. A legacy key's agent tools
+ * are not filtered, which keeps its list what it was: its permission gates
+ * them, and each write answers a 403 with the fix.
  *
  * Then the deployment filter, for the two features a deployment can switch
  * off. `/api/pages` and its siblings sit behind `CAPA_SITE_PREVIEW`, which is
@@ -30,11 +42,14 @@
  * ask once at startup, and a tool whose `feature` the deployment does not
  * serve is left out, for the same reason a tool that always answers 403 is.
  * A tool that stands in for a feature (`whenOff`, capa_read_entries for
- * GraphQL) is registered only where the probe found the feature off, or,
- * with a description of its own (`besideGraphQL`), where GraphQL is served
- * and leaves some of the key's models out: REST is the only way to read them.
+ * GraphQL) is registered for a legacy key only where the probe found the
+ * feature off, or, with a description of its own (`besideGraphQL`), where
+ * GraphQL is served and leaves some of the key's models out: REST is the only
+ * way to read them. A `cap_` key gets capa_read_entries wherever its scopes
+ * allow, described for reading beside GraphQL (`capDescription`), since it
+ * has no legacy content tool to read with instead.
  *
- * WHEN `/api/me` DOES NOT ANSWER, THE TOOLS REGISTER ANYWAY. Two real cases
+ * WHEN `/api/me` DOES NOT ANSWER, THE `/api/` TOOLS REGISTER ANYWAY. Two real cases
  * produce that: a deployment with the `/api/` surface switched off answers 404
  * on every path under it, and a machine with no route to the host answers
  * nothing at all. Neither is evidence about what the key may do. Dropping the
@@ -42,11 +57,15 @@
  * which is the wrong thing for an agent to conclude and an impossible one for a
  * person to debug from the tool list. So they register, the first call carries
  * the real error, and the reason goes to stderr where the person running the
- * server can read it.
+ * server can read it. A `cap_` key's agent tools are the exception: without
+ * an answer nothing says the deployment accepts the key on `/v2/agent`, and
+ * every legacy mount refuses it by default, so they stay out and the stderr
+ * line says why.
  */
-import { apiNextGet, apiNextPost, CapaApiError, CapaUnreachable } from "./client.mjs";
+import { apiGet, apiNextGet, apiNextPost, CapaApiError, CapaUnreachable } from "./client.mjs";
 import { loadSchema } from "./graphql/schema.mjs";
 import { graphqlNotServed } from "./graphql/served.mjs";
+import { AGENT_ROUTE_NEEDS_DRAFT_ACCESS } from "./media-tools.mjs";
 import { TOOLS } from "./tools.mjs";
 
 /**
@@ -61,6 +80,25 @@ import { TOOLS } from "./tools.mjs";
  */
 const ME_TIMEOUT_MS = 5000;
 
+/** What `GET /api/me` lists among a `cap_` key's `surfaces` where the deployment accepts it on the agent surface. */
+export const AGENT_SURFACE = "/v2/agent";
+
+/** The tools whose every call goes to `/v2/agent`. */
+// Not the media tools (`onlyWhen`): they wait on a probe that says yes, so no `/api/me` answer could bring them.
+const AGENT_TOOL_NAMES = TOOLS.filter((tool) => tool.surface === "agent" && !tool.onlyWhen).map((tool) => tool.name);
+
+/** The scopes `/api/me` reports, or null where the deployment does not report them. */
+const scopesOf = (me) => (Array.isArray(me?.scopes) ? me.scopes : null);
+
+/**
+ * Whether `/api/me` says this key reaches `/v2/agent`: true, false (it lists
+ * surfaces without it), or null (it lists none, so it does not say).
+ */
+export const agentSurface = (me) => (Array.isArray(me?.surfaces) ? me.surfaces.includes(AGENT_SURFACE) : null);
+
+/** The scopes a tool asks for, any one of which will do. */
+const scopesFor = (tool) => (Array.isArray(tool.scope) ? tool.scope : [tool.scope]);
+
 /**
  * Ask `/api/me` what this key is and what it holds.
  *
@@ -99,7 +137,11 @@ export async function loadMe(config, { timeoutMs = ME_TIMEOUT_MS } = {}) {
       apiMissing: error instanceof CapaApiError && error.status === 404,
       reason:
         `${why}. The /api/ tools are registered anyway, so a call to one reports the real ` +
-        `error instead of the tool silently not existing.`,
+        `error instead of the tool silently not existing.` +
+        (config?.family === "cap"
+          ? ` The model, workspace and entry tools (${inWords(AGENT_TOOL_NAMES)}) are not: nothing says this ` +
+            `deployment accepts a cap_ key on ${AGENT_SURFACE}.`
+          : ""),
     };
   }
 }
@@ -166,6 +208,46 @@ export async function probeRestOnly(config, { timeoutMs = ME_TIMEOUT_MS } = {})
   }
 }
 
+/**
+ * What the file list told this key: `{ uploads, mediaList }`.
+ *
+ * `uploads` is whether this deployment takes uploads with an API key: `true`,
+ * `false`, or `null` when the probe could not tell, and `null` without asking
+ * for a legacy key, which is offered no media tool whatever the answer.
+ * `mediaList` is whether the list is this key's to call, as far as the probe
+ * shows: `false` where it is off, and where it answered 403
+ * `agent_route_needs_draft_access`, which a key in the published view gets
+ * (a production key that may neither upload nor write entries, #294 and
+ * #354, per surface since #366).
+ *
+ * Asked of the file list, `GET /v2/agent/file-uploads?size=1`, whose first
+ * check is the switch: with `CAPA_AGENT_UPLOADS` off it answers 404
+ * `agent_uploads_disabled` before it looks at the key. Any other answer, a 403
+ * included, means the switch is on. A 403 for a missing scope leaves the list
+ * to the scope check, which names the scope in its note. A deployment older
+ * than the route answers a plain 404, which says nothing, so neither tool is
+ * offered (`onlyWhen` wants a yes).
+ */
+export async function probeUploads(config, { timeoutMs = ME_TIMEOUT_MS } = {}) {
+  const unsure = { uploads: null, mediaList: null };
+  if (config?.family !== "cap") return unsure;
+  try {
+    await apiGet({ ...config, requestTimeoutMs: timeoutMs }, "/v2/agent/file-uploads", { size: 1 });
+    return { uploads: true, mediaList: true };
+  } catch (error) {
+    if (!(error instanceof CapaApiError)) return unsure;
+    let code = null;
+    try {
+      code = JSON.parse(error.body)?.code ?? null;
+    } catch {
+      code = null;
+    }
+    if (error.status === 404) return code === "agent_uploads_disabled" ? { uploads: false, mediaList: false } : unsure;
+    if (error.status === 403 && code === AGENT_ROUTE_NEEDS_DRAFT_ACCESS) return { uploads: true, mediaList: false };
+    return { uploads: true, mediaList: true };
+  }
+}
+
 /**
  * The tools this key gets.
  *
@@ -184,18 +266,36 @@ export function selectTools(config, me, deployment = {}) {
   // "this deployment is not telling", not "this key holds none". Filtering on
   // an empty list there would drop every `/api/` tool on a stack where they all
   // work.
-  const scopes = Array.isArray(me?.scopes) ? me.scopes : null;
-  const besideGraphQL = (tool) => Boolean(tool.besideGraphQL) && deployment[tool.whenOff] !== false && deployment.restOnly?.length > 0;
+  const scopes = scopesOf(me);
+  // Compared WHOLE, not by prefix: the page routes ask for unscoped
+  // `instance:read`, and a key holding only `instance:read:<modelId>` is
+  // refused there because a page list spans every model a page touches. The
+  // agent routes ask the same way ("model:read" anywhere), so a one-model
+  // grant does not answer them either.
+  const holds = (tool) => scopesFor(tool).some((scope) => scopes.includes(scope));
+  const off = (tool) => deployment[tool.whenOff] === false;
+  const besideGraphQL = (tool) => Boolean(tool.besideGraphQL) && !off(tool) && deployment.restOnly?.length > 0;
   const registered = TOOLS.filter((tool) => {
     // Answers from this package alone, so every key gets it.
     if (tool.surface === "local") return true;
     if (tool.surface === "legacy") return family === "legacy";
+    if (tool.surface === "agent") {
+      // A tool added after 0.2.1 for the scoped family only (`capOnly`, the
+      // entry writes): a legacy key's list stays the one it was pinned at, so
+      // nobody running a pk_ or sk_ key gets new tools by upgrading.
+      if (family === "legacy") return !tool.capOnly;
+      if (agentSurface(me) !== true) return false;
+      // The media tools: only where the deployment said it takes API key
+      // uploads (probeUploads; unsure is no), the list only where it did not
+      // refuse this key's view, and the upload only with an uploader address
+      // to send the file to.
+      if (tool.onlyWhen && deployment[tool.onlyWhen] !== true) return false;
+      if (tool.requires && !config?.[tool.requires]) return false;
+      return !scopes || holds(tool);
+    }
     if (tool.feature && deployment[tool.feature] === false) return false;
-    if (tool.whenOff && deployment[tool.whenOff] !== false && !besideGraphQL(tool)) return false;
-    // Compared WHOLE, not by prefix: the page routes ask for unscoped
-    // `instance:read`, and a key holding only `instance:read:<modelId>` is
-    // refused there because a page list spans every model a page touches.
-    if (tool.scope && scopes) return scopes.includes(tool.scope);
+    if (tool.whenOff && family === "legacy" && !off(tool) && !besideGraphQL(tool)) return false;
+    if (tool.scope && scopes) return holds(tool);
     // By prefix, for the GraphQL tools: `/api/graphql` serves any key that can
     // read at least one model, and shows it only those models, so a one-model
     // `instance:read:<modelId>` key gets them and sees one model.
@@ -204,32 +304,100 @@ export function selectTools(config, me, deployment = {}) {
     }
     return true;
   });
-  return registered.map((tool) => (besideGraphQL(tool) ? { ...tool, description: tool.besideGraphQL } : tool));
+  const describe = (tool) => {
+    if (besideGraphQL(tool)) return tool.besideGraphQL;
+    // A stand-in where its feature is off keeps the words for that, whichever the family.
+    if (family === "cap" && tool.capDescription && !(tool.whenOff && off(tool))) return tool.capDescription;
+    return tool.description;
+  };
+  return registered.map((tool) => {
+    const description = describe(tool);
+    return description === tool.description ? tool : { ...tool, description };
+  });
+}
+
+/**
+ * The upload tool, where everything but the uploader's address would offer it:
+ * the person running the server is told which variable brings it.
+ */
+function uploadLine(config, me, deployment = {}) {
+  if (config?.family !== "cap" || !me || config.uploadUrl) return null;
+  const would = selectTools({ ...config, uploadUrl: "set" }, me, deployment).filter((tool) => tool.requires === "uploadUrl");
+  if (!would.length) return null;
+  return (
+    `capa-mcp: CAPA_UPLOAD_URL is not set, so ${inWords(would.map((tool) => tool.name))} is not offered: ` +
+    "it is the address of the uploader, the host the Capa admin sends files to. Only Capa's hosted API has a default."
+  );
 }
 
 /** `a`, `a and b`, `a, b and c`. */
 const inWords = (names) => (names.length < 2 ? names.join("") : `${names.slice(0, -1).join(", ")} and ${names.at(-1)}`);
 
+/** `a`, `a or b`, `a, b or c`. */
+const orWords = (names) => (names.length < 2 ? names.join("") : `${names.slice(0, -1).join(", ")} or ${names.at(-1)}`);
+
+/** What a tool needs, in words: its scope, its prefix, or `either a or b` for a tool any of two scopes serves. */
+const neededBy = (tool) => {
+  if (!tool.scope) return tool.scopePrefix;
+  const any = scopesFor(tool);
+  return any.length === 1 ? any[0] : `either ${orWords(any)}`;
+};
+
 /**
- * One line for the person running the server when the key's scopes leave
- * tools out, naming the scope those tools need, or null when they leave none
- * out. A key holding only `media:read` would otherwise start with
- * capa_explain_error alone and nothing to say why.
+ * What the person running the server is told about tools this key is not
+ * offered, as one `capa-mcp:` line per reason, or null when nothing is left
+ * out that the key could have. Two reasons have lines:
+ *
+ *   SCOPES. The key's scopes leave tools out: the line names the scope those
+ *   tools need. A key holding only `media:read` would otherwise start with
+ *   capa_explain_error alone and nothing to say why.
+ *
+ *   /v2/agent. A `cap_` key on a deployment that does not say it accepts one
+ *   there gets no model or workspace tool: the line names the ones its scopes
+ *   would get, and what they need, which is a deployment and not a scope. It
+ *   names no server switch: the person reading it may not run the server, and
+ *   a switch name is the deployment's business. When `/api/me` did not answer
+ *   at all, `loadMe`'s line says this instead.
  */
 export function scopeNote(config, me, deployment = {}) {
-  const scopes = Array.isArray(me?.scopes) ? me.scopes : null;
+  const lines = [scopeLine(config, me, deployment), agentLine(config, me, deployment), uploadLine(config, me, deployment)].filter(Boolean);
+  return lines.length ? lines.join("\n") : null;
+}
+
+function scopeLine(config, me, deployment) {
+  const scopes = scopesOf(me);
   if (!scopes) return null;
   const offered = selectTools(config, me, deployment);
   const offeredNames = new Set(offered.map((tool) => tool.name));
   const left = selectTools(config, { ...me, scopes: null }, deployment).filter((tool) => !offeredNames.has(tool.name));
   if (!left.length) return null;
-  const needed = inWords([...new Set(left.map((tool) => tool.scope ?? tool.scopePrefix))]);
   const shown = scopes.length > 4 ? [...scopes.slice(0, 4), `${scopes.length - 4} more`] : scopes;
   const held = scopes.length ? `holds ${inWords(shown)}` : "holds no scope";
   if (offered.every((tool) => tool.surface === "local")) {
     const local = inWords(offered.map((tool) => tool.name));
-    return `capa-mcp: this key ${held}, and every tool that reads Capa needs ${needed}, so only ${local} ${offered.length === 1 ? "is" : "are"} offered.`;
+    // Any one of these would bring a tool, so they are named with "or".
+    const any = orWords([...new Set(left.flatMap((tool) => (tool.scope ? scopesFor(tool) : [tool.scopePrefix])))]);
+    return `capa-mcp: this key ${held}, and every tool that reads Capa needs ${any}, so only ${local} ${offered.length === 1 ? "is" : "are"} offered.`;
   }
+  const needed = inWords([...new Set(left.map(neededBy))]);
   const names = inWords(left.map((tool) => tool.name));
   return `capa-mcp: this key ${held}, so ${names} ${left.length === 1 ? "is" : "are"} not offered: ${left.length === 1 ? "it needs" : "they need"} ${needed}.`;
 }
+
+function agentLine(config, me, found = {}) {
+  if (config?.family !== "cap" || !me) return null;
+  const accepts = agentSurface(me);
+  if (accepts === true) return null;
+  // The agent tools this key's scopes would get where the deployment accepts it there.
+  const would = selectTools(config, { ...me, surfaces: [...(me.surfaces ?? []), AGENT_SURFACE] }, found).filter((tool) => tool.surface === "agent");
+  if (!would.length) return null;
+  const deployment =
+    accepts === false
+      ? `this deployment does not accept a cap_ key on ${AGENT_SURFACE}`
+      : `this deployment does not say it accepts a cap_ key on ${AGENT_SURFACE}`;
+  const one = would.length === 1;
+  return (
+    `capa-mcp: ${deployment}, so ${inWords(would.map((tool) => tool.name))} ${one ? "is" : "are"} not offered: ` +
+    `${one ? "it needs" : "they need"} a deployment that accepts cap_ keys there.`
+  );
+}