@abinnovision/payloadcms-mcpx 1.1.0-beta.6 → 2.0.0-beta.7

package/dist/tools/get-document.mjs

@@ -1,28 +1,31 @@
+import { defineMcpxTool } from "../define-tool.mjs";
 import { errorResult, jsonResult } from "../result.mjs";
-import { JSON_POINTER_PATTERN, findRichTextField, splitPath } from "../schema/walk.mjs";
+import { JSON_POINTER_PATTERN, prototypeSegmentProblem, splitPath } from "../schema/path.mjs";
+import { findRichTextField } from "../schema/walk.mjs";
+import { SchemaError } from "../schema/errors.mjs";
 import { lexicalOutline } from "../schema/outline.mjs";
 import { resolveDataPointer } from "../schema/pointer.mjs";
 import "../schema/index.mjs";
-import { depthShape, idSchema, idShape, localeOf, localeShape, slugsFor, targetShape } from "./shared.mjs";
-import { refOf, requireIdFor, resolveTarget } from "./target.mjs";
-import { defineMcpxTool } from "../types.mjs";
+import { READ_LOCALE_DESCRIPTION, depthShape, entityShape, idSchema, idShape, localeOf, localeShape, slugsFor, widen } from "./shared.mjs";
+import { identityOf, resolveDocument } from "./document.mjs";
 import { diffDocuments, loadPublished, loadVersion, readLive } from "./versions.mjs";
 import { APIError } from "payload";
 import { z } from "zod";
 import { Pointer } from "rfc6902";
 //#region src/tools/get-document.ts
 const OUTLINE_ERROR = "\"outline\" applies to a rich text field; give \"path\" for one.";
-const 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.
+const VERSION_PARAGRAPH = `
 
-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.
-
-On an entity with versions, "versionId" (from findVersions) reads that version instead. "diffFrom" returns the RFC 6902 operations turning a version, or "published" (the newest version with published status, regardless of locale), into the document read, in the pointer syntax patchDocument takes and limited to "path" when given. To revert, pass the old version as "versionId" and the latest one from findVersions as "diffFrom", then apply the patch with patchDocument.`;
-/** Refuses `versionId` and `diffFrom` where they cannot apply. */ const assertVersionArgs = (scope, target, args) => {
+"versionId" and "diffFrom" work where findVersions does. To revert, call getDocument with the old version as "versionId", the version findVersions marks "latest" as "diffFrom" and the locale you will write, then apply the returned "patch" with patchDocument.`;
+const DESCRIPTION = `Reads one document or global, or with "path" only the value at that pointer. Returns the latest draft by default, with the "updatedAt" a write takes as "expectedUpdatedAt".`;
+const exposesVersions = (scope) => {
+	const { collections, globals } = slugsFor(scope, "versions");
+	return collections.length + globals.length > 0;
+};
+const assertVersionArgs = (scope, target, args) => {
 	if (args.versionId === void 0 && args.diffFrom === void 0) return;
 	const { collections, globals } = slugsFor(scope, "versions");
-	if (!(target.kind === "collection" ? collections : globals).includes(target.slug)) throw new APIError(`"${target.slug}" keeps no versions.`, 400);
+	if (!(target.kind === "collection" ? collections : globals).includes(target.slug)) throw new APIError(`"${target.slug}" does not expose version history.`, 400);
 	if (args.versionId !== void 0 && args.draft !== void 0) throw new APIError("Pass either \"versionId\" or \"draft\", not both.", 400);
 	if (args.diffFrom !== void 0 && args.outline) throw new APIError("\"outline\" cannot be combined with \"diffFrom\".", 400);
 };
@@ -36,39 +39,43 @@ const diffResult = async (scope, read, diff, doc) => {
 		patch: diffDocuments(from.version, doc, diff.pointer)
 	});
 };
+const versionShape = (scope) => {
+	if (!exposesVersions(scope)) return widen({});
+	return widen({
+		versionId: idSchema.optional().describe("From findVersions. Not with \"draft\"."),
+		diffFrom: idSchema.optional().describe("Version id, or \"published\" for the newest version published in any locale. Returns {from, to, patch}, the JSON Patch from that version to what is read.")
+	});
+};
 /**
 * 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.
+* `updatedAt` a client needs to write back, so reading one branch still gives
+* the `expectedUpdatedAt` timestamp without a second call.
 */ const getDocument = defineMcpxTool({
 	name: "getDocument",
-	description: DESCRIPTION,
+	description: (scope) => exposesVersions(scope) ? DESCRIPTION + VERSION_PARAGRAPH : DESCRIPTION,
 	annotations: {
 		readOnlyHint: true,
 		openWorldHint: false
 	},
-	isEnabled: (scope) => scope.readable.length + scope.readableGlobals.length > 0,
+	isEnabled: (scope) => scope.collections.readable.length + scope.globals.readable.length > 0,
 	inputSchema: (scope) => ({
-		...targetShape(scope, "read", {
-			collection: "Collection holding the document.",
-			global: "Global to read."
-		}),
+		...entityShape(scope, "read"),
 		...idShape(scope, "read"),
-		path: z.string().regex(JSON_POINTER_PATTERN).optional().describe("JSON pointer to return only a subtree, e.g. \"/layout/sections/0\"."),
+		path: z.string().regex(JSON_POINTER_PATTERN).optional().describe("e.g. \"/layout/sections/0\"."),
 		...depthShape(scope),
 		...localeShape(scope, {
 			required: false,
-			description: "Locale to read. Defaults to the default locale."
+			description: READ_LOCALE_DESCRIPTION
 		}),
-		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\"."),
-		versionId: idSchema.optional().describe("Version to read instead of the document, from findVersions. Only for entities with versions; not with \"draft\"."),
-		diffFrom: idSchema.optional().describe("Version id, or \"published\" for the newest published version in any locale, to diff from. Returns {from, to, patch} instead of the document. Only for entities with versions.")
+		draft: z.boolean().optional().describe("Default true. false reads the published version."),
+		outline: z.boolean().optional().describe("With \"path\" at a rich text field: list each node's pointer, type, \"version\" and text."),
+		...versionShape(scope)
 	}),
 	handler: async ({ args, scope }) => {
-		const target = resolveTarget(scope, args, "read");
-		const id = requireIdFor(target, args.id);
+		const target = resolveDocument(scope, args, "read");
 		assertVersionArgs(scope, target, args);
+		const prototyped = args.path ? prototypeSegmentProblem(args.path) : void 0;
+		if (prototyped !== void 0) return errorResult(prototyped);
 		let pointer;
 		try {
 			pointer = args.path ? Pointer.fromJSON(args.path) : void 0;
@@ -77,7 +84,6 @@ const diffResult = async (scope, read, diff, doc) => {
 		}
 		const read = {
 			target,
-			id,
 			depth: args.depth ?? 0,
 			locale: localeOf(scope, args.locale)
 		};
@@ -95,7 +101,7 @@ const diffResult = async (scope, read, diff, doc) => {
 		const path = pointer.toString();
 		const value = pointer.get(doc);
 		const envelope = {
-			...target.kind === "collection" ? { id } : { global: target.slug },
+			...identityOf(target, args.id),
 			status: doc["_status"],
 			updatedAt: doc["updatedAt"],
 			path
@@ -109,10 +115,11 @@ const diffResult = async (scope, read, diff, doc) => {
 			resolution = resolveDataPointer(scope.req.payload.config, {
 				doc,
 				pointer: path,
-				ref: refOf(target)
+				ref: target
 			});
 		} catch (error) {
-			return errorResult(error instanceof Error ? error.message : OUTLINE_ERROR);
+			if (!(error instanceof SchemaError)) throw error;
+			return errorResult(error.message);
 		}
 		const field = resolution.descriptor?.type === "richText" && !resolution.lexical ? findRichTextField(resolution.fields, splitPath(resolution.descriptor.path)) : void 0;
 		if (!field) return errorResult(OUTLINE_ERROR);

package/dist/tools/list-capabilities.mjs

@@ -1,20 +1,27 @@
+import { defineMcpxTool } from "../define-tool.mjs";
 import { canCreate } from "../capabilities.mjs";
 import { jsonResult } from "../result.mjs";
-import { translatorFor } from "../i18n.mjs";
-import { translateLabel } from "./shared.mjs";
-import { defineMcpxTool } from "../types.mjs";
+import { translateStatic, translatorFor } from "../i18n.mjs";
 import { hasDraftValidationEnabled } from "payload/shared";
+//#region src/tools/list-capabilities.ts
+const DESCRIPTION = `Lists what this key may do. Call it first. Returns each collection and global the key can read or write, with whether it can create, publish, has drafts and exposes versions to findVersions, and a collection's "idType". Also returns the locales, the "limits" on page size and depth, and the enabled custom tools.`;
+const translateLabel = (scope, label, fallback) => {
+	const { i18n, t } = scope.req;
+	const resolved = typeof label === "function" ? label({
+		i18n,
+		t
+	}) : label;
+	return translateStatic(resolved, i18n) ?? fallback;
+};
 /**
-* 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.
+* Registered for every key, even one with no capabilities ticked, so a client
+* always has a tool to call and gets an empty surface described instead of an
+* empty tool list. The response comes from the request scope and the sanitized
+* config, not 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, 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".`,
+	description: DESCRIPTION,
 	annotations: {
 		readOnlyHint: true,
 		openWorldHint: false
@@ -64,16 +71,16 @@ A global is a singleton: it has no id, is not listed by findDocuments and cannot
 				draftValidation: hasDraftValidationEnabled(config)
 			}];
 		});
-		return Promise.resolve(jsonResult({
+		return jsonResult({
 			collections,
 			...globals.length > 0 ? { globals } : {},
-			locales: scope.locales ? {
-				codes: scope.locales,
-				default: scope.defaultLocale
+			locales: scope.localization ? {
+				codes: scope.localization.locales,
+				default: scope.localization.defaultLocale
 			} : null,
 			limits: scope.limits,
 			tools: Object.entries(scope.capabilities.tools).filter(([, enabled]) => enabled).map(([name]) => name)
-		}));
+		});
 	}
 });
 //#endregion

package/dist/tools/patch-document.mjs

@@ -1,45 +1,67 @@
+import { defineMcpxTool } from "../define-tool.mjs";
+import { isPlainObject } from "../guards.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, applyPatchOperations, buildWriteData, isElementPointer } from "../write/patch.mjs";
+import { JSON_POINTER_PATTERN } from "../schema/path.mjs";
+import "../schema/index.mjs";
+import { entityShape, idShape, liveWriteSentence, localeOf, localeShape } from "./shared.mjs";
+import { identityOf, readDraft, resolveDocument, staleReadResult } from "./document.mjs";
 import { collectPublishBlockers } from "../write/publish-blockers.mjs";
+import { applyPatchOperations, isElementPointer } from "../write/patch.mjs";
 import { withTransaction } from "../write/transaction.mjs";
+import { buildWriteData } from "../write/write-data.mjs";
+import { Forbidden, NotFound } from "payload";
 import { z } from "zod";
 import { Pointer } from "rfc6902";
 //#region src/tools/patch-document.ts
-const DESCRIPTION = (scope) => `Applies RFC 6902 JSON Patch operations to one document.
+const DESCRIPTION = (scope) => `Applies JSON Patch operations to one document or global, e.g. {"op":"replace","path":"/title","value":"Home"}. If any operation fails, nothing is written and the response lists the problems.
 
-Pass exactly one of "collection" and "global". "id" is required with "collection" and must be omitted with "global", because a global is a singleton.
+${liveWriteSentence(scope, "write")}
 
-${draftSentence(scope)}
+Read the document with getDocument right before patching. Append to a list with "/-". A new block needs "blockType". To clear a field, "replace" it with null, or with [] for an array or blocks field. "remove" only removes list elements. Indices shift with every add or remove, so remove from the last index to the first.
 
-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".
+In a rich text field a pointer continues into the rich text state: "/content/root/children/2" is a node, "/content/root/children/2/tag" one of its properties and "/content/root/children/3/fields/tone" a field of a block node. getDocument "outline" lists each node's pointer and "version". Build nodes from describeSchema "nodeProperties". Check a position before writing to it, e.g. {"op":"test","path":"/content/root/children/2/type","value":"heading"}.
 
-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.
-
-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
-* allowed to carry more than was sent: Payload assigns fresh row ids and
-* backfills defaults and nulls on save, so `id` keys are ignored and only
-* the keys the client sent are compared. Null and absent count as equal.
-*/ const survives = (expected, actual) => {
+The response carries "updatedAt" and, if any, "publishBlockers": what must be fixed before publishing. "publishBlockersUnavailable" means that check failed. The write stands either way. "notApplied" lists pointers whose value did not change or cannot be read back, for example where field access denies the update.`;
+const POINTER = z.string().regex(JSON_POINTER_PATTERN);
+const PATCHES_LIMIT = 500;
+/** Discriminated on `op`, so an operation carries only its own members. */ const PATCH_OPERATION_SCHEMA = z.discriminatedUnion("op", [
+	z.strictObject({
+		op: z.literal("add"),
+		path: POINTER,
+		value: z.unknown()
+	}),
+	z.strictObject({
+		op: z.literal("remove"),
+		path: POINTER
+	}),
+	z.strictObject({
+		op: z.literal("replace"),
+		path: POINTER,
+		value: z.unknown()
+	}),
+	z.strictObject({
+		from: POINTER,
+		op: z.literal("move"),
+		path: POINTER
+	}),
+	z.strictObject({
+		from: POINTER,
+		op: z.literal("copy"),
+		path: POINTER
+	}),
+	z.strictObject({
+		op: z.literal("test"),
+		path: POINTER,
+		value: z.unknown()
+	})
+]);
+const survives = (expected, actual) => {
 	if (expected === void 0 || expected === null) return actual === void 0 || actual === null;
 	if (Array.isArray(expected)) return Array.isArray(actual) && expected.length === actual.length && expected.every((entry, index) => survives(entry, actual[index]));
 	if (isPlainObject(expected)) return isPlainObject(actual) && Object.entries(expected).every(([key, value]) => key === "id" || survives(value, actual[key]));
 	return isPlainObject(actual) || Array.isArray(actual) ? false : JSON.stringify(expected) === JSON.stringify(actual);
 };
-/**
-* Pointers whose intended value did not survive the write. Element pointers
-* are skipped: an append pointer (`/-`) does not resolve against the saved
-* document.
-*/ const notAppliedPointers = (patches, intended, saved) => patches.flatMap((operation) => {
+const notAppliedPointers = (patches, intended, saved) => patches.flatMap((operation) => {
 	if (operation.op !== "add" && operation.op !== "replace" || isElementPointer(operation.path)) return [];
 	const pointer = Pointer.fromJSON(operation.path);
 	const expected = pointer.get(intended);
@@ -48,10 +70,10 @@ const isPlainObject = (value) => typeof value === "object" && value !== null &&
 });
 /**
 * The handler validates the whole batch against the schema and the current
-* document before it writes anything, runs the write in a transaction, then
+* document before writing 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.
+* blocks publishing. The draft guard, not this tool, decides where the write
+* lands.
 */ const patchDocument = defineMcpxTool({
 	name: "patchDocument",
 	description: DESCRIPTION,
@@ -61,37 +83,33 @@ const isPlainObject = (value) => typeof value === "object" && value !== null &&
 		idempotentHint: false,
 		openWorldHint: false
 	},
-	isEnabled: (scope) => scope.writable.length + scope.writableGlobals.length > 0,
+	isEnabled: (scope) => scope.collections.writable.length + scope.globals.writable.length > 0,
 	inputSchema: (scope) => ({
-		...targetShape(scope, "write", {
-			collection: "Collection holding the document.",
-			global: "Global to patch."
-		}),
+		...entityShape(scope, "write"),
 		...idShape(scope, "write"),
 		...localeShape(scope, {
 			required: true,
-			description: "Locale the patch applies to. Localized fields write here only."
+			description: "Localized fields are written in this locale only."
 		}),
-		patches: z.array(PATCH_OPERATION_SCHEMA).min(1).describe("Operations, applied in order."),
-		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.")
+		patches: z.array(PATCH_OPERATION_SCHEMA).min(1).max(PATCHES_LIMIT),
+		expectedUpdatedAt: z.string().optional().describe("\"updatedAt\" from your last read. Refused if the document changed since.")
 	}),
 	handler: async ({ args, scope }) => {
-		const target = resolveTarget(scope, args, "write");
-		const id = requireIdFor(target, args.id);
+		const target = resolveDocument(scope, args, "write");
 		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, {
+			const doc = await readDraft(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 and re-apply the patch.", { updatedAt: doc["updatedAt"] });
+			const stale = staleReadResult(doc, args.expectedUpdatedAt, "The document changed since you read it. Read it again and re-apply the patch.");
+			if (stale) return stale;
 			const applied = applyPatchOperations(payload.config, {
 				doc,
 				patches,
-				ref: refOf(target)
+				ref: target
 			});
 			if ("problems" in applied) return errorResult("No operation was applied.", { problems: applied.problems });
 			const write = {
@@ -105,26 +123,32 @@ const isPlainObject = (value) => typeof value === "object" && value !== null &&
 			if (target.kind === "collection") await payload.update({
 				...write,
 				collection: target.slug,
-				id
+				id: target.id
 			});
 			else await payload.updateGlobal({
 				...write,
 				fallbackLocale: false,
 				slug: target.slug
 			});
-			const saved = await readTarget(scope, {
+			const saved = await readDraft(scope, {
 				target,
-				id,
 				locale,
 				privileged: true
 			});
-			const notApplied = notAppliedPointers(patches, applied.next, saved);
+			const readable = await readDraft(scope, {
+				target,
+				locale
+			}).catch((error) => {
+				if (error instanceof NotFound || error instanceof Forbidden) return;
+				throw error;
+			});
+			const notApplied = readable ? notAppliedPointers(patches, applied.next, readable) : [];
 			const validation = await collectPublishBlockers(scope.req, {
 				doc: saved,
 				entity: target
 			});
 			return jsonResult({
-				...target.kind === "collection" ? { id: saved["id"] } : { global: target.slug },
+				...identityOf(target, saved["id"]),
 				status: saved["_status"],
 				updatedAt: saved["updatedAt"],
 				...validation.blockers.length > 0 ? { publishBlockers: validation.blockers } : {},
@@ -135,4 +159,4 @@ const isPlainObject = (value) => typeof value === "object" && value !== null &&
 	}
 });
 //#endregion
-export { patchDocument };
+export { PATCH_OPERATION_SCHEMA, patchDocument };

package/dist/tools/publish-document.mjs

@@ -1,48 +1,38 @@
-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 { defineMcpxTool } from "../define-tool.mjs";
+import { jsonResult } from "../result.mjs";
+import { entityShape, idShape, localeOf } from "./shared.mjs";
+import { identityOf, readDraft, resolveDocument, staleReadResult } from "./document.mjs";
 import { 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
+* Publishes a draft. Available where the config exposes
+* `publish` on an entity with drafts and the key has both the `write` and
 * `publish` checkboxes.
 */ const publishDocument = defineMcpxTool({
 	name: "publishDocument",
-	description: `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.`,
+	description: `Makes the current draft of one document or global public. A draft with publish blockers is refused, so call validateDocument first. Publishing validates one locale only, normally the default, so a required field left empty in another locale goes live empty. Run validateDocument for each locale. There is no unpublish. A person takes content offline in the admin panel.`,
 	annotations: {
 		destructiveHint: true,
 		openWorldHint: false
 	},
-	isEnabled: (scope) => scope.publishable.length + scope.publishableGlobals.length > 0,
+	isEnabled: (scope) => scope.collections.publishable.length + scope.globals.publishable.length > 0,
 	inputSchema: (scope) => ({
-		...targetShape(scope, "publish", {
-			collection: "Collection holding the document.",
-			global: "Global to publish."
-		}),
+		...entityShape(scope, "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.")
+		expectedUpdatedAt: z.string().optional().describe("\"updatedAt\" from your last read. Refused if the document changed since.")
 	}),
 	handler: async ({ args, scope }) => {
-		const target = resolveTarget(scope, args, "publish");
-		const id = requireIdFor(target, args.id);
+		const target = resolveDocument(scope, args, "publish");
 		const { payload } = scope.req;
 		const locale = localeOf(scope, void 0);
 		return await withTransaction(scope.req, async () => {
-			const doc = await readTarget(scope, {
+			const doc = await readDraft(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 stale = staleReadResult(doc, args.expectedUpdatedAt, "The document changed since you read it. Read it again before publishing.");
+			if (stale) return stale;
 			const write = {
 				data: withPublishIntent({}),
 				depth: 0,
@@ -55,20 +45,19 @@ There is no unpublish: reverting to a draft stays a human action in the admin pa
 			if (target.kind === "collection") await payload.update({
 				...write,
 				collection: target.slug,
-				id
+				id: target.id
 			});
 			else await payload.updateGlobal({
 				...write,
 				slug: target.slug
 			});
-			const saved = await readTarget(scope, {
+			const saved = await readDraft(scope, {
 				target,
-				id,
 				locale,
 				privileged: true
 			});
 			return jsonResult({
-				...target.kind === "collection" ? { id: saved["id"] } : { global: target.slug },
+				...identityOf(target, saved["id"]),
 				status: saved["_status"],
 				updatedAt: saved["updatedAt"]
 			});

package/dist/tools/query-paths.mjs

@@ -0,0 +1,55 @@
+import { isPlainObject } from "../guards.mjs";
+import { addressesAdminHidden } from "../schema/admin-hidden.mjs";
+import "../schema/index.mjs";
+import { APIError, getLocalizedPaths } from "payload";
+//#region src/tools/query-paths.ts
+/**
+* The paths of a `where`, found the way Payload's `validateQueryPaths` finds
+* them: `and` and `or` (any case) hold arrays of clauses, every other key is a
+* path.
+*/ const wherePaths = (where) => isPlainObject(where) ? Object.entries(where).flatMap(([key, clause]) => ["and", "or"].includes(key.toLowerCase()) && Array.isArray(clause) ? clause.flatMap(wherePaths) : [key]) : [];
+/** The paths of a `sort`: a field name, `-` for descending, comma separated. */ const sortPaths = (sort) => (sort ?? "").split(",").map((entry) => entry.trim().replace(/^-/, "")).filter(Boolean);
+const normalise = (path) => path === "_id" ? "id" : path.replaceAll("__", ".");
+const isRefusedPath = (scope, args, seen = /* @__PURE__ */ new Set()) => {
+	const key = `${args.collection}:${args.path}`;
+	const { payload } = scope.req;
+	if (seen.has(key)) return false;
+	seen.add(key);
+	const hops = getLocalizedPaths({
+		collectionSlug: args.collection,
+		fields: payload.collections[args.collection]?.config.flattenedFields ?? [],
+		incomingPath: args.path,
+		...args.locale ? { locale: args.locale } : {},
+		payload
+	});
+	return hops.some((hop, index) => {
+		const { collectionSlug, field } = hop;
+		const via = hops[index - 1]?.field;
+		const isBareId = hop.path === "id" && (via?.type === "relationship" || via?.type === "upload" || via?.type === "join");
+		if (collectionSlug !== void 0 && addressesAdminHidden(payload.config, collectionSlug, hop.path)) return true;
+		if (index > 0 && collectionSlug !== void 0 && !scope.collections.readable.includes(collectionSlug) && !isBareId) return true;
+		return !hop.invalid && "virtual" in field && typeof field.virtual === "string" && isRefusedPath(scope, {
+			collection: collectionSlug ?? args.collection,
+			path: normalise(field.virtual),
+			locale: args.locale
+		}, seen);
+	});
+};
+/**
+* Refuses a `where` or `sort` that traverses a relationship, upload or join
+* field into a collection the key cannot read, since Payload answers it from
+* documents the key may not see, and one that names an `admin.hidden` field,
+* whose value the read tools withhold. Naming the relation field itself, or
+* its id, stays allowed, as does traversal into a readable collection. Unknown
+* paths are left to Payload.
+*/ const assertQueryable = (scope, args) => {
+	const reaches = (path) => isRefusedPath(scope, {
+		collection: args.collection,
+		path: normalise(path),
+		locale: args.locale ?? void 0
+	});
+	for (const path of wherePaths(args.where)) if (reaches(path)) throw new APIError(`This key cannot query through "${path}".`, 400);
+	for (const path of sortPaths(args.sort)) if (reaches(path) || normalise(path).split(".").some(reaches)) throw new APIError(`This key cannot query through "${path}".`, 400);
+};
+//#endregion
+export { assertQueryable, sortPaths, wherePaths };

package/dist/tools/read-request.d.mts

@@ -0,0 +1,10 @@
+import { McpxToolScope } from "../types.mjs";
+import { PayloadRequest } from "payload";
+//#region src/tools/read-request.d.ts
+/**
+ * A read request that populates only into collections this key may read, at
+ * every depth, through a data loader of its own. A refused relation resolves to
+ * its id. Each call returns a fresh request.
+ */
+export declare const mcpxReadRequest: (scope: McpxToolScope) => PayloadRequest;
+//#endregion

package/dist/tools/read-request.mjs

@@ -0,0 +1,43 @@
+import { createDataloaderCacheKey, getDataLoader, isolateObjectProperty } from "payload";
+//#region src/tools/read-request.ts
+const LOADER_KEY = (() => {
+	const slug = "\0slug";
+	const id = "\0id";
+	const parts = JSON.parse(createDataloaderCacheKey({
+		collectionSlug: slug,
+		currentDepth: 0,
+		depth: 0,
+		docID: id,
+		draft: false,
+		fallbackLocale: false,
+		locale: "",
+		overrideAccess: false,
+		showHiddenFields: false,
+		transactionID: ""
+	}));
+	return Array.isArray(parts) ? {
+		slug: parts.indexOf(slug),
+		id: parts.indexOf(id)
+	} : {
+		slug: -1,
+		id: -1
+	};
+})();
+/**
+* A read request that populates only into collections this key may read, at
+* every depth, through a data loader of its own. A refused relation resolves to
+* its id. Each call returns a fresh request.
+*/ const mcpxReadRequest = (scope) => {
+	const req = isolateObjectProperty(scope.req, "payloadDataLoader");
+	const loader = getDataLoader(req);
+	const load = loader.load.bind(loader);
+	loader.load = (key) => {
+		const parts = JSON.parse(key);
+		const collection = parts[LOADER_KEY.slug];
+		return typeof collection === "string" && scope.collections.readable.includes(collection) ? load(key) : Promise.resolve(parts[LOADER_KEY.id]);
+	};
+	req.payloadDataLoader = loader;
+	return req;
+};
+//#endregion
+export { mcpxReadRequest };