@abinnovision/payloadcms-mcpx 2.0.0-beta.7 → 2.0.0-beta.9

package/README.md

@@ -86,30 +86,29 @@ Claude Desktop and the MCP Inspector are covered in
 
 ## 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`.      |
-| `collections.<slug>.versions` | `false`                                   | Expose version history. Needs Payload `versions` on the entity.     |
-| `globals`                     | `{}`                                      | Globals to expose, with the same four 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. 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.                            |
 
 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
-without drafts, a write changes the live document. `versions` defaults to `false`: version history
-has no checkbox of its own and follows the key's read, so the config opts in. Read
-[version history](./docs/security.md#version-history) before turning it on.
+without drafts, a write changes the live document. Version history has no checkbox of its own: it
+follows the key's read wherever the entity keeps Payload `versions`. Read
+[version history](./docs/security.md#version-history) first.
 Mistakes in the options fail at startup. [`docs/integration.md`](./docs/integration.md) lists
 every check.
 
@@ -121,7 +120,7 @@ every check.
 | `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`, `versions` |
+| `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`            |

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

@@ -2,18 +2,26 @@ import { CapabilityMatrix } from "../api-keys/capability-matrix.mjs";
 import React from "react";
 //#region src/admin/capability-matrix.d.ts
 interface McpxCapabilityMatrixProps {
-  /** Built from the plugin options at config time. */
+  /**
+   * Built from the plugin options at config time.
+   */
   matrix: CapabilityMatrix;
-  /** The group's own config, supplied by Payload. Carries the description. */
+  /**
+   * The group's own config, supplied by Payload. Carries the description.
+   */
   field?: {
     admin?: {
       description?: unknown;
     };
   };
-  /** The `capabilities` group's own path, supplied by Payload. */
+  /**
+   * The `capabilities` group's own path, supplied by Payload.
+   */
   path?: string;
   readOnly?: boolean;
-  /** Whether the key form is split into tabs, from the plugin options. */
+  /**
+   * Whether the key form is split into tabs, from the plugin options.
+   */
   withinTab?: boolean;
 }
 /**

package/dist/admin/setup-guide.d.mts

@@ -1,7 +1,9 @@
 import React from "react";
 //#region src/admin/setup-guide.d.ts
 interface McpxSetupGuideProps {
-  /** Endpoint path below the API route, from the plugin options. */
+  /**
+   * Endpoint path below the API route, from the plugin options.
+   */
   endpointPath: string;
 }
 /**

package/dist/api-keys/capability-matrix.d.mts

@@ -7,12 +7,16 @@ import "../options.mjs";
  */
 export interface CapabilityRow {
   fieldName: string;
-  /** The slug, which is what MCP clients send and what refusals name. */
+  /**
+   * The slug, which is what MCP clients send and what refusals name.
+   */
   label: string;
   read: boolean;
   write: boolean;
   publish: boolean;
-  /** Said only where a row departs from what its column header promises. */
+  /**
+   * Said only where a row departs from what its column header promises.
+   */
   hint?: string;
 }
 interface CapabilityTool {

package/dist/api-keys/capability-matrix.mjs

@@ -53,6 +53,8 @@ const toRow = (entity) => ({
 });
 const cellPath = (basePath, namespace, fieldName, operation) => `${basePath}.${namespace}.${fieldName}.${operation}`;
 const toolPath = (basePath, name) => `${basePath}.tools.${name}`;
-/** Every path the matrix can address, in a stable order. */ const capabilityPaths = (matrix, basePath = CAPABILITIES_FIELD) => [...["collections", "globals"].flatMap((namespace) => matrix[namespace].flatMap((row) => CAPABILITY_OPERATIONS.filter((operation) => row[operation.id]).map((operation) => cellPath(basePath, namespace, row.fieldName, operation.id)))), ...matrix.tools.map((tool) => toolPath(basePath, tool.name))];
+/**
+* Every path the matrix can address, in a stable order.
+*/ const capabilityPaths = (matrix, basePath = CAPABILITIES_FIELD) => [...["collections", "globals"].flatMap((namespace) => matrix[namespace].flatMap((row) => CAPABILITY_OPERATIONS.filter((operation) => row[operation.id]).map((operation) => cellPath(basePath, namespace, row.fieldName, operation.id)))), ...matrix.tools.map((tool) => toolPath(basePath, tool.name))];
 //#endregion
 export { CAPABILITIES_DESCRIPTION, CAPABILITY_OPERATIONS, capabilityPaths, cellPath, createCapabilityMatrix, toolPath };

package/dist/api-keys/collection.mjs

@@ -5,7 +5,8 @@ import { generateApiKey, hashApiKey } from "./key.mjs";
 * 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 }) => {
+*/ const keyBeforeChange = ({ context, data, operation, req }) => {
+	if (context["mcpxTouch"]) return data;
 	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;

package/dist/api-keys/fields.mjs

@@ -34,6 +34,27 @@ const SETUP_GUIDE_FIELD = "setupGuide";
 		defaultValue: true,
 		admin: { description: "Disabled keys are refused without revoking them." }
 	},
+	{
+		name: "expiresAt",
+		type: "date",
+		admin: {
+			date: { pickerAppearance: "dayAndTime" },
+			description: "Refused from this time on. Leave empty for no expiry."
+		}
+	},
+	{
+		name: "lastUsedAt",
+		type: "date",
+		access: {
+			create: () => false,
+			update: () => false
+		},
+		admin: {
+			readOnly: true,
+			date: { pickerAppearance: "dayAndTime" },
+			description: "Updated at most once an hour."
+		}
+	},
 	{
 		name: "apiKey",
 		type: "text",

package/dist/auth/resolve.mjs

@@ -2,6 +2,8 @@ import { isPlainObject } from "../guards.mjs";
 import { hashApiKey } from "../api-keys/key.mjs";
 //#region src/auth/resolve.ts
 const BEARER = /^Bearer\s+(\S+)\s*$/i;
+const LAST_USED_INTERVAL_MS = 36e5;
+const toTime = (value) => typeof value === "string" || value instanceof Date ? new Date(value).getTime() : NaN;
 const relationId = (value) => {
 	if (typeof value === "string" || typeof value === "number") return value;
 	if (typeof value === "object" && value !== null && "id" in value) return value.id;
@@ -39,12 +41,15 @@ const isId = (value) => typeof value === "string" || typeof value === "number";
 		select: {
 			enabled: true,
 			user: true,
-			capabilities: true
+			capabilities: true,
+			expiresAt: true,
+			lastUsedAt: true
 		}
 	});
 	const keyDoc = docs[0];
 	const userId = relationId(keyDoc?.user);
 	if (!keyDoc || keyDoc.enabled !== true || userId === void 0) return null;
+	if (toTime(keyDoc.expiresAt) <= Date.now()) return null;
 	const userCollection = payload.collections[options.userCollection];
 	const lookup = {
 		collection: options.userCollection,
@@ -61,9 +66,24 @@ const isId = (value) => typeof value === "string" || typeof value === "number";
 		showHiddenFields: true,
 		select: { lockUntil: true }
 	})]);
-	const storedLock = lock?.["lockUntil"];
-	const lockUntil = typeof storedLock === "string" || storedLock instanceof Date ? new Date(storedLock).getTime() : NaN;
+	const lockUntil = toTime(lock?.["lockUntil"]);
 	if (!user || user["_verified"] === false || lockUntil > Date.now()) return null;
+	const lastUsed = toTime(keyDoc.lastUsedAt);
+	if (Number.isNaN(lastUsed) || Date.now() - lastUsed > LAST_USED_INTERVAL_MS) try {
+		await payload.update({
+			collection: options.apiKeysSlug,
+			id: keyDoc.id,
+			data: { lastUsedAt: (/* @__PURE__ */ new Date()).toISOString() },
+			overrideAccess: true,
+			depth: 0,
+			context: { mcpxTouch: true }
+		});
+	} catch (error) {
+		payload.logger.warn({
+			err: error,
+			msg: "Could not record the last use of an MCP API key"
+		});
+	}
 	return {
 		user: {
 			...user,

package/dist/capabilities.mjs

@@ -1,8 +1,14 @@
 import { isPlainObject } from "./guards.mjs";
 //#region src/capabilities.ts
-/** Group field holding the capability checkboxes on an API key document. */ const CAPABILITIES_FIELD = "capabilities";
-/** Covers draft and live writes; {@link isLiveWrite} separates them. */ const canWrite = (entity) => entity.write !== false;
-/** The config lets MCP change live content and a draft exists to promote. */ const canPublish = (entity) => entity.write === "live" && entity.hasDrafts;
+/**
+* Group field holding the capability checkboxes on an API key document.
+*/ const CAPABILITIES_FIELD = "capabilities";
+/**
+* Covers draft and live writes; {@link isLiveWrite} separates them.
+*/ const canWrite = (entity) => entity.write !== false;
+/**
+* The config lets MCP change live content and a draft exists 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.

package/dist/define-tool.d.mts

@@ -1,11 +1,15 @@
 import { McpxAnyTool, McpxTool, McpxToolScope } from "./types.mjs";
 import { z } from "zod";
 //#region src/define-tool.d.ts
-/** Fixed shape; arguments inferred from it. */
+/**
+ * Fixed shape; arguments inferred from it.
+ */
 export declare function defineMcpxTool<Shape extends z.ZodRawShape>(tool: McpxTool<Shape> & {
   inputSchema?: Shape;
 }): McpxTool<Shape>;
-/** Per-request shape returned as an object literal; arguments inferred from it. */
+/**
+ * Per-request shape returned as an object literal; arguments inferred from it.
+ */
 export declare function defineMcpxTool<Shape extends z.ZodRawShape>(tool: McpxTool<Shape> & {
   inputSchema: (scope: McpxToolScope) => Shape;
 }): McpxAnyTool;

package/dist/endpoint/server.mjs

@@ -4,9 +4,13 @@ import { BUILTIN_TOOLS } from "../tools/builtin.mjs";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { z } from "zod";
 //#region src/endpoint/server.ts
-/** Strict, so an unknown argument is rejected by name instead of stripped. */ const toolInputSchema = (tool, scope) => z.strictObject(typeof tool.inputSchema === "function" ? tool.inputSchema(scope) : tool.inputSchema ?? {});
+/**
+* Strict, so an unknown argument is rejected by name instead of stripped.
+*/ const toolInputSchema = (tool, scope) => z.strictObject(typeof tool.inputSchema === "function" ? tool.inputSchema(scope) : tool.inputSchema ?? {});
 const toolDescription = (tool, scope) => typeof tool.description === "function" ? tool.description(scope) : tool.description;
-/** A tool that does not decide for itself is gated by its own checkbox. */ const isToolEnabled = (tool, scope) => tool.isEnabled ? tool.isEnabled(scope) : scope.capabilities.tools[tool.name] === true;
+/**
+* A tool that does not decide for itself is gated by its own checkbox.
+*/ const isToolEnabled = (tool, scope) => tool.isEnabled ? tool.isEnabled(scope) : scope.capabilities.tools[tool.name] === true;
 const WORKFLOW = [
 	{
 		tools: ["listCapabilities"],
@@ -36,7 +40,9 @@ const WORKFLOW = [
 const PATHS = `describeSchema takes and returns schema paths. Every other "path", and "from" in a patch operation, is a pointer into a document, with a 0-based index where a schema path has "*" for an array element or a block slug: "/layout/sections/sectionWrapper/identifier" is "/layout/sections/0/identifier". In rich text a pointer enters the rich text state: "/content/block/callout/tone" is "/content/root/children/3/fields/tone". getDocument "outline" gives the index.`;
 const DRAFTS = "Writes are saved as drafts, except in collections and globals without drafts, which patchDocument names: those go live immediately.";
 const DRAFTS_ONLY = "Every write is saved as a draft.";
-/** The workflow for the tools this key has, and what its writes reach. */ const serverInstructions = (scope) => {
+/**
+* The workflow for the tools this key has, and what its writes reach.
+*/ const serverInstructions = (scope) => {
 	const enabled = new Set(BUILTIN_TOOLS.filter((tool) => isToolEnabled(tool, scope)).map((tool) => tool.name));
 	const steps = WORKFLOW.flatMap(({ tools, does }) => {
 		const present = tools.filter((name) => enabled.has(name));

package/dist/guards.mjs

@@ -1,5 +1,7 @@
 //#region src/guards.ts
 const isPlainObject = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
-/** An own property only, so a client-chosen key never reads the prototype. */ const ownValue = (record, key) => record !== void 0 && Object.hasOwn(record, key) ? record[key] : void 0;
+/**
+* An own property only, so a client-chosen key never reads the prototype.
+*/ const ownValue = (record, key) => record !== void 0 && Object.hasOwn(record, key) ? record[key] : void 0;
 //#endregion
 export { isPlainObject, ownValue };

package/dist/i18n.mjs

@@ -21,7 +21,9 @@ const pick = (record, language) => {
 	return pick(record, language.language) ?? pick(record, language.fallbackLanguage) ?? Object.values(record).find((entry) => entry.trim() !== "");
 };
 const translatorFor = (i18n) => (value) => translateStatic(value, i18n);
-/** For callers with no request. Both languages miss, so the first entry wins. */ const translateAny = translatorFor({
+/**
+* For callers with no request. Both languages miss, so the first entry wins.
+*/ const translateAny = translatorFor({
 	fallbackLanguage: "",
 	language: ""
 });

package/dist/options.mjs

@@ -12,7 +12,9 @@ const TOOL_NAME_PATTERN = /^[a-zA-Z][a-zA-Z0-9]*$/;
 const fail = (message) => {
 	throw new InvalidConfiguration(`[payloadcms-mcpx] ${message}`);
 };
-/** The same transform the stock MCP plugin uses to derive field names. */ const toCamelCase = (value) => value.replace(/[-_\s]+(.)?/g, (_, char) => char ? char.toUpperCase() : "").replace(/^(.)/, (_, char) => char.toLowerCase());
+/**
+* The same transform the stock MCP plugin uses to derive field names.
+*/ const toCamelCase = (value) => value.replace(/[-_\s]+(.)?/g, (_, char) => char ? char.toUpperCase() : "").replace(/^(.)/, (_, char) => char.toLowerCase());
 const assertExposable = (collection, apiKeysSlug) => {
 	const { slug } = collection;
 	if (slug === apiKeysSlug || slug.startsWith("payload-")) fail(`Collection "${slug}" cannot be exposed.`);
@@ -21,8 +23,7 @@ const assertExposable = (collection, apiKeysSlug) => {
 const OPTION_NAMES = [
 	"read",
 	"write",
-	"publish",
-	"versions"
+	"publish"
 ];
 const REMOVED_WRITE_MODES = {
 	draft: "Use { publish: false } instead.",
@@ -47,18 +48,15 @@ const normalizeCapabilities = (kind, config, raw) => {
 	const read = flag("read") ?? true;
 	const write = flag("write") ?? true;
 	const publish = flag("publish");
-	const versions = flag("versions") ?? false;
 	const hasDrafts = hasDraftsEnabled(config);
 	if (publish === false && write && !hasDrafts) fail(`${kind} "${slug}" has no drafts, so every write goes live. Set write: false or remove publish: false.`);
 	if (publish === true && !hasDrafts) fail(`${kind} "${slug}" has no drafts, so there is nothing to publish. Enable versions.drafts or remove publish: true.`);
 	if (publish === true && !write) fail(`${kind} "${slug}" has publish: true but write: false. Publishing follows write.`);
-	if (versions && !config.versions) fail(`${kind} "${slug}" keeps no versions. Enable versions or remove versions: true.`);
-	if (versions && !read) fail(`${kind} "${slug}" has versions: true but read: false. Version history follows read.`);
 	return {
 		read,
 		write: write ? publish === false ? "draft" : "live" : false,
 		hasDrafts,
-		hasVersions: versions
+		hasVersions: read && Boolean(config.versions)
 	};
 };
 const assertGlobalExposable = (global) => {
@@ -131,7 +129,9 @@ const normalizeLimits = (limits) => {
 		maxDepth
 	};
 };
-/** Every problem is an `InvalidConfiguration`, so it fails at startup. */ const normalizeOptions = (config, options) => {
+/**
+* Every problem is an `InvalidConfiguration`, so it fails at startup.
+*/ const normalizeOptions = (config, options) => {
 	const apiKeysSlug = options.apiKeys?.slug ?? DEFAULT_API_KEYS_SLUG;
 	const userCollection = options.userCollection ?? config.admin?.user ?? "users";
 	if ((config.collections ?? []).some((c) => c.slug === apiKeysSlug)) fail(`API key collection slug "${apiKeysSlug}" is already taken.`);

package/dist/schema/lexical.mjs

@@ -11,7 +11,9 @@ const LEXICAL_CORE_NODES = [
 const OPAQUE_NODE_TYPES = /* @__PURE__ */ new Set(["upload"]);
 const subSchemaCache = /* @__PURE__ */ new WeakMap();
 const featuresOf = (field) => field.editor?.editorConfig?.features;
-/** Editors other than Lexical report only the core nodes. */ const allowedNodeTypes = (field) => {
+/**
+* Editors other than Lexical report only the core nodes.
+*/ const allowedNodeTypes = (field) => {
 	const registered = (featuresOf(field)?.nodes ?? []).flatMap((entry) => {
 		const type = entry.node?.getType?.();
 		return type ? [type] : [];
@@ -41,7 +43,9 @@ const lexicalSubSchema = (field, nodeType) => {
 	if (!cached.has(nodeType)) cached.set(nodeType, resolveSubSchema(field, nodeType));
 	return cached.get(nodeType) ?? void 0;
 };
-/** In the order their features registered them. */ const subSchemaNodeTypes = (field) => [...featuresOf(field)?.getSubFields?.keys() ?? []].filter((nodeType) => lexicalSubSchema(field, nodeType) !== void 0);
+/**
+* In the order their features registered them.
+*/ const subSchemaNodeTypes = (field) => [...featuresOf(field)?.getSubFields?.keys() ?? []].filter((nodeType) => lexicalSubSchema(field, nodeType) !== void 0);
 const KINDS = {
 	array: {
 		accepts: (value) => Array.isArray(value),

package/dist/schema/path.mjs

@@ -1,7 +1,11 @@
 //#region src/schema/path.ts
 const JSON_POINTER_PATTERN = /^(\/([^~/]|~[01])*)*$/;
-/** No segments is the root pointer, `""`. */ const joinPath = (parts) => parts.map((part) => `/${part.replace(/~/g, "~0").replace(/\//g, "~1")}`).join("");
-/** Unescapes `~1` and `~0`. The root pointer yields no segments. */ const splitPath = (path) => path.split("/").slice(1).map((segment) => segment.replace(/~1/g, "/").replace(/~0/g, "~"));
+/**
+* No segments is the root pointer, `""`.
+*/ const joinPath = (parts) => parts.map((part) => `/${part.replace(/~/g, "~0").replace(/\//g, "~1")}`).join("");
+/**
+* Unescapes `~1` and `~0`. The root pointer yields no segments.
+*/ const splitPath = (path) => path.split("/").slice(1).map((segment) => segment.replace(/~1/g, "/").replace(/~0/g, "~"));
 const PROTOTYPE_SEGMENTS = /* @__PURE__ */ new Set([
 	"__proto__",
 	"constructor",
@@ -12,7 +16,9 @@ const PROTOTYPE_SEGMENTS = /* @__PURE__ */ new Set([
 * intermediate tokens but writes them as a final key, so a pointer containing
 * one is refused before anything resolves it.
 */ const prototypeSegmentProblem = (pointer) => splitPath(pointer).some((segment) => PROTOTYPE_SEGMENTS.has(segment)) ? `"${pointer}" contains a segment named __proto__, constructor or prototype, which no field or node property uses.` : void 0;
-/** `-` included, since RFC 6901 reads it as the position after the last. */ const isIndexSegment = (segment) => segment === "-" || /^\d+$/.test(segment);
+/**
+* `-` included, since RFC 6901 reads it as the position after the last.
+*/ const isIndexSegment = (segment) => segment === "-" || /^\d+$/.test(segment);
 /**
 * A path Payload reports on a validation error (`layout.0.title`) as a JSON
 * Pointer, so everything handed back addresses documents the same way. The

package/dist/schema/shape.mjs

@@ -220,7 +220,7 @@ const checkValue = (scope, value) => {
 		}, entry);
 	}
 };
-/** Shape problems with a value about to be written at a resolved pointer. */ const validateWriteValue = (config, target, value) => {
+const validateWriteValue = (config, target, value) => {
 	const problems = [];
 	const scope = {
 		config,

package/dist/schema/walk.mjs

@@ -10,12 +10,17 @@ const RESERVED_FIELD_NAMES = /* @__PURE__ */ new Set([
 	"id",
 	"updatedAt"
 ]);
-/** The keys a row carries beside its fields. */ const ROW_KEYS = /* @__PURE__ */ new Set([
+/**
+* The keys a row carries beside its fields.
+*/ const ROW_KEYS = /* @__PURE__ */ new Set([
 	"blockName",
 	"blockType",
 	"id"
 ]);
-/** On a flattened field, whichever of `blockReferences` and `blocks` was declared. */ const blockSlugsOf = (field) => [...new Set((field.blockReferences ?? field.blocks).map((block) => typeof block === "string" ? block : block.slug))];
+/**
+* On a flattened field, whichever of `blockReferences` and `blocks` was
+* declared.
+*/ const blockSlugsOf = (field) => [...new Set((field.blockReferences ?? field.blocks).map((block) => typeof block === "string" ? block : block.slug))];
 /**
 * An inlined definition wins over the registry (`config.blocks`). A block's own
 * fields are identical wherever it appears, but the blocks its children accept
@@ -101,7 +106,10 @@ const isInformative = (descriptor) => descriptor.description !== void 0 || descr
 * against a document needs. Containers are left out, since only
 * {@link nodeDescriber} reports one.
 */ const describeAddressableFields = (fields) => describeFields(fields).filter((descriptor) => !isContainer(descriptor));
-/** The addressable descriptors under `prefix`, with their paths split relative to it. */ const descriptorsUnder = (fields, prefix) => describeAddressableFields(fields).flatMap((descriptor) => {
+/**
+* The addressable descriptors under `prefix`, with their paths split relative
+* to it.
+*/ const descriptorsUnder = (fields, prefix) => describeAddressableFields(fields).flatMap((descriptor) => {
 	const parts = splitPath(descriptor.path);
 	return prefix.every((part, offset) => part === parts[offset]) ? [{
 		descriptor,

package/dist/tools/create-document.mjs

@@ -3,8 +3,8 @@ import { errorResult, jsonResult } from "../result.mjs";
 import { validateWriteValue } from "../schema/shape.mjs";
 import "../schema/index.mjs";
 import { liveWriteSentence, localeOf, localeShape, patchOnlySlugs, slugEnum, slugsFor } from "./shared.mjs";
-import { readDraft, resolveEntity } from "./document.mjs";
 import { collectPublishBlockers } from "../write/publish-blockers.mjs";
+import { readDraft, resolveEntity } from "./document.mjs";
 import { stripRowIds } from "../write/row-ids.mjs";
 import { z } from "zod";
 //#region src/tools/create-document.ts

package/dist/tools/document.mjs

@@ -1,5 +1,6 @@
 import { errorResult } from "../result.mjs";
 import { slugsFor } from "./shared.mjs";
+import { collectPublishBlockers } from "../write/publish-blockers.mjs";
 import { APIError, Forbidden, NotFound } from "payload";
 //#region src/tools/document.ts
 /**
@@ -45,9 +46,13 @@ import { APIError, Forbidden, NotFound } from "payload";
 		id: args.id
 	};
 };
-/** What a response names its subject by: a document's id, or a global's slug. */ const identityOf = (target, id) => target.kind === "collection" ? { id } : { global: target.slug };
+/**
+* What a response names its subject by: a document's id, or a global's slug.
+*/ const identityOf = (target, id) => target.kind === "collection" ? { id } : { global: target.slug };
 const sameInstant = (left, right) => (typeof left === "string" || left instanceof Date) && new Date(left).getTime() === new Date(right).getTime();
-/** Refuses a write when the document changed since the client read it. */ const staleReadResult = (doc, expectedUpdatedAt, message) => expectedUpdatedAt !== void 0 && !sameInstant(doc["updatedAt"], expectedUpdatedAt) ? errorResult(message, { updatedAt: doc["updatedAt"] }) : void 0;
+/**
+* Refuses a write when the document changed since the client read it.
+*/ const staleReadResult = (doc, expectedUpdatedAt, message) => expectedUpdatedAt !== void 0 && !sameInstant(doc["updatedAt"], expectedUpdatedAt) ? errorResult(message, { updatedAt: doc["updatedAt"] }) : void 0;
 /**
 * Reads the current draft in a fixed locale with no fallback, which is the
 * shape that may be written back or validated without mixing locales.
@@ -80,5 +85,40 @@ const sameInstant = (left, right) => (typeof left === "string" || left instanceo
 		slug: args.target.slug
 	});
 };
+/**
+* {@link collectPublishBlockers} over the draft of each locale, each blocker
+* tagged with its locale. Locales run in turn because hooks share `req`, and
+* the request's locale and fallback locale are restored afterwards.
+*/ const collectLocaleBlockers = async (scope, target, locales) => {
+	const { req } = scope;
+	const { fallbackLocale, locale: requestLocale } = req;
+	const blockers = [];
+	let unavailable = false;
+	for (const locale of locales) try {
+		const doc = await readDraft(scope, {
+			target,
+			locale,
+			privileged: true
+		});
+		const result = await collectPublishBlockers(req, {
+			doc,
+			entity: target
+		});
+		unavailable ||= result.unavailable === true;
+		blockers.push(...result.blockers.map((entry) => ({
+			...entry,
+			locale
+		})));
+	} catch (error) {
+		req.payload.logger.warn(`[payloadcms-mcpx] Could not read the ${target.slug} draft in ${locale}: ${error instanceof Error ? error.message : "unknown error"}`);
+		unavailable = true;
+	}
+	if (requestLocale !== void 0) req.locale = requestLocale;
+	if (fallbackLocale !== void 0) req.fallbackLocale = fallbackLocale;
+	return {
+		blockers,
+		...unavailable ? { unavailable: true } : {}
+	};
+};
 //#endregion
-export { identityOf, readDraft, resolveDocument, resolveEntity, staleReadResult };
+export { collectLocaleBlockers, identityOf, readDraft, resolveDocument, resolveEntity, staleReadResult };

package/dist/tools/find-versions.mjs

@@ -16,8 +16,8 @@ const statusShape = (scope) => {
 /**
 * Bodies are left out so a long history stays small; `getDocument` reads one
 * when it is needed. The document's `read` access is checked first, then
-* Payload's `readVersions`. Only entities with `versions: true` in the plugin
-* options are reachable.
+* Payload's `readVersions`. Only entities that keep Payload versions are
+* reachable.
 */ const findVersions = defineMcpxTool({
 	name: "findVersions",
 	description: DESCRIPTION,

package/dist/tools/patch-document.mjs

@@ -4,8 +4,8 @@ import { errorResult, jsonResult } from "../result.mjs";
 import { JSON_POINTER_PATTERN } from "../schema/path.mjs";
 import "../schema/index.mjs";
 import { entityShape, idShape, liveWriteSentence, localeOf, localeShape } from "./shared.mjs";
-import { identityOf, readDraft, resolveDocument, staleReadResult } from "./document.mjs";
 import { collectPublishBlockers } from "../write/publish-blockers.mjs";
+import { identityOf, readDraft, resolveDocument, staleReadResult } from "./document.mjs";
 import { applyPatchOperations, isElementPointer } from "../write/patch.mjs";
 import { withTransaction } from "../write/transaction.mjs";
 import { buildWriteData } from "../write/write-data.mjs";
@@ -24,7 +24,9 @@ In a rich text field a pointer continues into the rich text state: "/content/roo
 The response carries "updatedAt" and, if any, "publishBlockers": what must be fixed before publishing. "publishBlockersUnavailable" means that check failed. The write stands either way. "notApplied" lists pointers whose value did not change or cannot be read back, for example where field access denies the update.`;
 const POINTER = z.string().regex(JSON_POINTER_PATTERN);
 const PATCHES_LIMIT = 500;
-/** Discriminated on `op`, so an operation carries only its own members. */ const PATCH_OPERATION_SCHEMA = z.discriminatedUnion("op", [
+/**
+* Discriminated on `op`, so an operation carries only its own members.
+*/ const PATCH_OPERATION_SCHEMA = z.discriminatedUnion("op", [
 	z.strictObject({
 		op: z.literal("add"),
 		path: POINTER,

package/dist/tools/publish-document.mjs

@@ -1,17 +1,16 @@
 import { defineMcpxTool } from "../define-tool.mjs";
 import { jsonResult } from "../result.mjs";
-import { entityShape, idShape, localeOf } from "./shared.mjs";
-import { identityOf, readDraft, resolveDocument, staleReadResult } from "./document.mjs";
+import { entityShape, idShape, localeOf, localeShape } from "./shared.mjs";
+import { collectLocaleBlockers, identityOf, readDraft, resolveDocument, staleReadResult } from "./document.mjs";
 import { withTransaction } from "../write/transaction.mjs";
 import { withPublishIntent } from "../write/publish-intent.mjs";
 import { z } from "zod";
 /**
-* Publishes a draft. Available where the config exposes
-* `publish` on an entity with drafts and the key has both the `write` and
-* `publish` checkboxes.
+* Publishes a draft. Available where the config exposes `publish` on an entity
+* with drafts and the key has both the `write` and `publish` checkboxes.
 */ const publishDocument = defineMcpxTool({
 	name: "publishDocument",
-	description: `Makes the current draft of one document or global public. A draft with publish blockers is refused, so call validateDocument first. Publishing validates one locale only, normally the default, so a required field left empty in another locale goes live empty. Run validateDocument for each locale. There is no unpublish. A person takes content offline in the admin panel.`,
+	description: `Makes the current draft of one document or global public, in every locale or only in "locale". A scoped publish keeps the other locales of localized fields as last published, and a never-published document goes live in full. A draft with publish blockers is refused, so call validateDocument first. Payload checks only the published locale, so "otherLocaleBlockers" lists what other locales still lack. There is no unpublish.`,
 	annotations: {
 		destructiveHint: true,
 		openWorldHint: false
@@ -20,12 +19,14 @@ import { z } from "zod";
 	inputSchema: (scope) => ({
 		...entityShape(scope, "publish"),
 		...idShape(scope, "publish"),
+		...localeShape(scope, { required: false }),
 		expectedUpdatedAt: z.string().optional().describe("\"updatedAt\" from your last read. Refused if the document changed since.")
 	}),
 	handler: async ({ args, scope }) => {
 		const target = resolveDocument(scope, args, "publish");
 		const { payload } = scope.req;
-		const locale = localeOf(scope, void 0);
+		const locale = localeOf(scope, args.locale);
+		const { localization } = scope;
 		return await withTransaction(scope.req, async () => {
 			const doc = await readDraft(scope, {
 				target,
@@ -40,7 +41,8 @@ import { z } from "zod";
 				fallbackLocale: false,
 				overrideAccess: false,
 				req: scope.req,
-				...locale === void 0 ? {} : { locale }
+				...locale === void 0 ? {} : { locale },
+				...args.locale === void 0 ? {} : { publishSpecificLocale: args.locale }
 			};
 			if (target.kind === "collection") await payload.update({
 				...write,
@@ -56,10 +58,13 @@ import { z } from "zod";
 				locale,
 				privileged: true
 			});
+			const others = await collectLocaleBlockers(scope, target, localization?.locales.filter((entry) => entry !== locale) ?? []);
 			return jsonResult({
 				...identityOf(target, saved["id"]),
 				status: saved["_status"],
-				updatedAt: saved["updatedAt"]
+				updatedAt: saved["updatedAt"],
+				...others.blockers.length > 0 ? { otherLocaleBlockers: others.blockers } : {},
+				...others.unavailable ? { otherLocaleBlockersUnavailable: true } : {}
 			});
 		});
 	}

package/dist/tools/query-paths.mjs

@@ -8,7 +8,9 @@ import { APIError, getLocalizedPaths } from "payload";
 * them: `and` and `or` (any case) hold arrays of clauses, every other key is a
 * path.
 */ const wherePaths = (where) => isPlainObject(where) ? Object.entries(where).flatMap(([key, clause]) => ["and", "or"].includes(key.toLowerCase()) && Array.isArray(clause) ? clause.flatMap(wherePaths) : [key]) : [];
-/** The paths of a `sort`: a field name, `-` for descending, comma separated. */ const sortPaths = (sort) => (sort ?? "").split(",").map((entry) => entry.trim().replace(/^-/, "")).filter(Boolean);
+/**
+* The paths of a `sort`: a field name, `-` for descending, comma separated.
+*/ const sortPaths = (sort) => (sort ?? "").split(",").map((entry) => entry.trim().replace(/^-/, "")).filter(Boolean);
 const normalise = (path) => path === "_id" ? "id" : path.replaceAll("__", ".");
 const isRefusedPath = (scope, args, seen = /* @__PURE__ */ new Set()) => {
 	const key = `${args.collection}:${args.path}`;

package/dist/tools/shared.mjs

@@ -5,7 +5,9 @@ import { z } from "zod";
 * An out-of-scope slug fails schema validation before a handler runs, so a
 * client only ever sees what its key may touch.
 */ const slugEnum = (slugs) => z.enum(slugs);
-/** Payload's id type follows the adapter, so both forms are handed on as read. */ const idSchema = z.union([z.string(), z.number()]);
+/**
+* Payload's id type follows the adapter, so both forms are handed on as read.
+*/ const idSchema = z.union([z.string(), z.number()]);
 const slugsOf = (scope, key) => ({
 	collections: scope.collections[key],
 	globals: scope.globals[key]
@@ -22,7 +24,9 @@ const slugsWhere = (scope, predicate, allowed) => {
 	globals: []
 });
 const widen = (branch) => branch;
-/** The one list the shape helpers and {@link resolveEntity} both read. */ const slugsFor = (scope, operation) => {
+/**
+* The one list the shape helpers and {@link resolveEntity} both read.
+*/ const slugsFor = (scope, operation) => {
 	switch (operation) {
 		case "create": return {
 			collections: slugsWhere(scope, canCreate, {
@@ -62,7 +66,10 @@ const widen = (branch) => branch;
 		})
 	};
 };
-/** Slugs reachable by `operation` whose writes go live, because they have no draft to write. */ const liveWriteSlugs = (scope, operation) => slugsWhere(scope, isLiveWrite, slugsFor(scope, operation));
+/**
+* Slugs reachable by `operation` whose writes go live, because they have no
+* draft to write.
+*/ const liveWriteSlugs = (scope, operation) => slugsWhere(scope, isLiveWrite, slugsFor(scope, operation));
 /**
 * Stated on the tools that write, since a client calling them must know before
 * the call which writes are public.
@@ -72,7 +79,7 @@ const widen = (branch) => branch;
 };
 /**
 * With no reachable global, `global` is left out and `collection` stays
-* required, so a deployment without globals sees an unchanged schema. Only the
+* required, so a deployment without globals gets no extra argument. Only the
 * mixed case makes either optional, and the handler enforces exclusivity there.
 * `globalRule` states that rule on `global` for a tool without an `id`.
 */ const entityShape = (scope, operation, globalRule) => {
@@ -94,7 +101,9 @@ const widen = (branch) => branch;
 	if (globals.length === 0) return widen({ id: idSchema });
 	return widen({ id: idSchema.optional().describe("Required with \"collection\", omitted with \"global\".") });
 };
-/** For the reads that fall back to the default locale, unlike the writes. */ const READ_LOCALE_DESCRIPTION = "Default: the default locale. A value missing in this locale is shown from the default locale.";
+/**
+* For the reads that fall back to the default locale, unlike the writes.
+*/ const READ_LOCALE_DESCRIPTION = "Default: the default locale. A value missing in this locale is shown from the default locale.";
 const localeShape = (scope, options) => {
 	if (!scope.localization) return widen({});
 	const enumerated = z.enum(scope.localization.locales);

package/dist/tools/validate-document.mjs

@@ -1,8 +1,8 @@
 import { defineMcpxTool } from "../define-tool.mjs";
 import { jsonResult } from "../result.mjs";
 import { entityShape, idShape, localeOf, localeShape } from "./shared.mjs";
-import { identityOf, readDraft, resolveDocument } from "./document.mjs";
 import { collectPublishBlockers } from "../write/publish-blockers.mjs";
+import { collectLocaleBlockers, identityOf, readDraft, resolveDocument } from "./document.mjs";
 /**
 * Gated on write rather than read, because publish blockers only mean something
 * to a caller who can act on them.
@@ -13,16 +13,17 @@ import { collectPublishBlockers } from "../write/publish-blockers.mjs";
 * the traversal fires field hooks.
 */ const validateDocument = defineMcpxTool({
 	name: "validateDocument",
-	description: `Lists what still blocks publishing one document or global, without saving. Returns "publishBlockers", each with a pointer and a message. An empty list means it can be published, unless "publishBlockersUnavailable" is true: then the check itself failed. The check runs the field hooks a save runs.`,
+	description: `Lists what still blocks publishing one document or global, without saving. Checks one locale when "locale" is given, otherwise every locale. Returns "publishBlockers", each with a pointer and a message, and a "locale" when every locale was checked. An empty list means it can be published, unless "publishBlockersUnavailable" is true: then the check itself failed. The check runs the field hooks a save runs.`,
 	annotations: { openWorldHint: false },
 	isEnabled: (scope) => scope.collections.writable.length + scope.globals.writable.length > 0,
 	inputSchema: (scope) => ({
 		...entityShape(scope, "write"),
 		...idShape(scope, "write"),
-		...localeShape(scope, { required: true })
+		...localeShape(scope, { required: false })
 	}),
 	handler: async ({ args, scope }) => {
 		const target = resolveDocument(scope, args, "write");
+		const { localization } = scope;
 		const locale = localeOf(scope, args.locale);
 		await readDraft(scope, {
 			target,
@@ -33,7 +34,7 @@ import { collectPublishBlockers } from "../write/publish-blockers.mjs";
 			locale,
 			privileged: true
 		});
-		const validation = await collectPublishBlockers(scope.req, {
+		const validation = localization && args.locale === void 0 ? await collectLocaleBlockers(scope, target, localization.locales) : await collectPublishBlockers(scope.req, {
 			doc,
 			entity: target
 		});

package/dist/tools/versions.mjs

@@ -12,7 +12,10 @@ const NOISE = [
 	"_status"
 ];
 const NEWEST_FIRST = ["-updatedAt", "-id"];
-/** The document or global as the key's user sees it, without `admin.hidden` fields. */ const readLive = async (scope, read, options) => {
+/**
+* The document or global as the key's user sees it, without `admin.hidden`
+* fields.
+*/ const readLive = async (scope, read, options) => {
 	const shared = {
 		depth: read.depth,
 		draft: options.draft,
@@ -44,7 +47,9 @@ const assertReadable = async (scope, read) => {
 		select: {}
 	});
 };
-/** `parent` comes back as a raw id or, populated, as the document itself. */ const isVersionOf = (version, id) => {
+/**
+* `parent` comes back as a raw id or, populated, as the document itself.
+*/ const isVersionOf = (version, id) => {
 	const parent = version["parent"];
 	const parentId = typeof parent === "object" && parent !== null ? parent["id"] : parent;
 	return (typeof parentId === "string" || typeof parentId === "number") && String(parentId) === String(id);
@@ -76,7 +81,9 @@ const assertReadable = async (scope, read) => {
 	if (read.target.kind === "collection" && !isVersionOf(version, read.target.id)) return null;
 	return withoutHidden(scope, read, version);
 };
-/** One page of a document's or global's history, newest first. */ const queryVersions = async (scope, read, options) => {
+/**
+* One page of a document's or global's history, newest first.
+*/ const queryVersions = async (scope, read, options) => {
 	await assertReadable(scope, read);
 	const where = {
 		...read.target.kind === "collection" ? { parent: { equals: read.target.id } } : {},
@@ -100,7 +107,9 @@ const assertReadable = async (scope, read) => {
 		slug: read.target.slug
 	}));
 };
-/** The newest version whose status is published, or `null` if none is. */ const loadPublished = async (scope, read) => {
+/**
+* The newest version whose status is published, or `null` if none is.
+*/ const loadPublished = async (scope, read) => {
 	if (!hasDraftsEnabled(read.target.config)) return null;
 	const [newest] = (await queryVersions(scope, read, {
 		status: "published",

package/dist/types.d.mts

@@ -29,7 +29,9 @@ export type McpxWriteMode = "draft" | "live" | false;
  * shorthand for `{}`, which exposes everything the entity supports.
  */
 export interface McpxCollectionOptions {
-  /** Expose `describeSchema`, `findDocuments`, `getDocument`. Default `true`. */
+  /**
+   * Expose `describeSchema`, `findDocuments`, `getDocument`. Default `true`.
+   */
   read?: boolean;
   /**
    * Expose `patchDocument`, `validateDocument` and, unless this is an upload
@@ -43,46 +45,54 @@ export interface McpxCollectionOptions {
    * `false` keeps writes as drafts and is refused where there are none.
    */
   publish?: boolean;
-  /**
-   * Expose `findVersions` and the `versionId` and `diffFrom` arguments of
-   * `getDocument` to keys that may read the entity. Default `false`: version
-   * history has no checkbox of its own and follows the key's read, so the
-   * config opts in. `true` needs Payload `versions` and `read`.
-   */
-  versions?: boolean;
 }
-/** The same options. A singleton, so neither `findDocuments` nor `createDocument` reaches one. */
+/**
+ * The same options. A singleton, so neither `findDocuments` nor
+ * `createDocument` reaches one.
+ */
 export type McpxGlobalOptions = McpxCollectionOptions;
 export type McpxToolExtra = RequestHandlerExtra<ServerRequest, ServerNotification>;
-/** What the config exposes, before an API key's checkboxes narrow it. */
+/**
+ * What the config exposes, before an API key's checkboxes narrow it.
+ */
 export interface McpxExposedEntity {
   slug: string;
   read: boolean;
   write: McpxWriteMode;
   hasDrafts: boolean;
   /**
-   * Payload keeps a version history, with or without drafts, and the config
-   * exposes it. Says nothing about drafts; see `hasDrafts`.
+   * The entity has Payload `versions`, with or without drafts, and is
+   * readable. Says nothing about drafts; see `hasDrafts`.
    */
   hasVersions: boolean;
-  /** An upload document is a file, and no tool here can supply one. */
+  /**
+   * An upload document is a file, and no tool here can supply one.
+   */
   isUpload: boolean;
-  /** Name of the capability group on the key document. */
+  /**
+   * Name of the capability group on the key document.
+   */
   fieldName: string;
 }
-/** The slugs a key may read, write and publish. */
+/**
+ * The slugs a key may read, write and publish.
+ */
 export interface McpxScopeSlugs {
   readable: string[];
   writable: string[];
   publishable: string[];
 }
-/** What a tool knows about the current request. */
+/**
+ * What a tool knows about the current request.
+ */
 export interface McpxToolScope {
   req: PayloadRequest;
   capabilities: McpxResolvedCapabilities;
   collections: McpxScopeSlugs;
   globals: McpxScopeSlugs;
-  /** `null` when localization is off. */
+  /**
+   * `null` when localization is off.
+   */
   localization: null | {
     locales: string[];
     defaultLocale: string;
@@ -102,9 +112,13 @@ export interface McpxToolScope {
  * per request, leaving no static shape to infer from.
  */
 export interface McpxTool<Shape extends z.ZodRawShape = z.ZodRawShape, Args = z.infer<z.ZodObject<Shape>>> {
-  /** camelCase, unique, not one of the builtin tool names. */
+  /**
+   * camelCase, unique, not one of the builtin tool names.
+   */
   name: string;
-  /** Built per request so it can state what this key's writes do. */
+  /**
+   * Built per request so it can state what this key's writes do.
+   */
   description: string | ((scope: McpxToolScope) => string);
   annotations?: ToolAnnotations;
   /**
@@ -122,18 +136,26 @@ export interface McpxTool<Shape extends z.ZodRawShape = z.ZodRawShape, Args = z.
   handler(ctx: {
     args: Args;
     scope: McpxToolScope;
-    /** Shorthand for `scope.req`. */
+    /**
+     * Shorthand for `scope.req`.
+     */
     req: PayloadRequest;
     extra: McpxToolExtra;
   }): CallToolResult | Promise<CallToolResult>;
 }
-/** Argument type erased, so a registry can hold tools of differing shapes. */
+/**
+ * Argument type erased, so a registry can hold tools of differing shapes.
+ */
 export type McpxAnyTool = McpxTool<z.ZodRawShape, never>;
 export interface McpxAuthResult {
-  /** Must carry `collection`. */
+  /**
+   * Must carry `collection`.
+   */
   user: TypedUser;
   apiKeyId: DocumentId;
-  /** The `capabilities` group as stored on the key document. */
+  /**
+   * The `capabilities` group as stored on the key document.
+   */
   capabilities: unknown;
 }
 /**
@@ -143,31 +165,47 @@ export interface McpxAuthResult {
  * to `Record<string, unknown>`, which interfaces do not satisfy.
  */
 export type McpxPluginOptions = {
-  /** Allow-list of collections. `true` is shorthand for `{}`. */
+  /**
+   * Allow-list of collections. `true` is shorthand for `{}`.
+   */
   collections: Partial<Record<CollectionSlug, McpxCollectionOptions | true>>;
-  /** Allow-list of globals. `true` is shorthand for `{}`. */
+  /**
+   * Allow-list of globals. `true` is shorthand for `{}`.
+   */
   globals?: Partial<Record<GlobalSlug, McpxGlobalOptions | true>>;
-  /** Collection the keys act as. Default `config.admin.user`, then `users`. */
+  /**
+   * Collection the keys act as. Default `config.admin.user`, then `users`.
+   */
   userCollection?: CollectionSlug;
   apiKeys?: {
-    /** Slug of the generated API key collection. Default `mcpx-api-keys`. */
+    /**
+     * Slug of the generated API key collection. Default `mcpx-api-keys`.
+     */
     slug?: string;
     /**
      * Add a "Connect a client" tab to saved keys, holding ready-to-paste MCP
      * client config. Default `true`. The snippets contain the key in full.
      */
     setupGuide?: boolean;
-    /** Final override applied to the generated collection. */
+    /**
+     * Final override applied to the generated collection.
+     */
     overrideCollection?: (collection: CollectionConfig) => CollectionConfig;
   };
   endpoint?: {
-    /** Endpoint path below the API route. Default `/mcpx`. */
+    /**
+     * Endpoint path below the API route. Default `/mcpx`.
+     */
     path?: string;
   };
   limits?: {
-    /** Upper bound for `findDocuments.limit`. Default 25. */
+    /**
+     * Upper bound for `findDocuments.limit`. Default 25.
+     */
     maxLimit?: number;
-    /** Upper bound for `depth` on reads. Default 1. */
+    /**
+     * Upper bound for `depth` on reads. Default 1.
+     */
     maxDepth?: number;
   };
   tools?: McpxAnyTool[];
@@ -187,20 +225,28 @@ export type McpxPluginOptions = {
     version?: string;
   };
 };
-/** What a key may do with one entity. Globals reuse this shape. */
+/**
+ * What a key may do with one entity. Globals reuse this shape.
+ */
 export interface McpxCollectionCapabilities {
   read: boolean;
   write: boolean;
-  /** Only ever true where the config lets writes publish and drafts exist. */
+  /**
+   * Only ever true where the config lets writes publish and drafts exist.
+   */
   publish: boolean;
 }
-/** In force for one request: the plugin config and the key checkboxes together. */
+/**
+ * In force for one request: the plugin config and the key checkboxes together.
+ */
 export interface McpxResolvedCapabilities {
   collections: Record<string, McpxCollectionCapabilities>;
   globals: Record<string, McpxCollectionCapabilities>;
   tools: Record<string, boolean>;
 }
-/** Stamped on `req.context.mcpx`; see {@link isMcpxRequest}. */
+/**
+ * Stamped on `req.context.mcpx`; see {@link isMcpxRequest}.
+ */
 export interface McpxRequestContext {
   apiKeyId: DocumentId;
   capabilities: McpxResolvedCapabilities;

package/dist/write/draft-guard.mjs

@@ -6,14 +6,13 @@ import { hasDraftsEnabled } from "payload/shared";
 const STRIPPED_ARGS = /* @__PURE__ */ new Set([
 	"where",
 	"publishAllLocales",
-	"publishSpecificLocale",
 	"unpublishAllLocales",
 	"duplicateFromID",
 	"selectedLocales",
 	"overwriteExistingFiles"
 ]);
 const scrubWriteArgs = (args, publishing) => {
-	const next = Object.fromEntries(Object.entries(args).filter(([key]) => !STRIPPED_ARGS.has(key)));
+	const next = Object.fromEntries(Object.entries(args).filter(([key]) => !STRIPPED_ARGS.has(key) && (publishing || key !== "publishSpecificLocale")));
 	if (next["data"] && typeof next["data"] === "object") {
 		const { _status: _ignoredStatus, deletedAt: _ignoredDeletedAt, ...data } = next["data"];
 		next["data"] = publishing ? {
@@ -34,17 +33,20 @@ const forceDraftWrite = (hookArgs) => {
 	return scrubWriteArgs(args, publishing);
 };
 /**
-* The global counterpart of {@link forceDraftWrite}. `updateGlobal` destructures
-* `draft` and the publish arguments before it runs `beforeOperation` and
-* re-reads only `data` afterwards, so setting them here has no effect. Only
-* `data` with `_status` stripped lands, so {@link refusePublishGlobal} is what
-* enforces the guard. `publishDocument` therefore passes `draft: false` at the
-* call site, and this hook restores `_status` instead of stripping it.
+* The global counterpart of {@link forceDraftWrite}. `updateGlobal` reads
+* `draft` and the publish arguments before this hook runs, so only changes to
+* `data` take effect. A write to a global with drafts that did not ask for a
+* draft save is therefore refused here, and `_status` is restored for a publish.
 */ const forceDraftWriteGlobal = (hookArgs) => {
-	const { operation, req } = hookArgs;
+	const { global, operation, req } = hookArgs;
 	const args = hookArgs.args;
 	if (!isMcpxRequest(req) || operation !== "update") return args;
-	return scrubWriteArgs(args, hasPublishIntent(args["data"]));
+	const publishing = hasPublishIntent(args["data"]);
+	if (!publishing && args["draft"] !== true && hasDraftsEnabled(global)) {
+		req.payload.logger.warn(`[payloadcms-mcpx] Refused a write to ${global.slug} that did not ask for a draft save.`);
+		throw new APIError("MCP clients may only write drafts. This write was refused because it would not have been saved as one. Use publishDocument to publish.", 403);
+	}
+	return scrubWriteArgs(args, publishing);
 };
 const refuseUnlessExpected = (req, slug, data) => {
 	const publishing = takePublishIntent(data);

package/dist/write/publish-intent.mjs

@@ -8,7 +8,9 @@ const withPublishIntent = (data) => ({
 	[PUBLISH_INTENT]: TOKEN
 });
 const hasPublishIntent = (data) => isPlainObject(data) && data[PUBLISH_INTENT] === TOKEN;
-/** Called by the last hook that needs the marker, which removes it. */ const takePublishIntent = (data) => {
+/**
+* Called by the last hook that needs the marker, which removes it.
+*/ const takePublishIntent = (data) => {
 	if (!hasPublishIntent(data)) return false;
 	delete data[PUBLISH_INTENT];
 	return true;

package/dist/write/row-ids.mjs

@@ -33,7 +33,9 @@ const walkRows = (value, visit, isRow = false) => {
 		delete row["id"];
 	});
 };
-/** For create, where no stored row exists and any incoming id is invented. */ const stripRowIds = (value) => {
+/**
+* For create, where no stored row exists and any incoming id is invented.
+*/ const stripRowIds = (value) => {
 	const next = structuredClone(value);
 	walkRows(next, (row) => {
 		delete row["id"];

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "@abinnovision/payloadcms-mcpx",
-  "version": "2.0.0-beta.7",
+  "version": "2.0.0-beta.9",
   "description": "Payload CMS plugin exposing a fixed, schema-aware MCP tool surface with draft-only writes and per-API-key capabilities.",
   "keywords": [
     "payload",
@@ -65,6 +65,7 @@
     "@abinnovision/eslint-config-base": "^3.4.2",
     "@abinnovision/prettier-config": "^2.2.0",
     "@arethetypeswrong/core": "^0.18.5",
+    "@internal/test-utils": "0.0.0",
     "@payloadcms/db-sqlite": "3.89.0",
     "@payloadcms/richtext-lexical": "3.89.0",
     "@payloadcms/ui": "3.89.0",
@@ -101,4 +102,4 @@
     "npm": true,
     "npmAccess": "public"
   }
-}
+}