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

package/README.md

@@ -13,12 +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 always land as drafts; publishing stays a
-human action in the admin panel. Every write returns the publish
-blockers: the validation failures that still prevent a human from publishing
-the draft. Capabilities are declared twice: the plugin config decides what
-can exist, a checkbox on each API key decides what does, and a missing checkbox
-means no (fail-closed).
+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
 
@@ -43,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 },
     }),
@@ -77,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
@@ -140,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.
@@ -153,7 +158,8 @@ only the slugs the key may touch.
 | `getDocument`      | Read one document or a subtree of it.                       | `collection` + `id` \| `global`, `path?` (JSON pointer), `depth?`, `locale?`, `draft?`       |
 | `patchDocument`    | Apply RFC 6902 operations to the current draft.             | `collection` + `id` \| `global`, `locale`, `patches`, `expectedUpdatedAt?`                   |
 | `createDocument`   | Create a draft from a minimal seed.                         | `collection`, `locale`, `data`                                                               |
-| `validateDocument` | Publish blockers without writing.                           | `collection` + `id` \| `global`, `locale`                                                    |
+| `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:
 
@@ -244,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
@@ -266,6 +297,12 @@ Collections with `versions.drafts.validate: true` refuse invalid drafts
 outright; those failures come back as `validationErrors`. Both carry pointers,
 restated from the dotted paths Payload reports internally.
 
+`publishBlockersUnavailable` marks a check that could not complete, which is
+not the same answer as a document with nothing wrong with it. `validateDocument`
+runs the same traversal without saving anything, so it is not free of side
+effects: field `beforeValidate` and `beforeChange` hooks run, and it carries no
+`readOnlyHint` for that reason.
+
 Writes also report `notApplied`: pointers whose value Payload kept unchanged,
 which happens when field-level access denies the update.
 
@@ -301,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:
@@ -356,30 +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.                                                                                           |
-
-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.
 
@@ -390,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,25 +89,38 @@ 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, tool.description));
+	const toolCheckboxes = options.tools.map((tool) => checkbox(tool.name, typeof tool.description === "string" ? tool.description : tool.name));
 	const groups = [
 		...collectionGroups.length > 0 ? [{
 			name: "collections",

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/{result.mjs → errors.mjs}

@@ -1,6 +1,8 @@
+import { errorResult } from "../result.mjs";
 import { pointerFromPayloadPath } from "../schema/walk.mjs";
+import "../schema/index.mjs";
 import { APIError, ValidationError } from "payload";
-//#region src/endpoint/result.ts
+//#region src/endpoint/errors.ts
 /**
 * A JSON-RPC error response for failures that happen before the MCP server
 * is involved (auth, method, body parsing).
@@ -20,25 +22,6 @@ import { APIError, ValidationError } from "payload";
 	});
 };
 /**
-* A successful tool result carrying `value` as JSON text.
-*/ const jsonResult = (value) => ({ content: [{
-	type: "text",
-	text: JSON.stringify(value)
-}] });
-/**
-* A failed tool result. `extras` travel alongside the message so the client
-* can act on them (problems, validation errors, the current `updatedAt`).
-*/ const errorResult = (message, extras = {}) => ({
-	content: [{
-		type: "text",
-		text: JSON.stringify({
-			error: message,
-			...extras
-		})
-	}],
-	isError: true
-});
-/**
 * Maps an exception thrown by a tool to a result the client can read.
 *
 * Payload's public errors keep their message and status; a `ValidationError`
@@ -62,4 +45,4 @@ import { APIError, ValidationError } from "payload";
 	return errorResult("Internal error");
 };
 //#endregion
-export { errorResult, jsonResult, jsonRpcError, toToolError };
+export { jsonRpcError, toToolError };

package/dist/endpoint/handler.mjs

@@ -1,5 +1,5 @@
-import { jsonRpcError } from "./result.mjs";
-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";
 import { WebStandardStreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/webStandardStreamableHttp.js";
@@ -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/endpoint/index.mjs

@@ -0,0 +1,4 @@
+import { jsonRpcError, toToolError } from "./errors.mjs";
+import { createMcpServer, isToolEnabled, toolDescription, toolInputSchema } from "./server.mjs";
+import { createMcpxHandler, methodNotAllowed } from "./handler.mjs";
+export { createMcpServer, createMcpxHandler, isToolEnabled, jsonRpcError, methodNotAllowed, toToolError, toolDescription, toolInputSchema };

package/dist/endpoint/server.mjs

@@ -1,5 +1,6 @@
-import { toToolError } from "./result.mjs";
-import { BUILTIN_TOOLS } from "../tools/index.mjs";
+import { toToolError } from "./errors.mjs";
+import { draftSentence } from "../tools/shared.mjs";
+import { BUILTIN_TOOLS } from "../tools/builtin.mjs";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { z } from "zod";
 //#region src/endpoint/server.ts
@@ -10,6 +11,10 @@ import { z } from "zod";
 * scope to narrow enums to what the key may touch.
 */ const toolInputSchema = (tool, scope) => z.strictObject(typeof tool.inputSchema === "function" ? tool.inputSchema(scope) : tool.inputSchema ?? {});
 /**
+* A tool's description, which may be built from the scope so it can name the
+* targets this key writes live.
+*/ const toolDescription = (tool, scope) => typeof tool.description === "function" ? tool.description(scope) : tool.description;
+/**
 * Whether the key may call the tool. A tool that does not decide for itself is
 * gated by its own checkbox on the key, which is how the tools from
 * `options.tools` work; the builtins derive it from the key's collection and
@@ -26,7 +31,7 @@ import { z } from "zod";
 	const server = new McpServer({
 		name: options.serverInfo.name,
 		version: options.serverInfo.version
-	}, { instructions: "Start with listCapabilities, then describeSchema for the collection or global you work on. Writes always land as drafts; a human publishes." });
+	}, { instructions: `Start with listCapabilities, then describeSchema for the collection or global you work on. ${draftSentence(scope)}` });
 	const guarded = (run) => async () => {
 		try {
 			return await run();
@@ -37,7 +42,7 @@ import { z } from "zod";
 	for (const tool of [...BUILTIN_TOOLS, ...options.tools]) {
 		if (!isToolEnabled(tool, scope)) continue;
 		server.registerTool(tool.name, {
-			description: tool.description,
+			description: toolDescription(tool, scope),
 			inputSchema: toolInputSchema(tool, scope),
 			...tool.annotations ? { annotations: tool.annotations } : {}
 		}, (args, extra) => guarded(() => tool.handler({
@@ -50,4 +55,4 @@ import { z } from "zod";
 	return server;
 };
 //#endregion
-export { createMcpServer, isToolEnabled, toolInputSchema };
+export { createMcpServer, isToolEnabled, toolDescription, toolInputSchema };

package/dist/index.d.mts

@@ -1,6 +1,5 @@
-import { errorResult, jsonResult } from "./endpoint/result.mjs";
-import { McpxAnyTool, McpxAuthResult, McpxCollectionCapabilities, McpxCollectionOptions, McpxExposedEntity, McpxGlobalOptions, McpxPluginOptions, McpxRequestContext, McpxResolvedCapabilities, McpxTool, McpxToolExtra, McpxToolScope, 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 "./write/draft-guard.mjs";
-import { PublishBlocker } from "./write/publish-blockers.mjs";
-export { type McpxAnyTool, type McpxAuthResult, type McpxCollectionCapabilities, type McpxCollectionOptions, type McpxExposedEntity, type McpxGlobalOptions, type McpxPluginOptions, type McpxRequestContext, type McpxResolvedCapabilities, type McpxTool, type McpxToolExtra, type McpxToolScope, type PublishBlocker, defineMcpxTool, errorResult, isMcpxRequest, jsonResult, mcpxPlugin };
+import { isMcpxRequest } from "./request.mjs";
+import { errorResult, jsonResult } from "./result.mjs";
+export { McpxAnyTool, McpxAuthResult, McpxCollectionCapabilities, McpxCollectionOptions, McpxExposedEntity, McpxGlobalOptions, McpxPluginOptions, McpxRequestContext, McpxResolvedCapabilities, McpxTool, McpxToolExtra, McpxToolScope, McpxWriteMode, PublishBlocker, defineMcpxTool, errorResult, isMcpxRequest, jsonResult, mcpxPlugin };

package/dist/index.mjs

@@ -1,5 +1,5 @@
-import { errorResult, jsonResult } from "./endpoint/result.mjs";
+import { errorResult, jsonResult } from "./result.mjs";
 import { defineMcpxTool } from "./types.mjs";
-import { isMcpxRequest } from "./write/draft-guard.mjs";
+import { isMcpxRequest } from "./request.mjs";
 import { mcpxPlugin } from "./plugin.mjs";
 export { 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/plugin.mjs

@@ -1,5 +1,6 @@
 import { createApiKeysCollection } from "./api-keys/collection.mjs";
 import { createMcpxHandler, methodNotAllowed } from "./endpoint/handler.mjs";
+import "./endpoint/index.mjs";
 import { normalizeOptions } from "./options.mjs";
 import { installDraftGuards, installGlobalDraftGuards } from "./write/draft-guard.mjs";
 import { definePlugin } from "payload";

package/dist/{write/draft-guard.d.mts → request.d.mts}

@@ -1,5 +1,5 @@
-import { CollectionConfig, PayloadRequest } from "payload";
-//#region src/write/draft-guard.d.ts
+import { PayloadRequest } from "payload";
+//#region src/request.d.ts
 /**
  * Whether a request originated from the MCP endpoint. The endpoint stamps
  * `req.context.mcpx`, which travels into every local API call made with the

package/dist/request.mjs

@@ -0,0 +1,8 @@
+//#region src/request.ts
+/**
+* Whether a request originated from the MCP endpoint. The endpoint stamps
+* `req.context.mcpx`, which travels into every local API call made with the
+* same `req`, including those made by custom tools.
+*/ const isMcpxRequest = (req) => req.context.mcpx !== void 0;
+//#endregion
+export { isMcpxRequest };

package/dist/{endpoint/result.d.mts → result.d.mts}

@@ -1,6 +1,5 @@
-import "payload";
 import { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
-//#region src/endpoint/result.d.ts
+//#region src/result.d.ts
 /**
  * A successful tool result carrying `value` as JSON text.
  */

package/dist/result.mjs

@@ -0,0 +1,22 @@
+//#region src/result.ts
+/**
+* A successful tool result carrying `value` as JSON text.
+*/ const jsonResult = (value) => ({ content: [{
+	type: "text",
+	text: JSON.stringify(value)
+}] });
+/**
+* A failed tool result. `extras` travel alongside the message so the client
+* can act on them (problems, validation errors, the current `updatedAt`).
+*/ const errorResult = (message, extras = {}) => ({
+	content: [{
+		type: "text",
+		text: JSON.stringify({
+			error: message,
+			...extras
+		})
+	}],
+	isError: true
+});
+//#endregion
+export { errorResult, jsonResult };

package/dist/schema/index.mjs

@@ -0,0 +1,6 @@
+import { allowedNodeTypes, lexicalSubSchema, nodeOptions, subSchemaNodeTypes } from "./lexical.mjs";
+import { JSON_POINTER_PATTERN, RESERVED_FIELD_NAMES, blockOf, blockSlugsOf, describeAddressableFields, describeFields, findBlocksField, findRichTextField, joinPath, pointerFromPayloadPath, splitPath, targetOf } from "./walk.mjs";
+import { nodeDescriber, reachableSchemaPaths } from "./describe.mjs";
+import { resolveDataPointer } from "./pointer.mjs";
+import { validateWriteValue } from "./shape.mjs";
+export { JSON_POINTER_PATTERN, RESERVED_FIELD_NAMES, allowedNodeTypes, blockOf, blockSlugsOf, describeAddressableFields, describeFields, findBlocksField, findRichTextField, joinPath, lexicalSubSchema, nodeDescriber, nodeOptions, pointerFromPayloadPath, reachableSchemaPaths, resolveDataPointer, splitPath, subSchemaNodeTypes, targetOf, validateWriteValue };