@abinnovision/payloadcms-mcpx 1.0.0-beta.8 → 1.0.0

package/dist/tools/{index.mjs → builtin.mjs}

@@ -4,12 +4,14 @@ 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/index.ts
+//#region src/tools/builtin.ts
 /**
-* The builtin tools in registration order. The surface is fixed: adding a
-* collection, block or field never changes it. Typed over `never` because
-* each tool validates its own arguments through its input schema.
+* The builtin tools, in registration order. Fixed: adding a collection, block
+* or field never changes the surface. They differ from a custom tool only in
+* `isEnabled`, which derives from the key's capabilities rather than a
+* checkbox of their own.
 */ const BUILTIN_TOOLS = [
 	listCapabilities,
 	describeSchema,
@@ -17,7 +19,8 @@ import { validateDocument } from "./validate-document.mjs";
 	getDocument,
 	patchDocument,
 	createDocument,
-	validateDocument
+	validateDocument,
+	publishDocument
 ];
 //#endregion
 export { BUILTIN_TOOLS };

package/dist/tools/create-document.mjs

@@ -1,45 +1,63 @@
-import { errorResult, jsonResult } from "../endpoint/result.mjs";
-import { localeOf, localeShape, readTarget, slugEnum } from "./shared.mjs";
-import { resolveTarget } from "./target.mjs";
+import { errorResult, jsonResult } from "../result.mjs";
 import { validateWriteValue } from "../schema/shape.mjs";
+import "../schema/index.mjs";
+import { draftSentence, localeOf, localeShape, patchOnlySlugs, readTarget, slugEnum, slugsFor } from "./shared.mjs";
+import { resolveTarget } from "./target.mjs";
+import { defineMcpxTool } from "../types.mjs";
 import { stripRowIds } from "../write/patch.mjs";
 import { collectPublishBlockers } from "../write/publish-blockers.mjs";
 import { z } from "zod";
 //#region src/tools/create-document.ts
-const createDocument = {
+/** Names the writable slugs this tool leaves out, so the gap reads as intent. */ const uploadSentence = (scope) => {
+	const slugs = patchOnlySlugs(scope);
+	return slugs.length === 0 ? "" : `\n\nLeft out of "collection" on purpose: ${slugs.join(", ")}. Those documents are files, and no tool here carries one. Upload the file in the admin panel, then edit its fields with patchDocument.`;
+};
+const DESCRIPTION = (scope) => `Creates a new document from a minimal seed. Only the fields describeSchema lists may appear in "data"; unknown keys are refused with the valid siblings, and "id" is Payload's to assign. The document may be incomplete: the response lists "publishBlockers", which patchDocument can then work through, and "publishBlockersUnavailable" when that check itself failed. Use this when no document exists yet; prefer patching an existing draft otherwise.
+
+${draftSentence(scope)}${uploadSentence(scope)}`;
+/**
+* Collection-only, because a global always exists, and never reaches an upload
+* collection, because a create there would have to carry the file.
+*
+* The seed is checked against the collection's fields before the create, so an
+* unknown key is refused with its valid siblings rather than dropped. Row ids
+* in the seed are stripped and a top-level `id` is refused outright. The new
+* document is re-read privileged afterwards to collect publish blockers, which
+* is why an incomplete seed still succeeds and comes back with a checklist.
+*/ const createDocument = defineMcpxTool({
 	name: "createDocument",
-	description: `Creates a new document as a draft from a minimal seed. Only the fields describeSchema lists may appear in "data"; unknown keys are refused with the valid siblings. The draft may be incomplete: the response lists "publishBlockers", which patchDocument can then work through. Use this when no document exists yet; prefer patching an existing draft otherwise.`,
+	description: DESCRIPTION,
 	annotations: {
 		readOnlyHint: false,
 		destructiveHint: false,
 		idempotentHint: false,
 		openWorldHint: false
 	},
-	isEnabled: (scope) => scope.writable.length > 0,
+	isEnabled: (scope) => slugsFor(scope, "create").collections.length > 0,
 	inputSchema: (scope) => ({
-		collection: slugEnum(scope.writable).describe("Collection to create the document in."),
+		collection: slugEnum(slugsFor(scope, "create").collections).describe("Collection to create the document in."),
 		...localeShape(scope, {
 			required: true,
 			description: "Locale the localized fields of the seed belong to."
 		}),
 		data: z.record(z.string(), z.unknown()).describe("Initial field values, as describeSchema lists them.")
 	}),
-	handler: async (args, scope) => {
-		const target = resolveTarget(scope, { collection: args.collection }, "write");
+	handler: async ({ args, scope }) => {
+		const target = resolveTarget(scope, { collection: args.collection }, "create");
 		const { payload } = scope.req;
 		const locale = localeOf(scope, args.locale);
-		const { id: _ignored, ...seed } = args.data;
+		if ("id" in args.data) return errorResult("Nothing was created.", { problems: ["/id: Payload assigns the id; it cannot be supplied."] });
 		const problems = validateWriteValue(payload.config, {
 			pointer: "",
 			resolution: {
 				fields: target.config.flattenedFields,
 				prefix: []
 			}
-		}, seed);
+		}, args.data);
 		if (problems.length > 0) return errorResult("Nothing was created.", { problems });
 		const created = await payload.create({
 			collection: args.collection,
-			data: stripRowIds(seed),
+			data: stripRowIds(args.data),
 			depth: 0,
 			draft: true,
 			overrideAccess: false,
@@ -52,7 +70,7 @@ const createDocument = {
 			locale,
 			privileged: true
 		});
-		const publishBlockers = await collectPublishBlockers(scope.req, {
+		const validation = await collectPublishBlockers(scope.req, {
 			doc: saved,
 			entity: target
 		});
@@ -60,9 +78,10 @@ const createDocument = {
 			id: saved["id"],
 			status: saved["_status"],
 			updatedAt: saved["updatedAt"],
-			...publishBlockers.length > 0 ? { publishBlockers } : {}
+			...validation.blockers.length > 0 ? { publishBlockers: validation.blockers } : {},
+			...validation.unavailable ? { publishBlockersUnavailable: true } : {}
 		});
 	}
-};
+});
 //#endregion
 export { createDocument };

package/dist/tools/describe-schema.mjs

@@ -1,11 +1,19 @@
+import { jsonResult } from "../result.mjs";
+import { nodePropertiesFor } from "../schema/lexical.mjs";
 import { translatorFor } from "../i18n.mjs";
-import { jsonResult } from "../endpoint/result.mjs";
+import { nodeDescriber, reachableSchemaPaths } from "../schema/describe.mjs";
+import "../schema/index.mjs";
 import { targetShape } from "./shared.mjs";
 import { refOf, resolveTarget } from "./target.mjs";
-import { nodeDescriber, reachableSchemaPaths } from "../schema/describe.mjs";
+import { defineMcpxTool } from "../types.mjs";
 import { z } from "zod";
-//#region src/tools/describe-schema.ts
-const describeSchema = {
+/**
+* Describes each requested path independently and returns a per
+* path error object instead of failing the call, so a client exploring several
+* branches at once keeps the nodes that did resolve. `expand` swaps the
+* requested paths for every node reachable from the root and appends a
+* truncation notice past {@link REACHABLE_PATHS_LIMIT}.
+*/ const describeSchema = defineMcpxTool({
 	name: "describeSchema",
 	description: `Describes the writable shape of a document, one node at a time.
 
@@ -15,7 +23,11 @@ Call it with no "paths" to get a collection's own fields. Every "blocks" field s
 
 A "richText" field stops there too. It lists the Lexical node types it accepts in "nodes", and "next" carries a path for every node type that holds fields of its own: "/content/link" for a link node, "/content/block/callout" and "/content/inlineBlock/badge" for the block nodes. Descend to get the real field list instead of guessing what a node carries. Upload nodes are not addressable, because their fields depend on the collection the node points at.
 
-Paths here use the same JSON Pointer syntax as getDocument and patchDocument, and are already resolved through anything that does not nest in the stored document. The difference is only what stands in an element position: a path names an array element "*" and a block by its slug, where a pointer into a document carries a 0-based index. So "/items/*/title" is written at "/items/0/title", and "/layout/sections/hero" at "/layout/sections/0".
+Write each Lexical node the way Lexical serializes it, with every property its type carries rather than a trimmed subset, and with the value Lexical would have written there. Those requirements are stated rather than left to be discovered: the response carries one final "nodeProperties" entry keyed by node type, naming each property and what belongs there in the same words a refused write uses, so a node can be built from this response alone. A field's own "nodes" says which of those types it accepts. The root takes exactly "children", "direction", "format", "indent", "type" and "version" and refuses anything else. The admin editor rehydrates nodes through their classes, so a list item whose "indent" is missing, null or a string is stored and then throws on open, and a heading whose "tag" is a number is stored untagged. A write naming a property means exactly that. A state whose root holds no children is refused however it is written, because Lexical reads it as empty and throws; clear a field with null instead.
+
+A rich text field's value is addressable too, so an edit does not have to rewrite the whole state: "/content/root/children/0" is the first top-level node, "/content/root/children/0/children/1" a node inside it, "/content/root/children/0/tag" one property of a node, and "/content/root/children/0/fields/url" a field of a node, described at the "next" path for that node type. Append a node with "/-". Which node sits at an index is only knowable from what is stored, so read it first: getDocument with "outline" answers with the pointer, type, "version" and a text excerpt for every node, which is far cheaper than reading the whole state.
+
+Paths here use the same JSON Pointer syntax as getDocument and patchDocument, and are already resolved through anything that does not nest in the stored document. The difference is only what stands in an element position: a path names an array element "*" and a block by its slug, where a pointer into a document carries a 0-based index. So "/items/*/title" is written at "/items/0/title", and "/layout/sections/hero" at "/layout/sections/0". Inside a rich text field that substitution does not apply: a path there names the node type, and a block node its slug, where a pointer enters the stored state at "root" and walks "children" by an index counted over every child at that level, not over the blocks among them, with the node's own fields under "fields". So "/content/block/practice-note/variant" is written at "/content/root/children/7/fields/variant".
 
 Fields Payload maintains (id, _status, createdAt, updatedAt) are never listed and cannot be written. Fields marked readOnly are listed but refused on write.`,
 	annotations: {
@@ -31,7 +43,7 @@ Fields Payload maintains (id, _status, createdAt, updatedAt) are never listed an
 		paths: z.array(z.string()).optional().describe("Schema paths to describe, e.g. \"/layout/sections/sectionWrapper\". Omit for the collection root."),
 		expand: z.boolean().optional().describe("Return every node reachable from the root in one response. Ignores paths.")
 	}),
-	handler: (args, scope) => {
+	handler: ({ args, scope }) => {
 		const ref = refOf(resolveTarget(scope, args, "read"));
 		const { config } = scope.req.payload;
 		const describeNode = nodeDescriber(translatorFor(scope.req.i18n));
@@ -46,9 +58,11 @@ Fields Payload maintains (id, _status, createdAt, updatedAt) are never listed an
 				};
 			}
 		});
+		const nodeTypes = nodes.flatMap((node) => (node.fields ?? []).flatMap((field) => field.nodes ?? []));
+		if (nodeTypes.length > 0) nodes.push({ nodeProperties: nodePropertiesFor(nodeTypes) });
 		if (expanded?.truncated) nodes.push({ error: `Result truncated after ${String(400)} nodes. Request explicit paths instead.` });
 		return Promise.resolve(jsonResult(nodes));
 	}
-};
+});
 //#endregion
 export { describeSchema };

package/dist/tools/find-documents.mjs

@@ -1,9 +1,16 @@
-import { jsonResult } from "../endpoint/result.mjs";
+import { jsonResult } from "../result.mjs";
 import { depthShape, localeOf, localeShape, slugEnum } from "./shared.mjs";
 import { resolveTarget } from "./target.mjs";
+import { defineMcpxTool } from "../types.mjs";
 import { z } from "zod";
-//#region src/tools/find-documents.ts
-const findDocuments = {
+/**
+* Collection-only: a global is a singleton, so there is nothing to list.
+*
+* The query goes to Payload with `overrideAccess: false`, so the collection's
+* own access control decides what comes back. `limit` and `depth` are bounded
+* by the configured limits in the schema itself, which puts the ceiling in
+* front of the client rather than silently clamping behind it.
+*/ const findDocuments = defineMcpxTool({
 	name: "findDocuments",
 	description: `Finds documents in a collection. "where" is a Payload query object, e.g. {"title":{"contains":"home"}} or {"and":[...]}; "select" picks fields, e.g. {"title":true}. Drafts are included by default so unpublished work is visible. Keep depth at 0 unless populated relationships are needed; ids are enough for writes.`,
 	annotations: {
@@ -15,7 +22,7 @@ const findDocuments = {
 		collection: slugEnum(scope.readable).describe("Collection to search."),
 		where: z.record(z.string(), z.unknown()).optional().describe("Payload where query."),
 		sort: z.string().optional().describe("Sort field, prefix with \"-\" for descending."),
-		limit: z.number().int().min(1).max(scope.options.limits.maxLimit).optional().describe(`Documents per page. Default 10, at most ${String(scope.options.limits.maxLimit)}.`),
+		limit: z.number().int().min(1).max(scope.limits.maxLimit).optional().describe(`Documents per page. Default 10, at most ${String(scope.limits.maxLimit)}.`),
 		page: z.number().int().min(1).optional().describe("Page number, from 1."),
 		...depthShape(scope),
 		select: z.record(z.string(), z.unknown()).optional().describe("Fields to return, e.g. {\"title\":true}."),
@@ -25,7 +32,7 @@ const findDocuments = {
 		}),
 		draft: z.boolean().optional().describe("Include the latest drafts. Default true.")
 	}),
-	handler: async (args, scope) => {
+	handler: async ({ args, scope }) => {
 		resolveTarget(scope, { collection: args.collection }, "read");
 		const locale = localeOf(scope, args.locale);
 		const result = await scope.req.payload.find({
@@ -50,6 +57,6 @@ const findDocuments = {
 			hasNextPage: result.hasNextPage
 		});
 	}
-};
+});
 //#endregion
 export { findDocuments };

package/dist/tools/get-document.mjs

@@ -1,15 +1,26 @@
-import { JSON_POINTER_PATTERN } from "../schema/walk.mjs";
-import { errorResult, jsonResult } from "../endpoint/result.mjs";
+import { errorResult, jsonResult } from "../result.mjs";
+import { JSON_POINTER_PATTERN, findRichTextField, splitPath } from "../schema/walk.mjs";
+import { lexicalOutline } from "../schema/outline.mjs";
+import { resolveDataPointer } from "../schema/pointer.mjs";
+import "../schema/index.mjs";
 import { depthShape, idShape, localeOf, localeShape, targetShape } from "./shared.mjs";
-import { requireIdFor, resolveTarget } from "./target.mjs";
+import { refOf, requireIdFor, resolveTarget } from "./target.mjs";
+import { defineMcpxTool } from "../types.mjs";
 import { z } from "zod";
 import { Pointer } from "rfc6902";
 //#region src/tools/get-document.ts
-const getDocument = {
+const OUTLINE_ERROR = "\"outline\" applies to a rich text field; give \"path\" for one.";
+/**
+* With `path` the handler returns the subtree plus the `id`, `_status` and
+* `updatedAt` a client needs to write back, so a caller reading one branch
+* still gets the timestamp `expectedUpdatedAt` wants without a second call.
+*/ const getDocument = defineMcpxTool({
 	name: "getDocument",
 	description: `Reads one document, or one subtree of it when "path" is given as a JSON pointer such as "/layout/sections/2". Returns the latest draft by default. Read before patching: the response carries "updatedAt" for expectedUpdatedAt and the indices pointers need.
 
-Pass exactly one of "collection" and "global". "id" is required with "collection" and must be omitted with "global", because a global is a singleton.`,
+Pass exactly one of "collection" and "global". "id" is required with "collection" and must be omitted with "global", because a global is a singleton.
+
+Set "outline" on a rich text "path" to get a compact positional listing of its nodes instead of the raw editor state.`,
 	annotations: {
 		readOnlyHint: true,
 		openWorldHint: false
@@ -27,9 +38,10 @@ Pass exactly one of "collection" and "global". "id" is required with "collection
 			required: false,
 			description: "Locale to read. Defaults to the default locale."
 		}),
-		draft: z.boolean().optional().describe("Return the latest draft. Default true.")
+		draft: z.boolean().optional().describe("Return the latest draft. Default true."),
+		outline: z.boolean().optional().describe("For a rich text field, return a compact positional outline instead of the editor state. Requires \"path\".")
 	}),
-	handler: async (args, scope) => {
+	handler: async ({ args, scope }) => {
 		const target = resolveTarget(scope, args, "read");
 		const id = requireIdFor(target, args.id);
 		const locale = localeOf(scope, args.locale);
@@ -48,21 +60,43 @@ Pass exactly one of "collection" and "global". "id" is required with "collection
 			...shared,
 			slug: target.slug
 		}));
-		if (args.path === void 0 || args.path === "") return jsonResult(doc);
+		if (args.path === void 0 || args.path === "") {
+			if (args.outline) return errorResult(OUTLINE_ERROR);
+			return jsonResult(doc);
+		}
 		let value;
 		try {
 			value = Pointer.fromJSON(args.path).get(doc);
 		} catch {
 			return errorResult(`"${args.path}" is not a valid JSON pointer.`);
 		}
-		return jsonResult({
+		const envelope = {
 			...target.kind === "collection" ? { id: doc["id"] } : { global: target.slug },
 			status: doc["_status"],
 			updatedAt: doc["updatedAt"],
-			path: args.path,
+			path: args.path
+		};
+		if (!args.outline) return jsonResult({
+			...envelope,
 			value
 		});
+		let resolution;
+		try {
+			resolution = resolveDataPointer(scope.req.payload.config, {
+				doc,
+				pointer: args.path,
+				ref: refOf(target)
+			});
+		} catch (error) {
+			return errorResult(error instanceof Error ? error.message : OUTLINE_ERROR);
+		}
+		const field = resolution.descriptor?.type === "richText" && !resolution.lexical ? findRichTextField(resolution.fields, splitPath(resolution.descriptor.path)) : void 0;
+		if (!field) return errorResult(OUTLINE_ERROR);
+		return jsonResult({
+			...envelope,
+			outline: lexicalOutline(value, args.path, field)
+		});
 	}
-};
+});
 //#endregion
 export { getDocument };

package/dist/tools/list-capabilities.mjs

@@ -1,11 +1,18 @@
+import { canCreate } from "../capabilities.mjs";
+import { jsonResult } from "../result.mjs";
 import { translatorFor } from "../i18n.mjs";
-import { jsonResult } from "../endpoint/result.mjs";
 import { translateLabel } from "./shared.mjs";
+import { defineMcpxTool } from "../types.mjs";
 import { hasDraftValidationEnabled } from "payload/shared";
-//#region src/tools/list-capabilities.ts
-const listCapabilities = {
+/**
+* Registered for every key, including one with no capabilities ticked, so a
+* client always has something to call and gets an empty surface described
+* rather than an empty tool list. The response is assembled from the request
+* scope and the sanitized config, never from the content model, so it stays the
+* same size as a deployment grows.
+*/ const listCapabilities = defineMcpxTool({
 	name: "listCapabilities",
-	description: `Lists what this key may do: the collections and globals it can read or write, their draft behaviour and id type, the configured locales, the limits in force and the custom tools available. Call it first to orient; nothing here changes with the content model.
+	description: `Lists what this key may do: the collections and globals it can read or write, whether a collection can also be created in, their draft behaviour and id type, the configured locales, the limits in force and the custom tools available. Call it first to orient; nothing here changes with the content model.
 
 A global is a singleton: it has no id, is not listed by findDocuments and cannot be created. Address one with the "global" argument where a collection document would take "collection" and "id".`,
 	annotations: {
@@ -14,10 +21,10 @@ A global is a singleton: it has no id, is not listed by findDocuments and cannot
 	},
 	isEnabled: () => true,
 	inputSchema: () => ({}),
-	handler: (_args, scope) => {
+	handler: ({ scope }) => {
 		const { payload } = scope.req;
 		const translate = translatorFor(scope.req.i18n);
-		const collections = scope.options.collections.flatMap((entry) => {
+		const collections = scope.exposure.collections.flatMap((entry) => {
 			const capability = scope.capabilities.collections[entry.slug];
 			const collection = payload.collections[entry.slug];
 			if (!capability || !collection || !(capability.read || capability.write)) return [];
@@ -32,12 +39,14 @@ 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,
+				create: capability.write && canCreate(entry),
+				publish: capability.publish,
 				drafts: entry.hasDrafts,
 				draftValidation: hasDraftValidationEnabled(config),
 				idType: collection.customIDType ?? payload.db.defaultIDType
 			}];
 		});
-		const globals = scope.options.globals.flatMap((entry) => {
+		const globals = scope.exposure.globals.flatMap((entry) => {
 			const capability = scope.capabilities.globals[entry.slug];
 			const config = payload.globals.config.find((candidate) => candidate.slug === entry.slug);
 			if (!capability || !config || !(capability.read || capability.write)) return [];
@@ -48,6 +57,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)
 			}];
@@ -59,10 +69,10 @@ A global is a singleton: it has no id, is not listed by findDocuments and cannot
 				codes: scope.locales,
 				default: scope.defaultLocale
 			} : null,
-			limits: scope.options.limits,
+			limits: scope.limits,
 			tools: Object.entries(scope.capabilities.tools).filter(([, enabled]) => enabled).map(([name]) => name)
 		}));
 	}
-};
+});
 //#endregion
 export { listCapabilities };

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,24 +1,28 @@
-import { errorResult, jsonResult } from "../endpoint/result.mjs";
-import { idShape, localeOf, localeShape, readTarget, targetShape } from "./shared.mjs";
+import { errorResult, jsonResult } from "../result.mjs";
+import { draftSentence, idShape, localeOf, localeShape, readTarget, sameInstant, targetShape } from "./shared.mjs";
 import { refOf, requireIdFor, resolveTarget } from "./target.mjs";
-import { PATCH_OPERATION_SCHEMA, applyPatchToCopy, buildWriteData, findPatchProblems, isElementPointer } from "../write/patch.mjs";
+import { defineMcpxTool } from "../types.mjs";
+import { PATCH_OPERATION_SCHEMA, applyPatchOperations, buildWriteData, isElementPointer } from "../write/patch.mjs";
 import { collectPublishBlockers } from "../write/publish-blockers.mjs";
 import { withTransaction } from "../write/transaction.mjs";
 import { z } from "zod";
 import { Pointer } from "rfc6902";
 //#region src/tools/patch-document.ts
-const DESCRIPTION = `Applies RFC 6902 JSON Patch operations to one document.
+const DESCRIPTION = (scope) => `Applies RFC 6902 JSON Patch operations to one document.
 
 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 write always lands as a draft and is never published, whatever it contains; publishing stays a human action in the admin panel.
+${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.
+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. Inside a rich text field that substitution does not apply: a path there names the node type, and a block node its slug, where a pointer enters the stored state at "root" and walks "children" by an index counted over every child at that level, not over the blocks among them, with the node's own fields under "fields". So "/content/block/practice-note/variant" is written at "/content/root/children/7/fields/variant".
 
-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.`;
-const sameInstant = (left, right) => typeof left === "string" && new Date(left).getTime() === new Date(right).getTime();
+Inside a rich text field a pointer keeps going: "/content/root/children/2" is a node, "/content/root/children/2/tag" one of its properties, and "/content/root/children/2/fields/url" a field it carries. A node written at a position must carry everything Lexical serializes, "version" included, exactly as one written inside a whole state must; getDocument with "outline" returns each node's pointer and version, which is the cheapest way to get both right. A node's "type" cannot be replaced on its own, and neither can the root.
+
+Node positions shift as soon as anything is added or removed, so read immediately before patching, order removals from the last index to the first, and use a "test" operation on "/content/root/children/2/type" to assert a position is what you think it is before writing to it.
+
+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
@@ -42,12 +46,18 @@ const isPlainObject = (value) => typeof value === "object" && value !== null &&
 	const actual = pointer.get(saved);
 	return survives(expected, actual) ? [] : [operation.path];
 });
-const patchDocument = {
+/**
+* The handler validates the whole batch against the schema and the current
+* document before it writes anything, runs the write in a transaction, then
+* re-reads the saved document to report which pointers survived and what still
+* blocks publishing. Nothing here decides where the write lands: the draft
+* guard does that on the Payload operation.
+*/ const patchDocument = defineMcpxTool({
 	name: "patchDocument",
 	description: DESCRIPTION,
 	annotations: {
 		readOnlyHint: false,
-		destructiveHint: false,
+		destructiveHint: true,
 		idempotentHint: false,
 		openWorldHint: false
 	},
@@ -63,13 +73,14 @@ const patchDocument = {
 			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) => {
+	handler: async ({ args, scope }) => {
 		const target = resolveTarget(scope, args, "write");
 		const id = requireIdFor(target, args.id);
 		const { payload } = scope.req;
 		const locale = localeOf(scope, args.locale);
+		const patches = args.patches;
 		return await withTransaction(scope.req, async () => {
 			const doc = await readTarget(scope, {
 				target,
@@ -77,13 +88,11 @@ const patchDocument = {
 				locale
 			});
 			if (args.expectedUpdatedAt !== void 0 && !sameInstant(doc["updatedAt"], args.expectedUpdatedAt)) return errorResult("The document changed since you read it. Read it again and re-apply the patch.", { updatedAt: doc["updatedAt"] });
-			const problems = findPatchProblems(payload.config, {
+			const applied = applyPatchOperations(payload.config, {
 				doc,
-				patches: args.patches,
+				patches,
 				ref: refOf(target)
 			});
-			if (problems.length > 0) return errorResult("No operation was applied.", { problems });
-			const applied = applyPatchToCopy(doc, args.patches);
 			if ("problems" in applied) return errorResult("No operation was applied.", { problems: applied.problems });
 			const write = {
 				data: buildWriteData(payload.config, target.config, applied.next),
@@ -100,6 +109,7 @@ const patchDocument = {
 			});
 			else await payload.updateGlobal({
 				...write,
+				fallbackLocale: false,
 				slug: target.slug
 			});
 			const saved = await readTarget(scope, {
@@ -108,8 +118,8 @@ const patchDocument = {
 				locale,
 				privileged: true
 			});
-			const notApplied = notAppliedPointers(args.patches, applied.next, saved);
-			const publishBlockers = await collectPublishBlockers(scope.req, {
+			const notApplied = notAppliedPointers(patches, applied.next, saved);
+			const validation = await collectPublishBlockers(scope.req, {
 				doc: saved,
 				entity: target
 			});
@@ -117,11 +127,12 @@ const patchDocument = {
 				...target.kind === "collection" ? { id: saved["id"] } : { global: target.slug },
 				status: saved["_status"],
 				updatedAt: saved["updatedAt"],
-				...publishBlockers.length > 0 ? { publishBlockers } : {},
+				...validation.blockers.length > 0 ? { publishBlockers: validation.blockers } : {},
+				...validation.unavailable ? { publishBlockersUnavailable: true } : {},
 				...notApplied.length > 0 ? { notApplied } : {}
 			});
 		});
 	}
-};
+});
 //#endregion
 export { patchDocument };

package/dist/tools/publish-document.mjs

@@ -0,0 +1,79 @@
+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";
+/**
+* The only tool that changes live content, available where the config sets
+* `write: "live"` on a versioned entity and the key has both the `write` and
+* `publish` checkboxes.
+*/ 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: withPublishIntent({}),
+				depth: 0,
+				draft: false,
+				fallbackLocale: false,
+				overrideAccess: false,
+				req: scope.req,
+				...locale === void 0 ? {} : { locale }
+			};
+			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 };