@abinnovision/payloadcms-mcpx 2.0.0-beta.9 → 2.1.0-beta.1

package/CHANGELOG.md

@@ -1,5 +1,48 @@
 # Changelog
 
+## [2.0.0](https://github.com/abinnovision/payloadcms-commons/compare/payloadcms-mcpx-v1.0.0...payloadcms-mcpx-v2.0.0) (2026-10-08)
+
+
+### ⚠ BREAKING CHANGES
+
+* **mcpx:** align helpers and simplify the plugin internals ([#118](https://github.com/abinnovision/payloadcms-commons/issues/118))
+* **mcpx:** refine the capability matrix into access levels ([#108](https://github.com/abinnovision/payloadcms-commons/issues/108))
+* **mcpx:** expose version history wherever read is granted ([#89](https://github.com/abinnovision/payloadcms-commons/issues/89))
+* **mcpx:** clean up, harden and simplify the plugin for 2.0 ([#83](https://github.com/abinnovision/payloadcms-commons/issues/83))
+
+### Features
+
+* **mcpx:** add deleteDocument with approval in the admin panel ([#107](https://github.com/abinnovision/payloadcms-commons/issues/107)) ([87ffa2b](https://github.com/abinnovision/payloadcms-commons/commit/87ffa2bae203dfd4e869f7c067f016691062f051))
+* **mcpx:** add duplicateDocument tool ([#111](https://github.com/abinnovision/payloadcms-commons/issues/111)) ([b4b4b1c](https://github.com/abinnovision/payloadcms-commons/commit/b4b4b1c27d73ed1a472a8319e3d394525d141219))
+* **mcpx:** add key expiry and per-locale validation and publishing ([#92](https://github.com/abinnovision/payloadcms-commons/issues/92)) ([c926352](https://github.com/abinnovision/payloadcms-commons/commit/c926352a10ed910f5c76a62ea20a739fd50a7504))
+* **mcpx:** clean up, harden and simplify the plugin for 2.0 ([#83](https://github.com/abinnovision/payloadcms-commons/issues/83)) ([7d29edf](https://github.com/abinnovision/payloadcms-commons/commit/7d29edf9bcacf8bba85d8525274530c8416a5cce))
+* **mcpx:** expose diagnostics for bug reports ([#94](https://github.com/abinnovision/payloadcms-commons/issues/94)) ([6d171a1](https://github.com/abinnovision/payloadcms-commons/commit/6d171a18a54cef013ea051fb8e4b798860d8fb90))
+* **mcpx:** expose version history and diffs ([#82](https://github.com/abinnovision/payloadcms-commons/issues/82)) ([44c2eb5](https://github.com/abinnovision/payloadcms-commons/commit/44c2eb5b75a2387b6797b320632052289ddeffb9))
+* **mcpx:** expose version history wherever read is granted ([#89](https://github.com/abinnovision/payloadcms-commons/issues/89)) ([281f6b0](https://github.com/abinnovision/payloadcms-commons/commit/281f6b01ce82b69c41d69bbd0b820cd2d589c656))
+* **mcpx:** link written documents to the admin panel and preview ([#109](https://github.com/abinnovision/payloadcms-commons/issues/109)) ([3b9393d](https://github.com/abinnovision/payloadcms-commons/commit/3b9393d0cbec6eb1027bb121e107899dba9bddbf))
+* **mcpx:** open the setup guide from a "Connect a client" drawer ([#126](https://github.com/abinnovision/payloadcms-commons/issues/126)) ([35da035](https://github.com/abinnovision/payloadcms-commons/commit/35da03571f8a079311bcca0d842187cb32abdd9f))
+* **mcpx:** refine the capability matrix into access levels ([#108](https://github.com/abinnovision/payloadcms-commons/issues/108)) ([2a32a7f](https://github.com/abinnovision/payloadcms-commons/commit/2a32a7fb4517cbecde2dcebaf1026f822cddc6f7))
+* **mcpx:** render API key capabilities as a permission matrix ([#67](https://github.com/abinnovision/payloadcms-commons/issues/67)) ([fce9644](https://github.com/abinnovision/payloadcms-commons/commit/fce96445007b7bee1dfa463acfd6a388df151e60))
+* **mcpx:** rework the capability matrix layout and delete control ([#112](https://github.com/abinnovision/payloadcms-commons/issues/112)) ([be23744](https://github.com/abinnovision/payloadcms-commons/commit/be23744099b5b2b307c4b8f71af64fca3dcb3e56))
+* **mcpx:** upload and download files through single-use grants ([#96](https://github.com/abinnovision/payloadcms-commons/issues/96)) ([761fa66](https://github.com/abinnovision/payloadcms-commons/commit/761fa665949501a7a48eadab3ccaa6e115bca47d))
+
+
+### Bug Fixes
+
+* **deps:** align @payloadcms/ui with payload 3.89.0 ([#70](https://github.com/abinnovision/payloadcms-commons/issues/70)) ([7f083e3](https://github.com/abinnovision/payloadcms-commons/commit/7f083e3e040ffa99cd66347965c3a492c46e7f12))
+* **deps:** bump @modelcontextprotocol/sdk from 1.31.0 to 1.32.0 in the production-dependencies group ([#124](https://github.com/abinnovision/payloadcms-commons/issues/124)) ([9f7eda2](https://github.com/abinnovision/payloadcms-commons/commit/9f7eda2234cf6a57ed11bbb3d5761c26e53ffe6d))
+* **deps:** bump the production-dependencies group across 1 directory with 2 updates ([#110](https://github.com/abinnovision/payloadcms-commons/issues/110)) ([cfa968f](https://github.com/abinnovision/payloadcms-commons/commit/cfa968fabbde1851c42851f7ffdcded3eb2cf6df))
+* **deps:** bump the production-dependencies group across 1 directory with 6 updates ([#86](https://github.com/abinnovision/payloadcms-commons/issues/86)) ([57d002c](https://github.com/abinnovision/payloadcms-commons/commit/57d002c693b74da431e24c8e789ee2eb5c7e416e))
+* **deps:** bump the production-dependencies group with 10 updates ([#68](https://github.com/abinnovision/payloadcms-commons/issues/68)) ([786b528](https://github.com/abinnovision/payloadcms-commons/commit/786b528e7929376c5e6ea570d94d58bb0b4298cc))
+* **deps:** bump the production-dependencies group with 2 updates ([#49](https://github.com/abinnovision/payloadcms-commons/issues/49)) ([8f079ec](https://github.com/abinnovision/payloadcms-commons/commit/8f079ecfc3b675318b4501a6b0073d8f3f2f36b5))
+* **deps:** keep @payloadcms/ui aligned with the rest of the Payload family ([#61](https://github.com/abinnovision/payloadcms-commons/issues/61)) ([e77c0b9](https://github.com/abinnovision/payloadcms-commons/commit/e77c0b94fcb696e2e9165d76b33945bf98d5a4ba))
+* **mcpx:** let hooks fill required fields on file uploads ([#106](https://github.com/abinnovision/payloadcms-commons/issues/106)) ([8421860](https://github.com/abinnovision/payloadcms-commons/commit/84218601bc21fca89dc287988b45c9a7365fb50d))
+
+
+### Code Refactoring
+
+* **mcpx:** align helpers and simplify the plugin internals ([#118](https://github.com/abinnovision/payloadcms-commons/issues/118)) ([cda6739](https://github.com/abinnovision/payloadcms-commons/commit/cda67391e932bfc033a2f579a5e1e6d1cca50094))
+
 ## 1.0.0 (2026-09-03)
 
 

package/README.md

@@ -1,6 +1,6 @@
 # @abinnovision/payloadcms-mcpx
 
-![A content model of any size funnels through nine fixed tools out to one client](https://raw.githubusercontent.com/abinnovision/payloadcms-commons/main/packages/mcpx/assets/header.png)
+![A content model of any size funnels through a fixed set of tools out to one client](https://raw.githubusercontent.com/abinnovision/payloadcms-commons/main/packages/mcpx/assets/header.png)
 
 A [Payload CMS](https://payloadcms.com/) plugin that serves an MCP (Model Context Protocol) server
 on one `POST` endpoint. Clients authenticate with API keys that users create in the admin panel.
@@ -61,7 +61,7 @@ The plugin adds:
 - An `mcpx-api-keys` collection in the admin group "MCP", holding the keys.
 - A draft guard on every collection and global that turns MCP writes into draft saves.
 
-The key form uses two admin components, so regenerate the import map:
+The key form uses two admin components, three with `delete`, so regenerate the import map:
 
 ```sh
 payload generate:importmap
@@ -82,27 +82,29 @@ claude mcp add --transport http payload http://localhost:3000/api/mcpx \
 
 Claude Desktop and the MCP Inspector are covered in
 [`docs/integration.md`](./docs/integration.md#connecting-other-clients). Saved keys also have a
-"Connect a client" tab with ready-to-paste snippets.
+"Connect a client" button that opens ready-to-paste snippets.
 
 ## Options
 
-| Option                       | Default                                   | Description                                                         |
-| ---------------------------- | ----------------------------------------- | ------------------------------------------------------------------- |
-| `collections`                | required                                  | Collections to expose. `true` means `{}`, everything it supports.   |
-| `collections.<slug>.read`    | `true`                                    | Expose the read tools for this collection.                          |
-| `collections.<slug>.write`   | `true`                                    | Expose the write tools. Without drafts, a write goes live.          |
-| `collections.<slug>.publish` | `true` with drafts                        | Expose `publishDocument`. Needs `versions.drafts` and `write`.      |
-| `globals`                    | `{}`                                      | Globals to expose, with the same three options.                     |
-| `userCollection`             | `config.admin.user`, then `users`         | Auth collection whose users the keys act as.                        |
-| `apiKeys.slug`               | `mcpx-api-keys`                           | Slug of the key collection.                                         |
-| `apiKeys.setupGuide`         | `true`                                    | Add the "Connect a client" tab to saved keys.                       |
-| `apiKeys.overrideCollection` | none                                      | Function that receives the key collection and returns it.           |
-| `endpoint.path`              | `/mcpx`                                   | Endpoint path below the API route.                                  |
-| `limits.maxLimit`            | `25`                                      | Highest `limit` a client may pass to a list tool.                   |
-| `limits.maxDepth`            | `1`                                       | Highest `depth` a client may pass to a read tool.                   |
-| `tools`                      | `[]`                                      | Custom tools, see [`docs/custom-tools.md`](./docs/custom-tools.md). |
-| `auth.resolve`               | none                                      | Replace or wrap the key lookup.                                     |
-| `serverInfo`                 | `payloadcms-mcpx` and the package version | `{ name, version }` reported to clients.                            |
+| Option                       | Default                                   | Description                                                                                                                                       |
+| ---------------------------- | ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `collections`                | required                                  | Collections to expose. `true` means `{}`, everything it supports.                                                                                 |
+| `collections.<slug>.read`    | `true`                                    | Expose the read tools for this collection.                                                                                                        |
+| `collections.<slug>.write`   | `true`                                    | Expose the write tools. Needs `read`. Without drafts, a write goes live.                                                                          |
+| `collections.<slug>.publish` | `true` with drafts                        | Expose `publishDocument`. Needs `versions.drafts` and `write`.                                                                                    |
+| `collections.<slug>.delete`  | `false`                                   | Expose `deleteDocument`. Needs `read`. Each delete is approved in the admin. `"unattended"` also offers trashing without approval; needs `trash`. |
+| `globals`                    | `{}`                                      | Globals to expose, with `read`, `write` and `publish`.                                                                                            |
+| `userCollection`             | `config.admin.user`, then `users`         | Auth collection whose users the keys act as.                                                                                                      |
+| `apiKeys.slug`               | `mcpx-api-keys`                           | Slug of the key collection.                                                                                                                       |
+| `apiKeys.setupGuide`         | `true`                                    | Add the "Connect a client" button to saved keys.                                                                                                  |
+| `apiKeys.overrideCollection` | none                                      | Function that receives the key collection and returns it.                                                                                         |
+| `endpoint.path`              | `/mcpx`                                   | Endpoint path below the API route.                                                                                                                |
+| `limits.maxLimit`            | `25`                                      | Highest `limit` a client may pass to a list tool.                                                                                                 |
+| `limits.maxDepth`            | `1`                                       | Highest `depth` a client may pass to a read tool.                                                                                                 |
+| `tools`                      | `[]`                                      | Custom tools, see [`docs/custom-tools.md`](./docs/custom-tools.md).                                                                               |
+| `auth.resolve`               | none                                      | Replace or wrap the key lookup.                                                                                                                   |
+| `serverInfo`                 | `payloadcms-mcpx` and the package version | `{ name, version }` reported to clients.                                                                                                          |
+| `diagnostics`                | `true`                                    | Expose the server version plus repository and issue links.                                                                                        |
 
 The config only takes capabilities away: `true` exposes everything the entity supports, and a key's
 checkboxes decide what each key may do. `publish: false` keeps MCP writes as drafts. On an entity
@@ -114,17 +116,20 @@ every check.
 
 ## Tools
 
-| Tool               | What it does                                                       | Needs              |
-| ------------------ | ------------------------------------------------------------------ | ------------------ |
-| `listCapabilities` | Lists what this key may do. Clients call it first.                 | any key            |
-| `describeSchema`   | Describes the fields at one schema path, with the paths below it.  | `read`             |
-| `findDocuments`    | Queries a collection with a Payload `where`, `sort` and `select`.  | `read`             |
-| `getDocument`      | Reads a document, a subtree of it, an old version or a diff.       | `read`             |
-| `findVersions`     | Lists the version history of a document or global, without bodies. | `read`             |
-| `patchDocument`    | Applies JSON Patch operations to the current draft.                | `write`            |
-| `createDocument`   | Creates a draft from a seed. Not for upload collections.           | `write`            |
-| `validateDocument` | Lists what blocks publishing, without saving.                      | `write`            |
-| `publishDocument`  | Publishes the current draft.                                       | `write`, `publish` |
+| Tool                | What it does                                                       | Needs     |
+| ------------------- | ------------------------------------------------------------------ | --------- |
+| `listCapabilities`  | Lists what this key may do. Clients call it first.                 | any key   |
+| `describeSchema`    | Describes the fields at one schema path, with the paths below it.  | `read`    |
+| `findDocuments`     | Queries a collection with a Payload `where`, `sort` and `select`.  | `read`    |
+| `getDocument`       | Reads a document, a subtree of it, an old version or a diff.       | `read`    |
+| `findVersions`      | Lists the version history of a document or global, without bodies. | `read`    |
+| `patchDocument`     | Applies JSON Patch operations to the current draft, or a new file. | `write`   |
+| `createDocument`    | Creates a draft from a seed, with a file in an upload collection.  | `write`   |
+| `duplicateDocument` | Copies a document into a new draft, in every locale.               | `write`   |
+| `validateDocument`  | Lists what blocks publishing, without saving.                      | `write`   |
+| `publishDocument`   | Publishes the current draft.                                       | `publish` |
+| `deleteDocument`    | Asks to delete a document, which the key's user approves.          | `delete`  |
+| `runConfirmed`      | Runs the approved calls.                                           | `delete`  |
 
 Collections and globals use the same tools. A tool that addresses one document takes either
 `collection` and `id`, or `global` alone. [`docs/concepts.md`](./docs/concepts.md#tools) lists
@@ -137,11 +142,20 @@ A key can do something only when both the config and the key allow it.
 The plugin config sets the upper bound: which collections and globals are exposed, and whether
 each one is readable, writable and publishable. A key cannot go past it.
 
-Each key carries one checkbox per exposed entity and operation (`read`, `write`, `publish`), and
-one per custom tool. The admin panel shows them as a matrix with a row per entity and a column per
-operation. A cell the config does not expose shows a dash. `publish` exists only where the config
-exposes `write` and `publish` on an entity with drafts, and counts only when `write` is ticked as
-well. A write checkbox on an entity without drafts is marked "Writes go live immediately."
+Each key carries one checkbox per exposed entity and operation (`read`, `write`, `publish`,
+`delete`, `deleteUnattended`), and
+one per custom tool. The admin panel shows them as a matrix with a row per entity, an Access
+control (None, Read, Write, Publish) and a Delete checkbox with an approval shield. Each access level
+includes the ones before it, and a level the config does not expose has no segment. `publish`
+exists only where the config exposes `write` and `publish` on an entity with drafts, and counts
+only when `write` is ticked as well. `write` counts only when `read` is ticked, so a key never
+writes what it cannot read. An entity without drafts carries a "Live" badge, as its writes go live
+immediately.
+`delete` exists only where the config sets `delete: true` on a collection, and counts only when
+`read` is ticked as well. Setting access to None clears it. A delete runs only after the key's user
+approved it on the key's edit view, except where the config sets `delete: "unattended"` and the
+key's approval shield is off: there the document moves to trash at once. See
+[deleting](./docs/concepts.md#deleting).
 
 `tools/list` follows the key. A tool the key cannot use is not listed, and each `collection` and
 `global` argument lists only the slugs the key may use with that tool. A checkbox added by a later
@@ -163,6 +177,12 @@ To restrict that, use `apiKeys.overrideCollection` as shown in
   Blocker messages can name fields the user cannot read.
 - The request body is limited to 4 MB, a JSON-RPC batch to 10 messages, `patchDocument` to 500
   operations and `describeSchema` to 400 paths.
+- A file is sent in a second step, a `PUT`, and downloaded with a `GET`, each with a short-lived,
+  single-use grant. Only collections with `upload.mimeTypes` take files. Downloads go through the
+  collection's own file access. See [uploads](./docs/security.md#uploads).
+- A delete waits for the key's user to approve it in the admin panel and is then run by the same
+  key. Collections with `trash` move the document to trash. See
+  [confirmations](./docs/security.md#confirmations).
 - Custom tools are trusted code and must apply access control themselves.
 
 Open limitations: a filter through a relation into a readable collection ignores that collection's

package/dist/admin/capability-matrix.d.mts

@@ -25,9 +25,11 @@ interface McpxCapabilityMatrixProps {
   withinTab?: boolean;
 }
 /**
- * What an API key may do, as one table per namespace: a row per entity, a
- * column per operation and a bulk toggle in each column header. The nested
- * checkbox fields back every cell, so the stored document is unaffected.
+ * What an API key may do, as one table per namespace: a row per entity with
+ * an Access control and a Delete checkbox with an approval shield, and an
+ * "All" row that sets every row.
+ * The nested checkbox fields back every control, so the stored document is
+ * unaffected.
  */
 export declare const McpxCapabilityMatrix: React.FC<McpxCapabilityMatrixProps>;
 //#endregion