@abinnovision/payloadcms-mcpx 1.0.0-beta.13 → 1.0.0-beta.15

package/README.md

@@ -1,28 +1,40 @@
 # @abinnovision/payloadcms-mcpx
 
 A Payload CMS plugin that mounts an MCP (Model Context Protocol) server whose
-tool surface stays small and accurate regardless of the size of the
-content model.
+tool surface stays small and accurate regardless of the size of the content
+model.
 
 Instead of generating one tool per collection with the full document schema
-inlined, the plugin types its surface in three layers. The tool signatures are
-small and static: collection slugs, locales and operations as enums, everything
-else scalars. The field shapes are pulled on demand through `describeSchema`,
-one node at a time, stopping at every blocks boundary. And every write is
-resolved server-side against the real config and the real document, so unknown
-fields, misplaced blocks and unusable rich text nodes or node fields are refused with the
-valid alternatives listed, never silently dropped.
-
-Writes are RFC 6902 patches that land as drafts. One config axis decides how far
-they reach: `write: "draft"` never changes live content, `write: "live"` does —
-by exposing `publishDocument` where versions exist, and by permitting the write
-at all where they do not. Every write returns the publish blockers: the
-validation failures that still prevent the draft from being published.
-Capabilities are declared twice: the plugin config decides what can exist, a
-checkbox on each API key decides what does, and a missing checkbox means no
-(fail-closed).
-
-## Install
+inlined, the plugin types its surface in three layers. Tool signatures are small
+and static: collection slugs, locales and operations as enums, everything else
+scalars. Field shapes are pulled on demand through `describeSchema`, one node at
+a time, stopping at every blocks boundary. And every write is resolved
+server-side against the real config and the real document, so an unknown field,
+a misplaced block or an unusable rich text node comes back refused, with the
+valid alternatives listed rather than quietly dropped.
+
+Writes are RFC 6902 patches that land as drafts, and every write returns the
+publish blockers still standing between that draft and a publish. One config
+axis decides how far a write reaches. `write: "draft"` never changes live
+content. `write: "live"` does, by exposing `publishDocument` where versions
+exist and by permitting the write at all where they do not. Capabilities are
+declared twice: the plugin config decides what can exist, a checkbox on each API
+key decides what does, and a missing checkbox reads as no (fail-closed).
+
+## Contents
+
+- [Quick start](#quick-start)
+- [Configuration](#configuration)
+- [Tools](#tools)
+- [Globals](#globals)
+- [API keys](#api-keys)
+- [Drafts and publishing](#drafts-and-publishing)
+- [Custom tools](#custom-tools)
+- [How it is enforced](#how-it-is-enforced)
+- [Security notes](#security-notes)
+- [Non-goals of v1 / roadmap](#non-goals-of-v1--roadmap)
+
+## Quick start
 
 ```bash
 yarn add @abinnovision/payloadcms-mcpx
@@ -34,7 +46,8 @@ yarn add @abinnovision/payloadcms-mcpx
   `apiKeys.setupGuide: false`.
 - The package is published as ESM only, matching Payload itself.
 
-## Usage
+Add the plugin and name the collections and globals it may reach. Nothing is
+exposed that is not listed here:
 
 ```ts
 import { mcpxPlugin } from "@abinnovision/payloadcms-mcpx";
@@ -67,49 +80,12 @@ The plugin adds:
 - a draft guard on every collection and global, so any write carrying the MCP
   request marker lands as a draft, including writes made by custom tools.
 
-## API keys
-
-Keys are created in the admin panel under MCP > API Keys. The plaintext key is
-generated on create, stored encrypted with an HMAC index for lookup, and shown
-to anyone who may read the key document (own keys only, by default). Each key:
-
-- is bound to the user who created it and acts as that user: every operation
-  runs with `req.user` set to the linked user and `overrideAccess: false`, so
-  your collection access control applies unchanged;
-- carries one checkbox per exposed collection and operation, plus one per
-  custom tool. All checkboxes default to off. A key can never enable an
-  operation the plugin config does not expose, and keys created before a
-  capability existed stay without it. The `publish` checkbox only exists where
-  a versioned entity is configured `write: "live"`, so a key issued before
-  publishing was possible stays closed to it, and it counts only alongside
-  `write`: publishing is an extension of writing, not a capability of its own.
-
-Keys authenticate only the MCP endpoint. They are deliberately not a Payload
-auth strategy, so a key can never authenticate the REST or GraphQL API; the
-reverse also holds: an admin session or JWT is ignored by the MCP endpoint.
-
-Use `apiKeys.overrideCollection` to widen access (for example, admins manage
-all keys) or add fields.
-
-## Connecting a client
+Then create a key in the admin panel under MCP > API Keys, tick the capabilities
+it should have, and copy the plaintext key shown after saving. Checkboxes
+default to off, so a fresh key can do nothing until you say otherwise. See
+[API keys](#api-keys) for what a key is and is not.
 
-Saved keys carry a **Connect a client** tab in the admin holding these same
-instructions with their own URL and key filled in, each block behind a copy
-button. The tab only exists once the key does, so the create form stays free of
-it. Turn it off with `apiKeys.setupGuide: false`, which also drops the tabs and
-restores the flat form.
-
-The tab renders an admin component, so it has to be in the import map:
-
-```bash
-payload generate:importmap
-```
-
-Without that entry Payload logs a missing-component error and renders nothing
-else; the rest of the plugin is unaffected. The URL comes from `serverURL` when
-the config sets one and from the browser's origin otherwise.
-
-The endpoint speaks streamable HTTP with `Authorization: Bearer <key>`:
+Then point a client at the endpoint, passing the key as a bearer token:
 
 ```bash
 npx @modelcontextprotocol/inspector
@@ -143,6 +119,62 @@ Claude Desktop (no direct HTTP header support) via `mcp-remote`:
 }
 ```
 
+## Configuration
+
+| Option                       | Default                        | Description                                                       |
+| ---------------------------- | ------------------------------ | ----------------------------------------------------------------- |
+| `collections`                | required                       | Allow-list. `true` means `{ read: true }`.                        |
+| `collections.<slug>.read`    | `true`                         | Expose `describeSchema`, `findDocuments`, `getDocument`.          |
+| `collections.<slug>.write`   | `false`                        | `"draft"` or `"live"`. See below.                                 |
+| `globals`                    | `{}`                           | Allow-list of globals. `true` means `{ read: true }`.             |
+| `globals.<slug>.read`        | `true`                         | Expose `describeSchema`, `getDocument`.                           |
+| `globals.<slug>.write`       | `false`                        | `"draft"` or `"live"`. See below.                                 |
+| `userCollection`             | `config.admin.user` or `users` | Auth collection the keys act as.                                  |
+| `apiKeys.slug`               | `mcpx-api-keys`                | Slug of the generated key collection.                             |
+| `apiKeys.setupGuide`         | `true`                         | Add a "Connect a client" tab to saved keys. Needs the import map. |
+| `apiKeys.overrideCollection` | none                           | Final override applied to the generated collection.               |
+| `endpoint.path`              | `/mcpx`                        | Endpoint path below the API route.                                |
+| `limits.maxLimit`            | `25`                           | Upper bound for `findDocuments.limit`.                            |
+| `limits.maxDepth`            | `1`                            | Upper bound for `depth` on reads.                                 |
+| `tools`                      | `[]`                           | Custom tools, defined the same way as the builtins.               |
+| `auth.resolve`               | none                           | Replace or wrap the default key resolution.                       |
+| `serverInfo`                 | package name and version       | Reported to MCP clients.                                          |
+
+`write` is one axis: how far MCP writes to this entity reach.
+
+| `write`   | With `versions.drafts`                                  | Without                                        |
+| --------- | ------------------------------------------------------- | ---------------------------------------------- |
+| `false`   | no write tool reaches it                                | no write tool reaches it                       |
+| `"draft"` | writes land as drafts, nothing is ever published        | refused at startup: there is no draft to write |
+| `"live"`  | writes land as drafts, and `publishDocument` is exposed | writes land on the live document               |
+
+`"live"` is the only way an MCP write reaches live content, whichever of the two
+shapes it takes. Wherever it is set, the server instructions and the
+`patchDocument` and `createDocument` descriptions name those slugs for the key in
+question, so a client is never told its writes are drafts while they are not,
+nor that publishing is out of reach when it is not.
+
+Migrating from the previous option shape: `write: true` becomes
+`write: "draft"`, and `write: true` with `allowLiveWrites: true` becomes
+`write: "live"`. A versioned entity moved to `write: "live"` gains a `publish`
+checkbox on every key, unticked, so nothing publishes until someone says so.
+
+An upload collection may be exposed for write. `patchDocument` and
+`validateDocument` reach it, and `publishDocument` under the same `write:
+"live"` rule as anywhere else, so an agent can edit the fields the collection
+declares itself, such as `alt` or a credit. Its base fields (`filename`, `url`,
+`filesize`, `sizes`, the focal point) are neither described nor writable, and
+`createDocument` leaves the slug out of its `collection` enum and says why in
+its description: a create there would have to carry the file, and no tool does.
+Upload the file in the admin panel first.
+
+Misconfiguration (unknown slugs, `write: "draft"` on a collection without
+drafts, tool name collisions) fails at startup with `InvalidConfiguration`. So
+does `write: "live"` on an entity using `versions.drafts.localizeStatus`, which
+is not supported yet. Auth collections cannot be exposed at all, read included:
+their documents carry credentials, such as the decrypted Payload API key of
+every user.
+
 ## Tools
 
 The surface is fixed at eight tools plus your custom ones; exposing a global
@@ -150,16 +182,16 @@ adds an argument, never a tool. `tools/list` reflects the key: write tools
 disappear for read-only keys, and every `collection` and `global` enum contains
 only the slugs the key may touch.
 
-| Tool               | Purpose                                                     | Key arguments                                                                                |
-| ------------------ | ----------------------------------------------------------- | -------------------------------------------------------------------------------------------- |
-| `listCapabilities` | What this key may do; call first to orient.                 | none                                                                                         |
-| `describeSchema`   | Field shape of one node; `next` lists the drill-down paths. | `collection` \| `global`, `paths?`, `expand?`                                                |
-| `findDocuments`    | Query documents.                                            | `collection`, `where?`, `sort?`, `limit?`, `page?`, `depth?`, `select?`, `locale?`, `draft?` |
-| `getDocument`      | Read one document or a subtree of it.                       | `collection` + `id` \| `global`, `path?` (JSON pointer), `depth?`, `locale?`, `draft?`       |
-| `patchDocument`    | Apply RFC 6902 operations to the current draft.             | `collection` + `id` \| `global`, `locale`, `patches`, `expectedUpdatedAt?`                   |
-| `createDocument`   | Create a draft from a minimal seed.                         | `collection`, `locale`, `data`                                                               |
-| `validateDocument` | Publish blockers without saving anything.                   | `collection` + `id` \| `global`, `locale`                                                    |
-| `publishDocument`  | Publish the current draft.                                  | `collection` + `id` \| `global`, `expectedUpdatedAt?`                                        |
+| Tool               | Purpose                                                                  | Key arguments                                                                                |
+| ------------------ | ------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------- |
+| `listCapabilities` | What this key may do, `create` apart from `write`; call first to orient. | none                                                                                         |
+| `describeSchema`   | Field shape of one node; `next` lists the drill-down paths.              | `collection` \| `global`, `paths?`, `expand?`                                                |
+| `findDocuments`    | Query documents.                                                         | `collection`, `where?`, `sort?`, `limit?`, `page?`, `depth?`, `select?`, `locale?`, `draft?` |
+| `getDocument`      | Read one document or a subtree of it.                                    | `collection` + `id` \| `global`, `path?` (JSON pointer), `depth?`, `locale?`, `draft?`       |
+| `patchDocument`    | Apply RFC 6902 operations to the current draft.                          | `collection` + `id` \| `global`, `locale`, `patches`, `expectedUpdatedAt?`                   |
+| `createDocument`   | Create a draft from a minimal seed. Not for upload collections.          | `collection`, `locale`, `data`                                                               |
+| `validateDocument` | Publish blockers without saving anything.                                | `collection` + `id` \| `global`, `locale`                                                    |
+| `publishDocument`  | Publish the current draft.                                               | `collection` + `id` \| `global`, `expectedUpdatedAt?`                                        |
 
 Rules the tools enforce and explain in their own descriptions:
 
@@ -176,6 +208,10 @@ Rules the tools enforce and explain in their own descriptions:
   guessed. Any feature declaring `getSubFields` is picked up, custom ones
   included. `upload` nodes are the exception: their fields depend on the
   collection the node points at, so they are not addressable.
+- A field marked `admin.hidden` is not described and cannot be written. Payload
+  keeps such a field out of the admin panel only, and this is where the plugin
+  parts from it: kept from an editor means kept from a client. It is also what
+  keeps the base fields of an upload collection off the surface.
 - Constraints a field declares travel with it: `minRows`/`maxRows` on arrays
   and blocks fields, `maxLength`/`minLength` on text, `min`/`max` on numbers.
   An array is described in its own right, so the `*` in `/items/*/title` has
@@ -186,6 +222,19 @@ Rules the tools enforce and explain in their own descriptions:
   answers `{ "heading": { "tag": ["h4"] } }`, and a write carrying any other
   heading tag is refused. Lexical stores whatever tag it is given, so this is
   the only place the restriction is checked.
+- A Lexical node must be written the way Lexical serializes it, and carry the
+  values Lexical would have written. The admin editor rehydrates nodes through
+  their classes, so a list item whose `indent` is absent, `null` or `"0"` throws
+  when the document is opened, and a heading whose `tag` is `3` comes back
+  untagged, none of which Payload notices on write. A write breaking either is
+  refused, and the message names the property and what belongs there.
+- Where Payload states the shape itself, that statement is what is enforced: its
+  `outputSchema` declares `version` required on every node, and gives the root
+  exactly `children`, `direction`, `format`, `indent`, `type` and `version`, so
+  an unknown property on the root is refused too. Payload declares nothing per
+  node type, so the rest is measured against the node classes
+  `@payloadcms/richtext-lexical` ships. Both halves are pinned by
+  `src/schema/lexical.spec.ts` rather than assumed.
 - Field and collection `admin.description` values are included in
   `describeSchema` and `listCapabilities`, so intent written for the admin
   panel reaches the client. A locale-keyed record is resolved to one string for
@@ -240,8 +289,8 @@ camelCase name with a collection. Keys issued before a global was exposed have
 no such group, and an absent checkbox reads as `false`, so they stay closed to
 every global until one is ticked.
 
-Globals always carry `updatedAt` — Payload appends it and there is no
-`timestamps: false` for globals — so `expectedUpdatedAt` behaves as it does for
+Globals always carry `updatedAt`, because Payload appends it and there is no
+`timestamps: false` for globals, so `expectedUpdatedAt` behaves as it does for
 collections. The one exception is a global that has never been saved: it has no
 `updatedAt` to compare against, so the first write must omit
 `expectedUpdatedAt`, and supplying one is refused as a concurrency failure.
@@ -250,55 +299,78 @@ If `tools/list` omits `global` entirely, no global is exposed to that key; the
 argument only appears once one is. A deployment that uses no globals sees the
 tool schemas exactly as they were.
 
-## Drafts and publishing
+## API keys
+
+Keys are created in the admin panel under MCP > API Keys. The plaintext key is
+generated on create, stored encrypted with an HMAC index for lookup, and shown
+to anyone who may read the key document (own keys only, by default). Each key:
 
-Draft-only writing is enforced on the Payload operation, not in the tool
-handlers: a `beforeOperation` hook forces `draft: true` and strips `_status`
-from every write carrying the MCP request marker, so custom tools and anything
-else writing through the same request are covered too. A `beforeChange` hook
-refuses any write that would still not land as a draft.
+- is bound to the user who created it and acts as that user: every operation
+  runs with `req.user` set to the linked user and `overrideAccess: false`, so
+  your collection access control applies unchanged;
+- carries one checkbox per exposed collection and operation, plus one per
+  custom tool. All checkboxes default to off. A key can never enable an
+  operation the plugin config does not expose, and keys created before a
+  capability existed stay without it. The `publish` checkbox only exists where
+  a versioned entity is configured `write: "live"`, so a key issued before
+  publishing was possible stays closed to it, and it counts only alongside
+  `write`: publishing is an extension of writing, not a capability of its own.
 
-The two hooks are not equally load-bearing on both sides. `updateGlobal` reads
-`draft` and the publish arguments off its argument bag _before_ it runs
-`beforeOperation`, and re-reads only `data` afterwards, so for a global the
-correction cannot apply and the `beforeChange` refusal is what actually holds
-the line. Both are installed on every collection and global, exposed or not.
+Keys authenticate only the MCP endpoint. They are deliberately not a Payload
+auth strategy, so a key can never authenticate the REST or GraphQL API; the
+reverse also holds: an admin session or JWT is ignored by the MCP endpoint.
+
+Use `apiKeys.overrideCollection` to widen access (for example, admins manage
+all keys) or add fields.
+
+### The "Connect a client" tab
+
+Saved keys carry a **Connect a client** tab in the admin holding the client
+snippets from [Quick start](#quick-start) with their own URL and key filled in,
+each block behind a copy button. The tab only exists once the key does, so the create form stays free of
+it. Turn it off with `apiKeys.setupGuide: false`, which also drops the tabs and
+restores the flat form.
 
-`publishDocument` is the one way through, and it opens the door for exactly one
-operation: the tool records an intent naming the entity and id it is about to
-publish, in `AsyncLocalStorage` rather than on the request, and the guard
-consults it. A concurrent call in the same JSON-RPC batch runs in another async
-context and sees nothing, a nested write to a different document meets the
-unguarded rules, and the intent is claimed once so a re-entrant write to the
-same document cannot ride along. It is not a security boundary — a custom tool
-holds the whole `payload` instance — but no ordinary write can widen itself into
-a publish by accident.
-
-Publishing covers the whole document, as the admin Publish button does, but
-Payload only validates the locale the publish runs in. A required field left
-empty in another locale therefore goes live empty; that is Payload's behaviour,
-not something this plugin adds. `publishDocument` refuses a document that fails
-validation and reports `validationErrors` with JSON Pointers. It is refused
-while a human holds the document open in the admin panel, and republishing an
-unchanged document is accepted but writes another version.
+The tab renders an admin component, so it has to be in the import map:
+
+```bash
+payload generate:importmap
+```
+
+Without that entry Payload logs a missing-component error and renders nothing
+else; the rest of the plugin is unaffected. The URL comes from `serverURL` when
+the config sets one and from the browser's origin otherwise.
+
+## Drafts and publishing
+
+Every MCP write lands as a draft. That is enforced on the Payload operation
+rather than in the tool handlers, so a custom tool writing through the same
+request is covered as well; see [How it is enforced](#how-it-is-enforced) for
+the mechanism.
+
+`publishDocument` is the one way through. Publishing covers the whole document,
+as the admin Publish button does, but Payload only validates the locale the
+publish runs in. A required field left empty in another locale therefore goes
+live empty. That is Payload's behaviour, not something this plugin adds.
+`publishDocument` refuses a document that fails validation and reports
+`validationErrors` with JSON Pointers. It is refused while a human holds the
+document open in the admin panel, and republishing an unchanged document is
+accepted but writes another version.
 
 There is no unpublish tool. Reverting a published document to a draft stays a
 human action.
 
 Publish blockers are advisory. Payload skips validation on draft saves (unless
 `versions.drafts.validate` is set), so after every write the plugin re-runs
-Payload's own field validation over the saved draft and returns the failures
-as `publishBlockers` with paths and labels. The write stands; the client gets a
-checklist of what remains. Three limits: only the written locale is
-validated; field `beforeChange` hooks run again during the check, so they must
-be pure; and the check runs privileged, so blocker paths and messages may name
-fields the key's user cannot read (values are never included).
-Collections with `versions.drafts.validate: true` refuse invalid drafts
-outright; those failures come back as `validationErrors`. Both carry pointers,
-restated from the dotted paths Payload reports internally.
-
-`publishBlockersUnavailable` marks a check that could not complete, which is
-not the same answer as a document with nothing wrong with it. `validateDocument`
+Payload's own field validation over the saved draft and returns the failures as
+`publishBlockers` with paths and labels. The write stands; the client gets a
+checklist of what remains. Collections with `versions.drafts.validate: true`
+refuse invalid drafts outright, and those failures come back as
+`validationErrors` instead. Both carry pointers, restated from the dotted paths
+Payload reports internally.
+
+`publishBlockersUnavailable` marks a check that could not complete, which is not
+the same answer as a document with nothing wrong with it. `validateDocument`
 runs the same traversal without saving anything, so it is not free of side
 effects: field `beforeValidate` and `beforeChange` hooks run, and it carries no
 `readOnlyHint` for that reason.
@@ -391,52 +463,39 @@ argument is rejected by name rather than stripped before the handler runs.
 `jsonResult` and `errorResult` are exported so a custom tool can return
 results shaped like a builtin's.
 
-## Options
+## How it is enforced
 
-| Option                       | Default                        | Description                                                       |
-| ---------------------------- | ------------------------------ | ----------------------------------------------------------------- |
-| `collections`                | required                       | Allow-list. `true` means `{ read: true }`.                        |
-| `collections.<slug>.read`    | `true`                         | Expose `describeSchema`, `findDocuments`, `getDocument`.          |
-| `collections.<slug>.write`   | `false`                        | `"draft"` or `"live"`. See below.                                 |
-| `globals`                    | `{}`                           | Allow-list of globals. `true` means `{ read: true }`.             |
-| `globals.<slug>.read`        | `true`                         | Expose `describeSchema`, `getDocument`.                           |
-| `globals.<slug>.write`       | `false`                        | `"draft"` or `"live"`. See below.                                 |
-| `userCollection`             | `config.admin.user` or `users` | Auth collection the keys act as.                                  |
-| `apiKeys.slug`               | `mcpx-api-keys`                | Slug of the generated key collection.                             |
-| `apiKeys.setupGuide`         | `true`                         | Add a "Connect a client" tab to saved keys. Needs the import map. |
-| `apiKeys.overrideCollection` | none                           | Final override applied to the generated collection.               |
-| `endpoint.path`              | `/mcpx`                        | Endpoint path below the API route.                                |
-| `limits.maxLimit`            | `25`                           | Upper bound for `findDocuments.limit`.                            |
-| `limits.maxDepth`            | `1`                            | Upper bound for `depth` on reads.                                 |
-| `tools`                      | `[]`                           | Custom tools, defined the same way as the builtins.               |
-| `auth.resolve`               | none                           | Replace or wrap the default key resolution.                       |
-| `serverInfo`                 | package name and version       | Reported to MCP clients.                                          |
+Draft-only writing sits on the Payload operation, not in the tool handlers. A
+`beforeOperation` hook forces `draft: true` and strips `_status` from every
+write carrying the MCP request marker, so custom tools and anything else writing
+through the same request are covered too. A `beforeChange` hook then refuses any
+write that would still not land as a draft.
 
-`write` is one axis: how far MCP writes to this entity reach.
-
-| `write`   | With `versions.drafts`                                  | Without                                        |
-| --------- | ------------------------------------------------------- | ---------------------------------------------- |
-| `false`   | no write tool reaches it                                | no write tool reaches it                       |
-| `"draft"` | writes land as drafts, nothing is ever published        | refused at startup: there is no draft to write |
-| `"live"`  | writes land as drafts, and `publishDocument` is exposed | writes land on the live document               |
-
-`"live"` is the only way an MCP write reaches live content, whichever of the two
-shapes it takes. Wherever it is set, the server instructions and the
-`patchDocument` and `createDocument` descriptions name those slugs for the key in
-question, so a client is never told its writes are drafts while they are not,
-nor that publishing is out of reach when it is not.
-
-Migrating from the previous option shape: `write: true` becomes
-`write: "draft"`, and `write: true` with `allowLiveWrites: true` becomes
-`write: "live"`. A versioned entity moved to `write: "live"` gains a `publish`
-checkbox on every key, unticked, so nothing publishes until someone says so.
+The two hooks are not equally load-bearing on both sides. `updateGlobal` reads
+`draft` and the publish arguments off its argument bag _before_ it runs
+`beforeOperation`, and re-reads only `data` afterwards, so for a global the
+correction cannot apply and the `beforeChange` refusal is what actually holds
+the line. Both are installed on every collection and global, exposed or not.
 
-Misconfiguration (unknown slugs, `write: "draft"` on a collection without
-drafts, upload collections exposed for write, tool name collisions) fails at
-startup with `InvalidConfiguration`. So does `write: "live"` on an entity using
-`versions.drafts.localizeStatus`, which is not supported yet. Auth collections cannot be exposed at all, read
-included: their documents carry credentials, such as the decrypted Payload API
-key of every user.
+`publishDocument` opens the door for exactly one write: the tool marks that
+write's own `data` object, and the guard grants the publish only to a write
+carrying the mark. Nothing is scoped to a slug or an id because nothing else can
+reach it. A concurrent call in the same JSON-RPC batch has its own `data`, and
+so does a nested write from a hook during the publish.
+
+That distinction matters. The endpoint hands one `PayloadRequest` to every tool,
+and the transport dispatches the messages of a batch without awaiting each one,
+so an intent kept on the request would be reachable by a sibling `patchDocument`
+and would publish it instead. The mark is a string key holding a token minted
+per process, because Payload's copy of the write data keeps string keys and
+drops symbols, and a token cannot be forged by a client writing a field of the
+same name. None of this is a security boundary, since a custom tool holds the
+whole `payload` instance, but no ordinary write can widen itself into a publish.
+
+The publish-blocker check has three limits worth knowing. Only the written
+locale is validated. Field `beforeChange` hooks run again during the check, so
+they must be pure. And the check runs privileged, so blocker paths and messages
+may name fields the key's user cannot read, though values are never included.
 
 ## Security notes
 
@@ -448,17 +507,21 @@ key of every user.
 - Payload has no separate publish permission: at its access layer, anyone who
   may update a document may publish it. The `publish` checkbox is this plugin's
   fence, not Payload's.
-- Not covered in v1: `delete` (no tool exists and none is generated), uploads.
-  Custom tools are trusted code and can do what the linked user may.
+- Not covered in v1: `delete` (no tool exists and none is generated), creating
+  upload documents and writing any file. Custom tools are trusted code and can
+  do what the linked user may.
+
+How the draft and publish guarantees are enforced, and where they stop, is in
+[How it is enforced](#how-it-is-enforced).
 
 ## Non-goals of v1 / roadmap
 
-Unpublishing, `versions.drafts.localizeStatus`, deletes, uploads, markdown
-authoring for rich text, addressing a rich text node
-by position in a patch (an editor state is written whole), schemas for `upload`
-node fields, row addressing by id instead of index, cross-locale publish
-blockers, pagination of `describeSchema` with `expand`, and a handler-level
-timeout are all deliberate omissions for now.
+Unpublishing, `versions.drafts.localizeStatus`, deletes, creating upload
+documents and any file handling, markdown authoring for rich text, addressing a
+rich text node by position in a patch (an editor state is written whole),
+schemas for `upload` node fields, row addressing by id instead of index,
+cross-locale publish blockers, pagination of `describeSchema` with `expand`,
+and a handler-level timeout are all deliberate omissions for now.
 
 ## License
 

package/dist/api-keys/fields.mjs

@@ -1,4 +1,4 @@
-import { CAPABILITIES_FIELD, canPublish, canWrite } from "../capabilities.mjs";
+import { CAPABILITIES_FIELD, canCreate, canPublish, canWrite } from "../capabilities.mjs";
 //#region src/api-keys/fields.ts
 const encryptKey = ({ req, value }) => typeof value === "string" ? req.payload.encrypt(value) : value;
 const decryptKey = ({ req, value }) => {
@@ -15,7 +15,7 @@ const checkbox = (name, description) => ({
 	defaultValue: false,
 	admin: { description }
 });
-const SETUP_GUIDE_FIELD = "setupGuide";
+/** Name of the `ui` field the "Connect a client" tab renders. */ const SETUP_GUIDE_FIELD = "setupGuide";
 /**
 * Fields every key carries. Key generation and the HMAC index live in the
 * collection-level `beforeChange` hook (see `collection.ts`), because sibling
@@ -99,6 +99,10 @@ const PUBLISH_DESCRIPTION = "Publish the current draft. Changes what the public
 * An entity without versions gets no `publish` checkbox even under
 * `write: "live"`: there is no draft to promote there, the write itself is the
 * live change, and a second checkbox would only make `write` a dead setting.
+*
+* An upload collection gets the same checkboxes as any other, only worded for
+* what `write` reaches there: a document's own fields, never `createDocument`,
+* because the file comes from the admin panel.
 */ const createCapabilityFields = (options) => {
 	const collectionGroups = options.collections.map((collection) => ({
 		name: collection.fieldName,
@@ -106,7 +110,7 @@ const PUBLISH_DESCRIPTION = "Publish the current draft. Changes what the public
 		label: collection.slug,
 		fields: [
 			...collection.read ? [checkbox("read", "Describe, find and read documents.")] : [],
-			...canWrite(collection) ? [checkbox("write", "Create, patch and validate drafts.")] : [],
+			...canWrite(collection) ? [checkbox("write", canCreate(collection) ? "Create, patch and validate drafts." : "Patch and validate drafts. The file itself is uploaded in the admin panel.")] : [],
 			...canPublish(collection) ? [checkbox("publish", PUBLISH_DESCRIPTION)] : []
 		]
 	}));

package/dist/api-keys/setup-guide.mjs

@@ -1,5 +1,8 @@
 //#region src/api-keys/setup-guide.ts
-const KEY_PLACEHOLDER = "<your-key>";
+/**
+* Stands in for the key in the snippets whenever the real one is unavailable,
+* so the instructions still render and say what is missing.
+*/ const KEY_PLACEHOLDER = "<your-key>";
 /**
 * Server name for the client config. MCP clients key their config by this, so
 * it has to survive labels with spaces or punctuation.
@@ -8,9 +11,8 @@ const KEY_PLACEHOLDER = "<your-key>";
 	return slug === "" ? "payload" : slug;
 };
 /**
-* The connection instructions for one key, split into independently copyable
-* blocks. Kept a pure builder so the admin component holds only rendering and
-* the snippets stay unit-testable.
+* A pure builder, so the admin component holds only rendering and the snippets
+* stay unit-testable.
 */ const buildSetupGuide = (input) => {
 	const key = typeof input.apiKey === "string" ? input.apiKey : KEY_PLACEHOLDER;
 	const name = toServerName(input.label);

package/dist/auth/resolve.mjs

@@ -5,9 +5,7 @@ const relationId = (value) => {
 	if (typeof value === "string" || typeof value === "number") return value;
 	if (typeof value === "object" && value !== null && "id" in value) return value.id;
 };
-/**
-* The bearer token of an `Authorization` header, or `null`.
-*/ const parseBearer = (headers) => {
+const parseBearer = (headers) => {
 	const header = headers.get("authorization");
 	if (!header) return null;
 	return BEARER.exec(header.trim())?.[1] ?? null;

package/dist/capabilities.mjs

@@ -1,13 +1,13 @@
 //#region src/capabilities.ts
-/** Name of the capability group on the key document. */ const CAPABILITIES_FIELD = "capabilities";
-/** Whether any write tool reaches this entity. */ const canWrite = (entity) => entity.write !== false;
+/** Group field holding the capability checkboxes on an API key document. */ const CAPABILITIES_FIELD = "capabilities";
+/** Whatever the write lands on; {@link isLiveWrite} tells the two apart. */ const canWrite = (entity) => entity.write !== false;
+/** The config lets MCP change live content and there is a draft to promote. */ const canPublish = (entity) => entity.write === "live" && entity.hasDrafts;
 /**
-* Whether `publishDocument` reaches this entity: the config lets MCP change
-* live content and there is a draft to promote.
-*/ const canPublish = (entity) => entity.write === "live" && entity.hasDrafts;
+* An upload document is a file, and no tool here carries one. Its own fields
+* stay patchable; the first version is made in the admin panel.
+*/ const canCreate = (entity) => canWrite(entity) && !entity.isUpload;
 /**
-* Whether an ordinary write to this entity changes the live document. With no
-* versions there is no draft to land on, so `write: "live"` is what permits the
+* With no versions there is no draft to land on, so `write: "live"` permits the
 * write at all and every write is live.
 */ const isLiveWrite = (entity) => entity.write === "live" && !entity.hasDrafts;
 const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
@@ -59,4 +59,4 @@ const readableGlobalSlugs = (capabilities) => pick(capabilities.globals, "read")
 const writableGlobalSlugs = (capabilities) => pick(capabilities.globals, "write");
 const publishableGlobalSlugs = (capabilities) => pick(capabilities.globals, "publish");
 //#endregion
-export { CAPABILITIES_FIELD, canPublish, canWrite, isLiveWrite, publishableGlobalSlugs, publishableSlugs, readableGlobalSlugs, readableSlugs, resolveCapabilities, writableGlobalSlugs, writableSlugs };
+export { CAPABILITIES_FIELD, canCreate, canPublish, canWrite, isLiveWrite, publishableGlobalSlugs, publishableSlugs, readableGlobalSlugs, readableSlugs, resolveCapabilities, writableGlobalSlugs, writableSlugs };

package/dist/endpoint/errors.mjs

@@ -22,8 +22,6 @@ import { APIError, ValidationError } from "payload";
 	});
 };
 /**
-* Maps an exception thrown by a tool to a result the client can read.
-*
 * Payload's public errors keep their message and status; a `ValidationError`
 * also surfaces its per-field detail, with each field's path restated as a
 * JSON Pointer so it reads like every other path this plugin reports. Anything