@abinnovision/payloadcms-mcpx 1.0.0-beta.3

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,258 @@
+# @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 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`.
+- 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 }
+      },
+      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, 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
+
+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. `tools/list`
+reflects the key: write tools disappear for read-only keys, and every
+`collection` 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`, `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`, `path?` (JSON pointer), `depth?`, `locale?`, `draft?`                    |
+| `patchDocument`    | Apply RFC 6902 operations to the current draft.             | `collection`, `id`, `locale`, `patches`, `expectedUpdatedAt?`                                |
+| `createDocument`   | Create a draft from a minimal seed.                         | `collection`, `locale`, `data`                                                               |
+| `validateDocument` | Publish blockers without writing.                           | `collection`, `id`, `locale`                                                                 |
+
+Rules the tools enforce and explain in their own descriptions:
+
+- `describeSchema` paths are dotted and 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.
+- Field and collection `admin.description` values are included in
+  `describeSchema` and `listCapabilities`, so intent written for the admin
+  panel reaches the client. Strings and locale-keyed records pass through;
+  functions and components are dropped.
+- Builtin tools reject unknown arguments by name instead of silently ignoring
+  them.
+- A schema path becomes a patch pointer by replacing `.` with `/`, adding a
+  leading `/`, and replacing each `[]` with a 0-based index.
+- 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.
+
+## 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.
+
+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`.
+
+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).                                                     |
+| `userCollection`                     | `config.admin.user` or `users` | Auth collection the keys act as.                                                                                   |
+| `apiKeys.slug`                       | `mcpx-api-keys`                | Slug of the generated key collection.                                                                              |
+| `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), globals,
+  uploads. Custom tools are trusted code and can do what the linked user may.
+
+## Non-goals of v1 / roadmap
+
+Globals, deletes, uploads, markdown authoring for rich text, 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 } 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: [
+			{
+				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)
+		]
+	};
+};
+//#endregion
+export { createApiKeysCollection, keyBeforeChange };

package/dist/api-keys/fields.mjs

@@ -0,0 +1,88 @@
+import { CAPABILITIES_FIELD } 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 }) => {
+	if (typeof value !== "string") return value;
+	try {
+		return req.payload.decrypt(value);
+	} catch {
+		return;
+	}
+};
+const checkbox = (name, description) => ({
+	name,
+	type: "checkbox",
+	defaultValue: false,
+	admin: { description }
+});
+/**
+* Fields every key carries. Key generation and the HMAC index live in the
+* collection-level `beforeChange` hook (see `collection.ts`), because sibling
+* field hooks run in parallel and cannot depend on each other's values.
+*/ const createKeyFields = () => [
+	{
+		name: "label",
+		type: "text",
+		required: true,
+		admin: { description: "What this key is used for." }
+	},
+	{
+		name: "enabled",
+		type: "checkbox",
+		defaultValue: true,
+		admin: { description: "Disabled keys are refused without revoking them." }
+	},
+	{
+		name: "apiKey",
+		type: "text",
+		access: {
+			create: () => false,
+			update: () => false
+		},
+		admin: {
+			readOnly: true,
+			description: "Generated when the key is created. Send it as `Authorization: Bearer <key>`."
+		},
+		hooks: {
+			beforeChange: [encryptKey],
+			afterRead: [decryptKey]
+		}
+	},
+	{
+		name: "apiKeyIndex",
+		type: "text",
+		hidden: true,
+		index: true
+	}
+];
+/**
+* One checkbox per exposed operation, grouped per collection 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.
+*/ 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.")] : []]
+	}));
+	const toolCheckboxes = options.tools.map((tool) => checkbox(tool.name, tool.description));
+	const groups = [...collectionGroups.length > 0 ? [{
+		name: "collections",
+		type: "group",
+		fields: collectionGroups
+	}] : [], ...toolCheckboxes.length > 0 ? [{
+		name: "tools",
+		type: "group",
+		fields: toolCheckboxes
+	}] : []];
+	if (groups.length === 0) return [];
+	return [{
+		name: CAPABILITIES_FIELD,
+		type: "group",
+		admin: { description: "What this key may do. Unchecked means refused, whatever the plugin config allows." },
+		fields: groups
+	}];
+};
+//#endregion
+export { createCapabilityFields, createKeyFields };

package/dist/api-keys/key.mjs

@@ -0,0 +1,10 @@
+import crypto from "node:crypto";
+//#region src/api-keys/key.ts
+/**
+* A fresh API key: 32 random bytes, base64url so it is safe in headers.
+*/ const generateApiKey = () => crypto.randomBytes(32).toString("base64url");
+/**
+* Lookup index of a key, the same HMAC Payload core uses for `apiKeyIndex`.
+*/ const hashApiKey = (secret, key) => crypto.createHmac("sha256", secret).update(key).digest("hex");
+//#endregion
+export { generateApiKey, hashApiKey };

package/dist/auth/resolve.mjs

@@ -0,0 +1,62 @@
+import { hashApiKey } from "../api-keys/key.mjs";
+//#region src/auth/resolve.ts
+const BEARER = /^Bearer\s+(\S+)\s*$/i;
+/**
+* The bearer token of an `Authorization` header, or `null`.
+*/ const parseBearer = (headers) => {
+	const header = headers.get("authorization");
+	if (!header) return null;
+	return BEARER.exec(header.trim())?.[1] ?? null;
+};
+const relationId = (value) => {
+	if (typeof value === "string" || typeof value === "number") return value;
+	if (typeof value === "object" && value !== null && "id" in value) return value.id;
+};
+/**
+* Resolves the bearer key of a request to the user it acts as.
+*
+* The key is looked up by its HMAC index, the same way Payload resolves its own
+* API keys. A missing, unknown, disabled or orphaned key yields `null`; nothing
+* here throws, so the handler alone decides how a refusal looks.
+*/ const resolveApiKeyAuth = async (req, options) => {
+	const key = parseBearer(req.headers);
+	if (key === null) return null;
+	const { payload } = req;
+	const { docs } = await payload.find({
+		collection: options.apiKeysSlug,
+		where: { apiKeyIndex: { equals: hashApiKey(payload.secret, key) } },
+		limit: 1,
+		pagination: false,
+		depth: 0,
+		overrideAccess: true,
+		select: {
+			enabled: true,
+			user: true,
+			capabilities: true
+		}
+	});
+	const keyDoc = docs[0];
+	const userId = relationId(keyDoc?.user);
+	if (!keyDoc || keyDoc.enabled !== true || userId === void 0) return null;
+	const userCollection = payload.collections[options.userCollection];
+	const user = await payload.findByID({
+		collection: options.userCollection,
+		id: userId,
+		depth: userCollection?.config.auth.depth ?? 0,
+		overrideAccess: true,
+		disableErrors: true
+	});
+	const lockUntil = typeof user?.["lockUntil"] === "string" ? Date.parse(user["lockUntil"]) : NaN;
+	if (!user || user["_verified"] === false || lockUntil > Date.now()) return null;
+	return {
+		user: {
+			...user,
+			collection: options.userCollection,
+			_strategy: "mcpx-api-key"
+		},
+		apiKeyId: keyDoc.id,
+		capabilities: keyDoc.capabilities
+	};
+};
+//#endregion
+export { parseBearer, resolveApiKeyAuth };