@abinnovision/payloadcms-mcpx 1.0.0-beta.12 → 1.0.0-beta.14

package/README.md

@@ -1,27 +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, with `allowLiveWrites` as the
-one documented exception; publishing stays a human action in the admin panel.
-Every write returns the publish
-blockers: the validation failures that still prevent a human from publishing
-the draft. 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
@@ -33,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";
@@ -44,12 +58,12 @@ export default buildConfig({
   plugins: [
     mcpxPlugin({
       collections: {
-        pages: { read: true, write: true },
-        posts: { read: true, write: true },
+        pages: { read: true, write: "live" }, // may be published through MCP
+        posts: { read: true, write: "draft" }, // drafts only
         tags: true, // shorthand for { read: true }
       },
       globals: {
-        "site-settings": { read: true, write: true },
+        "site-settings": { read: true, write: "draft" },
       },
       limits: { maxLimit: 25, maxDepth: 1 },
     }),
@@ -66,46 +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.
-
-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
-
-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
-```
+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.
 
-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
@@ -139,22 +119,79 @@ 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 seven tools plus your custom ones; exposing a global
+The surface is fixed at eight tools plus your custom ones; exposing a global
 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`                                                    |
+| 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:
 
@@ -171,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
@@ -235,8 +276,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.
@@ -245,30 +286,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 publish blockers
+## API keys
 
-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. Globals expose the same
-`beforeOperation` interception point at the same position in the operation, so
-they are guarded exactly as strongly as collections, exposed or not.
+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.
+
+### 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.
+
+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.
@@ -308,9 +397,9 @@ Custom tools take the same route as the builtins: one `McpxTool` shape, one
 registration loop. Anything a builtin does, a custom tool can do.
 
 `handler` receives `scope` alongside `args`, `req` and `extra`. The scope
-carries what the key may touch (`readable`, `writable`, `readableGlobals`,
-`writableGlobals`), the configured locales, the limits in force and the
-exposed collections and globals. `req` is shorthand for `scope.req`.
+carries what the key may touch (`readable`, `writable`, `publishable`,
+`readableGlobals`, `writableGlobals`, `publishableGlobals`), the configured
+locales, the limits in force and the exposed collections and globals. `req` is shorthand for `scope.req`.
 
 `inputSchema` may be a function of that scope instead of a fixed shape, which
 is how a tool narrows an enum to what the key may read:
@@ -361,39 +450,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
-
-| Option                               | Default                        | Description                                                                                                        |
-| ------------------------------------ | ------------------------------ | ------------------------------------------------------------------------------------------------------------------ |
-| `collections`                        | required                       | Allow-list. `true` means `{ read: true }`.                                                                         |
-| `collections.<slug>.read`            | `true`                         | Expose `describeSchema`, `findDocuments`, `getDocument`.                                                           |
-| `collections.<slug>.write`           | `false`                        | Expose `patchDocument`, `createDocument`, `validateDocument`. Requires `versions.drafts` unless `allowLiveWrites`. |
-| `collections.<slug>.allowLiveWrites` | `false`                        | Permit writes to a collection without drafts (they land live).                                                     |
-| `globals`                            | `{}`                           | Allow-list of globals. `true` means `{ read: true }`.                                                              |
-| `globals.<slug>.read`                | `true`                         | Expose `describeSchema`, `getDocument`.                                                                            |
-| `globals.<slug>.write`               | `false`                        | Expose `patchDocument`, `validateDocument`. Requires `versions.drafts` unless `allowLiveWrites`.                   |
-| `globals.<slug>.allowLiveWrites`     | `false`                        | Permit writes to a global without drafts (they land live).                                                         |
-| `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.                                                                                           |
-
-`allowLiveWrites` is the only way an MCP write reaches live content. Where 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.
-
-Misconfiguration (unknown slugs, write on a collection without drafts, upload
-collections exposed for write, tool name collisions) fails at startup with
-`InvalidConfiguration`. Auth collections cannot be exposed at all, read
-included: their documents carry credentials, such as the decrypted Payload API
-key of every user.
+## How it is enforced
+
+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.
+
+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.
+
+`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
 
@@ -402,16 +491,24 @@ key of every user.
 - The endpoint authenticates with Bearer keys only; admin JWTs and cookies are
   ignored. Keys cannot authenticate REST or GraphQL.
 - Every operation runs under the linked user with `overrideAccess: false`.
-- 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.
+- 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), 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
 
-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 } 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
@@ -89,23 +89,40 @@ const SETUP_GUIDE_FIELD = "setupGuide";
 		}]
 	}];
 };
+const PUBLISH_DESCRIPTION = "Publish the current draft. Changes what the public sees.";
 /**
 * One checkbox per exposed operation, grouped per collection, per global and
 * per custom tool. Only operations the plugin config exposes get a checkbox, so
 * a key can never enable more than the config allows. Everything defaults to
 * off, which is why a key issued before a capability existed stays closed to it.
+*
+* 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,
 		type: "group",
 		label: collection.slug,
-		fields: [...collection.read ? [checkbox("read", "Describe, find and read documents.")] : [], ...collection.write ? [checkbox("write", "Create, patch and validate drafts.")] : []]
+		fields: [
+			...collection.read ? [checkbox("read", "Describe, find and read documents.")] : [],
+			...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)] : []
+		]
 	}));
 	const globalGroups = options.globals.map((global) => ({
 		name: global.fieldName,
 		type: "group",
 		label: global.slug,
-		fields: [...global.read ? [checkbox("read", "Describe and read this global.")] : [], ...global.write ? [checkbox("write", "Patch and validate this global's draft.")] : []]
+		fields: [
+			...global.read ? [checkbox("read", "Describe and read this global.")] : [],
+			...canWrite(global) ? [checkbox("write", "Patch and validate this global's draft.")] : [],
+			...canPublish(global) ? [checkbox("publish", PUBLISH_DESCRIPTION)] : []
+		]
 	}));
 	const toolCheckboxes = options.tools.map((tool) => checkbox(tool.name, typeof tool.description === "string" ? tool.description : tool.name));
 	const groups = [

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,8 +1,23 @@
 //#region src/capabilities.ts
-/** Name of the capability group on the key document. */ const CAPABILITIES_FIELD = "capabilities";
+/** 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;
+/**
+* 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;
+/**
+* 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);
 const flag = (group, name) => isRecord(group) && group[name] === true;
 /**
+* Publishing is an extension of writing, never a capability of its own: a key
+* that may publish may also edit the draft it publishes. Both checkboxes are
+* therefore required, on top of the config exposing publishing at all.
+*/ const publishFlag = (entity, group) => canPublish(entity) && flag(group, "write") && flag(group, "publish");
+/**
 * Capabilities in force for a key: the plugin config decides what can exist,
 * the key's checkboxes decide what does. A missing checkbox is `false`, so keys
 * issued before a capability existed stay closed.
@@ -15,7 +30,8 @@ const flag = (group, name) => isRecord(group) && group[name] === true;
 		const group = isRecord(collectionsGroup) ? collectionsGroup[collection.fieldName] : void 0;
 		collections[collection.slug] = {
 			read: collection.read && flag(group, "read"),
-			write: collection.write && flag(group, "write")
+			write: canWrite(collection) && flag(group, "write"),
+			publish: publishFlag(collection, group)
 		};
 	}
 	const globals = {};
@@ -23,7 +39,8 @@ const flag = (group, name) => isRecord(group) && group[name] === true;
 		const group = isRecord(globalsGroup) ? globalsGroup[global.fieldName] : void 0;
 		globals[global.slug] = {
 			read: global.read && flag(group, "read"),
-			write: global.write && flag(group, "write")
+			write: canWrite(global) && flag(group, "write"),
+			publish: publishFlag(global, group)
 		};
 	}
 	const tools = {};
@@ -37,7 +54,9 @@ const flag = (group, name) => isRecord(group) && group[name] === true;
 const pick = (entries, operation) => Object.entries(entries).filter(([, value]) => value[operation]).map(([slug]) => slug);
 const readableSlugs = (capabilities) => pick(capabilities.collections, "read");
 const writableSlugs = (capabilities) => pick(capabilities.collections, "write");
+const publishableSlugs = (capabilities) => pick(capabilities.collections, "publish");
 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, readableGlobalSlugs, readableSlugs, resolveCapabilities, writableGlobalSlugs, writableSlugs };
+export { CAPABILITIES_FIELD, canCreate, canPublish, canWrite, isLiveWrite, publishableGlobalSlugs, publishableSlugs, readableGlobalSlugs, readableSlugs, resolveCapabilities, writableGlobalSlugs, writableSlugs };