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

package/dist/schema/pointer.mjs

@@ -43,7 +43,7 @@ const partMatches = (part, segment) => segment !== void 0 && (part === "*" ? isI
 			if (isSubtreePrefix(descriptors, segments)) return {
 				...blockType === void 0 ? {} : { blockType },
 				fields,
-				prefix: segments
+				prefix: segments.map((segment) => isIndexSegment(segment) ? "*" : segment)
 			};
 			throw new Error(`"${joinPath(segments)}" is not a field here. Available: ${descriptors.map((descriptor) => descriptor.path).join(", ")}`);
 		}

package/dist/schema/walk.mjs

@@ -83,7 +83,7 @@ const withRows = (descriptor, field) => ({
 * Whether a descriptor stands for a construct that only holds other fields.
 *
 * These describe a position rather than a value, so everything that resolves a
-* path to something writable skips them; only {@link describeNode} reports
+* path to something writable skips them; only {@link nodeDescriber} reports
 * them, to carry what the container itself declares.
 */ const isContainer = (descriptor) => descriptor.type === "array" || descriptor.type === "group" || descriptor.type === "tab";
 /**
@@ -133,29 +133,25 @@ const withRows = (descriptor, field) => ({
 /**
 * The descriptors that address a value, which is what every walk resolving a
 * path against a document needs. A container describes a position rather than
-* a value, so only {@link describeNode} reports one.
+* a value, so only {@link nodeDescriber} reports one.
 */ const describeAddressableFields = (fields) => describeFields(fields).filter((descriptor) => !isContainer(descriptor));
 /**
-* Locates the blocks field that a resolved descriptor path refers to.
-*/ const findBlocksField = (fields, path) => {
+* Locates the field of `type` that a resolved descriptor path refers to.
+*/ const findFieldAt = (fields, path, type) => {
 	for (const field of fields) {
 		if (!("name" in field) || field.name !== path[0]) continue;
-		if (field.type === "blocks" && path.length === 1) return field;
-		if (field.type === "tab" || field.type === "group") return findBlocksField(field.flattenedFields, path.slice(1));
-		if (field.type === "array" && path[1] === "*") return findBlocksField(field.flattenedFields, path.slice(2));
+		if (field.type === type && path.length === 1) return field;
+		if (field.type === "tab" || field.type === "group") return findFieldAt(field.flattenedFields, path.slice(1), type);
+		if (field.type === "array" && path[1] === "*") return findFieldAt(field.flattenedFields, path.slice(2), type);
 	}
 };
 /**
+* Locates the blocks field that a resolved descriptor path refers to.
+*/ const findBlocksField = (fields, path) => findFieldAt(fields, path, "blocks");
+/**
 * Locates the rich text field that a resolved descriptor path refers to, so
 * its editor can be introspected for the fields its nodes carry.
-*/ const findRichTextField = (fields, path) => {
-	for (const field of fields) {
-		if (!("name" in field) || field.name !== path[0]) continue;
-		if (field.type === "richText" && path.length === 1) return field;
-		if (field.type === "tab" || field.type === "group") return findRichTextField(field.flattenedFields, path.slice(1));
-		if (field.type === "array" && path[1] === "*") return findRichTextField(field.flattenedFields, path.slice(2));
-	}
-};
+*/ const findRichTextField = (fields, path) => findFieldAt(fields, path, "richText");
 const targetOf = (config, ref) => {
 	const found = ref.kind === "collection" ? config.collections.find((candidate) => candidate.slug === ref.slug) : config.globals.find((candidate) => candidate.slug === ref.slug);
 	if (!found) throw new Error(`Unknown ${ref.kind} "${ref.slug}".`);

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

@@ -4,8 +4,9 @@ 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. They are ordinary {@link McpxTool}s
 * that ship with the plugin and register through the same loop as the tools
@@ -20,7 +21,8 @@ import { validateDocument } from "./validate-document.mjs";
 	getDocument,
 	patchDocument,
 	createDocument,
-	validateDocument
+	validateDocument,
+	publishDocument
 ];
 //#endregion
 export { BUILTIN_TOOLS };

package/dist/tools/create-document.mjs

@@ -1,15 +1,19 @@
-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, readTarget, slugEnum } 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 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)}`;
 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,
@@ -29,18 +33,18 @@ const createDocument = defineMcpxTool({
 		const target = resolveTarget(scope, { collection: args.collection }, "write");
 		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,
@@ -53,7 +57,7 @@ const createDocument = defineMcpxTool({
 			locale,
 			privileged: true
 		});
-		const publishBlockers = await collectPublishBlockers(scope.req, {
+		const validation = await collectPublishBlockers(scope.req, {
 			doc: saved,
 			entity: target
 		});
@@ -61,7 +65,8 @@ const createDocument = defineMcpxTool({
 			id: saved["id"],
 			status: saved["_status"],
 			updatedAt: saved["updatedAt"],
-			...publishBlockers.length > 0 ? { publishBlockers } : {}
+			...validation.blockers.length > 0 ? { publishBlockers: validation.blockers } : {},
+			...validation.unavailable ? { publishBlockersUnavailable: true } : {}
 		});
 	}
 });

package/dist/tools/describe-schema.mjs

@@ -1,11 +1,11 @@
+import { jsonResult } from "../result.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 { defineMcpxTool } from "../types.mjs";
-import { nodeDescriber, reachableSchemaPaths } from "../schema/describe.mjs";
 import { z } from "zod";
-//#region src/tools/describe-schema.ts
 const describeSchema = defineMcpxTool({
 	name: "describeSchema",
 	description: `Describes the writable shape of a document, one node at a time.

package/dist/tools/find-documents.mjs

@@ -1,9 +1,8 @@
-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 = 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.`,

package/dist/tools/get-document.mjs

@@ -1,11 +1,11 @@
+import { errorResult, jsonResult } from "../result.mjs";
 import { JSON_POINTER_PATTERN } from "../schema/walk.mjs";
-import { errorResult, jsonResult } from "../endpoint/result.mjs";
+import "../schema/index.mjs";
 import { depthShape, idShape, localeOf, localeShape, targetShape } from "./shared.mjs";
 import { 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 = 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.

package/dist/tools/list-capabilities.mjs

@@ -1,9 +1,8 @@
+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 = 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.
@@ -33,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
@@ -49,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,25 +1,24 @@
-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 { defineMcpxTool } from "../types.mjs";
-import { PATCH_OPERATION_SCHEMA, applyPatchToCopy, buildWriteData, findPatchProblems, isElementPointer } from "../write/patch.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.
 
-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();
+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
@@ -48,7 +47,7 @@ const patchDocument = defineMcpxTool({
 	description: DESCRIPTION,
 	annotations: {
 		readOnlyHint: false,
-		destructiveHint: false,
+		destructiveHint: true,
 		idempotentHint: false,
 		openWorldHint: false
 	},
@@ -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");
@@ -79,13 +78,11 @@ const patchDocument = defineMcpxTool({
 				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,
 				ref: refOf(target)
 			});
-			if (problems.length > 0) return errorResult("No operation was applied.", { problems });
-			const applied = applyPatchToCopy(doc, patches);
 			if ("problems" in applied) return errorResult("No operation was applied.", { problems: applied.problems });
 			const write = {
 				data: buildWriteData(payload.config, target.config, applied.next),
@@ -102,6 +99,7 @@ const patchDocument = defineMcpxTool({
 			});
 			else await payload.updateGlobal({
 				...write,
+				fallbackLocale: false,
 				slug: target.slug
 			});
 			const saved = await readTarget(scope, {
@@ -111,7 +109,7 @@ const patchDocument = defineMcpxTool({
 				privileged: true
 			});
 			const notApplied = notAppliedPointers(patches, applied.next, saved);
-			const publishBlockers = await collectPublishBlockers(scope.req, {
+			const validation = await collectPublishBlockers(scope.req, {
 				doc: saved,
 				entity: target
 			});
@@ -119,7 +117,8 @@ const patchDocument = defineMcpxTool({
 				...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 } : {}
 			});
 		});

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,18 +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.");
+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)];
+};
+/**
+* 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);
+	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.
 *
@@ -99,4 +144,4 @@ const depthShape = (scope) => ({ depth: z.number().int().min(0).max(scope.limits
 	return translateStatic(resolved, i18n) ?? fallback;
 };
 //#endregion
-export { depthShape, idSchema, idShape, 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/tools/validate-document.mjs

@@ -1,18 +1,16 @@
-import { jsonResult } from "../endpoint/result.mjs";
+import { jsonResult } from "../result.mjs";
 import { idShape, localeOf, localeShape, readTarget, targetShape } from "./shared.mjs";
 import { requireIdFor, resolveTarget } from "./target.mjs";
 import { defineMcpxTool } from "../types.mjs";
 import { collectPublishBlockers } from "../write/publish-blockers.mjs";
-//#region src/tools/validate-document.ts
 const validateDocument = defineMcpxTool({
 	name: "validateDocument",
 	description: `Reports what still prevents a human from publishing the draft, without writing anything. The same list patchDocument returns after a write; use it to check work or to answer "is this ready".
 
-Pass exactly one of "collection" and "global". "id" is required with "collection" and must be omitted with "global", because a global is a singleton.`,
-	annotations: {
-		readOnlyHint: true,
-		openWorldHint: false
-	},
+Pass exactly one of "collection" and "global". "id" is required with "collection" and must be omitted with "global", because a global is a singleton.
+
+Nothing is written, but the check runs the same field-level beforeValidate and beforeChange hooks a save would, so a hook with side effects fires. "publishBlockersUnavailable" means the check itself failed, so the empty list says nothing.`,
+	annotations: { openWorldHint: false },
 	isEnabled: (scope) => scope.writable.length + scope.writableGlobals.length > 0,
 	inputSchema: (scope) => ({
 		...targetShape(scope, "write", {
@@ -40,7 +38,7 @@ Pass exactly one of "collection" and "global". "id" is required with "collection
 			locale,
 			privileged: true
 		});
-		const publishBlockers = await collectPublishBlockers(scope.req, {
+		const validation = await collectPublishBlockers(scope.req, {
 			doc,
 			entity: target
 		});
@@ -48,7 +46,8 @@ Pass exactly one of "collection" and "global". "id" is required with "collection
 			...target.kind === "collection" ? { id: doc["id"] } : { global: target.slug },
 			status: doc["_status"],
 			updatedAt: doc["updatedAt"],
-			publishBlockers
+			publishBlockers: validation.blockers,
+			...validation.unavailable ? { publishBlockersUnavailable: true } : {}
 		});
 	}
 });