@abinnovision/payloadcms-mcpx 1.0.0-beta.10

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 abi group GmbH
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,353 @@
+# @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.
+
+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 always land as drafts; 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
+
+```bash
+yarn add @abinnovision/payloadcms-mcpx
+```
+
+- Peer dependency: `payload >=3.88.0 <4`.
+- `@payloadcms/ui` and `react` are optional peers, needed only by the admin
+  setup guide. A headless install can leave them out and set
+  `apiKeys.setupGuide: false`.
+- The package is published as ESM only, matching Payload itself.
+
+## Usage
+
+```ts
+import { mcpxPlugin } from "@abinnovision/payloadcms-mcpx";
+import { buildConfig } from "payload";
+
+export default buildConfig({
+  // ...
+  plugins: [
+    mcpxPlugin({
+      collections: {
+        pages: { read: true, write: true },
+        posts: { read: true, write: true },
+        tags: true, // shorthand for { read: true }
+      },
+      globals: {
+        "site-settings": { read: true, write: true },
+      },
+      limits: { maxLimit: 25, maxDepth: 1 },
+    }),
+  ],
+});
+```
+
+The plugin adds:
+
+- a `POST /api/mcpx` endpoint speaking MCP over streamable HTTP (stateless,
+  JSON responses; `GET`/`DELETE` answer 405),
+- an `mcpx-api-keys` collection (admin group "MCP") holding the keys and their
+  capability checkboxes,
+- 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
+```
+
+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>`:
+
+```bash
+npx @modelcontextprotocol/inspector
+# transport: Streamable HTTP, URL: http://localhost:3000/api/mcpx
+# header: Authorization: Bearer <key>
+```
+
+Claude Code:
+
+```bash
+claude mcp add --transport http payload http://localhost:3000/api/mcpx \
+	--header "Authorization: Bearer <key>"
+```
+
+Claude Desktop (no direct HTTP header support) via `mcp-remote`:
+
+```json
+{
+  "mcpServers": {
+    "payload": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "mcp-remote",
+        "http://localhost:3000/api/mcpx",
+        "--header",
+        "Authorization: Bearer <key>"
+      ]
+    }
+  }
+}
+```
+
+## Tools
+
+The surface is fixed at seven 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 writing.                           | `collection` + `id` \| `global`, `locale`                                                    |
+
+Rules the tools enforce and explain in their own descriptions:
+
+- `describeSchema` paths stop at blocks fields, which list the block slugs they
+  accept; every node carries `next`, the ready-to-use paths for those blocks
+  (`/layout/sections/sectionWrapper`), so pass an entry of `next` as a `paths`
+  element to descend. A block is described as it exists at that position.
+- Rich text paths continue the same way. A `richText` field lists the Lexical
+  node types it accepts in `nodes`, and `next` carries a path for every node
+  type that holds fields of its own: `/content/link` for a link node,
+  `/content/block/callout` and `/content/inlineBlock/badge` for the block
+  nodes. Descending returns the real field list, so a link extended through
+  `LinkFeature({ fields })` and a Lexical block are both described rather than
+  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.
+- 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
+  something to read; a group or named tab only when it declares a description
+  or a constraint of its own.
+- A `richText` field also reports `nodeOptions`, the node properties its editor
+  narrows. An editor built with `HeadingFeature({ enabledHeadingSizes: ["h4"] })`
+  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.
+- 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
+  the request's language, falling back to the deployment's fallback language and
+  then to the record's first entry; functions and components are dropped.
+- Builtin tools reject unknown arguments by name instead of silently ignoring
+  them.
+- Every path this plugin accepts or reports is a JSON Pointer. A schema path
+  and a pointer into a document differ only in what stands in an element
+  position: a schema path writes `*` for an array element and names a block by
+  its slug, where a pointer carries a 0-based index. So `/items/*/title` is
+  written at `/items/0/title`, and `/layout/sections/hero` at
+  `/layout/sections/0`.
+- Adding a block requires `blockType` on the value; append with `/-`.
+- Clearing is `replace` with `null`; a list is emptied with `[]` and refuses
+  `null`. `remove` is only valid on list elements, because Payload keeps
+  fields absent from a write.
+- Nothing in a patch batch is applied unless every operation validates first.
+- Pass the `updatedAt` you read as `expectedUpdatedAt` so a concurrent edit is
+  refused instead of overwritten.
+- Fields Payload maintains (`id`, `_status`, `createdAt`, `updatedAt`,
+  `deletedAt`) are never listed and never writable; `readOnly` fields are
+  listed but refused on write.
+
+## Globals
+
+A global is exposed the same way a collection is, and reached through the same
+tools rather than tools of its own:
+
+```ts
+mcpxPlugin({
+  collections: { pages: { read: true, write: true } },
+  globals: { "site-settings": { read: true, write: true } },
+});
+```
+
+Two rules follow from a global being a singleton, and because JSON Schema cannot
+state either one, both are enforced in the handler and repeated in every
+affected tool description:
+
+- Pass exactly **one** of `collection` and `global`.
+- `id` is required with `collection` and must be omitted with `global`.
+
+Refusals name the offending argument and the slug, so one failed call teaches
+the rule. `findDocuments` and `createDocument` stay collection-only: there is
+nothing to list and nothing to create when the document always exists. They
+reject a `global` argument by name.
+
+Globals get their own `capabilities.globals.<name>` checkbox group, a separate
+namespace from `capabilities.collections.<name>`, so a global may share a
+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
+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.
+
+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
+
+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.
+
+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.
+
+Writes also report `notApplied`: pointers whose value Payload kept unchanged,
+which happens when field-level access denies the update.
+
+## Custom tools
+
+```ts
+import { defineMcpxTool } from "@abinnovision/payloadcms-mcpx";
+import { z } from "zod";
+
+const publishQueue = defineMcpxTool({
+  name: "queueForReview",
+  description: "Marks a page as ready for editorial review.",
+  inputSchema: { id: z.string() },
+  handler: async ({ args, req }) => {
+    // req.user is the key's linked user, req.context.mcpx carries the
+    // key id and capabilities. Writes through payload.update({ req })
+    // land as drafts like every other MCP write.
+    await req.payload.update({
+      collection: "pages",
+      id: args.id,
+      data: { reviewRequested: true },
+      overrideAccess: false,
+      req,
+    });
+    return { content: [{ type: "text", text: "queued" }] };
+  },
+});
+```
+
+Each custom tool gets its own checkbox on every API key, default off.
+
+Custom tool shapes are registered as given, and the MCP SDK wraps them in a
+non-strict object: unknown arguments are stripped before your handler runs.
+Builtin tools reject them instead.
+
+## 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.                                                                                                      |
+| `auth.resolve`                       | none                           | Replace or wrap the default key resolution.                                                                        |
+| `serverInfo`                         | package name and version       | Reported to MCP clients.                                                                                           |
+
+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.
+
+## Security notes
+
+- Keys are stored encrypted; lookup is by HMAC-SHA256 index derived from
+  `payload.secret`, the same scheme Payload uses for its own API keys.
+- 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.
+
+## 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.
+
+## License
+
+Apache-2.0

package/dist/api-keys/collection.mjs

@@ -0,0 +1,58 @@
+import { createCapabilityFields, createKeyFields, withSetupGuideTab } from "./fields.mjs";
+import { generateApiKey, hashApiKey } from "./key.mjs";
+//#region src/api-keys/collection.ts
+/**
+* Generates the key on create and keeps the lookup index in step with it.
+* Runs after field `beforeValidate` fallbacks, so on update `data.apiKey` is the
+* decrypted plaintext of the stored key.
+*/ const keyBeforeChange = ({ data, operation, req }) => {
+	if (operation === "create" && typeof data["apiKey"] !== "string") data["apiKey"] = generateApiKey();
+	if (typeof data["apiKey"] === "string") data["apiKeyIndex"] = hashApiKey(req.payload.secret, data["apiKey"]);
+	return data;
+};
+/**
+* The collection holding MCP API keys. It is not an auth collection on
+* purpose: keys must only ever authenticate the MCP endpoint, never the REST
+* or GraphQL API.
+*/ const createApiKeysCollection = (options) => {
+	const { userCollection } = options;
+	const isUser = ({ req }) => Boolean(req.user && req.user.collection === userCollection);
+	const ownKeysOnly = ({ req }) => isUser({ req }) && req.user ? { user: { equals: req.user.id } } : false;
+	return {
+		slug: options.apiKeysSlug,
+		labels: {
+			singular: "API Key",
+			plural: "API Keys"
+		},
+		admin: {
+			group: "MCP",
+			useAsTitle: "label",
+			description: "Keys for MCP clients. Each key acts as its user and may only do what its capabilities allow."
+		},
+		access: {
+			create: isUser,
+			read: ownKeysOnly,
+			update: ownKeysOnly,
+			delete: ownKeysOnly
+		},
+		hooks: { beforeChange: [keyBeforeChange] },
+		fields: withSetupGuideTab([
+			{
+				name: "user",
+				type: "relationship",
+				relationTo: userCollection,
+				required: true,
+				access: {
+					create: () => false,
+					update: () => false
+				},
+				defaultValue: ({ req }) => isUser({ req }) ? req.user?.id : void 0,
+				admin: { description: "The user this key acts as." }
+			},
+			...createKeyFields(),
+			...createCapabilityFields(options)
+		], options)
+	};
+};
+//#endregion
+export { createApiKeysCollection, keyBeforeChange };