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

package/dist/tools/list-capabilities.mjs

@@ -1,20 +1,29 @@
-import { canCreate } from "../capabilities.mjs";
+import { defineMcpxTool } from "../define-tool.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 { slugsFor } from "./shared.mjs";
+import { MCPX_ISSUES_URL, MCPX_REPOSITORY_URL } from "../version.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 DIAGNOSTICS = ` Its "server" block holds the server version with repository and issue links, for a bug report.`;
+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: (scope) => scope.diagnostics ? `${DESCRIPTION}${DIAGNOSTICS}` : DESCRIPTION,
 	annotations: {
 		readOnlyHint: true,
 		openWorldHint: false
@@ -24,6 +33,7 @@ A global is a singleton: it has no id, is not listed by findDocuments and cannot
 	handler: ({ scope }) => {
 		const { payload } = scope.req;
 		const translate = translatorFor(scope.req.i18n);
+		const creatable = slugsFor(scope, "create").collections;
 		const collections = scope.exposure.collections.flatMap((entry) => {
 			const capability = scope.capabilities.collections[entry.slug];
 			const collection = payload.collections[entry.slug];
@@ -39,7 +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,
-				create: capability.write && canCreate(entry),
+				create: creatable.includes(entry.slug),
 				publish: capability.publish,
 				drafts: entry.hasDrafts,
 				versions: entry.hasVersions,
@@ -64,16 +74,22 @@ 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)
-		}));
+			tools: Object.entries(scope.capabilities.tools).filter(([, enabled]) => enabled).map(([name]) => name),
+			...scope.diagnostics ? { server: {
+				name: scope.diagnostics.name,
+				version: scope.diagnostics.version,
+				repository: MCPX_REPOSITORY_URL,
+				issues: MCPX_ISSUES_URL
+			} } : {}
+		});
 	}
 });
 //#endregion

package/dist/tools/patch-document.mjs

@@ -1,45 +1,70 @@
+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 { collectPublishBlockers } from "../write/publish-blockers.mjs";
+import { assertAcceptsFile, fileShape, fileSlugs, fileWriteRefusal, uploadHandoff, uploadedFile } from "../upload/file.mjs";
+import { entityShape, idShape, liveWriteSentence, localeOf, localeShape } from "./shared.mjs";
+import { identityOf, readDraft, resolveDocument, staleReadResult } from "./document.mjs";
+import { applyPatchOperations, isElementPointer } from "../write/patch.mjs";
 import { withTransaction } from "../write/transaction.mjs";
+import { buildWriteData } from "../write/write-data.mjs";
+import { APIError, 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);
+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;
 /**
-* 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) => {
+* 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 +73,11 @@ 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. With `file`, the patches and the file land as one update, and the
+* transaction commits right after it because Payload has moved files by then.
 */ const patchDocument = defineMcpxTool({
 	name: "patchDocument",
 	description: DESCRIPTION,
@@ -61,39 +87,80 @@ 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: fileSlugs(scope).length === 0 ? z.array(PATCH_OPERATION_SCHEMA).min(1).max(PATCHES_LIMIT) : z.array(PATCH_OPERATION_SCHEMA).max(PATCHES_LIMIT).describe("May be empty when \"file\" is given."),
+		expectedUpdatedAt: z.string().optional().describe("\"updatedAt\" from your last read. Refused if the document changed since."),
+		...fileShape(scope, (slugs) => `Replaces the file of a document in ${slugs}. The call returns an "upload" for the bytes instead of writing.`)
 	}),
 	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 { file } = args;
+		const bytes = uploadedFile(scope.req);
+		if (file !== void 0) assertAcceptsFile(scope, target, file);
+		if (patches.length === 0 && file === void 0) throw new APIError("\"patches\" may be empty only when \"file\" is given.", 400);
+		const report = async (next) => {
+			const saved = await readDraft(scope, {
+				target,
+				locale,
+				privileged: true
+			});
+			const readable = await readDraft(scope, {
+				target,
+				locale
+			}).catch((error) => {
+				if (error instanceof NotFound || error instanceof Forbidden) return;
+				throw error;
+			});
+			const notApplied = readable ? notAppliedPointers(patches, next, readable) : [];
+			const validation = await collectPublishBlockers(scope.req, {
+				doc: saved,
+				entity: target
+			});
+			return jsonResult({
+				...identityOf(target, saved["id"]),
+				status: saved["_status"],
+				updatedAt: saved["updatedAt"],
+				...validation.blockers.length > 0 ? { publishBlockers: validation.blockers } : {},
+				...validation.unavailable ? { publishBlockersUnavailable: true } : {},
+				...notApplied.length > 0 ? { notApplied } : {}
+			});
+		};
+		const outcome = await withTransaction(scope.req, async () => {
+			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 { done: 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 });
+			if ("problems" in applied) return { done: errorResult("No operation was applied.", { problems: applied.problems }) };
+			if (file !== void 0 && target.kind === "collection") {
+				const refusal = await fileWriteRefusal(scope, {
+					entity: target,
+					id: target.id,
+					data: applied.next
+				});
+				if (refusal) return { done: refusal };
+				if (!bytes) return { handoff: {
+					...args,
+					file,
+					expectedUpdatedAt: doc["updatedAt"]
+				} };
+			}
 			const write = {
 				data: buildWriteData(payload.config, target.config, applied.next),
 				depth: 0,
@@ -105,34 +172,23 @@ const isPlainObject = (value) => typeof value === "object" && value !== null &&
 			if (target.kind === "collection") await payload.update({
 				...write,
 				collection: target.slug,
-				id
+				id: target.id,
+				...bytes === void 0 ? {} : { file: bytes }
 			});
 			else await payload.updateGlobal({
 				...write,
 				fallbackLocale: false,
 				slug: target.slug
 			});
-			const saved = await readTarget(scope, {
-				target,
-				id,
-				locale,
-				privileged: true
-			});
-			const notApplied = notAppliedPointers(patches, applied.next, saved);
-			const validation = await collectPublishBlockers(scope.req, {
-				doc: saved,
-				entity: target
-			});
-			return jsonResult({
-				...target.kind === "collection" ? { id: saved["id"] } : { global: target.slug },
-				status: saved["_status"],
-				updatedAt: saved["updatedAt"],
-				...validation.blockers.length > 0 ? { publishBlockers: validation.blockers } : {},
-				...validation.unavailable ? { publishBlockersUnavailable: true } : {},
-				...notApplied.length > 0 ? { notApplied } : {}
-			});
+			return bytes === void 0 ? { done: await report(applied.next) } : { written: applied.next };
+		});
+		if ("done" in outcome) return outcome.done;
+		if ("handoff" in outcome) return await uploadHandoff(scope, {
+			tool: "patchDocument",
+			args: outcome.handoff
 		});
+		return await report(outcome.written);
 	}
 });
 //#endregion
-export { patchDocument };
+export { PATCH_OPERATION_SCHEMA, patchDocument };

package/dist/tools/publish-document.mjs

@@ -1,48 +1,39 @@
-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, localeShape } from "./shared.mjs";
+import { collectLocaleBlockers, 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
-* `publish` checkboxes.
+* 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, in every locale or only in "locale". A scoped publish keeps the other locales of localized fields as last published, and a never-published document goes live in full. A draft with publish blockers is refused, so call validateDocument first. Payload checks only the published locale, so "otherLocaleBlockers" lists what other locales still lack. There is no unpublish.`,
 	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.")
+		...localeShape(scope, { required: false }),
+		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);
+		const locale = localeOf(scope, args.locale);
+		const { localization } = scope;
 		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,
@@ -50,27 +41,30 @@ There is no unpublish: reverting to a draft stays a human action in the admin pa
 				fallbackLocale: false,
 				overrideAccess: false,
 				req: scope.req,
-				...locale === void 0 ? {} : { locale }
+				...locale === void 0 ? {} : { locale },
+				...args.locale === void 0 ? {} : { publishSpecificLocale: args.locale }
 			};
 			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
 			});
+			const others = await collectLocaleBlockers(scope, target, localization?.locales.filter((entry) => entry !== locale) ?? []);
 			return jsonResult({
-				...target.kind === "collection" ? { id: saved["id"] } : { global: target.slug },
+				...identityOf(target, saved["id"]),
 				status: saved["_status"],
-				updatedAt: saved["updatedAt"]
+				updatedAt: saved["updatedAt"],
+				...others.blockers.length > 0 ? { otherLocaleBlockers: others.blockers } : {},
+				...others.unavailable ? { otherLocaleBlockersUnavailable: true } : {}
 			});
 		});
 	}

package/dist/tools/query-paths.mjs

@@ -0,0 +1,57 @@
+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 };