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

package/README.md

@@ -13,13 +13,14 @@ resolved server-side against the real config and the real document, so unknown
 fields, misplaced blocks and unusable rich text nodes or node fields are refused with the
 valid alternatives listed, never silently dropped.
 
-Writes are RFC 6902 patches that land as drafts, with `allowLiveWrites` as the
-one documented exception; publishing stays a human action in the admin panel.
-Every write returns the publish
-blockers: the validation failures that still prevent a human from publishing
-the draft. Capabilities are declared twice: the plugin config decides what
-can exist, a checkbox on each API key decides what does, and a missing checkbox
-means no (fail-closed).
+Writes are RFC 6902 patches that land as drafts. One config axis decides how far
+they reach: `write: "draft"` never changes live content, `write: "live"` does —
+by exposing `publishDocument` where versions exist, and by permitting the write
+at all where they do not. Every write returns the publish blockers: the
+validation failures that still prevent the draft from being published.
+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
 
@@ -44,12 +45,12 @@ export default buildConfig({
   plugins: [
     mcpxPlugin({
       collections: {
-        pages: { read: true, write: true },
-        posts: { read: true, write: true },
+        pages: { read: true, write: "live" }, // may be published through MCP
+        posts: { read: true, write: "draft" }, // drafts only
         tags: true, // shorthand for { read: true }
       },
       globals: {
-        "site-settings": { read: true, write: true },
+        "site-settings": { read: true, write: "draft" },
       },
       limits: { maxLimit: 25, maxDepth: 1 },
     }),
@@ -78,7 +79,10 @@ to anyone who may read the key document (own keys only, by default). Each key:
 - 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.
+  capability existed stay without it. The `publish` checkbox only exists where
+  a versioned entity is configured `write: "live"`, so a key issued before
+  publishing was possible stays closed to it, and it counts only alongside
+  `write`: publishing is an extension of writing, not a capability of its own.
 
 Keys authenticate only the MCP endpoint. They are deliberately not a Payload
 auth strategy, so a key can never authenticate the REST or GraphQL API; the
@@ -141,7 +145,7 @@ Claude Desktop (no direct HTTP header support) via `mcp-remote`:
 
 ## Tools
 
-The surface is fixed at seven tools plus your custom ones; exposing a global
+The surface is fixed at eight tools plus your custom ones; exposing a global
 adds an argument, never a tool. `tools/list` reflects the key: write tools
 disappear for read-only keys, and every `collection` and `global` enum contains
 only the slugs the key may touch.
@@ -155,6 +159,7 @@ only the slugs the key may touch.
 | `patchDocument`    | Apply RFC 6902 operations to the current draft.             | `collection` + `id` \| `global`, `locale`, `patches`, `expectedUpdatedAt?`                   |
 | `createDocument`   | Create a draft from a minimal seed.                         | `collection`, `locale`, `data`                                                               |
 | `validateDocument` | Publish blockers without saving anything.                   | `collection` + `id` \| `global`, `locale`                                                    |
+| `publishDocument`  | Publish the current draft.                                  | `collection` + `id` \| `global`, `expectedUpdatedAt?`                                        |
 
 Rules the tools enforce and explain in their own descriptions:
 
@@ -245,15 +250,40 @@ 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
+## Drafts and publishing
 
 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.
+refuses any write that would still not land as a draft.
+
+The two hooks are not equally load-bearing on both sides. `updateGlobal` reads
+`draft` and the publish arguments off its argument bag _before_ it runs
+`beforeOperation`, and re-reads only `data` afterwards, so for a global the
+correction cannot apply and the `beforeChange` refusal is what actually holds
+the line. Both are installed on every collection and global, exposed or not.
+
+`publishDocument` is the one way through, and it opens the door for exactly one
+operation: the tool records an intent naming the entity and id it is about to
+publish, in `AsyncLocalStorage` rather than on the request, and the guard
+consults it. A concurrent call in the same JSON-RPC batch runs in another async
+context and sees nothing, a nested write to a different document meets the
+unguarded rules, and the intent is claimed once so a re-entrant write to the
+same document cannot ride along. It is not a security boundary — a custom tool
+holds the whole `payload` instance — but no ordinary write can widen itself into
+a publish by accident.
+
+Publishing covers the whole document, as the admin Publish button does, but
+Payload only validates the locale the publish runs in. A required field left
+empty in another locale therefore goes live empty; that is Payload's behaviour,
+not something this plugin adds. `publishDocument` refuses a document that fails
+validation and reports `validationErrors` with JSON Pointers. It is refused
+while a human holds the document open in the admin panel, and republishing an
+unchanged document is accepted but writes another version.
+
+There is no unpublish tool. Reverting a published document to a draft stays a
+human action.
 
 Publish blockers are advisory. Payload skips validation on draft saves (unless
 `versions.drafts.validate` is set), so after every write the plugin re-runs
@@ -308,9 +338,9 @@ Custom tools take the same route as the builtins: one `McpxTool` shape, one
 registration loop. Anything a builtin does, a custom tool can do.
 
 `handler` receives `scope` alongside `args`, `req` and `extra`. The scope
-carries what the key may touch (`readable`, `writable`, `readableGlobals`,
-`writableGlobals`), the configured locales, the limits in force and the
-exposed collections and globals. `req` is shorthand for `scope.req`.
+carries what the key may touch (`readable`, `writable`, `publishable`,
+`readableGlobals`, `writableGlobals`, `publishableGlobals`), the configured
+locales, the limits in force and the exposed collections and globals. `req` is shorthand for `scope.req`.
 
 `inputSchema` may be a function of that scope instead of a fixed shape, which
 is how a tool narrows an enum to what the key may read:
@@ -363,35 +393,48 @@ results shaped like a builtin's.
 
 ## Options
 
-| Option                               | Default                        | Description                                                                                                        |
-| ------------------------------------ | ------------------------------ | ------------------------------------------------------------------------------------------------------------------ |
-| `collections`                        | required                       | Allow-list. `true` means `{ read: true }`.                                                                         |
-| `collections.<slug>.read`            | `true`                         | Expose `describeSchema`, `findDocuments`, `getDocument`.                                                           |
-| `collections.<slug>.write`           | `false`                        | Expose `patchDocument`, `createDocument`, `validateDocument`. Requires `versions.drafts` unless `allowLiveWrites`. |
-| `collections.<slug>.allowLiveWrites` | `false`                        | Permit writes to a collection without drafts (they land live).                                                     |
-| `globals`                            | `{}`                           | Allow-list of globals. `true` means `{ read: true }`.                                                              |
-| `globals.<slug>.read`                | `true`                         | Expose `describeSchema`, `getDocument`.                                                                            |
-| `globals.<slug>.write`               | `false`                        | Expose `patchDocument`, `validateDocument`. Requires `versions.drafts` unless `allowLiveWrites`.                   |
-| `globals.<slug>.allowLiveWrites`     | `false`                        | Permit writes to a global without drafts (they land live).                                                         |
-| `userCollection`                     | `config.admin.user` or `users` | Auth collection the keys act as.                                                                                   |
-| `apiKeys.slug`                       | `mcpx-api-keys`                | Slug of the generated key collection.                                                                              |
-| `apiKeys.setupGuide`                 | `true`                         | Add a "Connect a client" tab to saved keys. Needs the import map.                                                  |
-| `apiKeys.overrideCollection`         | none                           | Final override applied to the generated collection.                                                                |
-| `endpoint.path`                      | `/mcpx`                        | Endpoint path below the API route.                                                                                 |
-| `limits.maxLimit`                    | `25`                           | Upper bound for `findDocuments.limit`.                                                                             |
-| `limits.maxDepth`                    | `1`                            | Upper bound for `depth` on reads.                                                                                  |
-| `tools`                              | `[]`                           | Custom tools, defined the same way as the builtins.                                                                |
-| `auth.resolve`                       | none                           | Replace or wrap the default key resolution.                                                                        |
-| `serverInfo`                         | package name and version       | Reported to MCP clients.                                                                                           |
-
-`allowLiveWrites` is the only way an MCP write reaches live content. Where it is
-set, the server instructions and the `patchDocument` and `createDocument`
-descriptions name those slugs for the key in question, so a client is never told
-its writes are drafts while they are not.
-
-Misconfiguration (unknown slugs, write on a collection without drafts, upload
-collections exposed for write, tool name collisions) fails at startup with
-`InvalidConfiguration`. Auth collections cannot be exposed at all, read
+| Option                       | Default                        | Description                                                       |
+| ---------------------------- | ------------------------------ | ----------------------------------------------------------------- |
+| `collections`                | required                       | Allow-list. `true` means `{ read: true }`.                        |
+| `collections.<slug>.read`    | `true`                         | Expose `describeSchema`, `findDocuments`, `getDocument`.          |
+| `collections.<slug>.write`   | `false`                        | `"draft"` or `"live"`. See below.                                 |
+| `globals`                    | `{}`                           | Allow-list of globals. `true` means `{ read: true }`.             |
+| `globals.<slug>.read`        | `true`                         | Expose `describeSchema`, `getDocument`.                           |
+| `globals.<slug>.write`       | `false`                        | `"draft"` or `"live"`. See below.                                 |
+| `userCollection`             | `config.admin.user` or `users` | Auth collection the keys act as.                                  |
+| `apiKeys.slug`               | `mcpx-api-keys`                | Slug of the generated key collection.                             |
+| `apiKeys.setupGuide`         | `true`                         | Add a "Connect a client" tab to saved keys. Needs the import map. |
+| `apiKeys.overrideCollection` | none                           | Final override applied to the generated collection.               |
+| `endpoint.path`              | `/mcpx`                        | Endpoint path below the API route.                                |
+| `limits.maxLimit`            | `25`                           | Upper bound for `findDocuments.limit`.                            |
+| `limits.maxDepth`            | `1`                            | Upper bound for `depth` on reads.                                 |
+| `tools`                      | `[]`                           | Custom tools, defined the same way as the builtins.               |
+| `auth.resolve`               | none                           | Replace or wrap the default key resolution.                       |
+| `serverInfo`                 | package name and version       | Reported to MCP clients.                                          |
+
+`write` is one axis: how far MCP writes to this entity reach.
+
+| `write`   | With `versions.drafts`                                  | Without                                        |
+| --------- | ------------------------------------------------------- | ---------------------------------------------- |
+| `false`   | no write tool reaches it                                | no write tool reaches it                       |
+| `"draft"` | writes land as drafts, nothing is ever published        | refused at startup: there is no draft to write |
+| `"live"`  | writes land as drafts, and `publishDocument` is exposed | writes land on the live document               |
+
+`"live"` is the only way an MCP write reaches live content, whichever of the two
+shapes it takes. Wherever it is set, the server instructions and the
+`patchDocument` and `createDocument` descriptions name those slugs for the key in
+question, so a client is never told its writes are drafts while they are not,
+nor that publishing is out of reach when it is not.
+
+Migrating from the previous option shape: `write: true` becomes
+`write: "draft"`, and `write: true` with `allowLiveWrites: true` becomes
+`write: "live"`. A versioned entity moved to `write: "live"` gains a `publish`
+checkbox on every key, unticked, so nothing publishes until someone says so.
+
+Misconfiguration (unknown slugs, `write: "draft"` on a collection without
+drafts, upload collections exposed for write, tool name collisions) fails at
+startup with `InvalidConfiguration`. So does `write: "live"` on an entity using
+`versions.drafts.localizeStatus`, which is not supported yet. Auth collections cannot be exposed at all, read
 included: their documents carry credentials, such as the decrypted Payload API
 key of every user.
 
@@ -402,12 +445,16 @@ key of every user.
 - The endpoint authenticates with Bearer keys only; admin JWTs and cookies are
   ignored. Keys cannot authenticate REST or GraphQL.
 - Every operation runs under the linked user with `overrideAccess: false`.
+- Payload has no separate publish permission: at its access layer, anyone who
+  may update a document may publish it. The `publish` checkbox is this plugin's
+  fence, not Payload's.
 - Not covered in v1: `delete` (no tool exists and none is generated), 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
+Unpublishing, `versions.drafts.localizeStatus`, 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

package/dist/api-keys/fields.mjs

@@ -1,4 +1,4 @@
-import { CAPABILITIES_FIELD } from "../capabilities.mjs";
+import { CAPABILITIES_FIELD, canPublish, canWrite } from "../capabilities.mjs";
 //#region src/api-keys/fields.ts
 const encryptKey = ({ req, value }) => typeof value === "string" ? req.payload.encrypt(value) : value;
 const decryptKey = ({ req, value }) => {
@@ -89,23 +89,36 @@ const SETUP_GUIDE_FIELD = "setupGuide";
 		}]
 	}];
 };
+const PUBLISH_DESCRIPTION = "Publish the current draft. Changes what the public sees.";
 /**
 * One checkbox per exposed operation, grouped per collection, per global and
 * per custom tool. Only operations the plugin config exposes get a checkbox, so
 * a key can never enable more than the config allows. Everything defaults to
 * off, which is why a key issued before a capability existed stays closed to it.
+*
+* An entity without versions gets no `publish` checkbox even under
+* `write: "live"`: there is no draft to promote there, the write itself is the
+* live change, and a second checkbox would only make `write` a dead setting.
 */ const createCapabilityFields = (options) => {
 	const collectionGroups = options.collections.map((collection) => ({
 		name: collection.fieldName,
 		type: "group",
 		label: collection.slug,
-		fields: [...collection.read ? [checkbox("read", "Describe, find and read documents.")] : [], ...collection.write ? [checkbox("write", "Create, patch and validate drafts.")] : []]
+		fields: [
+			...collection.read ? [checkbox("read", "Describe, find and read documents.")] : [],
+			...canWrite(collection) ? [checkbox("write", "Create, patch and validate drafts.")] : [],
+			...canPublish(collection) ? [checkbox("publish", PUBLISH_DESCRIPTION)] : []
+		]
 	}));
 	const globalGroups = options.globals.map((global) => ({
 		name: global.fieldName,
 		type: "group",
 		label: global.slug,
-		fields: [...global.read ? [checkbox("read", "Describe and read this global.")] : [], ...global.write ? [checkbox("write", "Patch and validate this global's draft.")] : []]
+		fields: [
+			...global.read ? [checkbox("read", "Describe and read this global.")] : [],
+			...canWrite(global) ? [checkbox("write", "Patch and validate this global's draft.")] : [],
+			...canPublish(global) ? [checkbox("publish", PUBLISH_DESCRIPTION)] : []
+		]
 	}));
 	const toolCheckboxes = options.tools.map((tool) => checkbox(tool.name, typeof tool.description === "string" ? tool.description : tool.name));
 	const groups = [

package/dist/capabilities.mjs

@@ -1,8 +1,23 @@
 //#region src/capabilities.ts
 /** Name of the capability group on the key document. */ const CAPABILITIES_FIELD = "capabilities";
+/** Whether any write tool reaches this entity. */ const canWrite = (entity) => entity.write !== false;
+/**
+* Whether `publishDocument` reaches this entity: the config lets MCP change
+* live content and there is a draft to promote.
+*/ const canPublish = (entity) => entity.write === "live" && entity.hasDrafts;
+/**
+* Whether an ordinary write to this entity changes the live document. With no
+* versions there is no draft to land on, so `write: "live"` is what permits the
+* write at all and every write is live.
+*/ const isLiveWrite = (entity) => entity.write === "live" && !entity.hasDrafts;
 const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
 const flag = (group, name) => isRecord(group) && group[name] === true;
 /**
+* Publishing is an extension of writing, never a capability of its own: a key
+* that may publish may also edit the draft it publishes. Both checkboxes are
+* therefore required, on top of the config exposing publishing at all.
+*/ const publishFlag = (entity, group) => canPublish(entity) && flag(group, "write") && flag(group, "publish");
+/**
 * Capabilities in force for a key: the plugin config decides what can exist,
 * the key's checkboxes decide what does. A missing checkbox is `false`, so keys
 * issued before a capability existed stay closed.
@@ -15,7 +30,8 @@ const flag = (group, name) => isRecord(group) && group[name] === true;
 		const group = isRecord(collectionsGroup) ? collectionsGroup[collection.fieldName] : void 0;
 		collections[collection.slug] = {
 			read: collection.read && flag(group, "read"),
-			write: collection.write && flag(group, "write")
+			write: canWrite(collection) && flag(group, "write"),
+			publish: publishFlag(collection, group)
 		};
 	}
 	const globals = {};
@@ -23,7 +39,8 @@ const flag = (group, name) => isRecord(group) && group[name] === true;
 		const group = isRecord(globalsGroup) ? globalsGroup[global.fieldName] : void 0;
 		globals[global.slug] = {
 			read: global.read && flag(group, "read"),
-			write: global.write && flag(group, "write")
+			write: canWrite(global) && flag(group, "write"),
+			publish: publishFlag(global, group)
 		};
 	}
 	const tools = {};
@@ -37,7 +54,9 @@ const flag = (group, name) => isRecord(group) && group[name] === true;
 const pick = (entries, operation) => Object.entries(entries).filter(([, value]) => value[operation]).map(([slug]) => slug);
 const readableSlugs = (capabilities) => pick(capabilities.collections, "read");
 const writableSlugs = (capabilities) => pick(capabilities.collections, "write");
+const publishableSlugs = (capabilities) => pick(capabilities.collections, "publish");
 const readableGlobalSlugs = (capabilities) => pick(capabilities.globals, "read");
 const writableGlobalSlugs = (capabilities) => pick(capabilities.globals, "write");
+const publishableGlobalSlugs = (capabilities) => pick(capabilities.globals, "publish");
 //#endregion
-export { CAPABILITIES_FIELD, readableGlobalSlugs, readableSlugs, resolveCapabilities, writableGlobalSlugs, writableSlugs };
+export { CAPABILITIES_FIELD, canPublish, canWrite, isLiveWrite, publishableGlobalSlugs, publishableSlugs, readableGlobalSlugs, readableSlugs, resolveCapabilities, writableGlobalSlugs, writableSlugs };

package/dist/endpoint/handler.mjs

@@ -1,4 +1,4 @@
-import { readableGlobalSlugs, readableSlugs, resolveCapabilities, writableGlobalSlugs, writableSlugs } from "../capabilities.mjs";
+import { publishableGlobalSlugs, publishableSlugs, readableGlobalSlugs, readableSlugs, resolveCapabilities, writableGlobalSlugs, writableSlugs } from "../capabilities.mjs";
 import { jsonRpcError } from "./errors.mjs";
 import { resolveApiKeyAuth } from "../auth/resolve.mjs";
 import { createMcpServer } from "./server.mjs";
@@ -11,8 +11,10 @@ const buildScope = (req, options, capabilities) => {
 		capabilities,
 		readable: readableSlugs(capabilities),
 		writable: writableSlugs(capabilities),
+		publishable: publishableSlugs(capabilities),
 		readableGlobals: readableGlobalSlugs(capabilities),
 		writableGlobals: writableGlobalSlugs(capabilities),
+		publishableGlobals: publishableGlobalSlugs(capabilities),
 		locales: localization ? localization.localeCodes : null,
 		defaultLocale: localization ? localization.defaultLocale : null,
 		limits: options.limits,

package/dist/index.d.mts

@@ -1,5 +1,5 @@
-import { McpxAnyTool, McpxAuthResult, McpxCollectionCapabilities, McpxCollectionOptions, McpxExposedEntity, McpxGlobalOptions, McpxPluginOptions, McpxRequestContext, McpxResolvedCapabilities, McpxTool, McpxToolExtra, McpxToolScope, PublishBlocker, defineMcpxTool } from "./types.mjs";
+import { McpxAnyTool, McpxAuthResult, McpxCollectionCapabilities, McpxCollectionOptions, McpxExposedEntity, McpxGlobalOptions, McpxPluginOptions, McpxRequestContext, McpxResolvedCapabilities, McpxTool, McpxToolExtra, McpxToolScope, McpxWriteMode, PublishBlocker, defineMcpxTool } from "./types.mjs";
 import { mcpxPlugin } from "./plugin.mjs";
 import { isMcpxRequest } from "./request.mjs";
 import { errorResult, jsonResult } from "./result.mjs";
-export { McpxAnyTool, McpxAuthResult, McpxCollectionCapabilities, McpxCollectionOptions, McpxExposedEntity, McpxGlobalOptions, McpxPluginOptions, McpxRequestContext, McpxResolvedCapabilities, McpxTool, McpxToolExtra, McpxToolScope, PublishBlocker, defineMcpxTool, errorResult, isMcpxRequest, jsonResult, mcpxPlugin };
+export { McpxAnyTool, McpxAuthResult, McpxCollectionCapabilities, McpxCollectionOptions, McpxExposedEntity, McpxGlobalOptions, McpxPluginOptions, McpxRequestContext, McpxResolvedCapabilities, McpxTool, McpxToolExtra, McpxToolScope, McpxWriteMode, PublishBlocker, defineMcpxTool, errorResult, isMcpxRequest, jsonResult, mcpxPlugin };

package/dist/options.mjs

@@ -1,7 +1,7 @@
 import { BUILTIN_TOOL_NAMES } from "./tools/names.mjs";
 import "./version.mjs";
 import { InvalidConfiguration } from "payload";
-import { hasDraftsEnabled } from "payload/shared";
+import { hasDraftsEnabled, hasLocalizeStatusEnabled } from "payload/shared";
 //#region src/options.ts
 const DEFAULT_API_KEYS_SLUG = "mcpx-api-keys";
 const DEFAULT_ENDPOINT_PATH = "/mcpx";
@@ -24,11 +24,29 @@ const fail = (message) => {
 	if (slug === apiKeysSlug || slug.startsWith("payload-")) fail(`Collection "${slug}" cannot be exposed.`);
 	if (collection.auth) fail(`Auth collection "${slug}" cannot be exposed. Its documents carry credentials.`);
 };
+/**
+* The write mode, checked at runtime as well as in the type. JS callers get no
+* type checking, and a typo reading as "no write" would be a silent downgrade.
+*/ const normalizeWriteMode = (kind, slug, value) => {
+	if (value === void 0 || value === false) return false;
+	if (value === "draft" || value === "live") return value;
+	return fail(`${kind} "${slug}" has write: ${JSON.stringify(value)}. Use false, "draft" or "live".`);
+};
+/**
+* `localizeStatus` makes `_status` a localized field, which flips Payload's
+* `publishAllLocales` default to false and turns `_status` into a locale-keyed
+* object. Publishing would then cover one locale while reporting success, and
+* the tool responses model `_status` as a string. Refused until both are
+* handled.
+*/ const assertPublishable = (kind, config) => {
+	if (hasLocalizeStatusEnabled(config)) fail(`${kind} "${config.slug}" has versions.drafts.localizeStatus enabled, which write: "live" does not support yet.`);
+};
 const assertWritable = (collection, options) => {
 	const { slug } = collection;
 	if (collection.upload) fail(`Upload collection "${slug}" cannot be exposed for write.`);
 	if (collection.timestamps === false) fail(`Collection "${slug}" has timestamps disabled, which write tools need for concurrency checks.`);
-	if (!options.hasDrafts && !options.allowLiveWrites) fail(`Collection "${slug}" has no drafts. Enable versions.drafts or set allowLiveWrites.`);
+	if (options.write === "draft" && !options.hasDrafts) fail(`Collection "${slug}" has no drafts. Enable versions.drafts or set write: "live".`);
+	if (options.write === "live") assertPublishable("Collection", collection);
 };
 /**
 * Refuses globals that must never be reachable. Globals cannot be auth or
@@ -41,7 +59,8 @@ const assertWritable = (collection, options) => {
 * `createdAt`/`updatedAt`, so the concurrency check the collection path guards
 * for is always available here. Drafts are the only requirement left.
 */ const assertGlobalWritable = (global, options) => {
-	if (!options.hasDrafts && !options.allowLiveWrites) fail(`Global "${global.slug}" has no drafts. Enable versions.drafts or set allowLiveWrites.`);
+	if (options.write === "draft" && !options.hasDrafts) fail(`Global "${global.slug}" has no drafts. Enable versions.drafts or set write: "live".`);
+	if (options.write === "live") assertPublishable("Global", global);
 };
 const normalizeCollections = (config, options, apiKeysSlug) => {
 	const collections = config.collections ?? [];
@@ -56,12 +75,11 @@ const normalizeCollections = (config, options, apiKeysSlug) => {
 		const normalized = {
 			slug,
 			read: settings.read ?? true,
-			write: settings.write ?? false,
-			allowLiveWrites: settings.allowLiveWrites ?? false,
+			write: normalizeWriteMode("Collection", slug, settings.write),
 			hasDrafts,
 			fieldName: toCamelCase(slug)
 		};
-		if (normalized.write) assertWritable(collection, normalized);
+		if (normalized.write !== false) assertWritable(collection, normalized);
 		if (fieldNames.has(normalized.fieldName)) fail(`Collection "${slug}" maps to capability field "${normalized.fieldName}", which another exposed collection already uses.`);
 		fieldNames.add(normalized.fieldName);
 		return [normalized];
@@ -80,12 +98,11 @@ const normalizeGlobals = (config, options) => {
 		const normalized = {
 			slug,
 			read: settings.read ?? true,
-			write: settings.write ?? false,
-			allowLiveWrites: settings.allowLiveWrites ?? false,
+			write: normalizeWriteMode("Global", slug, settings.write),
 			hasDrafts,
 			fieldName: toCamelCase(slug)
 		};
-		if (normalized.write) assertGlobalWritable(global, normalized);
+		if (normalized.write !== false) assertGlobalWritable(global, normalized);
 		if (fieldNames.has(normalized.fieldName)) fail(`Global "${slug}" maps to capability field "${normalized.fieldName}", which another exposed global already uses.`);
 		fieldNames.add(normalized.fieldName);
 		return [normalized];

package/dist/tools/builtin.mjs

@@ -4,6 +4,7 @@ import { findDocuments } from "./find-documents.mjs";
 import { getDocument } from "./get-document.mjs";
 import { listCapabilities } from "./list-capabilities.mjs";
 import { patchDocument } from "./patch-document.mjs";
+import { publishDocument } from "./publish-document.mjs";
 import { validateDocument } from "./validate-document.mjs";
 //#region src/tools/builtin.ts
 /**
@@ -20,7 +21,8 @@ import { validateDocument } from "./validate-document.mjs";
 	getDocument,
 	patchDocument,
 	createDocument,
-	validateDocument
+	validateDocument,
+	publishDocument
 ];
 //#endregion
 export { BUILTIN_TOOLS };

package/dist/tools/list-capabilities.mjs

@@ -32,6 +32,7 @@ A global is a singleton: it has no id, is not listed by findDocuments and cannot
 				...description === void 0 ? {} : { description },
 				read: capability.read,
 				write: capability.write,
+				publish: capability.publish,
 				drafts: entry.hasDrafts,
 				draftValidation: hasDraftValidationEnabled(config),
 				idType: collection.customIDType ?? payload.db.defaultIDType
@@ -48,6 +49,7 @@ A global is a singleton: it has no id, is not listed by findDocuments and cannot
 				...description === void 0 ? {} : { description },
 				read: capability.read,
 				write: capability.write,
+				publish: capability.publish,
 				drafts: entry.hasDrafts,
 				draftValidation: hasDraftValidationEnabled(config)
 			}];

package/dist/tools/names.mjs

@@ -8,7 +8,8 @@
 	"getDocument",
 	"patchDocument",
 	"createDocument",
-	"validateDocument"
+	"validateDocument",
+	"publishDocument"
 ];
 //#endregion
 export { BUILTIN_TOOL_NAMES };

package/dist/tools/patch-document.mjs

@@ -1,5 +1,5 @@
 import { errorResult, jsonResult } from "../result.mjs";
-import { draftSentence, idShape, localeOf, localeShape, readTarget, targetShape } from "./shared.mjs";
+import { draftSentence, idShape, localeOf, localeShape, readTarget, sameInstant, targetShape } from "./shared.mjs";
 import { refOf, requireIdFor, resolveTarget } from "./target.mjs";
 import { defineMcpxTool } from "../types.mjs";
 import { PATCH_OPERATION_SCHEMA, applyPatchOperations, buildWriteData, isElementPointer } from "../write/patch.mjs";
@@ -16,10 +16,9 @@ ${draftSentence(scope)}
 
 Only the fields describeSchema lists can be addressed. A pointer that does not resolve is refused with the fields that are valid at that point, and nothing is applied unless every operation in the batch validates first. describeSchema reports field paths in this same pointer syntax; a path becomes a pointer into a document by replacing each "*" and each block slug with its 0-based index.
 
-Adding a block requires "blockType" on the value. Append with "/-" as the last segment. To clear a field use "replace" with null; an array or blocks field refuses null and is emptied with [] instead. "remove" is only for list elements, because a field left out of a write is kept rather than cleared. Read the document first to learn the indices, and pass its "updatedAt" as expectedUpdatedAt so a concurrent edit is refused rather than overwritten.
+Adding a block requires "blockType" on the value. Append with "/-" as the last segment. To clear a field use "replace" with null; an array or blocks field refuses null and is emptied with [] instead. "remove" is only for list elements, because a field left out of a write is kept rather than cleared. Read the document first to learn the indices, and pass its "updatedAt" as expectedUpdatedAt so an edit made since that read is refused rather than overwritten.
 
-A successful write may come back with "publishBlockers": everything still wrong with the draft, such as required fields left empty. Those do not fail the write, because a draft is allowed to be incomplete, but a human cannot publish the document until the list is empty. "notApplied" lists pointers whose value Payload kept unchanged, which happens when field-level access denies the update. "publishBlockersUnavailable" means the check itself failed, so the empty list says nothing about whether the document is publishable.`;
-const sameInstant = (left, right) => typeof left === "string" && new Date(left).getTime() === new Date(right).getTime();
+A successful write may come back with "publishBlockers": everything still wrong with the draft, such as required fields left empty. Those do not fail the write, because a draft is allowed to be incomplete, but the document cannot be published until the list is empty. "notApplied" lists pointers whose value Payload kept unchanged, which happens when field-level access denies the update. "publishBlockersUnavailable" means the check itself failed, so the empty list says nothing about whether the document is publishable.`;
 const isPlainObject = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
 /**
 * Whether the intended value survived the write. The saved document is
@@ -64,7 +63,7 @@ const patchDocument = defineMcpxTool({
 			description: "Locale the patch applies to. Localized fields write here only."
 		}),
 		patches: z.array(PATCH_OPERATION_SCHEMA).min(1).describe("Operations, applied in order."),
-		expectedUpdatedAt: z.string().optional().describe("The updatedAt read before patching. The write is refused if the document has changed since.")
+		expectedUpdatedAt: z.string().optional().describe("The updatedAt read before patching. Best effort: the write is refused if the document changed before the check, but not if it changes between the check and the write.")
 	}),
 	handler: async ({ args, scope }) => {
 		const target = resolveTarget(scope, args, "write");
@@ -100,6 +99,7 @@ const patchDocument = defineMcpxTool({
 			});
 			else await payload.updateGlobal({
 				...write,
+				fallbackLocale: false,
 				slug: target.slug
 			});
 			const saved = await readTarget(scope, {

package/dist/tools/publish-document.mjs

@@ -0,0 +1,81 @@
+import { errorResult, jsonResult } from "../result.mjs";
+import { idShape, localeOf, readTarget, sameInstant, targetShape } from "./shared.mjs";
+import { requireIdFor, resolveTarget } from "./target.mjs";
+import { defineMcpxTool } from "../types.mjs";
+import { withTransaction } from "../write/transaction.mjs";
+import { withPublishIntent } from "../write/publish-intent.mjs";
+import { z } from "zod";
+const publishDocument = defineMcpxTool({
+	name: "publishDocument",
+	description: `Publishes the current draft, which changes what the public sees. This is the only tool that does; every other write lands as a draft. Call validateDocument first: a document that still has publish blockers is refused, and nothing is written.
+
+Pass exactly one of "collection" and "global". "id" is required with "collection" and must be omitted with "global", because a global is a singleton.
+
+The whole document is published, but Payload only validates the locale the publish runs in, so a required field left empty in another locale goes live empty. That is how the admin panel behaves too. Publishing is refused while a human holds the document open in the admin panel, and republishing an unchanged document is accepted but writes another version.
+
+There is no unpublish: reverting to a draft stays a human action in the admin panel.`,
+	annotations: {
+		destructiveHint: true,
+		openWorldHint: false
+	},
+	isEnabled: (scope) => scope.publishable.length + scope.publishableGlobals.length > 0,
+	inputSchema: (scope) => ({
+		...targetShape(scope, "publish", {
+			collection: "Collection holding the document.",
+			global: "Global to publish."
+		}),
+		...idShape(scope, "publish"),
+		expectedUpdatedAt: z.string().optional().describe("The updatedAt read before publishing. Best effort: the publish is refused if the document has changed since, but a write landing between the check and the publish is not.")
+	}),
+	handler: async ({ args, scope }) => {
+		const target = resolveTarget(scope, args, "publish");
+		const id = requireIdFor(target, args.id);
+		const { payload } = scope.req;
+		const locale = localeOf(scope, void 0);
+		return await withTransaction(scope.req, async () => {
+			const doc = await readTarget(scope, {
+				target,
+				id,
+				locale
+			});
+			if (args.expectedUpdatedAt !== void 0 && !sameInstant(doc["updatedAt"], args.expectedUpdatedAt)) return errorResult("The document changed since you read it. Read it again before publishing.", { updatedAt: doc["updatedAt"] });
+			const write = {
+				data: {},
+				depth: 0,
+				draft: false,
+				fallbackLocale: false,
+				overrideAccess: false,
+				req: scope.req,
+				...locale === void 0 ? {} : { locale }
+			};
+			await withPublishIntent({
+				kind: target.kind,
+				slug: target.slug,
+				id
+			}, async () => {
+				if (target.kind === "collection") await payload.update({
+					...write,
+					collection: target.slug,
+					id
+				});
+				else await payload.updateGlobal({
+					...write,
+					slug: target.slug
+				});
+			});
+			const saved = await readTarget(scope, {
+				target,
+				id,
+				locale,
+				privileged: true
+			});
+			return jsonResult({
+				...target.kind === "collection" ? { id: saved["id"] } : { global: target.slug },
+				status: saved["_status"],
+				updatedAt: saved["updatedAt"]
+			});
+		});
+	}
+});
+//#endregion
+export { publishDocument };

package/dist/tools/shared.mjs

@@ -1,33 +1,63 @@
+import { canPublish, isLiveWrite } from "../capabilities.mjs";
 import { translateStatic } from "../i18n.mjs";
 import { NotFound } from "payload";
 import { z } from "zod";
 //#region src/tools/shared.ts
 const slugEnum = (slugs) => z.enum(slugs);
 const idSchema = z.union([z.string(), z.number()]).describe("Document id.");
-/**
-* Slugs this key may write whose writes land live rather than as a draft,
-* which is what `allowLiveWrites` permits for an entity without versions.
-* Empty for every key that can only write drafts.
-*/ const liveWriteSlugs = (scope) => {
-	const live = (entities, writable) => entities.filter((entity) => writable.includes(entity.slug) && entity.allowLiveWrites && !entity.hasDrafts).map((entity) => entity.slug);
-	return [...live(scope.exposure.collections, scope.writable), ...live(scope.exposure.globals, scope.writableGlobals)];
+const slugsWhere = (scope, predicate, allowed) => {
+	const pick = (entities, slugs) => entities.filter((entity) => slugs.includes(entity.slug) && predicate(entity)).map((entity) => entity.slug);
+	return [...pick(scope.exposure.collections, allowed.collections), ...pick(scope.exposure.globals, allowed.globals)];
 };
 /**
-* The sentence the write tools and the server instructions end on: what a
-* write actually does for this key.
+* Slugs this key may write whose writes land live rather than as a draft. An
+* entity without versions has no draft to land on, so `write: "live"` there
+* makes every write a live one. Empty for every key that can only write drafts.
+*/ const liveWriteSlugs = (scope) => slugsWhere(scope, isLiveWrite, {
+	collections: scope.writable,
+	globals: scope.writableGlobals
+});
+/** Slugs this key may write and, separately, publish. */ const publishableWriteSlugs = (scope) => slugsWhere(scope, canPublish, {
+	collections: scope.publishable,
+	globals: scope.publishableGlobals
+});
+/**
+* The sentence the write tools and the server instructions end on: what a write
+* actually does for this key, and what it takes to make it public. The three
+* groups are distinct — a live-write slug has no draft and no publish step, a
+* publishable one has both — so a client is never told its writes are drafts
+* while they are not, nor that publishing is out of reach when it is not.
 */ const draftSentence = (scope) => {
 	const live = liveWriteSlugs(scope);
-	return live.length === 0 ? "Every write lands as a draft and is never published; publishing stays a human action in the admin panel." : `Writes land as drafts and are never published, except for ${live.join(", ")}, which have no drafts: a write there changes the live document immediately. Publishing anything else stays a human action in the admin panel.`;
+	const publishable = publishableWriteSlugs(scope);
+	return `${live.length === 0 ? "Every write lands as a draft." : `Writes land as drafts, except for ${live.join(", ")}, which have no drafts: a write there changes the live document immediately.`} ${publishable.length === 0 ? "Nothing this key writes is ever published; publishing stays a human action in the admin panel." : `Publish a draft with publishDocument, which this key may do for ${publishable.join(", ")}. Publishing anything else stays a human action in the admin panel.`}`;
 };
 /**
+* Whether two timestamps name the same instant, which is how
+* `expectedUpdatedAt` is compared: the value a client read back is a string,
+* and what it is compared against may be a Date.
+*/ const sameInstant = (left, right) => typeof left === "string" && new Date(left).getTime() === new Date(right).getTime();
+/**
 * Widens one branch to the superset a handler sees. The widening itself is
 * unchecked — the runtime shape really does vary — so `Branch` checks what it
 * can around it.
 */ const widen = (branch) => branch;
-const slugsFor = (scope, operation) => ({
-	collections: operation === "read" ? scope.readable : scope.writable,
-	globals: operation === "read" ? scope.readableGlobals : scope.writableGlobals
-});
+const slugsFor = (scope, operation) => {
+	switch (operation) {
+		case "publish": return {
+			collections: scope.publishable,
+			globals: scope.publishableGlobals
+		};
+		case "read": return {
+			collections: scope.readable,
+			globals: scope.readableGlobals
+		};
+		case "write": return {
+			collections: scope.writable,
+			globals: scope.writableGlobals
+		};
+	}
+};
 /**
 * The `collection` and `global` arguments.
 *
@@ -114,4 +144,4 @@ const depthShape = (scope) => ({ depth: z.number().int().min(0).max(scope.limits
 	return translateStatic(resolved, i18n) ?? fallback;
 };
 //#endregion
-export { depthShape, draftSentence, idSchema, idShape, liveWriteSlugs, localeOf, localeShape, readTarget, slugEnum, targetShape, translateLabel };
+export { depthShape, draftSentence, idSchema, idShape, localeOf, localeShape, readTarget, sameInstant, slugEnum, slugsFor, targetShape, translateLabel };

package/dist/tools/target.mjs

@@ -1,3 +1,4 @@
+import { slugsFor } from "./shared.mjs";
 import { APIError, Forbidden } from "payload";
 //#region src/tools/target.ts
 const refOf = (target) => ({
@@ -14,12 +15,12 @@ const refOf = (target) => ({
 * failed call teaches it.
 */ const resolveTarget = (scope, args, operation) => {
 	const { collection, global } = args;
+	const allowedSlugs = slugsFor(scope, operation);
 	if (collection !== void 0 && global !== void 0) throw new APIError("Pass either \"collection\" or \"global\", not both.", 400);
 	if (collection === void 0 && global === void 0) throw new APIError("One of \"collection\" or \"global\" is required. Call listCapabilities to see which slugs are available.", 400);
 	if (collection !== void 0) {
-		const allowed = operation === "read" ? scope.readable : scope.writable;
 		const found = scope.req.payload.collections[collection];
-		if (!allowed.includes(collection) || !found) throw new Forbidden(scope.req.t);
+		if (!allowedSlugs.collections.includes(collection) || !found) throw new Forbidden(scope.req.t);
 		return {
 			kind: "collection",
 			slug: collection,
@@ -27,9 +28,8 @@ const refOf = (target) => ({
 		};
 	}
 	const slug = global;
-	const allowed = operation === "read" ? scope.readableGlobals : scope.writableGlobals;
 	const found = scope.req.payload.globals.config.find((candidate) => candidate.slug === slug);
-	if (!allowed.includes(slug) || !found) throw new Forbidden(scope.req.t);
+	if (!allowedSlugs.globals.includes(slug) || !found) throw new Forbidden(scope.req.t);
 	return {
 		kind: "global",
 		slug,

package/dist/types.d.mts

@@ -11,6 +11,17 @@ declare module "payload" {
     "@abinnovision/payloadcms-mcpx": McpxPluginOptions;
   }
 }
+/**
+ * How far an exposed entity lets MCP writes reach.
+ *
+ * - `false`: no write tool touches it.
+ * - `"draft"`: writes land as drafts and nothing MCP does changes what the
+ *   public sees. Requires `versions.drafts`.
+ * - `"live"`: MCP may change live content. On an entity with drafts that means
+ *   `publishDocument` is exposed; on one without, where there is no draft to
+ *   land on, it means the write itself is permitted and lands live.
+ */
+type McpxWriteMode = "draft" | "live" | false;
 /**
  * What an exposed collection offers to MCP clients. A key can only enable
  * what the config exposes here.
@@ -21,15 +32,10 @@ interface McpxCollectionOptions {
    */
   read?: boolean;
   /**
-   * Expose `patchDocument`, `createDocument` and `validateDocument`. Default
-   * `false`. Requires `versions.drafts` unless `allowLiveWrites` is set.
-   */
-  write?: boolean;
-  /**
-   * Permit writes to a collection without drafts. Such writes land on the live
-   * document because there is no draft to land on. Default `false`.
+   * Expose `patchDocument`, `createDocument` and `validateDocument`, and how
+   * far those writes reach. Default `false`.
    */
-  allowLiveWrites?: boolean;
+  write?: McpxWriteMode;
 }
 /**
  * What an exposed global offers to MCP clients. Structurally the same as
@@ -41,15 +47,10 @@ interface McpxGlobalOptions {
   /** Expose `describeSchema` and `getDocument`. Default `true`. */
   read?: boolean;
   /**
-   * Expose `patchDocument` and `validateDocument`. Default `false`. Requires
-   * `versions.drafts` unless `allowLiveWrites` is set.
+   * Expose `patchDocument` and `validateDocument`, and how far those writes
+   * reach. Default `false`.
    */
-  write?: boolean;
-  /**
-   * Permit writes to a global without drafts. Such writes land on the live
-   * document because there is no draft to land on. Default `false`.
-   */
-  allowLiveWrites?: boolean;
+  write?: McpxWriteMode;
 }
 type McpxToolExtra = RequestHandlerExtra<ServerRequest, ServerNotification>;
 /**
@@ -59,8 +60,7 @@ type McpxToolExtra = RequestHandlerExtra<ServerRequest, ServerNotification>;
 interface McpxExposedEntity {
   slug: string;
   read: boolean;
-  write: boolean;
-  allowLiveWrites: boolean;
+  write: McpxWriteMode;
   hasDrafts: boolean;
   /** Name of the capability group on the key document. */
   fieldName: string;
@@ -72,12 +72,14 @@ interface McpxExposedEntity {
 interface McpxToolScope {
   req: PayloadRequest;
   capabilities: McpxResolvedCapabilities;
-  /** Collection slugs the key may read / write. */
+  /** Collection slugs the key may read / write / publish. */
   readable: string[];
   writable: string[];
-  /** Global slugs the key may read / write. */
+  publishable: string[];
+  /** Global slugs the key may read / write / publish. */
   readableGlobals: string[];
   writableGlobals: string[];
+  publishableGlobals: string[];
   /** Configured locale codes, or `null` when localization is off. */
   locales: null | string[];
   defaultLocale: null | string;
@@ -214,6 +216,11 @@ type McpxPluginOptions = {
 interface McpxCollectionCapabilities {
   read: boolean;
   write: boolean;
+  /**
+   * Whether the key may publish this entity's draft. Only ever true where the
+   * config sets `write: "live"` and the entity has drafts.
+   */
+  publish: boolean;
 }
 /**
  * Capabilities in force for one request: plugin config AND key checkboxes.
@@ -238,4 +245,4 @@ interface PublishBlocker {
   path: string;
 }
 //#endregion
-export { McpxAnyTool, McpxAuthResult, McpxCollectionCapabilities, McpxCollectionOptions, McpxExposedEntity, McpxGlobalOptions, McpxPluginOptions, McpxRequestContext, McpxResolvedCapabilities, McpxTool, McpxToolExtra, McpxToolScope, PublishBlocker, defineMcpxTool };
+export { McpxAnyTool, McpxAuthResult, McpxCollectionCapabilities, McpxCollectionOptions, McpxExposedEntity, McpxGlobalOptions, McpxPluginOptions, McpxRequestContext, McpxResolvedCapabilities, McpxTool, McpxToolExtra, McpxToolScope, McpxWriteMode, PublishBlocker, defineMcpxTool };

package/dist/write/draft-guard.mjs

@@ -1,10 +1,11 @@
+import { claimPublishIntent, isClaimedPublish } from "./publish-intent.mjs";
 import { isMcpxRequest } from "../request.mjs";
 import { APIError } from "payload";
 import { hasDraftsEnabled } from "payload/shared";
 //#region src/write/draft-guard.ts
 /**
 * Operation arguments that widen or redirect a write. Cleared on every MCP
-* create and update so a tool cannot smuggle them in.
+* create and update, publishes included, so a tool cannot smuggle them in.
 */ const STRIPPED_ARGS = /* @__PURE__ */ new Set([
 	"where",
 	"publishAllLocales",
@@ -15,75 +16,113 @@ import { hasDraftsEnabled } from "payload/shared";
 	"overwriteExistingFiles"
 ]);
 /**
-* Forces every MCP write into a draft save.
+* Forces every MCP write into a draft save, unless it is the one write
+* `publishDocument` asked for.
 *
 * `draft` alone is not enough: Payload's update path only saves a draft when
 * `data._status !== "published"`, so `_status` is dropped and left to Payload.
 * This runs as `beforeOperation`, before Payload reads any of these arguments,
 * so it holds for every create and update on an MCP request, not only the
 * builtin tools. Deletes are not guarded in v1; custom tools that delete are
-* the integrator's responsibility.
-*/ const scrubWriteArgs = (args) => {
+* the integrator's responsibility. `restoreVersion` and `duplicate` are outside
+* the operation filter too — `restoreVersion` is caught by `refusePublish`
+* because it runs the collection's `beforeChange` hooks, and anything going
+* straight to `payload.db` bypasses all of this.
+*
+* On a claimed publish the argument scrubbing is unchanged — the whole
+* `STRIPPED_ARGS` list still goes, `deletedAt` still goes, autosave, locks and
+* trash are still forced off. Only `draft` and `_status` differ. Writing
+* `_status` here rather than in the tool keeps the tool honest: it asks to
+* publish, and this is the only thing that can grant it.
+*/ const scrubWriteArgs = (args, publishing) => {
 	const next = Object.fromEntries(Object.entries(args).filter(([key]) => !STRIPPED_ARGS.has(key)));
 	if (next["data"] && typeof next["data"] === "object") {
 		const { _status: _ignoredStatus, deletedAt: _ignoredDeletedAt, ...data } = next["data"];
-		next["data"] = data;
+		next["data"] = publishing ? {
+			...data,
+			_status: "published"
+		} : data;
 	}
-	next["draft"] = true;
+	next["draft"] = !publishing;
 	next["autosave"] = false;
 	next["overrideLock"] = false;
 	next["trash"] = false;
 	return next;
 };
 const forceDraftWrite = (hookArgs) => {
-	const { args, operation, req } = hookArgs;
+	const { args, collection, operation, req } = hookArgs;
 	if (!isMcpxRequest(req) || operation !== "create" && operation !== "update") return args;
-	return scrubWriteArgs(args);
+	const publishing = operation === "update" && claimPublishIntent({
+		kind: "collection",
+		slug: collection.slug,
+		id: args.id
+	});
+	return scrubWriteArgs(args, publishing);
 };
 /**
-* The global counterpart of {@link forceDraftWrite}. Payload invokes a global's
-* `beforeOperation` with the whole argument bag and assigns the result back,
-* exactly as the collection path does and before it reads `draft`,
-* `publishAllLocales` or `data._status`, so the guard has the same reach here:
-* every MCP write to a global, builtin tool or custom.
+* The global counterpart of {@link forceDraftWrite}, with one important
+* difference: Payload's `updateGlobal` destructures `draft`,
+* `publishAllLocales`, `publishSpecificLocale`, `unpublishAllLocales` and
+* `overrideLock` *before* it runs `beforeOperation`, and re-reads only `data`
+* afterwards. Setting those here is a no-op. What still lands is `data`, and
+* that is what the global draft guarantee actually rests on: `_status` is
+* stripped, so a rogue `updateGlobal({ draft: false })` reaches
+* {@link refusePublishGlobal} with no status and is refused there. The alarm,
+* not the correction, is load-bearing for globals.
+*
+* The publish branch matters for the same reason. `publishDocument` passes
+* `draft: false` at the call site because the hook cannot, and this hook must
+* put `_status` back rather than strip it.
 *
 * The global operation union has no `create` member because a global always
-* exists, so only `update` is intercepted. `STRIPPED_ARGS` covers the three
-* publish vectors `updateGlobal` accepts; the rest of the set does not exist on
-* that signature and filtering it is a harmless no-op. `slug` survives the
-* filter, so the operation still knows what it is updating.
+* exists, so only `update` is intercepted.
 */ 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);
+	const publishing = claimPublishIntent({
+		kind: "global",
+		slug: global.slug
+	});
+	return scrubWriteArgs(args, publishing);
 };
 /**
-* Refuses an MCP write that would still not land as a draft. An alarm rather
-* than the guarantee: `forceDraftWrite` should make it unreachable. It throws
-* instead of correcting `_status` because Payload has already chosen the write
-* branch by the time a `beforeChange` hook runs.
-*/ const refuseUnlessDraft = (req, slug, data) => {
+* Refuses an MCP write that would still not land as a draft, and — on the one
+* operation that claimed a publish intent — refuses anything that would not
+* land as a publish. An alarm rather than the guarantee for collections, where
+* `forceDraftWrite` should make it unreachable; the guarantee itself for
+* globals, per {@link forceDraftWriteGlobal}. It throws instead of correcting
+* `_status` because Payload has already chosen the write branch by the time a
+* `beforeChange` hook runs.
+*/ const refuseUnlessExpected = (req, target, data) => {
 	if (!isMcpxRequest(req)) return;
 	const status = data._status;
-	if (status === "draft") return;
-	req.payload.logger.warn(`[payloadcms-mcpx] Refused a write to ${slug} that would not have been a draft (_status: ${String(status)}).`);
-	throw new APIError("MCP clients may only write drafts. This write was refused because it would not have been saved as one.", 403);
+	const publishing = isClaimedPublish(target.kind, target.slug);
+	const expected = publishing ? "published" : "draft";
+	if (status === expected) return;
+	req.payload.logger.warn(`[payloadcms-mcpx] Refused a write to ${target.slug} that would not have been a ${expected} (_status: ${String(status)}).`);
+	throw new APIError(publishing ? "This publish was refused because it would not have saved a published document." : "MCP clients may only write drafts. This write was refused because it would not have been saved as one. Use publishDocument to publish.", 403);
 };
 const refusePublish = ({ collection, data, req }) => {
-	refuseUnlessDraft(req, collection.slug, data);
+	refuseUnlessExpected(req, {
+		kind: "collection",
+		slug: collection.slug
+	}, data);
 	return data;
 };
 /** The global counterpart of {@link refusePublish}. */ const refusePublishGlobal = ({ data, global, req }) => {
 	const next = data;
-	refuseUnlessDraft(req, global.slug, next);
+	refuseUnlessExpected(req, {
+		kind: "global",
+		slug: global.slug
+	}, next);
 	return next;
 };
 /**
 * Attaches the draft guard to every collection: `forceDraftWrite` everywhere
 * (it is a no-op outside MCP requests) and `refusePublish` wherever drafts
 * exist. Applied to the built collection list so nothing can join later
-* without being covered.
+* without being covered. Both are appended last, so a user hook cannot win.
 */ const installDraftGuards = (collections) => collections.map((collection) => ({
 	...collection,
 	hooks: {

package/dist/write/patch.mjs

@@ -155,7 +155,7 @@ const isPlainObject = (value) => typeof value === "object" && value !== null &&
 	const pointers = [operation.path, ..."from" in operation ? [operation.from] : []];
 	if (pointers.includes("")) return ["an empty pointer addresses the whole document. Address a field instead."];
 	const reserved = pointers.find(isReservedPointer);
-	if (reserved !== void 0) return [`"${reserved}" addresses a field Payload maintains. Drafts are the only thing this tool writes, and id, _status, createdAt and updatedAt are not writable.`];
+	if (reserved !== void 0) return [`"${reserved}" addresses a field Payload maintains. This tool only ever writes drafts, and id, _status, createdAt and updatedAt are not writable; use publishDocument to publish.`];
 	const dropped = droppedPointer(operation);
 	if (dropped !== void 0 && !isElementPointer(dropped)) return [`"${dropped}" is a field, not a list element, and removing it would do nothing. The patched document is written whole, and Payload keeps any field absent from a write rather than clearing it. Use "replace" with null to clear a field, or with [] to empty a list.`];
 	try {

package/dist/write/publish-intent.mjs

@@ -0,0 +1,39 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+//#region src/write/publish-intent.ts
+const store = new AsyncLocalStorage();
+/** Runs `fn` with `intent` in force. */ const withPublishIntent = async (intent, fn) => await store.run({
+	...intent,
+	claimed: false
+}, fn);
+const activeFor = (target) => {
+	const active = store.getStore();
+	return active && active.kind === target.kind && active.slug === target.slug && active.id === target.id ? active : void 0;
+};
+/**
+* Claims the intent for one operation, which `beforeOperation` does so that a
+* re-entrant write to the same document — an `afterChange` hook calling
+* `payload.update`, say — cannot ride along on it. Only the first operation to
+* ask gets it.
+*/ const claimPublishIntent = (target) => {
+	const active = activeFor(target);
+	if (!active || active.claimed) return false;
+	active.claimed = true;
+	return true;
+};
+/**
+* Whether this change belongs to the operation that claimed the intent, which
+* is what lets the `beforeChange` alarm accept a published status.
+*
+* The id is deliberately not compared here. A `beforeChange` hook reads it from
+* the loaded document, where Payload has already coerced it to the collection's
+* id type, while the claim above saw the raw tool argument; comparing the two
+* would refuse a legitimate publish over `1` versus `"1"`. Nothing is lost: a
+* nested write to another document of the same collection during the publish
+* cannot claim the intent, so `forceDraftWrite` has already stripped its
+* `_status` and it fails the alarm on that.
+*/ const isClaimedPublish = (kind, slug) => {
+	const active = store.getStore();
+	return active?.kind === kind && active.slug === slug && active.claimed;
+};
+//#endregion
+export { claimPublishIntent, isClaimedPublish, withPublishIntent };

package/dist/write/transaction.mjs

@@ -2,8 +2,14 @@ import { commitTransaction, initTransaction, killTransaction } from "payload";
 //#region src/write/transaction.ts
 /**
 * Runs `fn` inside one database transaction on `req`, so a read followed by a
-* write cannot interleave with another writer. Adapters without transaction
+* write is committed or rolled back together. Adapters without transaction
 * support, or a request that already owns one, run `fn` as is.
+*
+* Atomicity, not isolation: neither SQLite nor Postgres at read committed locks
+* the row on the read, so an `expectedUpdatedAt` check remains best effort. Nor
+* is this safe across the tool calls of one JSON-RPC batch, which share a
+* request: the second caller joins the first's transaction, so one tool's
+* rollback takes the other's work with it.
 */ const withTransaction = async (req, fn) => {
 	if (!await initTransaction(req)) return await fn();
 	try {

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "@abinnovision/payloadcms-mcpx",
-  "version": "1.0.0-beta.12",
+  "version": "1.0.0-beta.13",
   "description": "Payload CMS plugin exposing a fixed, schema-aware MCP tool surface with draft-only writes and per-API-key capabilities.",
   "keywords": [
     "payload",