@capacms/mcp 0.2.0

package/README.md

@@ -0,0 +1,881 @@
+# @capacms/mcp
+
+stdio MCP server for Capa. Seventeen reads, two writes, two resources and three
+prompts. People set it up from the
+[AI assistants guide](https://docs.capacms.com/api/ai-assistants), which has
+the Claude Code, Cursor and Codex config.
+
+It has no dependencies, so `npx` fetches the package and runs it with nothing
+else to install. It needs Node 20.3 or later: every request is bounded with
+`AbortSignal.any`, and Node 18's `fetch` tried only `::1` for `localhost`, so
+an API listening on IPv4 looked down. A Node without `AbortSignal.any` exits
+at once and says so.
+
+With a `cap_` key minted in the Capa admin under **Developers > Keys**:
+
+```sh
+CAPA_API_URL=https://api.capacms.com CAPA_KEY=cap_live_... npx -y @capacms/mcp
+```
+
+An MCP client starts it the same way: the command is `npx`, the arguments are
+`-y @capacms/mcp`, and the variables below go in the client's `env`.
+
+| variable | needed | value |
+|---|---|---|
+| `CAPA_API_URL` | always | the API, `https://api.capacms.com` |
+| `CAPA_KEY` | always | the key the server reads with |
+| `CAPA_TENANT_ID` | a legacy key only: `pk_`, `sk_` or unprefixed | the tenant's id |
+| `CAPA_API_VERSION` | no | the dated `/api/` version, `2026-10-01` |
+
+`CAPA_API_URL` and `CAPA_KEY` are the names every Capa tool reads
+(`@capacms/sdk/nextjs`, `capa-codegen`, the docs' curl examples), so one
+`.env` serves a site and this server. `CAPA_BASE_URL` and
+`CAPA_API_KEY`, this server's first names, still work as aliases; when both
+are set, `CAPA_API_URL` and `CAPA_KEY` win.
+
+`CAPA_API_URL` is the API's address with no route after it: every tool adds
+the route it calls (`/api/graphql`, `/v2/api/...`). An address that holds
+`/api`, `/v2` or `/v3` as a path segment is refused at startup, naming the
+part to drop, since each call would repeat it. A path before the routes, such
+as a proxy's `/capa`, is kept. Spaces around `CAPA_API_URL`, `CAPA_KEY` and
+`CAPA_TENANT_ID`, as a pasted line can carry, are trimmed.
+
+`CAPA_TENANT_ID` is needed by a **legacy key only**: `pk_`, `sk_`, or an
+older key with no prefix, since every key but `cap_` is legacy. The `/v2` and
+`/v3` mounts every legacy tool calls read it as `X-Tenant-Key`. A `cap_` key
+reaches `/api/`, which resolves the tenant from the key and never reads that
+header, and no legacy tool that could send it is registered for a `cap_` key,
+so the server starts without it rather than refusing over a value nothing it
+can call will read. Started with no key at all, the server names
+`CAPA_API_URL` and `CAPA_KEY` as missing, and labels `CAPA_TENANT_ID` as for
+legacy keys only.
+
+`CAPA_API_VERSION` is the dated `/api/` version the `/api/` tools ask for. Unset,
+they send the newest date this package knows. A date the deployment does not
+serve is refused with a list of the ones it does.
+
+Nineteen tools, of which a given key is offered a subset. The `needs` column is
+the key permission or the scope a tool asks for, and the `surface` column is
+which half of the API it calls, which is what decides whether it is registered
+at all (see [the page tools](#the-page-tools)).
+
+| tool | answers | surface | needs |
+|---|---|---|---|
+| `capa_list_models` | what content exists here, and what relates to what | legacy | read |
+| `capa_get_model` | what shape is this model: fields, types, relations, and how its editor is laid out | legacy | read |
+| `capa_set_model_layout` | design that model's entry editor, or reset it to linear | legacy | **agent** |
+| `capa_list_content` | which instances of this model exist | legacy | read |
+| `capa_get_content` | this one instance, in full, with relations | legacy | read |
+| `capa_search_content` | where does this text live, when you don't know the model | legacy | read |
+| `capa_get_types` | the generated TypeScript, for writing code against a tenant | legacy | read |
+| `capa_list_workspaces` | which saved arrangements of the admin rail exist | legacy | read |
+| `capa_get_workspace` | one workspace as a document you can edit and write back | legacy | read |
+| `capa_set_workspace` | create a workspace, or apply a document to one | legacy | **write** |
+| `capa_list_pages` | which pages this site has, what they read and how busy they are | `/api/` | `instance:read` |
+| `capa_get_page` | one page: its models, its entries, and the exact queries it issues | `/api/` | `instance:read` |
+| `capa_suggest_queries` | what Capa suggests changing about how one page fetches | `/api/` | `instance:read` |
+| `capa_graphql_schema` | what this key can read: models, fields, relations; with `model`, filters, sorts and an example; SDL on request | `/api/` | `instance:read` for any model |
+| `capa_graphql_build` | write a query from an intent, as GraphQL, REST and SDK code, checked | `/api/` | `instance:read` for any model |
+| `capa_graphql_query` | run a GraphQL read and get data, errors with hints, cost and budget | `/api/` | `instance:read` for any model |
+| `capa_explore_data` | what the content actually holds: counts, ranges, values, fan-out | `/api/` | `instance:read` for any model |
+| `capa_explain_error` | what an API error means and what to do next | none (offline) | nothing |
+| `capa_read_entries` | read entries over REST, where the deployment serves no GraphQL, or of the models GraphQL leaves out | `/api/` | `instance:read` for any model |
+
+Every tool has a `title` and MCP annotations, so a client can run the reads
+without asking and confirm a write. The seventeen reads are
+`readOnlyHint: true`. The two writes are `readOnlyHint: false` and
+`destructiveHint: true`, since each can replace what is there.
+`capa_set_model_layout` is `idempotentHint: true`: the same layout twice is one
+layout. `capa_set_workspace` is not, because without an `id` it creates a new
+workspace on every call. Every tool is `openWorldHint: false`, since none
+reaches past this Capa deployment.
+
+Every answer is held to 20,000 characters. The GraphQL tools and
+`capa_read_entries` take `maxChars` for another budget, and every tool cuts the same way: list items from the end,
+then long text, each cut named in `truncated` or `clipped`, with a `hint` on
+how to ask for less. `capa_get_types` is cut between whole declarations and
+names the ones it left out in `notPrinted`. Three answers are never cut,
+because an agent edits them and writes them back: `capa_get_model`,
+`capa_set_model_layout` and `capa_get_workspace`.
+
+A host that does not answer is named with the cause and the next step, on
+every tool and in the startup line on stderr:
+
+```text
+Could not reach Capa at http://localhost:6199 for POST /api/graphql (ECONNREFUSED). Next: check that CAPA_API_URL is right and that the API is running and reachable from this machine, then retry.
+```
+
+It names the origin only. A `CAPA_API_URL` with a user name or password in
+it is refused by `fetch`, and the message says so without repeating them.
+
+Calls that reach Capa run one at a time, in the order they came. `ping`,
+`initialize`, the lists, the prompts and `capa_explain_error` answer at once
+beside a call in flight, so a slow host never makes the server look dead.
+`notifications/cancelled` stops the call it names, running or still waiting
+its turn, and that call is never answered, as MCP requires.
+
+The legacy tools call a model `namespace`, as `/v2` does, and
+`capa_set_model_layout` calls it `modelId`. Each also takes `model`, the name
+the GraphQL tools teach. An argument that another tool of this server, or
+REST, calls by a different name is refused with the name this tool takes:
+`limit` on `capa_graphql_build` suggests `first`, `where` suggests `filter`,
+`select` suggests `fields`.
+
+## The GraphQL tools
+
+Five tools take an agent from "what is in this project?" to a working query,
+in the order it needs them:
+
+| step | tool | returns |
+|---|---|---|
+| what is here? | `capa_graphql_schema` | the models, fields and relations this key can read; with `model`, filters, sorts and an example; with `sdl`, the SDL |
+| what does it look like? | `capa_explore_data` | real values, measured: counts, ranges, distinct values, relation fan-out, samples |
+| write me a query | `capa_graphql_build` | GraphQL and the equal REST URL, checked by running it, and `@capacms/sdk` code when asked |
+| run this | `capa_graphql_query` | data, errors with hints, cost, budget, and the REST request per root field |
+| what went wrong? | `capa_explain_error` | what a code means, the fix, and the tool to call next (offline) |
+
+These five names are final. The four that read cost 3,991 characters of context (descriptions plus
+input schemas), and the tests hold them under 4,000. All five also declare an
+`outputSchema` and return `structuredContent` beside the JSON text, a refusal
+in band included. The output schemas, for a client that reads them, are held
+under 4,000 characters by the tests too.
+
+Every answer the API ran says which key read it: `environment` is
+`production` or `development`. A development key's answer also carries
+`drafts`, `"A development key reads drafts and unpublished changes; a
+production key reads published entries only."`, so an assistant never
+describes a draft title as what the site shows. A production key's read of
+one entry that answers `null` carries `notFound`: `"article is null: no entry
+this key reads has that id. A production key reads published entries only, so
+an entry that exists only as a draft reads as null too."`
+
+They all read through `/api/graphql`, whose schema is built per key: a key
+holding `instance:read:<articles>` sees articles and nothing else, its
+relations to other models are plain ids, and no tool output names a model it
+cannot read. Every answer has a character budget (`maxChars`, default 20,000)
+that holds for the whole answer. A text value longer than half the budget is
+clipped first, to the room the answer has, so one long body does not cost the
+entries after it. Then a big result loses list items from the end, measured
+one by one, and `truncated` says which list, how many were kept and how many
+there were; a connection that selects both `edges` and `nodes` loses entries
+from both, and both are listed. Then the longest text values are clipped, each
+to the room left and never below 200 characters, each listed in `clipped`
+with its `path`, the characters `kept` and the `total`; an id, a cursor, a URL
+or an error's text never is. The hint names the longest clipped value, and
+`capa_graphql_query` with the same query and `slice: { "path", "offset" }`
+reads the rest of it from `offset` on, as `text`, as much as the budget
+holds, with `clipped` and a hint for the next call while more follows. The
+REST twins (`rest`) are cut last, unless they take more than half the budget
+and more than 2,000 characters, as a `nodes(ids:)` read's can, which lists
+every id: then their last rows go first. When even one entry per list does
+not fit, the hint gives way first, and then `capa_graphql_query` leaves out
+the `drafts` note and then the REST twin, each named in `truncated`, before
+it gives up the data; `environment` still says which key read it. A
+cut list stays
+pageable: `hasNextPage` turns true, and `endCursor` becomes the cursor of the
+last entry kept, so passing it as `after` skips nothing. A page read backward
+(`last` and `before`) loses entries from its start instead, the ones farthest
+from `before`, and says `"cutFrom": "start"`: `hasPreviousPage` turns true and
+`startCursor` becomes the cursor of the first entry kept, so passing it as
+`before` skips nothing. When the answer holds no cursor for that entry (no
+`edges { cursor }` selected), the cursor is `null` and the cut's `resume` says
+how to go on: run again with `first` (or `last` and the same `before`) set to
+the number kept. The uncut page's cursor would skip every entry cut. The
+connections are read from the document, so `items: nodes` and `info:
+pageInfo` are repaired under the names they answer with.
+
+A relation list inside an entry is a page of its own: `first` entries, 100
+when the document gives none. When one holds more than it shows, the answer
+says so at its top, in `more` and a `note`, so 100 of a bin's 250 items never
+read as all of them:
+
+```json
+"more": [{ "path": "data.bins.nodes[0].items", "shown": 100, "endCursor": "c1.eyJ...", "entry": "084f404f-..." }],
+"note": "1 relation list holds more entries than it shows: see more. A relation list pages on only in a read of one entry: ..."
+```
+
+`capa_graphql_query` names a list whose `pageInfo` says `hasNextPage`, and one
+that selected no `pageInfo` but fills its page (`"pageInfo": false`: it may
+hold more). The API pages a relation list with `after` only in a read of one
+entry, so `entry` is the id to read it from, with the model's single field.
+`capa_graphql_build` hands over plan 1.3's document, where a relation list
+selects `nodes` only, but its run reads each list's `pageInfo` and cursors:
+each list in its `more` carries `next`, the `capa_graphql_query` arguments
+that read that one entry's list on from where it stopped, cut or not. Its
+`result` keeps the shape of the document handed over. `capa_graphql_query`
+gives a list its `next` too, the same document with that list's `after` set,
+where the list sits in a read of one entry; a list under a list is read on
+by hand, from `entry`.
+
+Arguments are checked against each tool's input schema,
+so a misspelled one (`frist`, `filters`) is refused by name with the allowed
+names and a suggestion, never silently dropped. A relation spec in `capa_graphql_build`'s
+`fields` is checked the same way at every depth:
+`Unknown argument frist in fields[1]. Did you mean first? Allowed: field, fields, first, sort.` Every request this server makes, on
+either surface, gives up after 25 seconds with the next step. Every other
+refusal is in band and names the next tool for its own error: a typo points
+at `capa_graphql_schema`, a bad argument at `capa_graphql_build`, and a
+mutation at nothing, since no tool can write. A budget refusal passes on what
+the API measured and the limit, and names the tool for that budget:
+`capa_graphql_build` to lower `first` or nest less, `capa_graphql_query` to
+split a document with too many root fields, connections or `in` values, and
+`capa_graphql_schema` for an introspection query too deep.
+
+Where GraphQL is switched off (`CAPA_API_GRAPHQL=off`), `/api/graphql`
+answers as any path the API does not serve: `405 mutations_not_enabled` to a
+POST, in the REST envelope `{ error }`. The GraphQL handler never answers in
+that envelope, a real mutation's refusal included, so the envelope tells the
+two apart. The server asks once at startup, with `POST /api/graphql` and
+`{ __typename }`, and on such a deployment registers no GraphQL tool, resource
+or prompt, with a line on stderr. A GraphQL tool called there anyway, because
+the startup probe could not tell, answers:
+
+```text
+This deployment does not serve GraphQL: POST /api/graphql answered 405 mutations_not_enabled as a path it does not serve, which is what CAPA_API_GRAPHQL=off does. No GraphQL tool can answer until it is switched back on.
+Next: tell the person running Capa that GraphQL is off here. Code can read the same content over REST with this key: GET /api/entries/<model>.
+```
+
+A legacy key is also pointed at `capa_list_content` and `capa_get_content`.
+A real mutation is still told it tried to write, and nothing more.
+
+Where the startup probe finds GraphQL off, the server registers
+`capa_read_entries` in its place, so a key keeps a read tool for as long as
+GraphQL is off. It reads `GET /api/entries/<model>` with REST's own
+parameters (`select`, `where`, `sort`, `limit`, `after`, `before`, `count`),
+answers the models the key reads when called without `model`, and is cut like
+every other answer. A cut page's `next` would skip what was cut, so it is
+`null`, and `resume` says how to read on:
+
+```json
+{"data":[{"id":"00000000-0000-4000-8000-00000000002e","model":"articles","status":"published",...}],
+ "page":{"limit":10,"hasNext":true,"next":null,"hasPrev":false,"prev":null},"environment":"production","rest":"/api/entries/articles?limit=10",
+ "truncated":[{"path":"data","kept":1,"total":10,"resume":"page.next is null because entries were cut; the uncut page's would skip them. Read again with limit: 1 for a next after the last entry shown."}],
+ "hint":"Pass select for fewer fields, or a smaller limit."}
+```
+
+The examples below are real outputs of this server, driven over stdio against
+a local API on the seed (`pnpm -F @capa/api seed:local`) with a `cap_` key
+holding `instance:read`, `model:read` and `media:read`, captured on
+2026-09-26. Outputs are shortened where they show `...`.
+
+`capa_graphql_schema` with no arguments is the map:
+
+```json
+{"version":"2026-10-01","key":{"environment":"production","bundle":"scoped","scopes":["instance:read","model:read","media:read"]},
+ "models":[{"model":"articles","name":"Article","type":"Articles","graphql":"articles, article(id)","rest":"/api/entries/articles",
+   "fields":["title: String","body: String","views: Float","featured: Boolean","tags: [String]","author -> authors","coauthors ->> authors"]},
+  {"model":"authors","name":"Author","type":"Authors","graphql":"authors, author(id)","rest":"/api/entries/authors","fields":["name: String","bio: String"]},
+  {"model":"snippets","name":"Snippet","type":"Snippets","graphql":"snippets, snippet(id)","rest":"/api/entries/snippets","fields":["title: String","code: String"]}],
+ "system":"Every model type also has id, model, status, createdAt, updatedAt, publishedAt, _version, _tags, _folder. Filters and sorts take id, createdAt, updatedAt and publishedAt of those. Filters also take _tags.",
+ "next":"Pass model for filters, sorts and an example, or call capa_graphql_build."}
+```
+
+`key.scopes` is listed where the deployment reports scopes
+(`CAPA_KEY_SCOPES=on`), as the one above does. The switch is off by default,
+and then `key` has no `scopes`.
+
+`model` takes any of a model's names, in any case: the namespace
+(`articles`), the name the admin shows (`Article`) or the type (`Articles`).
+A near miss comes back with the nearest (`Authr` suggests `authors`). On a
+project with too many models to list with their fields, the map keeps every
+model, with its roots, and shortens the field lists; past that it lists the
+names alone and says to pass `model`. A deprecated field is marked
+`(deprecated)`.
+
+`capa_graphql_schema { "model": "articles" }` adds, per field, its filter
+operators, the fields a relation filter reaches (`"author"` has
+`"filter":["eq","ne","in","nin","exists","null"]` and `"hops":["id","name","bio"]`),
+whether it sorts, the sort values (`views_DESC`, `author__name_ASC`, ...), the
+reason a deprecated field is deprecated, and an example query with its REST
+twin. For a model
+with an image, video or file field it adds `media`, what a media value holds,
+read from the schema: `"Media fields: id, url, alt, type, width, height. type:
+The kind of file, or null when it is not one of MediaKind's. MediaKind: image,
+video, audio, document, pdf, file, unknown."`
+
+`sdl: true` adds the SDL, in a compact form: types, fields and arguments keep
+their descriptions (each field's label and Capa type), while input fields and
+enum values print without theirs, since an operator's or sort value's name
+says what it does. With `model: "authors"` that is about 20 types: the authors
+types, `Query` narrowed to them, and the shared filter, paging and entry
+types; a kept type that points at a model left out is named in
+`alsoReferenced`. The details and the SDL each come whole: when both do not
+fit in 20,000 characters, `sdl` is left out whole and the note says so and
+points at the resource `capa://graphql/schema.graphql`. The SDL is never cut
+mid-type. Without `model` it is the whole schema, with every
+`@deprecated(reason:)`. Over 20,000 characters it is cut between whole
+models: each model printed comes with `Query` and every type it uses, and the
+note names the models left out ("Printed 40 of 55 models, each with the types
+it uses. Not printed: ... Pass model for one."). The resource prints the full
+form, every description included.
+
+`capa_explore_data { "model": "articles", "field": "tags", "sample": 0 }`:
+
+```json
+{"model":"articles","environment":"production","total":13,"scanned":13,"statuses":{"published":13},
+ "counts":"Counts are of what is stored, so they agree with filters. present: has a value. empty: blank text or an empty list. missing: null or absent, what { null: true } matches; ...",
+ "fields":[{"field":"tags","type":"array of string","present":12,"empty":1,"missing":0,
+  "items":17,"perEntry":{"min":0,"max":2,"mean":1.31,"median":1},"distinct":3,"values":[["news",6],["tech",6],["life",5]]}],"samples":[]}
+```
+
+So "how many articles have no tags?" is `empty` plus `missing`: 1. `statuses`
+counts the entries read by status, and `environment` says which key read
+them: a production key reads published entries only.
+
+Every count is of what is stored, so it agrees with a filter: `missing` is
+what `{ null: true }` matches, and `present` plus `empty` is what
+`{ exists: true }` matches. A query returns something else for two kinds of
+stored value: a reference to an entry it cannot return (deleted, draft only,
+another model), and a value that does not fit its field's type, such as the
+text `"42"` in a number field. It returns both as `null`. So each page the
+query returns is read again over REST, relations unexpanded, for the same
+ids, and the two reads side by side give `dangling` and `mistyped`. Here is
+the seed with four values changed by hand: one article's author and one
+coauthor pointed at authors that do not exist, one `views` stored as `"42"`
+and another as `null`:
+
+```json
+{"field":"author","type":"relation","present":13,"empty":0,"missing":0,"target":"authors","dangling":1,"distinct":4,"top":[...]}
+{"field":"views","type":"number","present":12,"empty":0,"missing":1,"min":5,"max":150,"mean":44,"median":33,"mistyped":1}
+{"field":"coauthors","type":"array of relation","present":8,"empty":5,"missing":0,"target":"authors","items":12,"fanOut":{"min":0,"max":3,"mean":0.92,"median":1},"dangling":1}
+```
+
+On the same data the API's filters count 0 articles for
+`{ author: { null: true } }` and 1 for `{ views: { null: true } }`, as those
+counts say. The range of `views` is over the values of its type only.
+
+REST shows three stored relation lists the same way, as an empty list: one
+stored empty, one stored as `null` or not at all, and one stored as
+something that is not a list, such as text an import wrote. So the entries
+whose list REST shows empty are read twice more. `{ null: true }` finds the
+missing ones. `not` of `has` an id no entry holds finds the ones stored as a
+list, since `not` never matches a value that is not a list. Those count as
+`empty`, and the rest as `present` and `mistyped`.
+
+REST shows some wrong-typed values as `null` too: text stored in an image
+field, a media list that is not a list, a reference that is not an id. For
+media and single relation fields, the entries REST shows as `null` are
+checked once more with `{ exists: true }`, which tests what is stored. Each
+one it matches counts as `present` and `mistyped` (never `dangling`), so the
+counts still agree with the filters.
+
+A media field reports `mediaTypes`, how many values are of each kind of
+file, counted across every item for a list of media, which also reports
+`items` and `perEntry` like any list.
+
+Cut to fit its budget, the answer leaves out `samples` first, then `counts`
+(the legend of what each count means, which the output schema's `counts`
+also carries), and only then shortens `fields`, from the end, with the hint
+`Pass field to measure one field, or sample: 0.` On the zoo's 33-field
+`scalars` model, `maxChars: 3000` keeps 16 fields' numbers, and `1000` keeps 3.
+
+It reads up to `maxEntries` (default 200, at most 1,000) and says so in `note`
+when that is fewer than `total`. The query reads array relations as ids, at
+most 20 per entry, and the page size shrinks with each relation, leaving room
+for the 500 its entry count costs, so the query stays inside the API's
+5,000-entry budget. `items` and `fanOut` count every id stored, from the REST
+read, and `fanOut` is per entry scanned, so a list stored as null counts as 0.
+`dangling` on a relation list checks the first 20 ids of each entry, and
+`danglingChecked` says so when an entry stores more. One query expands at most
+12 relation fields; past that, `skipped` names the rest, and `field` measures
+one of them.
+
+`capa_graphql_build`:
+
+```json
+{"model":"articles","fields":["title",{"field":"author","fields":["name"]}],"filter":{"featured":{"eq":true}},"sort":["views_DESC"],"first":2,"run":true,"code":"all"}
+```
+
+```json
+{"query":"query ArticlesList($first: Int, $sort: [ArticlesSort!], $filter: ArticlesFilter) {\n  articles(first: $first, sort: $sort, filter: $filter) {\n    nodes {\n      id\n      title\n      author {\n        id\n        name\n      }\n    }\n    pageInfo {\n      hasNextPage\n      endCursor\n    }\n  }\n}",
+ "variables":{"first":2,"sort":["views_DESC"],"filter":{"featured":{"eq":true}}},"operationName":"ArticlesList",
+ "rest":"/api/entries/articles?select=title,author(name)&where=%7B%22featured%22:%7B%22eq%22:true%7D%7D&sort=-views&limit=2",
+ "sdk":{"document":"// Run capa-codegen --graphql after saving this: ...","next":"import { draftMode, headers } from \"next/headers\";\n...","node":"...","rest":"..."},
+ "environment":"production",
+ "result":{"data":{"articles":{"nodes":[{"id":"00000000-0000-4000-8000-000000000025","title":"Epsilon engineering notes","author":{"id":"00000000-0000-4000-8000-000000000012","name":"Brin Cole"}},
+   {"id":"00000000-0000-4000-8000-00000000002a","title":"Kappa keeps it simple","author":{"id":"00000000-0000-4000-8000-000000000011","name":"Ada Vale"}}],
+   "pageInfo":{"hasNextPage":true,"endCursor":"c1.eyJ2IjoiMjAyNi0xMC0wMSIs..."}}},
+   "cost":{"depth":3,"rootFields":1,"connections":1,"nodesBound":4,"scans":1,"nodes":4,"fields":12},"budget":{"counted":504,"limit":5000}}}
+```
+
+`sdk` is code for the user's app, typed the way `@capacms/sdk` types its own
+examples, and it comes only when `code` asks for it: `next` for a Next.js
+server component, `node` for anywhere else, `rest` for the REST read, `all`
+for the three, and `none`, the default. `next` and `node` bring `document`
+with them. An agent refining a query pays for no code, and asks for it once,
+on the final build. For the call above it is:
+
+```ts
+// sdk.document
+// Run capa-codegen --graphql after saving this: it types data and the variables from this text.
+const ArticlesList = `#graphql
+query ArticlesList($first: Int, $sort: [ArticlesSort!], $filter: ArticlesFilter) {
+  ...the query above...
+}
+`;
+
+// sdk.next
+import { draftMode, headers } from "next/headers";
+import { graphql, tagsFor } from "@capacms/sdk/nextjs";
+import { ArticlesListModels } from "./capa-graphql"; // written by capa-codegen --graphql
+// In a server component:
+const { data, errors } = await graphql(ArticlesList, {"first":2,"sort":["views_DESC"],"filter":{"featured":{"eq":true}}}, {
+  draftMode,
+  headers,
+  tags: tagsFor({ namespace: ArticlesListModels }),
+  revalidate: 60,
+});
+
+// sdk.node
+import { createClient } from "@capacms/sdk/next";
+const capa = createClient({ baseUrl: process.env.CAPA_API_URL!, apiKey: process.env.CAPA_KEY!, version: "2026-10-01" });
+const { data, errors } = await capa.graphql(ArticlesList, {"first":2,"sort":["views_DESC"],"filter":{"featured":{"eq":true}}});
+
+// sdk.rest, with the same capa
+const page = await capa.entries.list("articles", { select: "title,author(name)", where: {"featured":{"eq":true}}, sort: ["-views"], limit: 2 });
+```
+
+`sdk.document` is the only copy of the document in the code: `sdk.next` and
+`sdk.node` name it. Once `capa-codegen --graphql` has read the literal,
+`data` and the variables are typed from it. `sdk.next` is the SDK's Next.js
+path: drafts and edit marks under preview, the read kept in Next's data
+cache under a tag for every model the query reads (so `revalidateFromWebhook`
+refreshes it on a publish, and `revalidate: 60` at most a minute later if a
+webhook is missed), and an answer with errors never cached. The models are
+`ArticlesListModels`, which `capa-codegen --graphql` writes beside the
+document's types, so the tags follow the query when it is edited. `sdk.node` is for anywhere else. The SDK's
+type test compiles all of it as handed over
+(`packages/sdk/test/types/mcp-snippets.ts`, written by
+`test/support/sdk-snippets.mjs`). `result` carries no `rest` of its own,
+since the API's REST twin is the `rest` above; one that differs comes back as
+`restFromApi`.
+
+A filter value needs its operator: `{ "featured": true }` is refused with the
+form to write, `featured takes operators, not a bare value: write {"featured":{"eq":true}}`,
+since the API would refuse it too, and a REST twin written from it would read
+every entry.
+
+With `run`, the answer is cut to `maxChars` without cutting the document:
+the SDK code goes first, whole, then entries from the result. `query`,
+`variables` and `rest` are never cut. When not even one entry fits beside
+them, `result` is left out, and the note says so and points at
+`capa_graphql_query`, whose answer does not repeat the document. The note,
+then the hint, give way before the budget does, while `truncated` still names
+what was left out. The budget always holds: a document too long for
+`maxChars` is left out whole, the largest part first, and named in
+`truncated`, and the hint gives the `maxChars` that returns it.
+
+The SDK code is for the key the server holds. `@capacms/sdk/next` reads with
+a `cap_` key and with the legacy keys sites already hold (`pk_`, `sk_` or
+unprefixed), so every key gets the same code; for a legacy key `sdk` also
+carries a `note`:
+the SDK warns once about that key, and draft previews need a `cap_` key,
+minted under Developers > Keys.
+
+Each filter value goes as the type the schema declares for its operator,
+whichever way it was written: `{ "a_bool": { "has": "true" } }` on a list of
+true/false values goes as `true`, since that list filters as a
+`BooleanListFilter`, and `"10"` on a number as `10`.
+
+Without `run` it still runs the query once, as a check, and answers
+`check: { ok, entries, cost }` instead of the data. When the API refuses the
+query, the document still comes back, with
+`check: { ok: false, status, errors, next }`, `next` being the tool that helps
+with that error. Over the entries budget, `check.fix` works out the `first`
+that fits, with the API's numbers as it wrote them, and when the API's hint
+names a relation list's `first` instead, names both changes:
+`"Either change fits the limit of 5,000: coauthors(first: 24), as the API's
+hint says, or first: 24 on articles, since each Articles entry can read 201
+with its relations."` A production key's read of one entry that finds
+nothing answers `check: { ok: true, entries: 0 }` beside `notFound`, which
+says a draft-only entry reads as null too. `rest` is written exactly as the API writes it in
+`extensions.capa.rest` (the filter as `where` JSON, the root's default page
+size left out, a relation list's `first` written as `limit:`, 100 included),
+so an agent meets one REST syntax everywhere; if the API ever
+prints a different twin, the answer carries it as `restFromApi`. A name the
+schema does not have comes back as `{"error":"unknown field titel on Articles","didYouMean":["title"],"available":[...],"next":"capa_graphql_schema"}`;
+a query the key cannot build says how to change it, for example `"author on Articles is an id here: this key cannot read the model it points at. Select author without fields for the id"`.
+The GraphQL and REST it writes are byte-identical to `@capacms/sdk`'s
+`buildGraphQLQuery` and `graphqlToSelect`: both packages are tested against
+`packages/sdk/test/fixtures/graphql-vectors.json`, whose REST twins are
+captured from the live API. The admin's GraphQL Explorer builder is pinned to
+the plan's vectors B1 to B5 in the same format.
+
+`capa_graphql_query` runs any read:
+
+```json
+{"query":"{ articles(first: 2, filter: { author: { name: { eq: \"Ada Vale\" } } }) { nodes { title views } } }"}
+```
+
+```json
+{"data":{"articles":{"nodes":[{"title":"Kappa keeps it simple","views":74},{"title":"Eta on effort estimation","views":3}]}},
+ "cost":{"depth":2,"rootFields":1,"connections":1,"nodesBound":2,"scans":1,"nodes":2,"fields":4},"budget":{"counted":502,"limit":5000},
+ "rest":[{"field":"articles","url":"/api/entries/articles?select=title,views&where=%7B%22author.name%22:%7B%22eq%22:%22Ada%20Vale%22%7D%7D&limit=2"}],
+ "environment":"production"}
+```
+
+`cost` is the API's own measure from `extensions.capa.cost`, `rest` the
+REST request each root field equals, from `extensions.capa.rest`, and
+`environment` the key's, from `extensions.capa.environment`. The API sends
+`extensions.capa` to a production key only when the request asks for it, and
+this server always asks.
+
+`budget` is `extensions.cost.budget`, which every answer carries: `counted`
+is the figure the API checked against the 5,000-entry `limit` before it read.
+Each relation filter costs 500, so this read counts 502 although it returns 2
+entries; a document whose `counted` nears the limit is the one to trim before
+it is refused. A read that used a field a later API version deprecates also
+gets `deprecations`, one `{ coordinate, reason }` for each, from
+`extensions.deprecations`, which is left out when there is none.
+
+A refused query (a typo, a mutation, a budget) is an `isError` result that
+lists each error with its code and hint, then under `Next:` the fix for each
+code and the tool that helps with it, if one does. A refusal is a body with
+`errors` and no `data`, which the API sends as a 200 on `application/json`
+(what this server asks for) and as a 4xx on
+`application/graphql-response+json`, as GraphQL over HTTP has it. Every tool
+reads both the same way, as `HTTP 400`; a query the API ran answers `data`
+with any `errors` beside it. The commonest mistakes get
+the exact fix: a field selected on a list says to select it inside
+`nodes { ... }`, `where` or `limit` says GraphQL calls it `filter` or
+`first`, a bare filter value gets the form with its operator, and a missing
+variable names the variable and its type, and a document of several
+operations names the ones `operationName` can take. For a budget the line
+quotes the API's message and the change its hint names, as the API wrote
+them, then the tool:
+
+```text
+Next:
+- query_too_complex: articles: could read 40,200 entries, over the limit of 5,000. Pass coauthors(first: 24) to fit, or lower first elsewhere. Tool: capa_graphql_build.
+```
+
+Where the hint names no change, the line says which knob the budget turns,
+still with the API's numbers.
+
+A cursor passed with another sort than it was issued for is refused by the
+API with `This cursor was issued for a different sort.`, which is what an
+agent pastes:
+
+`capa_explain_error { "error": "invalid_cursor: This cursor was issued for a different sort." }`:
+
+```json
+{"errors":[{"code":"invalid_cursor","message":"invalid_cursor: This cursor was issued for a different sort.",
+  "meaning":"The after or before cursor is malformed, was minted for another sort, or belongs to another parent entry.",
+  "fix":"Pass a cursor from a page of the same query, unchanged, with the same sort: its endCursor as after, or its startCursor as before.",
+  "next":"capa_graphql_query","docs":"https://docs.capacms.com/errors/invalid_cursor"}]}
+```
+
+A budget refusal also gets `budget: { measured, limit }`, from the API's own
+message; `measured` keeps an "at least" where the API stopped counting early.
+
+It takes a GraphQL `errors` body, a REST error envelope, an SDK `CapaError`,
+plain text or a bare `code`. A request that never reached Capa is told apart
+from an API error: `fetch failed`, `ECONNREFUSED`, `ENOTFOUND` and a timeout
+answer `code: "unreachable"` with the step this server gives for a host it
+cannot reach, and no tool, since none helps. A status is read only where the
+text states one (`HTTP 404`, `status 400`, `Capa API 401`), never from an
+address such as `127.0.0.1`. It calls nothing, so it needs no scope and is
+offered to every key. The server itself still needs `CAPA_API_URL` and
+`CAPA_KEY` to start: one that started with a single tool would hide the
+misconfiguration instead of naming it.
+
+`mutations_not_enabled` is the one code with two causes, so its advice
+depends on what came with it. The GraphQL handler's refusal of a mutation
+carries a hint, and gets "Send a query instead; nothing here can write." A
+bare code also gets the other cause: a query sent where GraphQL is off.
+
+### Resources and prompts
+
+| resource | what |
+|---|---|
+| `capa://graphql/schema.graphql` | the key's SDL, whole and never cut, for clients that attach a schema as context. `resources/list` gives its `size` in bytes and says to read one model's instead; the tools read the schema in bounded pieces |
+| `capa://graphql/schema/{model}.graphql` | a template: one model's SDL, its type, connection, filter and sort and the shared types they use. `{model}` is a namespace or type name; an unknown one is MCP's resource-not-found error (-32002), with the nearest names |
+| `capa://guide/querying` | the order to call the tools in, the filter and sort grammar, and the limits |
+
+`initialize` also answers `instructions`, a few sentences a client can put
+before the model: start with `capa_graphql_schema`, never guess a name it has
+not shown, what a production and a development key read, and where the guide
+is. They name only the tools this key was given.
+
+| prompt | arguments | what it asks the agent to do |
+|---|---|---|
+| `explore-content` | `model?` | describe, explore and summarise a model's content, quoting the numbers |
+| `write-query` | `goal`, `model?` | turn a plain request into a working query and hand back GraphQL, REST and SDK code |
+| `fix-query-error` | `error` | explain a failed call and rebuild the query |
+
+A prompt is offered only to a key that has every tool it sends the agent to,
+and the guide only with `capa_graphql_schema`, so a key holding nothing but
+`capa_explain_error` gets neither.
+
+## The page tools
+
+A **page** is a string starting with `/` that Capa learned about in one of two
+ways, and the list is their union (`docs/api/pages.md`):
+
+* **declared**: a model carries a route, `/blog/[slug]` or `/pricing`, set in
+  the Capa admin. It exists with zero traffic, because a route somebody just set
+  up should show up immediately rather than after the first visitor.
+* **observed**: a read arrived carrying the page as the `Capa-Page` header. It
+  exists whether or not any model declares it, because most sites have pages
+  Capa knows nothing about.
+
+They join on the string, so a page in both is `kind: "both"`. That is what makes
+these tools worth an agent's time: asked to change `/pricing`, an agent
+otherwise has to guess which models render it.
+
+The examples in this section are real outputs on the same seed, with the page
+routes on (`CAPA_SITE_PREVIEW=on`) and six entry reads sent with `Capa-Page`.
+The seed declares no routes, so every page here is `observed`.
+
+`capa_list_pages` is the map, busiest first:
+
+```json
+{"pages":[
+  {"id":"/blog","kind":"observed","models":[{"id":"00000000-0000-4000-8000-000000000003","namespace":"articles","name":"Article"}],
+   "reads30d":3,"lastReadAt":"2026-09-25T05:03:06.788Z","slugField":null},
+  {"id":"/blog/[slug]","kind":"observed","models":[...],"reads30d":2,"lastReadAt":"2026-09-25T05:03:06.808Z","slugField":null},
+  {"id":"/authors","kind":"observed","models":[{"id":"00000000-0000-4000-8000-000000000010","namespace":"authors","name":"Author"}],
+   "reads30d":1,"lastReadAt":"2026-09-25T05:03:06.817Z","slugField":null}],
+ "total":3,"insights":[]}
+```
+
+Pass `entry: "<uuid>"` and it answers **which pages read that entry**, each row
+carrying an extra `entryReads`: for the article "Epsilon engineering notes",
+`/blog` with `"entryReads":3` and `/blog/[slug]` with `"entryReads":1`. That is the "what breaks if I unpublish this?"
+question. `entryReads` covers a shorter window than `reads30d` (seven days,
+because entry ids live only on the raw read rows), which is why it is its own
+key rather than a narrowing of that number. An entry nothing reads and an id
+that never existed both answer an empty list, deliberately, so the route cannot
+be used to find out which ids exist. That is why a malformed `entry` is
+refused here instead of sent.
+
+`capa_get_page` is one page in full, passed through exactly as the API sends it:
+
+```json
+{"page":"/blog/[slug]","kind":"observed",
+ "models":[{"id":"00000000-0000-4000-8000-000000000003","namespace":"articles","name":"Article"}],
+ "reads30d":2,"readsByDay":[{"day":"2026-09-25T00:00:00.000Z","reads":2}],
+ "entries":[{"id":"00000000-0000-4000-8000-000000000011","modelId":"00000000-0000-4000-8000-000000000010","namespace":"authors","title":"Ada Vale","reads":1},
+   ...,
+   {"id":"00000000-0000-4000-8000-00000000002a","modelId":"00000000-0000-4000-8000-000000000003","namespace":"articles","title":"Kappa keeps it simple","reads":1}],
+ "queries":[{"modelId":"00000000-0000-4000-8000-000000000003","namespace":"articles","selectText":"title,body,author(name,bio)","reads":2,
+   "lastAt":"2026-09-25T05:03:06.808Z","keyIds":["..."],
+   "url":"/api/entries/articles/00000000-0000-4000-8000-000000000025?select=title,body,author(name,bio)",
+   "selection":{...},"selectionError":null}],
+ "since":"2026-08-27T00:00:00.000Z","slugField":null,"lastReadAt":"2026-09-25T05:03:06.808Z","insights":[]}
+```
+
+`queries` is one row per distinct (model, select) the page asked for, which is
+how a page fetching far more than it renders shows up. An entry whose `modelId`
+and `namespace` are empty is one Capa no longer holds a row for, and it is kept
+on purpose: "this page reads something that is gone" is the most useful thing
+that list can say. A `null` title alone means only that the entry's row stores
+no title, which is common. The
+response is handed over **verbatim**, so fields the API adds later reach an
+agent without this package being edited. A page nobody declared and nobody has
+read answers `page_not_found` in band, with the pages this project does have.
+
+`capa_suggest_queries` is the same page's suggestions, plus the queries they are
+about:
+
+```json
+{"page":"/blog",
+ "insights":[{"kind":"overfetch","severity":"warn","title":"This page asks for the whole entry.",
+   "detail":"This read sends no select, so every field comes back and each relation is expanded as well. Naming the fields the page renders stops the relation rows being fetched at all.",
+   "evidence":{"fieldCount":7,"relationCount":2,"reads":1},"modelId":"00000000-0000-4000-8000-000000000003",
+   "queryKey":"00000000-0000-4000-8000-000000000003:*","rewrite":{"select":"title,body,views,featured,tags"}}],
+ "queries":[{"modelNamespace":"articles","selectText":"title,views,author(name)","reads":2},
+   {"modelNamespace":"articles","selectText":"*","reads":1}]}
+```
+
+**It computes nothing.** The rules that read a page's queries and say "this one
+fetches more than it renders" run on the API, so the Capa admin and an agent
+read one answer rather than two implementations that drift, and this package
+stays dependency-free rather than growing a select parser. An empty `insights`
+is an answer, not a failure, and `note` says which kind of empty it is: no reads
+in the window at all, or reads the API had nothing to say about.
+
+### Which tools a key is offered
+
+The server takes one key and registers by its **family**, decided at startup
+from the prefix:
+
+| key | gets |
+|---|---|
+| `cap_…` | the eight `/api/` and offline tools, and nothing else (`capa_read_entries` in place of the four GraphQL tools where GraphQL is off) |
+| any other key: `pk_…`, `sk_…` or unprefixed | those eight **and** all ten legacy tools |
+
+A `cap_` key is refused on every legacy mount before the lookup even runs, so
+offering it `capa_list_models` would be offering a tool that cannot work. A
+legacy key loses nothing: `/api/` accepts it and derives its scopes from the
+key's bundle.
+
+Then `GET /api/me` is asked what the key holds, and an `/api/` tool whose scope
+is missing is left out rather than registered and refused every time. The page
+routes want **unscoped** `instance:read`: a key holding only
+`instance:read:<modelId>` does not get them, because a page list spans every
+model a page touches and there is no per-model projection of it that is still a
+page list.
+
+The GraphQL tools are the opposite case, on purpose: they register for any key
+holding `instance:read` or an `instance:read:<modelId>` scope, because
+`/api/graphql` builds its schema per key and a one-model key reads that model
+there and nothing else. `capa_explain_error` never calls Capa and is offered
+to every key. When the key's scopes leave a tool out, a line on stderr says
+which scopes the key holds and what the missing tools need, so a person
+reading the tool list knows why it is short.
+
+The page routes are served only where `CAPA_SITE_PREVIEW` is on, and it is
+off by default. So at startup, beside `/api/me`, the server asks
+`GET /api/preview` with no token: `route_not_found` means the deployment does
+not serve pages, and the three page tools are left out, with a line on
+stderr. Any other answer, a 401 included, means the route is there. A page
+tool called anyway on such a deployment answers `pages_not_enabled` and points
+at `capa_graphql_schema` and `capa_explore_data`.
+
+GraphQL is on by default and `CAPA_API_GRAPHQL=off` switches it off, so the
+server also asks `POST /api/graphql` with `{ __typename }`, a POST because an
+admin-role host serves GraphQL by POST only. Only the answer of a path the API
+does not serve, in the REST envelope, means no: then the four GraphQL tools,
+the schema resource, the guide and the prompts are left out, and
+`capa_read_entries` is registered in their place, with a line on stderr that
+names it. Any answer from the GraphQL handler, a refusal included, means the
+route is there. `capa_explain_error` stays, since it calls nothing.
+
+GraphQL leaves a model out when its type name would be the same as another's
+(`twin_a` and `twin-a`), and the schema lists it as `Models not exposed in
+GraphQL`. REST still reads it, so where the key's schema leaves one out, the
+server also reads the schema at startup and registers `capa_read_entries`
+beside the GraphQL tools, described as the read for those models, with a line
+on stderr that names them. `capa_graphql_schema` lists them among the models
+as `"graphql": "none: readable over REST only; capa_read_entries reads it"`
+with their REST path, and every GraphQL tool asked for one answers
+`"twin_a is readable over REST only: GET /api/entries/twin_a. GraphQL leaves it
+out, since it and twin-a would have the same GraphQL type name."` with
+`"next": "capa_read_entries"`, never a suggestion of another model.
+
+If `/api/me` does not answer (a deployment with the `/api/` surface switched
+off answers 404, an unreachable host answers nothing), the `/api/` tools register
+anyway and the reason goes to stderr. Neither failure is evidence about what the
+key may do, and dropping the tools there would turn a reachability problem into
+"Capa has no page tools", which is the wrong conclusion for an agent and an
+impossible one for a person to debug from a tool list. After a 404 from
+`/api/me`, a GraphQL tool whose request is refused the same way says that
+either `CAPA_API_URL` is not the API's address or the deployment does not
+serve `/api/`, rather than that GraphQL is off.
+
+## The layout tool
+
+A **layout** says how one model's entry editor is arranged: cards in a main
+column and a side column, each field placed in one of them, and relation fields
+optionally shown as editable line items
+(`docs/design/ADMIN_UI_OVERHAUL.md` section 0m, and `apps/api/LAYOUT.md` for the
+whole contract). `layout: null` is the plain linear editor, which is what every
+model has until somebody designs one.
+
+A relation field takes `display: "picker"`, `"inline"` or `"embedded"`.
+`embedded` (section 0m.8) draws the related entry's own fields directly in the
+parent card rather than as a link or a row. With no `display` on the node, the
+RELATED model's own `embedByDefault` decides, which is why `capa_get_model`
+reports that flag as well: it is the fact a layout written for a parent depends
+on. A node's explicit `display` always wins over it.
+
+`capa_get_model` returns the document, and `capa_set_model_layout` takes the
+same one back, so an agent reads, edits and writes. If the key could not read
+the model's detail, `capa_get_model` omits `layout` and `embedByDefault`
+ALTOGETHER and says why in `layoutUnavailable`. `layout: null` is a claim that
+the model has no page, `embedByDefault: false` a claim that it does not pass
+through, and neither is ever made on a guess:
+
+```json
+{
+  "v": 1,
+  "main": [
+    { "id": "c1", "title": "Hero", "collapsible": false, "collapsed": false,
+      "items": [{ "id": "n1", "fieldId": "<field id>", "width": "full" }] }
+  ],
+  "aside": []
+}
+```
+
+Fields are placed by **id**, which is why `capa_get_model` now returns one per
+field. It costs a second request for one model, and without it the write tool
+could not be used at all. A field may appear at most once in the whole
+document; the fields left out are not lost, they render in a "More fields" card
+at the end.
+
+A rejected document is answered with the NODE it is about,
+`{ error, path: "main[0].items[2].fieldId" }`, so a retry can fix one thing
+rather than guess. Unlike the workspace tools, this one needs a key whose
+permission is `agent`: it writes a model, and that is the gate every other
+model write asks for.
+
+## The workspace tools
+
+A **workspace** is one saved arrangement of the Capa admin's left rail: which
+models, entries and media folders a person or a team keeps in reach, in which
+folders, in which order (`docs/design/ADMIN_UI_OVERHAUL.md` sections 0h and 0t).
+It is navigation, not storage: a workspace node points at a record, and removing
+it changes nothing about the record.
+
+`capa_get_workspace` and `capa_set_workspace` speak the **same JSON document**,
+so an agent can read one, edit it, and write it back:
+
+```json
+{
+  "name": "Team",
+  "tree": [
+    { "folder": "Schema", "children": [{ "model": "blog_post" }] },
+    {
+      "folder": "Launch",
+      "children": [{ "instance": "0d1f…" }, { "media_folder": "9a2c…" }]
+    }
+  ]
+}
+```
+
+Models are addressed by **namespace or id**; entries and media folders by id.
+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 to choose between: the folders in the example are words
+somebody typed, not categories of ours.
+
+`template` on a create starts a workspace with a handful of folders:
+`"blank"` (the default) makes none, `"website"` makes Pages, Components,
+Settings and Media, `"catalog"` makes Products, Collections and Assets. It is
+ignored when applying to a workspace that already exists.
+
+`mode` defaults to `"merge"`, which adds what is missing and removes nothing.
+`"replace"` makes the workspace exactly the document. Applying the same document
+twice is a no-op, and the `changes` summary says so, so a retry is safe and an
+agent can tell whether it did anything.
+
+**The old three-key shape still works, for one release.** A `tree` of
+`{ model, content, media }` is accepted and lands in folders called Models,
+Content and Media, keeping the rule it came with: a key the document does not
+name is left alone even in `replace` mode, so a half document cannot empty a
+section by omission. Send a `Node[]` instead.
+
+## Tests
+
+`pnpm -F @capacms/mcp test` runs every case with no network beyond localhost. The
+GraphQL tools run against `test/support/graphql-stub.mjs`, a local
+`/api/graphql` that serves the seed schema from `packages/sdk/test/fixtures`
+with a small content set of its own, not the seed's. It also serves the
+stored values of `/api/entries/<model>` that `capa_explore_data` reads, and
+with `{ graphql: false }` answers as `CAPA_API_GRAPHQL=off` does. Run it on
+its own with `node test/support/graphql-stub.mjs 4461` to drive the stdio
+server by hand. The worked examples above come from a real API, not the stub.
+The tests also hold the context budget: each new description at most 700
+characters, the four reading tools' descriptions and schemas at most 4,000,
+the five output schemas at most 4,000, and `capa_graphql_schema` on the seed
+at most 1,500 (4,000 for one model). The write tools are driven
+through a fetch stub that records the METHOD and the body, because "it sent a
+PUT to /tree with mode merge" is the only thing separating applying a document
+from asking for one. The stub records the HEADERS for the same reason on the
+other surface: that `/api/` sends `Capa-Version` and never sends `X-Tenant-Key`
+is invisible in any response body. Already enforced in CI via `turbo run test`.
+
+(Not `node --test packages/mcp/test/`: passing a DIRECTORY to `node --test` is
+resolved as a module path on Node 22 and fails with MODULE_NOT_FOUND. The
+package script names the file explicitly, which is the house pattern.)