@capacms/mcp 0.2.1 → 0.3.0

package/README.md

@@ -1,9 +1,14 @@
 # @capacms/mcp
 
-stdio MCP server for Capa. Seventeen reads, two writes, two resources and three
+stdio MCP server for Capa. Eighteen reads, seven writes, two resources and three
 prompts. People set it up from the
 [AI assistants guide](https://docs.capacms.com/ai/mcp), which has
-the Claude Code, Cursor and Codex config.
+the Claude Code, Cursor and Codex config. `capa init claude`, `capa init codex`
+and `capa init cursor` from `@capacms/cli` write that config, and serve these
+tools as `capa mcp` with the key `capa login` kept in the keychain.
+
+The server is also a module (`import { connect, runTool } from
+"@capacms/mcp"`): the `capa` CLI's content commands are these tools by name.
 
 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
@@ -43,10 +48,10 @@ as a proxy's `/capa`, is kept. Spaces around `CAPA_API_URL`, `CAPA_KEY` and
 `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
+reaches `/api/`, and `/v2/agent` on a deployment that accepts it there. Both
+resolve the tenant from the key and never read that header, and the server
+never sends it 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.
 
@@ -54,23 +59,24 @@ legacy keys only.
 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)).
+Twenty-five tools, of which a given key is offered a subset. The `needs` column is
+the permission a legacy key needs, then the scope a `cap_` key needs where it
+is offered the tool. The `surface` column is which part of the API it calls,
+which is what decides whether it is registered at all (see
+[which tools a key is offered](#which-tools-a-key-is-offered)).
 
 | 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_models` | what content exists here, and what relates to what | legacy | read; never a `cap_` key |
+| `capa_get_model` | what shape is this model: fields, types, relations, and how its editor is laid out | `/v2/agent` | read, or `model:read` |
+| `capa_set_model_layout` | design that model's entry editor, or reset it to linear | `/v2/agent` | **agent**, or `model:update` |
+| `capa_list_content` | which instances of this model exist | legacy | read; never a `cap_` key |
+| `capa_get_content` | this one instance, in full, with relations | legacy | read; never a `cap_` key |
+| `capa_search_content` | where does this text live, when you don't know the model | legacy | read; never a `cap_` key |
+| `capa_get_types` | the generated TypeScript, for writing code against a tenant | legacy | read; never a `cap_` key |
+| `capa_list_workspaces` | which saved arrangements of the admin rail exist | `/v2/agent` | read, or `workspace:read` |
+| `capa_get_workspace` | one workspace as a document you can edit and write back | `/v2/agent` | read, or `workspace:read` |
+| `capa_set_workspace` | create a workspace, or apply a document to one | `/v2/agent` | **write**, or `workspace:create` or `workspace:update` |
 | `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` |
@@ -79,15 +85,26 @@ at all (see [the page tools](#the-page-tools)).
 | `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 |
+| `capa_read_entries` | read entries over REST: for a `cap_` key always; for a legacy key where the deployment serves no GraphQL, or of the models GraphQL leaves out | `/api/` | `instance:read` for any model |
+| `capa_create_entry` | save a new entry in a model, as a draft | `/v2/agent` | `instance:create`; never a legacy key |
+| `capa_update_entry` | change fields of one entry, saved as a new draft version | `/v2/agent` | `instance:update`; never a legacy key |
+| `capa_publish_entry` | make an entry's newest draft the version sites read | `/v2/agent` | `instance:publish`; never a legacy key |
+| `capa_unpublish_entry` | stop sites reading an entry, keeping it as a draft | `/v2/agent` | `instance:publish`; never a legacy key |
+| `capa_list_media` | which files the project has, as the objects image, video and file fields take | `/v2/agent` | `media:read`; never a legacy key; only where uploads are on, and not for a production key that may neither upload nor write entries |
+| `capa_upload_media` | upload a file from the project folder, answered as that field value | `/v2/agent` | `media:create`; never a legacy key; only where uploads are on, and with an uploader address |
 
 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.
+without asking and confirm a write. The eighteen reads are
+`readOnlyHint: true`. The seven writes are `readOnlyHint: false`. Six are
+`destructiveHint: true`, since each can replace what is there;
+`capa_upload_media` only adds a file, so it is `destructiveHint: false` and
+`idempotentHint: false`.
 `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
+layout, and so are `capa_publish_entry` and `capa_unpublish_entry`: a
+repeated publish or unpublish answers `skipped`. `capa_set_workspace` is not,
+because without an `id` it creates a new workspace on every call, and neither
+is `capa_create_entry`. Nor is `capa_update_entry`: every call saves a new
+draft version, the same values included. Every tool is `openWorldHint: false`, since none
 reaches past this Capa deployment.
 
 Every answer is held to 20,000 characters. The GraphQL tools and
@@ -215,7 +232,7 @@ names and a suggestion, never silently dropped. A relation spec in `capa_graphql
 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
+mutation at the entry tools, since GraphQL here only reads. 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
@@ -232,15 +249,18 @@ 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>.
+Next: tell the person running Capa that GraphQL is off here. To read entries meanwhile, capa_read_entries reads them over REST with this key. 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`.
+That is a `cap_` key's answer. A legacy key is pointed at `capa_list_content`
+and `capa_get_content` instead.
 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
+GraphQL is off. A `cap_` key gets it wherever GraphQL is served too, described
+as the REST read beside the GraphQL tools, since it has no legacy content tool
+to read with. 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
@@ -581,7 +601,7 @@ 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
+carries a hint, and gets "Send a query instead; GraphQL here cannot write.", with the entry tools named. A
 bare code also gets the other cause: a query sent where GraphQL is off.
 
 ### Resources and prompts
@@ -702,13 +722,43 @@ 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 |
+| `cap_…` | the `/api/` and offline tools, `capa_read_entries` among them, and the nine `/v2/agent` tools where the deployment accepts a `cap_` key there, plus the two media tools where it also takes uploads |
+| any other key: `pk_…`, `sk_…` or unprefixed | the `/api/` and offline tools **and** all ten legacy and `/v2/agent` tools, as before 0.3.0; never the entry or media tools |
+
+`/v2/schema`, `/v2/api` and `/v2/schema/types` refuse a `cap_` key before the
+lookup even runs, so `capa_list_models`, `capa_list_content`,
+`capa_get_content`, `capa_search_content` and `capa_get_types` are never
+offered to one. A legacy key loses nothing: `/api/` accepts it and derives its
+scopes from the key's bundle.
+
+`/v2/agent` accepts a `cap_` key on a deployment that turned that on, and
+`GET /api/me` says so: the key's `surfaces` list `"/v2/agent"` there. On such
+a deployment a `cap_` key also gets `capa_get_model`,
+`capa_set_model_layout`, `capa_list_workspaces`, `capa_get_workspace`,
+`capa_set_workspace`, `capa_create_entry`, `capa_update_entry`,
+`capa_publish_entry` and `capa_unpublish_entry`, each only with the scope its
+route checks, from the `needs` column. `capa_set_workspace` needs either scope: without an `id` it
+creates a workspace (`workspace:create`), with one it applies a document
+(`workspace:update`). For a `cap_` key `capa_get_model` reads
+`/v2/agent/models/<namespace>` alone, never `/v2/schema`, and answers the same
+document; a legacy key's call reads `/v2/schema` first, as before. No call
+sends `X-Tenant-Key` for a `cap_` key. Where `surfaces` does not list
+`"/v2/agent"`, or is not reported, these nine are left out, and a line on
+stderr names the ones the key's scopes would get, and that they need a
+deployment that accepts `cap_` keys there.
+
+A `cap_` key holding the Read only preset is offered, on a deployment without
+the page routes:
+
+| deployment | tools |
+|---|---|
+| keeps a `cap_` key on `/api/` | `capa_graphql_schema`, `capa_graphql_build`, `capa_graphql_query`, `capa_explore_data`, `capa_explain_error`, `capa_read_entries` |
+| accepts a `cap_` key on `/v2/agent` | those six, and `capa_get_model`, `capa_list_workspaces`, `capa_get_workspace` |
 
-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.
+The six write tools need `model:update`, `workspace:create` or
+`workspace:update`, `instance:create`, `instance:update` and
+`instance:publish`, which the Read only preset does not hold. The Content
+writer preset holds the three entry scopes.
 
 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
@@ -756,7 +806,9 @@ out, since it and twin-a would have the same GraphQL type name."` with
 
 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
+anyway and the reason goes to stderr. A `cap_` key's `/v2/agent` tools do not:
+nothing then says the deployment accepts the key there, and the stderr line
+says that too. 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
@@ -856,6 +908,161 @@ 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.
 
+## The entry tools
+
+`capa_create_entry`, `capa_update_entry`, `capa_publish_entry` and
+`capa_unpublish_entry` write content through `/v2/agent/model-instances`. They
+are offered to a `cap_` key only, where the deployment accepts one on
+`/v2/agent` and the key holds the tool's scope (`instance:create`,
+`instance:update`, `instance:publish`); the Content writer preset holds all
+three. A legacy key never gets them, so its tool list is the one it had
+before.
+
+Both save a **draft**. Neither ever publishes, whatever the key may do, so
+what a site reads does not change until the entry is published. A model is
+named by its namespace, the name every read answers with, and `data` is flat:
+`{ "<field namespace>": <value> }`. A relation takes the related entry's id;
+an image, video or file field takes the whole file object an upload answered.
+
+```json
+{"model":"articles","data":{"title":"Hello from an agent","body":"First draft."}}
+{"created":true,"entry":{"id":"...","model":"articles","title":"Hello from an agent","status":"draft","live":false,"versionId":"...","versionNumber":1,
+ "data":{"title":"Hello from an agent","body":"First draft."}},"next":"Saved as a draft. A development or draft key reads it now with capa_read_entries { model, id }; ..."}
+```
+
+`capa_update_entry` takes `id` and `data`, and **merges**: a field `data`
+leaves out keeps its value, and `null` clears one. Each update is a new
+draft version. A published entry keeps serving its published version until
+it is published again.
+
+Every key of `data` must be one of the model's field namespaces. The API
+builds what it stores from the model's own fields, so it drops any other key
+without a word and answers success: `{"titel":"x"}` saved an identical
+version. Both tools refuse such a key before writing anything:
+
+```json
+{"error":"The model \"articles\" has no field \"titel\".","didYouMean":["title"],"available":["title","body","views"],
+ "next":"Nothing was written. Name each field by a namespace from available and send it again. ..."}
+```
+
+The check reads the model, which takes `model:read` (and, for an update,
+`instance:read` to find the entry's model). A key without them writes
+unchecked, and the answer says so in `unchecked`; `entry.data` in it is what
+was stored. Such a key cannot name a model by its namespace either: that is
+refused with the two ways forward, the model's id or a key with `model:read`.
+
+A key of any environment writes. What it reads back differs: a development
+or draft key reads drafts, so `capa_read_entries { model, id }` returns the
+new entry at once; a production key reads published entries only, so a draft
+it wrote shows up in its reads once the entry is published. Every answer says
+so in `next`.
+
+Publishing is its own tool, with its own scope. `capa_publish_entry { id }`
+makes the newest draft the version sites read (`versionId` publishes an older
+one); `capa_unpublish_entry { id }` stops sites reading the entry and keeps
+its content as a draft. Both change what every visitor reads, so both are
+marked destructive, and a client asks its person before each call unless told
+not to. Their descriptions ask the agent to publish only what the person
+asked for. A second publish of the same version, or an unpublish of an entry
+with nothing published, answers `skipped` and changes nothing. The agent
+mount has no one-entry unpublish route, so `capa_unpublish_entry` sends
+`POST /v2/agent/model-instances/bulk-unpublish` with one id.
+
+A refusal comes back in band with the API's own words and the next step: a
+missing or wrong field gets the API's message and points at
+`capa_get_model`, a model that does not exist gets `didYouMean` and
+`available`, and a key without the scope gets the scope to ask for. An
+unpublish the API could not do answers `unpublished: false` with its `error`
+and `code`, says the entry is still published, and says to try again or tell
+the person.
+
+## Changes in 0.3.0
+
+- **Deep imports are refused.** 0.2.1 had no `exports` map, so
+  `@capacms/mcp/lib/<file>.mjs` could be imported. 0.3.0 exports the package
+  root (`connect`, `loadConfig`, `runTool`, `serveStdio`, `selectTools`,
+  `TOOLS`, `TOOLS_BY_NAME` and the rest of `lib/index.mjs`) and
+  `package.json` only, so a deep import fails with
+  `ERR_PACKAGE_PATH_NOT_EXPORTED`. Import the same names from
+  `@capacms/mcp`. The `capa-mcp` command is unchanged.
+- **The entry tools** (`capa_create_entry`, `capa_update_entry`,
+  `capa_publish_entry`, `capa_unpublish_entry`) are new, for a `cap_` key on a
+  deployment that accepts one on `/v2/agent`. A legacy key's tool list and
+  its stderr lines are unchanged.
+- **A `cap_` key's stderr lines name the entry tools.** Four startup lines list
+  the `/v2/agent` tools a `cap_` key is not offered, and each now lists the
+  four entry tools too:
+  - "this deployment does not accept a cap_ key on /v2/agent, so ... are not
+    offered", which is production's case while `CAPA_AGENT_CAP_KEYS` is off;
+  - "this deployment does not say it accepts a cap_ key on /v2/agent, so ...
+    are not offered";
+  - "this key holds ..., so ... are not offered: they need ...", which now
+    also names `instance:create`, `instance:update` and `instance:publish`;
+  - the line when `/api/me` cannot be read, which now says "The model,
+    workspace and entry tools (...) are not" where 0.2.1 said "The model and
+    workspace tools".
+- **The media tools** (`capa_list_media`, `capa_upload_media`) are new, for a
+  `cap_` key on a deployment that accepts one on `/v2/agent` and takes
+  uploads with an API key (`CAPA_AGENT_UPLOADS=on`). The upload tool also
+  needs the uploader's address. At startup a `cap_` key now asks
+  `GET /v2/agent/file-uploads?size=1` once. Where uploads are off, the list
+  is not the key's, or there is no uploader address, a new stderr line says
+  which tool is left out and why. A legacy key's tool list, startup requests
+  and stderr lines are unchanged. See [the media tools](#the-media-tools).
+
+## The media tools
+
+`capa_list_media` and `capa_upload_media` are offered to a `cap_` key only,
+where the deployment accepts one on `/v2/agent` **and** takes uploads with an
+API key (`CAPA_AGENT_UPLOADS=on`). The server asks
+`GET /v2/agent/file-uploads?size=1` at startup: with the switch off that
+answers `404 agent_uploads_disabled`, and both tools are left out with a line
+on stderr. Unlike the page and GraphQL probes, an answer that says nothing (no
+answer, or an API older than the route) also leaves them out, since every call
+would be refused. A key that sees published content only there (a
+production key that may neither upload nor write entries) is answered
+`403 agent_route_needs_draft_access`: uploads are on, but files have no
+published view, so the list is left out for that key, with a line on stderr.
+A production key holding `media:create` uploads like any other, and lists the
+files too: on the file routes a media write reads drafts. `workspace:update`
+and `model:update` do not count there.
+
+`capa_list_media` reads `GET /v2/agent/file-uploads` (`media:read`): the
+project's files, newest first, narrowed by `search` (part of the name),
+`type` (`image`, `video`, `file`, `audio`, `document` with PDFs, or `pdf`) or
+`folderId`, a page of `size` at a time. Each file is the object an image,
+video or file field takes, so it goes into `capa_create_entry` or
+`capa_update_entry` whole.
+
+`capa_upload_media { path }` uploads one file in two calls, so the key never
+reaches the uploader:
+
+1. `POST /v2/agent/file-uploads/ticket` with the key (`media:create`) answers
+   a ten-minute ticket. The API decides which keys get one, and a refused key
+   gets the API's reason in band.
+2. `POST <CAPA_UPLOAD_URL>/upload?wait=true`, multipart field `file`, with
+   the ticket as the bearer token. `wait=true` answers once the file is
+   stored, so its URL works when the agent uses it.
+
+`CAPA_UPLOAD_URL` is the uploader's address, the host the Capa admin sends
+files to. Capa's hosted API (`CAPA_API_URL` of `https://api.capacms.com`,
+`https://cdn.capacms.com` or its Fly hosts) defaults it to
+`https://uploads.capacms.com` (`HOSTED_UPLOAD_URL`), Capa's uploader. Any other API has no default, so a file never
+goes to Capa's uploader with a ticket from somewhere else. With no address
+the upload tool is not offered, and stderr says so.
+
+The tool reads a path an agent chose, so it reads only inside one folder:
+`CAPA_UPLOAD_ROOT` when the person sets it, else `CLAUDE_PROJECT_DIR` (the
+project Claude Code names), else the folder the server started in. A folder
+nobody chose that is the home folder or holds it (`~`, `/Users`, `/`) is
+refused outright. The path is resolved with symlinks followed, and a path
+outside the folder, under any hidden name (`.env`, `.git/`, `.npmrc`), or
+named like a private key or certificate (`id_rsa*`, `*.pem`, `*.key`,
+`*.p12`, `*.pfx`, `*.ppk`, `*.p8`, `*.jks`, `*.keystore`, `*.gpg`, or a backup
+of one such as `server.pem.bak`) is refused before a ticket is asked for.
+`CAPA_UPLOAD_ALLOW`, separated as `PATH` is, names files the person lets
+through anyway; the agent cannot set it.
+
 ## Tests
 
 `pnpm -F @capacms/mcp test` runs every case with no network beyond localhost. The
@@ -863,7 +1070,8 @@ 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
+with `{ graphql: false }` answers as `CAPA_API_GRAPHQL=off` does, and with
+`{ surfaces }` reports those surfaces on `/api/me`. 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

package/bin/capa-mcp.mjs

@@ -12,25 +12,25 @@
  * From a checkout of this repository, `node packages/mcp/bin/capa-mcp.mjs`
  * runs the same server.
  *
- * A `cap_` key needs no tenant id: `/api/` resolves the tenant from the key,
- * and the mounts that read `X-Tenant-Key` are the ones a `cap_` key is refused
- * on anyway.
+ * A `cap_` key needs no tenant id: `/api/` and `/v2/agent` resolve the tenant
+ * from the key, and the mounts that read `X-Tenant-Key` are the ones a `cap_`
+ * key is refused on anyway.
  *
  * THE TOOL LIST DEPENDS ON THE KEY, and is decided once, here, before the
- * loop starts. A `cap_` key gets the `/api/` tools it holds the scopes for; a
- * `pk_`/`sk_` key gets those plus every legacy tool. The GraphQL tools need
- * only some `instance:read` scope, a one-model key's included, and
+ * loop starts. A `cap_` key gets the `/api/` tools it holds the scopes for,
+ * capa_read_entries among them, and the model and workspace tools where
+ * `/api/me` says the deployment accepts it on `/v2/agent`; a `pk_`/`sk_` key
+ * gets the `/api/` tools plus every legacy and agent tool. The GraphQL tools
+ * need only some `instance:read` scope, a one-model key's included, and
  * `capa_explain_error` is offline and always there. `lib/registry.mjs` carries
  * the rule and the reason. README.md lists what each tool answers.
  *
- * Still absent rather than stubbed: tools that edit or publish CONTENT. They
- * want their own shaping against the write surface, and a tool that always
- * fails teaches an agent to stop trying.
+ * Content is written as drafts only (lib/entry-tools.mjs), for a `cap_` key
+ * holding the scopes, where the deployment accepts it on `/v2/agent`.
  */
-import { createInterface } from "node:readline";
 import { loadConfig } from "../lib/client.mjs";
-import { loadMe, probeGraphQL, probePages, probeRestOnly, scopeNote, selectTools } from "../lib/registry.mjs";
-import { createSession } from "../lib/session.mjs";
+import { connect } from "../lib/connect.mjs";
+import { serveStdio } from "../lib/stdio.mjs";
 
 // Every request is bounded with AbortSignal.any (Node 20.3), and Node 18's
 // fetch tried only ::1 for localhost, so an API listening on IPv4 looked down.
@@ -47,50 +47,8 @@ try {
   process.exit(1);
 }
 
-// One `/api/me` call, before any client message is read. It is what turns the
-// key's family and scopes into the advertised list, and a client reads that
-// list once at startup — deciding later would mean advertising tools and then
-// changing our mind about them mid-session.
-const [me, pages, graphql, restOnly] = await Promise.all([loadMe(config), probePages(config), probeGraphQL(config), probeRestOnly(config)]);
-if (!me.ok) process.stderr.write(`capa-mcp: ${me.reason}\n`);
-// Only an answering /api/ says anything about its features: without one, every /api/ tool registers and reports the real error.
-const deployment = { pages: me.ok ? pages : null, graphql: me.ok ? graphql : null, restOnly };
-if (deployment.pages === false) {
-  process.stderr.write("capa-mcp: this deployment does not serve /api/pages (CAPA_SITE_PREVIEW is off), so the page tools are not registered.\n");
-}
-const tools = selectTools(config, me.me, deployment);
-const scoped = scopeNote(config, me.me, deployment);
-if (scoped) process.stderr.write(`${scoped}\n`);
-if (deployment.graphql === false) {
-  const instead = tools.some((tool) => tool.name === "capa_read_entries") ? " capa_read_entries reads the same entries over REST instead." : "";
-  process.stderr.write(`capa-mcp: this deployment does not serve /api/graphql (CAPA_API_GRAPHQL is off), so the GraphQL tools are not registered.${instead}\n`);
-}
-if (deployment.graphql !== false && restOnly.length && tools.some((tool) => tool.name === "capa_read_entries")) {
-  process.stderr.write(`capa-mcp: GraphQL leaves out ${restOnly.join(", ")} (their type names collide), so capa_read_entries is registered to read them over REST.\n`);
-}
-const ctx = { config: me.apiMissing ? { ...config, apiMissing: true } : config, tools };
-
-const rl = createInterface({ input: process.stdin, crlfDelay: Infinity });
-const session = createSession(ctx, {
-  write: (message) => process.stdout.write(JSON.stringify(message) + "\n"),
-  log: (text) => process.stderr.write(`${text}\n`),
-});
-rl.on("line", session.receive);
-
-// Drain before exiting. `close` fires as soon as stdin 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) {
-    process.stderr.write(`capa-mcp: drain failed: ${String(e?.stack ?? e)}\n`);
-  }
-  // Exit once stdout 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.
-  process.stdout.write("", () => process.exit(0));
-});
+// The startup calls, and what the person running the server reads about the
+// tool list, live in lib/connect.mjs, which `capa mcp` shares.
+const { ctx, notes } = await connect(config);
+for (const note of notes) process.stderr.write(`${note}\n`);
+await serveStdio(ctx);

package/lib/annotations.mjs

@@ -19,9 +19,9 @@ export function reads(title) {
 
 /**
  * A tool that writes. `idempotent`: the same arguments a second time leave
- * the same result. Every writer here can replace what is there, so each is
- * destructive.
+ * the same result. `destructive`: it can replace what is there, which every
+ * writer here but the upload can; an upload only adds a file.
  */
-export function writes(title, { idempotent }) {
-  return { title, annotations: { title, readOnlyHint: false, destructiveHint: true, idempotentHint: idempotent, openWorldHint: false } };
+export function writes(title, { idempotent, destructive = true }) {
+  return { title, annotations: { title, readOnlyHint: false, destructiveHint: destructive, idempotentHint: idempotent, openWorldHint: false } };
 }

package/lib/arguments.mjs

@@ -88,7 +88,8 @@ function check(schema, value, path) {
     if (schema.minimum !== undefined && value < schema.minimum) return `${label(path)} must be at least ${schema.minimum}.`;
     if (schema.maximum !== undefined && value > schema.maximum) return `${label(path)} must be at most ${schema.maximum}.`;
   }
-  if (typeof value === "string" && schema.minLength !== undefined && value.length < schema.minLength) {
+  // Measured without surrounding whitespace: "  " is as empty as "" to every handler here.
+  if (typeof value === "string" && schema.minLength !== undefined && value.trim().length < schema.minLength) {
     return schema.minLength === 1 ? `${label(path)} must not be empty.` : `${label(path)} must be at least ${schema.minLength} characters.`;
   }
   if (Array.isArray(value)) {