@capacms/mcp 0.2.0 → 0.3.0

package/lib/rest-tools.mjs

@@ -6,8 +6,11 @@
  * registered there (registry.mjs), and without this tool an assistant would
  * lose every read for as long as GraphQL is off. It is registered then, and
  * where GraphQL leaves some of the key's models out (N1: their type names
- * collide), for those. Elsewhere capa_graphql_build writes the same REST read
- * and checks it, and a second way to read would only cost context.
+ * collide), for those. For a legacy key that is all: elsewhere it has
+ * capa_graphql_build, which writes the same REST read and checks it, and the
+ * legacy content tools besides, so a second way to read would only cost
+ * context. A `cap_` key gets it always (0.3.0): it has no legacy content tool,
+ * and REST reads every model it holds whatever else the deployment serves.
  *
  * It takes REST's parameters as docs/api/entries.md writes them and passes
  * them through, so the API's own grammar, limits and refusals apply. The
@@ -113,13 +116,24 @@ export const REST_TOOLS = [
     ...BOUNDED,
     surface: "api",
     scopePrefix: "instance:read",
-    // Registered where the deployment serves no GraphQL, or where GraphQL leaves models out (registry.mjs).
+    // For a legacy key, registered where the deployment serves no GraphQL, or
+    // where GraphQL leaves models out. For a cap_ key, always (registry.mjs).
     whenOff: "graphql",
     description: `Read entries over REST (GET /api/entries/<model>): this deployment serves no GraphQL. Without model: the models this key reads. ${USAGE}`,
     /** The description where GraphQL is served and leaves models out, which this tool is then registered to read. */
     besideGraphQL:
       "Read entries over REST (GET /api/entries/<model>) of the models GraphQL leaves out, which capa_graphql_schema " +
       `lists as readable over REST only; read every other model with capa_graphql_build. ${USAGE}`,
+    /**
+     * The description a `cap_` key reads where GraphQL is not known to be off
+     * and leaves no model out: the tool is registered for every `cap_` key,
+     * since REST is the read a `cap_` key always has, and the GraphQL tools
+     * stay the way to shape one.
+     */
+    capDescription:
+      "Read entries over REST (GET /api/entries/<model>) of any model this key reads. Without model: the " +
+      "models this key reads. To shape a read (fields, filters, relations) as one checked query, start from " +
+      `capa_graphql_build. ${USAGE}`,
     inputSchema: {
       type: "object",
       properties: {

package/lib/server.mjs

@@ -28,7 +28,7 @@ import { instructionsFor } from "./instructions.mjs";
 const PROTOCOL_VERSION = "2025-06-18";
 const SUPPORTED = new Set(["2025-06-18", "2025-03-26", "2024-11-05"]);
 
-export const SERVER_INFO = { name: "capa-mcp", version: "0.2.0" };
+export const SERVER_INFO = { name: "capa-mcp", version: "0.3.0" };
 
 const ok = (id, result) => ({ jsonrpc: "2.0", id, result });
 const fail = (id, code, message) => ({ jsonrpc: "2.0", id, error: { code, message } });
@@ -58,8 +58,26 @@ function withAliases(tool, args) {
  */
 const configFor = (ctx, signal) => (signal ? { ...ctx.config, signal } : ctx.config);
 
-async function callTool(ctx, params, signal) {
-  const name = params?.name;
+/**
+ * One tool call, for every front end: the `tools/call` answer below, and the
+ * `capa` CLI, which runs the same tools by name and needs to tell a refusal
+ * from an answer without reading the words. Either way the caller gets the
+ * same checks and the same sentences, so a CLI command and an MCP tool can
+ * never disagree about an argument or an error.
+ *
+ *   { ok: true, tool, answer }                 the tool's answer, bounded
+ *   { ok: false, reason, text, tool?, error? }
+ *
+ * `reason` is "unknown_tool", "invalid_arguments" or "failed" (the handler
+ * threw: an API refusal, a host that never answered, a timeout). `text` is
+ * what the model reads. `error` is what the handler threw, for a caller that
+ * classifies it (`CapaApiError`, `CapaUnreachable`, `CapaTimeout`).
+ *
+ * An answer the API gave and the tool shaped into a refusal (`{ error,
+ * didYouMean }` for a model that does not exist) is `ok: true`: the model is
+ * meant to read it and correct in one step, and MCP sends it as a result.
+ */
+export async function runTool(ctx, name, rawArgs, { signal } = {}) {
   const tools = ctx.tools;
   const tool = name ? tools.find((t) => t.name === name) : undefined;
   if (!tool) {
@@ -71,24 +89,16 @@ async function callTool(ctx, params, signal) {
     // cannot reach would answer "that one does not exist" with a suggestion
     // that is equally unusable.
     return {
-      content: [
-        {
-          type: "text",
-          text:
-            `Unknown tool: ${String(name)}\n` +
-            `Available: ${tools.map((t) => t.name).join(", ")}`,
-        },
-      ],
-      isError: true,
+      ok: false,
+      reason: "unknown_tool",
+      text: `Unknown tool: ${String(name)}\nAvailable: ${tools.map((t) => t.name).join(", ")}`,
     };
   }
   // Checked against the schema the tool advertised, so a misspelled or
   // mistyped argument is refused by name instead of silently ignored.
-  const args = withAliases(tool, params.arguments);
+  const args = withAliases(tool, rawArgs);
   const problem = checkArguments(tool.inputSchema, args);
-  if (problem) {
-    return { content: [{ type: "text", text: `Invalid arguments for ${name}: ${problem}` }], isError: true };
-  }
+  if (problem) return { ok: false, reason: "invalid_arguments", tool, text: `Invalid arguments for ${name}: ${problem}` };
   try {
     const answer = await tool.handler(configFor(ctx, signal), args ?? {});
     // Every answer fits its budget and says how to ask for less (lib/bound.mjs),
@@ -97,11 +107,7 @@ async function callTool(ctx, params, signal) {
     // not cut again: only it knows which parts are never cut (a built query's
     // document and REST twin) and how a connection pages on once cut.
     const data = tool.whole || tool.bounded ? answer : boundAnswer(answer, args?.maxChars ?? DEFAULT_MAX_CHARS, { hint: tool.cutHint });
-    // Compact: indentation is a third of the characters and tells a model nothing.
-    const content = [{ type: "text", text: JSON.stringify(data) }];
-    // A tool with an output schema also answers the object itself, for a
-    // client that reads results as data; the text stays for one that does not.
-    return tool.outputSchema ? { content, structuredContent: data } : { content };
+    return { ok: true, tool, answer: data };
   } catch (error) {
     // Same reasoning: an API failure is reported to the MODEL so it can adapt
     // (retry narrower, pick another tool), rather than surfaced as a transport
@@ -118,10 +124,21 @@ async function callTool(ctx, params, signal) {
             "(the Capa API rejected this call; a 401 means the key or tenant is wrong, a 404 means the model or id does not exist)"
           }`
         : String(error?.message ?? error);
-    return { content: [{ type: "text", text }], isError: true };
+    return { ok: false, reason: "failed", tool, text, error };
   }
 }
 
+/** `runTool` as MCP's `tools/call` result. */
+export async function callTool(ctx, params, signal) {
+  const run = await runTool(ctx, params?.name, params?.arguments, { signal });
+  if (!run.ok) return { content: [{ type: "text", text: run.text }], isError: true };
+  // Compact: indentation is a third of the characters and tells a model nothing.
+  const content = [{ type: "text", text: JSON.stringify(run.answer) }];
+  // A tool with an output schema also answers the object itself, for a
+  // client that reads results as data; the text stays for one that does not.
+  return run.tool.outputSchema ? { content, structuredContent: run.answer } : { content };
+}
+
 /**
  * One message's answer. `signal` is the call's own, aborted when the client
  * cancels it (session.mjs); a message that never reaches Capa has none.

package/lib/stdio.mjs

@@ -0,0 +1,47 @@
+/**
+ * stdio.mjs — the server on a pair of streams: one JSON-RPC message per line
+ * in, one per line out, and every log line on the error stream.
+ *
+ * The bin runs it on the process's own streams, and so does `capa mcp`, which
+ * starts the same server with the credentials `capa login` stored. A test can
+ * run it on streams of its own.
+ */
+import { createInterface } from "node:readline";
+import { createSession } from "./session.mjs";
+
+/**
+ * Serve `ctx` (connect.mjs) until the input ends. Resolves once every message
+ * read has been answered and the output has flushed, then calls `exit(0)`,
+ * which is `process.exit` unless the caller passes its own.
+ */
+export function serveStdio(ctx, { input = process.stdin, output = process.stdout, error = process.stderr, exit = (code) => process.exit(code) } = {}) {
+  const rl = createInterface({ input, crlfDelay: Infinity });
+  const session = createSession(ctx, {
+    write: (message) => output.write(JSON.stringify(message) + "\n"),
+    log: (text) => error.write(`${text}\n`),
+  });
+  rl.on("line", session.receive);
+
+  return new Promise((resolve) => {
+    // Drain before exiting. `close` fires as soon as the input ends, which for
+    // a piped or scripted client is right after the last line, while a call may
+    // still be mid-fetch: exiting there would leave it unanswered, with nothing
+    // on stderr. A long-lived client holds stdin open, so only a pipe meets this.
+    rl.on("close", async () => {
+      try {
+        await session.drain();
+      } catch (e) {
+        error.write(`capa-mcp: drain failed: ${String(e?.stack ?? e)}\n`);
+      }
+      // Exit once the output has flushed, not before. process.exit() drops what
+      // stdout still buffers, and on macOS a write to a pipe is asynchronous: the
+      // answer to one tools/list came back cut at 8,192 bytes ("Unterminated
+      // string in JSON at position 8192", graphql-tools.test.mjs on Node 22.13).
+      // The empty write's callback runs after every earlier write has gone out.
+      output.write("", () => {
+        resolve();
+        exit(0);
+      });
+    });
+  });
+}

package/lib/tools.mjs

@@ -23,9 +23,8 @@
  * the key has only `read` — see the corrected note in client.mjs, which used to
  * claim no write verb existed behind a key at all.
  *
- * The rest of #4583's write half (edit content, validate, publish) still needs
- * tools of its own against `/v2/agent/model-instances`. Absent rather than
- * stubbed, because a tool that always fails teaches an agent to stop trying.
+ * Entries are written as drafts by lib/entry-tools.mjs, against
+ * `/v2/agent/model-instances`, for `cap_` keys only.
  *
  * WHY /v2/seo/ai-bundle IS NOT A TOOL, having been measured rather than assumed
  * It is API-key reachable and the source calls it a "RAG-ready export across
@@ -45,25 +44,37 @@
  * different tool with a different contract, and it should be built deliberately
  * rather than by pointing a `capa_get_*` at a large endpoint.
  *
- * TWO SURFACES, AND EVERY TOOL SAYS WHICH IT IS ON.
+ * THREE SURFACES, AND EVERY TOOL SAYS WHICH IT IS ON.
  *
- * `surface: "legacy"` means the tool calls `/v2/*` or `/v3/*`, which a `pk_` or
- * `sk_` key reaches and a `cap_` key is refused on before any lookup.
+ * `surface: "legacy"` means the tool calls `/v2/schema`, `/v2/api` or
+ * `/v2/schema/types`, which a `pk_` or `sk_` key reaches and a `cap_` key is
+ * refused on before any lookup.
+ * `surface: "agent"` means every call it makes goes to `/v2/agent/*`, which a
+ * legacy key reaches and a `cap_` key reaches where the deployment accepts one
+ * there (`GET /api/me` lists `/v2/agent` among the key's `surfaces`).
  * `surface: "api"` means it calls `/api/`, which both families reach.
- * `lib/registry.mjs` turns those two words into the tool list one key actually
+ * `lib/registry.mjs` turns those words into the tool list one key actually
  * gets, so an agent is never offered a tool its key cannot use.
  *
- * An `api` tool also declares the `scope` it needs. `/api/me` reports the
- * scopes a key holds, and a tool whose scope is missing from that list is left
- * out rather than registered and refused. The field is a string compared
- * whole: the page routes ask for UNSCOPED `instance:read`, so a key holding
- * only `instance:read:<modelId>` does not get them, which is the same answer
- * the API would give.
+ * An `api` or `agent` tool also declares the `scope` it needs. `/api/me`
+ * reports the scopes a key holds, and a tool whose scope is missing from that
+ * list is left out rather than registered and refused. The field is a string
+ * compared whole, or a list of which any one will do: the page routes ask for
+ * UNSCOPED `instance:read`, so a key holding only `instance:read:<modelId>`
+ * does not get them, which is the same answer the API would give. An `agent`
+ * tool's scope filters a `cap_` key only; a legacy key gets every agent tool,
+ * as it did before a `cap_` key could reach them.
+ *
+ * `capDescription` is what a `cap_` key's agent reads instead of
+ * `description`, where the two keys need different words: a legacy key's
+ * write is gated by its permission, a `cap_` key's by a scope.
  */
 import { reads, writes } from "./annotations.mjs";
 import { DEFAULT_MAX_CHARS, someNames } from "./bound.mjs";
 import { apiGet, apiGetText, apiNextGet, apiWrite, CapaApiError } from "./client.mjs";
 import { GRAPHQL_TOOLS } from "./graphql-tools.mjs";
+import { ENTRY_TOOLS } from "./entry-tools.mjs";
+import { MEDIA_TOOLS } from "./media-tools.mjs";
 import { REST_TOOLS } from "./rest-tools.mjs";
 
 /**
@@ -104,18 +115,98 @@ function typesAnswer(blocks, extra = {}) {
   return cut(fits);
 }
 
-/** /v2/schema is the one call that describes everything; cache it per process. */
+/**
+ * /v2/schema is the one call that describes everything; cache it per process,
+ * or in `config.schemaCache` when the config carries one (graphql/schema.mjs
+ * says why the hosted server's does).
+ */
 let schemaCache = null;
 export function __resetSchemaCacheForTests() {
   schemaCache = null;
 }
 async function schema(config) {
+  if (config.schemaCache) {
+    if (!config.schemaCache.has("/v2/schema")) config.schemaCache.set("/v2/schema", await apiGet(config, "/v2/schema"));
+    return config.schemaCache.get("/v2/schema");
+  }
   if (!schemaCache) schemaCache = await apiGet(config, "/v2/schema");
   return schemaCache;
 }
 
 const lc = (s) => String(s ?? "").toLowerCase();
 
+/**
+ * capa_get_model for a `cap_` key: ONE request, to `/v2/agent/models/<namespace>`.
+ *
+ * The legacy path reads `/v2/schema` first, and that mount refuses a `cap_`
+ * key whatever the deployment does on `/v2/agent`. The agent route resolves a
+ * namespace (or an id) itself and answers the fields, their ids, the layout
+ * and `embedByDefault` in one body, so everything the legacy answer holds
+ * comes from it, in the same shape:
+ *
+ *   - `enumValues` is `[]` there where `/v2/schema` says null, so an empty
+ *     list reads as absent, as it does on the legacy path.
+ *   - `relationRef` is `""` or null on a field that relates to nothing.
+ *   - `relations` is built from the fields as `/v2/schema` builds it. Its
+ *     `toModel` is the field's `relationRef` as stored, which is the target's
+ *     namespace on every real tenant (apps/api schema.ts); `/v2/schema`
+ *     resolves the rare id-form one against every model, which one model's
+ *     detail cannot, so an edge stored by id names the id.
+ *
+ * A miss is answered as the legacy path answers one, with the near names, read
+ * from the model list on the same mount (`model:read`, the scope this tool is
+ * registered by). A refusal is not a miss and throws as the API's error.
+ */
+async function agentModel(config, namespace) {
+  let detail;
+  try {
+    detail = await apiGet(config, `/v2/agent/models/${encodeURIComponent(namespace)}`);
+  } catch (error) {
+    if (!(error instanceof CapaApiError && error.status === 404 && /model not found/i.test(error.body))) throw error;
+    let available = null;
+    try {
+      const list = await apiGet(config, "/v2/agent/models", { limit: 250 });
+      available = (list.data ?? []).map((m) => m.namespace);
+    } catch {
+      available = null;
+    }
+    return {
+      error: `No model with namespace "${namespace}".`,
+      // Omitted, not empty, when the list call failed too: `[]` would claim this tenant has no models.
+      ...(available === null
+        ? {}
+        : { didYouMean: available.filter((n) => lc(n).includes(lc(namespace)) || lc(namespace).includes(lc(n))), available }),
+    };
+  }
+  const fields = detail.fields ?? [];
+  const relations = [];
+  for (const f of fields) {
+    if (!f.relationRef) continue;
+    const isOne = f.type === "relation";
+    const isMany = f.type === "array" && f.arrayType === "relation";
+    if (!isOne && !isMany) continue;
+    relations.push({ fromModel: detail.namespace, fromField: f.namespace, toModel: f.relationRef, type: isOne ? "one" : "many" });
+  }
+  // Key for key what the legacy path answers, which the tests hold byte-equal.
+  return {
+    namespace: detail.namespace,
+    name: detail.modelName,
+    singleInstance: detail.isSingleInstance,
+    fields: fields.map((f) => ({
+      id: f.id,
+      namespace: f.namespace,
+      name: f.name,
+      type: f.arrayType ? `${f.type}<${f.arrayType}>` : f.type,
+      required: f.required,
+      relatesTo: f.relationRef || undefined,
+      enumValues: f.enumValues?.length > 0 ? f.enumValues : undefined,
+    })),
+    relations,
+    layout: detail.layout ?? null,
+    embedByDefault: detail.embedByDefault === true,
+  };
+}
+
 /**
  * Capa stores most values as `{ type, value, sortOrder }` rather than bare
  * scalars — including `title`, which reads like a plain column and is not.
@@ -166,6 +257,57 @@ const instanceIdOf = (row) => {
   return typeof row?.id === "string" && UUID_RE.test(row.id) ? row.id : null;
 };
 
+/** capa_set_model_layout's description, around the sentence that says what its write needs, which differs by key family. */
+const LAYOUT_LEAD =
+  "Design a model's entry editor: cards in a main column and a side column, with each field " +
+  "placed in one of them. ";
+const LAYOUT_DOCUMENT =
+  "Pass " +
+  "layout: null to reset the model to the plain linear editor. The document is " +
+  "{ v: 1, main: Card[], aside: Card[] } where a Card is { id, title, description?, " +
+  "collapsible, collapsed, items: Field[] } and a Field is { id, fieldId, width, display?, " +
+  "inline? }. `id` is any id you choose, unique in the document; `fieldId` is the field's id " +
+  "from capa_get_model. Widths are full, two_thirds, half or third. Relation fields may take " +
+  "display \"picker\", \"inline\" or \"embedded\" (embedded draws the related entry's own " +
+  "fields directly in the parent card), plus inline { allowCreate, allowRemove, " +
+  "allowReorder, summary } where summary is up to 3 field ids OF THE RELATED model. Leave " +
+  "display out and the related model's own embedByDefault decides, which capa_get_model " +
+  "reports. Read the current one with capa_get_model first: it returns the same document, " +
+  "so you can edit and write it back.";
+
+/** capa_set_workspace's description, around the sentence that says what its write needs. */
+const WORKSPACE_LEAD = "Create a workspace, or apply a document to one that exists. ";
+const WORKSPACE_REST =
+  "`mode: \"replace\"` makes the workspace exactly the document you " +
+  "send; `mode: \"merge\"` adds what is missing and removes nothing. Applying the same " +
+  "document twice changes nothing, so it is safe to retry. It never touches a record: a " +
+  "workspace is navigation, and removing something from it does not delete it. It creates no " +
+  "models or entries: a reference to one that does not exist is not placed, and the answer says so first.";
+
+/** The API's unresolved references, `kind:ref`, as a person would name them. */
+const UNRESOLVED_KIND = { model: "model", instance: "entry", media_folder: "media folder" };
+
+/**
+ * A workspace answer led by a sentence for what it could not place. The API
+ * applies the rest of the document and lists the misses as `unresolved`; an
+ * agent that asked for a model which does not exist read that list past and
+ * told the person the model had been created (scripts/tool-evals, M20).
+ */
+function withNotPlaced(answer) {
+  const missed = Array.isArray(answer.unresolved) ? answer.unresolved : [];
+  if (missed.length === 0) return answer;
+  const named = missed.map((ref) => {
+    const at = String(ref).indexOf(":");
+    const kind = at > 0 ? String(ref).slice(0, at) : "";
+    return UNRESOLVED_KIND[kind] ? `${UNRESOLVED_KIND[kind]} ${String(ref).slice(at + 1)}` : String(ref);
+  });
+  const notPlaced =
+    `${missed.length} of the document's ${missed.length === 1 ? "references was" : "references were"} not placed, because nothing in this ` +
+    `project has that id or namespace: ${named.join(", ")}. This tool arranges what exists; it creates no models or entries. ` +
+    "Everything else was applied.";
+  return { notPlaced, ...answer };
+}
+
 export const TOOLS = [
   {
     name: "capa_list_models",
@@ -212,7 +354,10 @@ export const TOOLS = [
     name: "capa_get_model",
     ...reads("Get a model and its editor layout"),
     whole: true,
-    surface: "legacy",
+    // Every call goes to /v2/agent for a cap_ key (agentModel). A legacy key
+    // reads /v2/schema first, which its key reaches, exactly as it always did.
+    surface: "agent",
+    scope: "model:read",
     ...MODEL_ALIAS,
     description:
       "Full field definitions for ONE model as the editor sees them: every field's namespace, " +
@@ -228,6 +373,7 @@ export const TOOLS = [
       additionalProperties: false,
     },
     handler: async (config, args) => {
+      if (config.family === "cap") return agentModel(config, args.namespace);
       const s = await schema(config);
       const model = (s.models ?? []).find((m) => m.namespace === args.namespace);
       if (!model) {
@@ -309,22 +455,14 @@ export const TOOLS = [
     name: "capa_set_model_layout",
     ...writes("Set a model's editor layout", { idempotent: true }),
     whole: true,
-    surface: "legacy",
+    surface: "agent",
+    scope: "model:update",
     aliases: { model: "modelId" },
     description:
-      "Design a model's entry editor: cards in a main column and a side column, with each field " +
-      "placed in one of them. WRITES: it needs an API key whose permission is `agent`. Pass " +
-      "layout: null to reset the model to the plain linear editor. The document is " +
-      "{ v: 1, main: Card[], aside: Card[] } where a Card is { id, title, description?, " +
-      "collapsible, collapsed, items: Field[] } and a Field is { id, fieldId, width, display?, " +
-      "inline? }. `id` is any id you choose, unique in the document; `fieldId` is the field's id " +
-      "from capa_get_model. Widths are full, two_thirds, half or third. Relation fields may take " +
-      "display \"picker\", \"inline\" or \"embedded\" (embedded draws the related entry's own " +
-      "fields directly in the parent card), plus inline { allowCreate, allowRemove, " +
-      "allowReorder, summary } where summary is up to 3 field ids OF THE RELATED model. Leave " +
-      "display out and the related model's own embedByDefault decides, which capa_get_model " +
-      "reports. Read the current one with capa_get_model first: it returns the same document, " +
-      "so you can edit and write it back.",
+      LAYOUT_LEAD +
+      "WRITES: it needs an API key whose permission is `agent`. " +
+      LAYOUT_DOCUMENT,
+    capDescription: `${LAYOUT_LEAD}WRITES: it needs a key holding model:update. ${LAYOUT_DOCUMENT}`,
     inputSchema: {
       type: "object",
       properties: {
@@ -371,8 +509,11 @@ export const TOOLS = [
           return {
             error: error.message,
             hint:
-              "This tool writes a model, so it needs a Capa API key whose permission is `agent`. " +
-              "`read`, `write` and `delete` keys can call capa_get_model but not this one.",
+              config.family === "cap"
+                ? "This tool writes a model, so it needs a key holding the model:update scope. A key " +
+                  "holding model:read can call capa_get_model but not this one."
+                : "This tool writes a model, so it needs a Capa API key whose permission is `agent`. " +
+                  "`read`, `write` and `delete` keys can call capa_get_model but not this one.",
           };
         }
         throw error;
@@ -670,7 +811,8 @@ export const TOOLS = [
     name: "capa_list_workspaces",
     ...reads("List workspaces"),
     cutHint: "Name the workspace you want and read it with capa_get_workspace.",
-    surface: "legacy",
+    surface: "agent",
+    scope: "workspace:read",
     description:
       "List this tenant's saved workspaces: the arrangements of the Capa admin's left rail. " +
       "Each one is a named tree of models, entries and media folders. Start here before " +
@@ -682,8 +824,8 @@ export const TOOLS = [
         includePrivate: {
           type: "boolean",
           description:
-            "Also list workspaces individual people made for themselves. Off by default: " +
-            "those are personal, and an agent almost always wants the team ones.",
+            "Has no effect: workspaces people made for themselves are personal, and the API " +
+            "never lists them to an API key. Accepted so existing calls keep working.",
         },
       },
       additionalProperties: false,
@@ -709,13 +851,16 @@ export const TOOLS = [
     name: "capa_get_workspace",
     ...reads("Get a workspace document"),
     whole: true,
-    surface: "legacy",
+    surface: "agent",
+    scope: "workspace:read",
     description:
       "One workspace as a JSON document you can edit and write back with capa_set_workspace. " +
       "The tree is `Node[]`, where a Node is `{folder, children?}`, `{model}`, `{instance}` or " +
       "`{media_folder}`. A folder is named by the customer and holds any mix of the three, so " +
       "there are no fixed sections. Models come back as NAMESPACES, so you can read and " +
-      "rearrange without resolving ids first.",
+      "rearrange without resolving ids first. A key that may update workspaces is shown every pin, " +
+      "so the document can name an entry that /v2/agent/model-instances does not serve that key: " +
+      "one never published, in a model it does not write.",
     inputSchema: {
       type: "object",
       properties: {
@@ -732,13 +877,15 @@ export const TOOLS = [
     name: "capa_set_workspace",
     ...writes("Create or apply a workspace", { idempotent: false }),
     cutHint: "The write is done; capa_get_workspace reads the whole document.",
-    surface: "legacy",
-    description:
-      "Create a workspace, or apply a document to one that exists. WRITES: it needs an API key " +
-      "with write permission. `mode: \"replace\"` makes the workspace exactly the document you " +
-      "send; `mode: \"merge\"` adds what is missing and removes nothing. Applying the same " +
-      "document twice changes nothing, so it is safe to retry. It never touches a record: a " +
-      "workspace is navigation, and removing something from it does not delete it.",
+    surface: "agent",
+    // Either will do: without an id it creates (POST, workspace:create), with
+    // one it applies (PUT, workspace:update), and a key holding one of the two
+    // can do that half. The other half answers the API's 403 and the fix.
+    scope: ["workspace:create", "workspace:update"],
+    description: `${WORKSPACE_LEAD}WRITES: it needs an API key with write permission. ${WORKSPACE_REST}`,
+    capDescription:
+      `${WORKSPACE_LEAD}WRITES: it needs a key holding workspace:create to create one and ` +
+      `workspace:update to apply to one. ${WORKSPACE_REST}`,
     inputSchema: {
       type: "object",
       properties: {
@@ -788,7 +935,7 @@ export const TOOLS = [
           // workspace from this surface; saying so up front beats a 400.
           if (args.template !== undefined) body.template = args.template;
           const created = await apiWrite(config, "POST", "/v2/agent/workspaces", { ...body, visibility: "team" });
-          return { created: true, workspace: created.workspace, changes: created.changes ?? null, unresolved: created.unresolved ?? [] };
+          return withNotPlaced({ created: true, workspace: created.workspace, changes: created.changes ?? null, unresolved: created.unresolved ?? [] });
         }
         const applied = await apiWrite(
           config,
@@ -796,14 +943,14 @@ export const TOOLS = [
           `/v2/agent/workspaces/${encodeURIComponent(args.id)}/tree`,
           { ...body, mode },
         );
-        return {
+        return withNotPlaced({
           created: false,
           workspace: applied.workspace,
           // The summary is the point of the call: an agent reads it to find out
           // whether it actually changed anything, and a no-op says so.
           changes: applied.changes,
           unresolved: applied.unresolved ?? [],
-        };
+        });
       } catch (error) {
         // The API's OWN message, not a guess at it. A 403 here means the key
         // may read and not write, which is a configuration fact somebody can
@@ -812,9 +959,13 @@ export const TOOLS = [
           return {
             error: error.message,
             hint:
-              "This tool writes, so it needs a Capa API key whose permission is `write` " +
-              "(or `agent`). A `read` key can call capa_list_workspaces and capa_get_workspace " +
-              "but not this one.",
+              config.family === "cap"
+                ? "This tool writes, so it needs a key holding workspace:create to create a " +
+                  "workspace and workspace:update to apply a document to one. A key holding " +
+                  "workspace:read can call capa_list_workspaces and capa_get_workspace but not this one."
+                : "This tool writes, so it needs a Capa API key whose permission is `write` " +
+                  "(or `agent`). A `read` key can call capa_list_workspaces and capa_get_workspace " +
+                  "but not this one.",
           };
         }
         throw error;
@@ -1124,6 +1275,16 @@ export const TOOLS = [
   //
   // Reading entries when the deployment serves no GraphQL: lib/rest-tools.mjs.
   ...REST_TOOLS,
+
+  // ----------------------------------------- entries (/v2/agent, drafts) ---
+  //
+  // Creating and changing entries as drafts: lib/entry-tools.mjs.
+  ...ENTRY_TOOLS,
+
+  // ------------------------------------ media (/v2/agent/file-uploads) ---
+  //
+  // Listing files and uploading one: lib/media-tools.mjs.
+  ...MEDIA_TOOLS,
 ];
 
 /**