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

package/dist/schema/walk.mjs

@@ -1,4 +1,5 @@
 import { allowedNodeTypes, nodeOptions } from "./lexical.mjs";
+import { joinPath, splitPath } from "./path.mjs";
 import { translateAny } from "../i18n.mjs";
 import { fieldIsHiddenOrDisabled, fieldIsVirtual } from "payload/shared";
 //#region src/schema/walk.ts
@@ -9,21 +10,16 @@ const RESERVED_FIELD_NAMES = /* @__PURE__ */ new Set([
 	"id",
 	"updatedAt"
 ]);
-const JSON_POINTER_PATTERN = /^(\/([^~/]|~[01])*)*$/;
-/** No segments is the root pointer, `""`. */ const joinPath = (parts) => parts.map((part) => `/${part.replace(/~/g, "~0").replace(/\//g, "~1")}`).join("");
-/** Unescapes `~1` and `~0`. The root pointer yields no segments. */ const splitPath = (path) => path.split("/").slice(1).map((segment) => segment.replace(/~1/g, "/").replace(/~0/g, "~"));
-/** `-` included, since RFC 6901 reads it as the position after the last. */ const isIndexSegment = (segment) => segment === "-" || /^\d+$/.test(segment);
-const isPlainObject = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
-/**
-* A path Payload reports on a validation error (`layout.0.title`) as a JSON
-* Pointer, so everything handed back addresses documents the same way. The
-* path already carries real indices, so it maps directly.
-*/ const pointerFromPayloadPath = (path) => path ? joinPath(path.split(".")) : "";
+/** The keys a row carries beside its fields. */ const ROW_KEYS = /* @__PURE__ */ new Set([
+	"blockName",
+	"blockType",
+	"id"
+]);
 /** On a flattened field, whichever of `blockReferences` and `blocks` was declared. */ const blockSlugsOf = (field) => [...new Set((field.blockReferences ?? field.blocks).map((block) => typeof block === "string" ? block : block.slug))];
 /**
 * An inlined definition wins over the registry (`config.blocks`). A block's own
 * fields are identical wherever it appears, but the blocks its children accept
-* are not, so an inline definition has to be read at its position.
+* are not, so an inline definition must be read at its position.
 */ const blockOf = (config, field, slug) => {
 	const declared = field.blockReferences ?? field.blocks;
 	const inline = declared.find((block) => typeof block !== "string" && block.slug === slug);
@@ -32,9 +28,9 @@ const isPlainObject = (value) => typeof value === "object" && value !== null &&
 };
 /**
 * Payload's `fieldIsHiddenOrDisabled` reads `hidden` and `admin.disabled`, not
-* `admin.hidden`, which is what its own upload base fields carry.
+* `admin.hidden`, which its own upload base fields carry.
 */ const isAdminHidden = (field) => "admin" in field && field.admin.hidden === true;
-/** A field kept out of the admin panel is kept out of the MCP surface too. */ const isSkipped = (field) => !("name" in field) || field.type === "join" || RESERVED_FIELD_NAMES.has(field.name) || fieldIsVirtual(field) || isAdminHidden(field) || fieldIsHiddenOrDisabled(field);
+const isSkipped = (field) => !("name" in field) || field.type === "join" || RESERVED_FIELD_NAMES.has(field.name) || fieldIsVirtual(field) || isAdminHidden(field) || fieldIsHiddenOrDisabled(field);
 const isReadOnly = (field) => "admin" in field && field.admin.readOnly === true;
 const describeBase = (field, { path, readOnly, translate }) => {
 	const description = translate("admin" in field ? field.admin.description : void 0);
@@ -68,28 +64,15 @@ const withRows = (descriptor, field) => ({
 	...field.minRows === void 0 ? {} : { minRows: field.minRows },
 	...field.maxRows === void 0 ? {} : { maxRows: field.maxRows }
 });
+const isContainer = (descriptor) => descriptor.type === "array" || descriptor.type === "group" || descriptor.type === "tab";
+const isInformative = (descriptor) => descriptor.description !== void 0 || descriptor.required === true || descriptor.localized === true;
 /**
-* A container describes a position rather than a value, so everything resolving
-* a path to something writable skips it. Only {@link nodeDescriber} reports one,
-* to carry what the container itself declares.
-*/ const isContainer = (descriptor) => descriptor.type === "array" || descriptor.type === "group" || descriptor.type === "tab";
-/**
-* Whether a container declares anything a client could not infer from the
-* fields beneath it. A group that exists only to nest is not worth reporting.
-*/ const isInformative = (descriptor) => descriptor.description !== void 0 || descriptor.required === true || descriptor.localized === true;
-/**
-* Flattens a field list into descriptors addressed relative to the node.
-*
-* The input is Payload's own flattened shape, so the admin-only constructs
-* (unnamed tabs and groups, `row`, `collapsible`, `ui`) are already gone. Named
-* tabs, groups and arrays contribute a path segment, and are described in their
-* own right when they declare something of their own: an array always, since
-* its row counts live nowhere else, a group or tab only when it carries a
-* description or a constraint. The walk stops at every blocks field and names
-* the slugs, which keeps a node proportional to the number of blocks it allows
-* rather than to the size of their definitions.
-*
-* Omitting `translate` costs language selection, never the description itself.
+* Named tabs, groups and arrays add a path segment and are described
+* themselves only when they declare something of their own: an array always,
+* since its row counts live nowhere else. The walk stops at every blocks field
+* and names the slugs, so a node's size follows the number of blocks it
+* allows, not their definitions. Omitting `translate` costs language
+* selection, never the description itself.
 */ const describeFields = (fields, translate = translateAny) => {
 	const walk = (current, prefix, parentReadOnly) => current.flatMap((field) => {
 		if (isSkipped(field)) return [];
@@ -114,10 +97,17 @@ const withRows = (descriptor, field) => ({
 	return walk(fields, [], false);
 };
 /**
-* 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 nodeDescriber} reports one.
+* The descriptors that address a value, which every walk resolving a path
+* against a document needs. Containers are left out, since only
+* {@link nodeDescriber} reports one.
 */ const describeAddressableFields = (fields) => describeFields(fields).filter((descriptor) => !isContainer(descriptor));
+/** The addressable descriptors under `prefix`, with their paths split relative to it. */ const descriptorsUnder = (fields, prefix) => describeAddressableFields(fields).flatMap((descriptor) => {
+	const parts = splitPath(descriptor.path);
+	return prefix.every((part, offset) => part === parts[offset]) ? [{
+		descriptor,
+		parts: parts.slice(prefix.length)
+	}] : [];
+});
 const findFieldAt = (fields, path, type) => {
 	for (const field of fields) {
 		if (!("name" in field) || field.name !== path[0]) continue;
@@ -128,18 +118,18 @@ const findFieldAt = (fields, path, type) => {
 };
 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.
+* Locates the rich text field a resolved descriptor path refers to, so its
+* editor can be introspected for the fields its nodes carry.
 */ const findRichTextField = (fields, path) => findFieldAt(fields, path, "richText");
 /**
-* Looks up the sanitized config for a collection or global, as a
-* {@link SchemaTarget}. Throws on an unknown slug rather than returning
-* undefined, because a reference reaching here has already been checked against
-* the key's capabilities and a miss means the config changed underneath it.
-*/ const targetOf = (config, ref) => {
+* Looks up the sanitized config for a collection or global as an
+* {@link EntitySchema}. Throws on an unknown slug instead of returning
+* undefined: a reference reaching here was already checked against the key's
+* capabilities, so a miss means the config changed underneath it.
+*/ const schemaOf = (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}".`);
 	return found;
 };
 //#endregion
-export { JSON_POINTER_PATTERN, RESERVED_FIELD_NAMES, blockOf, blockSlugsOf, describeAddressableFields, describeFields, findBlocksField, findRichTextField, isIndexSegment, isPlainObject, joinPath, pointerFromPayloadPath, splitPath, targetOf };
+export { RESERVED_FIELD_NAMES, ROW_KEYS, blockOf, blockSlugsOf, describeAddressableFields, describeFields, descriptorsUnder, findBlocksField, findRichTextField, isAdminHidden, schemaOf };

package/dist/tools/builtin.mjs

@@ -9,10 +9,10 @@ import { publishDocument } from "./publish-document.mjs";
 import { validateDocument } from "./validate-document.mjs";
 //#region src/tools/builtin.ts
 /**
-* The builtin tools, in registration order. Fixed: adding a collection, block
-* or field never changes the surface. They differ from a custom tool only in
-* `isEnabled`, which derives from the key's capabilities rather than a
-* checkbox of their own.
+* The builtin tools, in registration order. The set is fixed, so adding a
+* collection, block or field never changes it. They differ from custom tools
+* only in `isEnabled`, which derives from the key's capabilities instead of a
+* checkbox of its own.
 */ const BUILTIN_TOOLS = [
 	listCapabilities,
 	describeSchema,

package/dist/tools/create-document.mjs

@@ -1,29 +1,29 @@
+import { defineMcpxTool } from "../define-tool.mjs";
 import { errorResult, jsonResult } from "../result.mjs";
 import { validateWriteValue } from "../schema/shape.mjs";
 import "../schema/index.mjs";
-import { draftSentence, localeOf, localeShape, patchOnlySlugs, readTarget, slugEnum, slugsFor } from "./shared.mjs";
-import { resolveTarget } from "./target.mjs";
-import { defineMcpxTool } from "../types.mjs";
-import { stripRowIds } from "../write/patch.mjs";
+import { liveWriteSentence, localeOf, localeShape, patchOnlySlugs, slugEnum, slugsFor } from "./shared.mjs";
+import { readDraft, resolveEntity } from "./document.mjs";
 import { collectPublishBlockers } from "../write/publish-blockers.mjs";
+import { stripRowIds } from "../write/row-ids.mjs";
 import { z } from "zod";
 //#region src/tools/create-document.ts
-/** Names the writable slugs this tool leaves out, so the gap reads as intent. */ const uploadSentence = (scope) => {
+const uploadSentence = (scope) => {
 	const slugs = patchOnlySlugs(scope);
-	return slugs.length === 0 ? "" : `\n\nLeft out of "collection" on purpose: ${slugs.join(", ")}. Those documents are files, and no tool here carries one. Upload the file in the admin panel, then edit its fields with patchDocument.`;
+	return slugs.length === 0 ? "" : ` Documents in ${slugs.join(", ")} are files and cannot be created here. Upload the file in the admin panel, then edit its fields with patchDocument.`;
 };
-const DESCRIPTION = (scope) => `Creates a new document from a minimal seed. Only the fields describeSchema lists may appear in "data"; unknown keys are refused with the valid siblings, and "id" is Payload's to assign. The document may be incomplete: the response lists "publishBlockers", which patchDocument can then work through, and "publishBlockersUnavailable" when that check itself failed. Use this when no document exists yet; prefer patching an existing draft otherwise.
+const DESCRIPTION = (scope) => `Creates a document in a collection. Use it only when the document does not exist yet. Returns "id", "status", "updatedAt" and, if any, "publishBlockers". "publishBlockersUnavailable" means that check failed. "data" may leave required fields empty for patchDocument to fill later, except in a collection whose listCapabilities entry has "draftValidation" true or "drafts" false. A field describeSchema does not list is refused, and "id" is always assigned.
 
-${draftSentence(scope)}${uploadSentence(scope)}`;
+${liveWriteSentence(scope, "create")}${uploadSentence(scope)}`;
 /**
-* Collection-only, because a global always exists, and never reaches an upload
-* collection, because a create there would have to carry the file.
+* Collection-only, because a global always exists. Upload collections are
+* excluded because a create there would need the file.
 *
-* The seed is checked against the collection's fields before the create, so an
-* unknown key is refused with its valid siblings rather than dropped. Row ids
-* in the seed are stripped and a top-level `id` is refused outright. The new
-* document is re-read privileged afterwards to collect publish blockers, which
-* is why an incomplete seed still succeeds and comes back with a checklist.
+* The seed is checked against the collection's fields first, so an unknown key
+* is refused along with its valid siblings. Row ids in the seed are stripped
+* and a top-level `id` is refused. The new document is re-read privileged to
+* collect publish blockers, so an incomplete seed still succeeds and returns a
+* checklist.
 */ const createDocument = defineMcpxTool({
 	name: "createDocument",
 	description: DESCRIPTION,
@@ -35,18 +35,19 @@ ${draftSentence(scope)}${uploadSentence(scope)}`;
 	},
 	isEnabled: (scope) => slugsFor(scope, "create").collections.length > 0,
 	inputSchema: (scope) => ({
-		collection: slugEnum(slugsFor(scope, "create").collections).describe("Collection to create the document in."),
+		collection: slugEnum(slugsFor(scope, "create").collections),
 		...localeShape(scope, {
 			required: true,
-			description: "Locale the localized fields of the seed belong to."
+			description: "Locale of the localized fields in \"data\"."
 		}),
-		data: z.record(z.string(), z.unknown()).describe("Initial field values, as describeSchema lists them.")
+		data: z.record(z.string(), z.unknown()).describe("Field values by name, e.g. {\"title\":\"Home\",\"slug\":\"home\"}.")
 	}),
 	handler: async ({ args, scope }) => {
-		const target = resolveTarget(scope, { collection: args.collection }, "create");
+		const target = resolveEntity(scope, { collection: args.collection }, "create");
+		if (target.kind === "global") throw new Error("createDocument resolved a global.");
 		const { payload } = scope.req;
 		const locale = localeOf(scope, args.locale);
-		if ("id" in args.data) return errorResult("Nothing was created.", { problems: ["/id: Payload assigns the id; it cannot be supplied."] });
+		if (Object.hasOwn(args.data, "id")) return errorResult("Nothing was created.", { problems: ["/id: Payload assigns the id; it cannot be supplied."] });
 		const problems = validateWriteValue(payload.config, {
 			pointer: "",
 			resolution: {
@@ -64,9 +65,11 @@ ${draftSentence(scope)}${uploadSentence(scope)}`;
 			req: scope.req,
 			...locale === void 0 ? {} : { locale }
 		});
-		const saved = await readTarget(scope, {
-			target,
-			id: created["id"],
+		const saved = await readDraft(scope, {
+			target: {
+				...target,
+				id: created["id"]
+			},
 			locale,
 			privileged: true
 		});

package/dist/tools/describe-schema.mjs

@@ -1,67 +1,71 @@
+import { defineMcpxTool } from "../define-tool.mjs";
 import { jsonResult } from "../result.mjs";
 import { nodePropertiesFor } from "../schema/lexical.mjs";
 import { translatorFor } from "../i18n.mjs";
+import { SchemaError } from "../schema/errors.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 { entityShape } from "./shared.mjs";
+import { resolveEntity } from "./document.mjs";
 import { z } from "zod";
-/**
-* Describes each requested path independently and returns a per
-* path error object instead of failing the call, so a client exploring several
-* branches at once keeps the nodes that did resolve. `expand` swaps the
-* requested paths for every node reachable from the root and appends a
-* truncation notice past {@link REACHABLE_PATHS_LIMIT}.
-*/ const describeSchema = defineMcpxTool({
-	name: "describeSchema",
-	description: `Describes the writable shape of a document, one node at a time.
-
-Pass exactly one of "collection" and "global". A global is a singleton: it has no id, is not listed by findDocuments and cannot be created.
-
-Call it with no "paths" to get a collection's own fields. Every "blocks" field stops there and lists the block slugs it accepts instead of nesting them; each node's "next" lists the ready-to-use paths for those blocks, so pass any entry of "next" as a "paths" element to descend, e.g. "/layout/sections/sectionWrapper" and then "/layout/sections/sectionWrapper/modules/hero". A block is described as it exists at that position, because the same block can accept different children elsewhere.
-
-A "richText" field stops there too. It lists the Lexical node types it accepts in "nodes", and "next" carries a path for every node type that holds fields of its own: "/content/link" for a link node, "/content/block/callout" and "/content/inlineBlock/badge" for the block nodes. Descend to get the real field list instead of guessing what a node carries. Upload nodes are not addressable, because their fields depend on the collection the node points at.
-
-Write each Lexical node the way Lexical serializes it, with every property its type carries rather than a trimmed subset, and with the value Lexical would have written there. Those requirements are stated rather than left to be discovered: the response carries one final "nodeProperties" entry keyed by node type, naming each property and what belongs there in the same words a refused write uses, so a node can be built from this response alone. A field's own "nodes" says which of those types it accepts. The root takes exactly "children", "direction", "format", "indent", "type" and "version" and refuses anything else. The admin editor rehydrates nodes through their classes, so a list item whose "indent" is missing, null or a string is stored and then throws on open, and a heading whose "tag" is a number is stored untagged. A write naming a property means exactly that. A state whose root holds no children is refused however it is written, because Lexical reads it as empty and throws; clear a field with null instead.
+//#region src/tools/describe-schema.ts
+const DESCRIPTION = `Describes the fields of a collection or global, one node at a time. Use it before a query or a write.
 
-A rich text field's value is addressable too, so an edit does not have to rewrite the whole state: "/content/root/children/0" is the first top-level node, "/content/root/children/0/children/1" a node inside it, "/content/root/children/0/tag" one property of a node, and "/content/root/children/0/fields/url" a field of a node, described at the "next" path for that node type. Append a node with "/-". Which node sits at an index is only knowable from what is stored, so read it first: getDocument with "outline" answers with the pointer, type, "version" and a text excerpt for every node, which is far cheaper than reading the whole state.
+Without "paths" it returns the top-level node. A node has a "schemaPath", its "fields" and "next". Each field has a "path" relative to its node, a "type" and constraints such as "required", "localized", "readOnly", "options" and "relationTo". A "blocks" field lists the block slugs it accepts, and a "richText" field lists its node types in "nodes". "next" holds the schema paths of the blocks and rich text node types with fields below the node, e.g. "/layout/sections/sectionWrapper" or "/content/block/callout". Pass them as "paths" to describe those nodes. A block can accept different children at another position, so describe it at the schema path where it is used.
 
-Paths here use the same JSON Pointer syntax as getDocument and patchDocument, and are already resolved through anything that does not nest in the stored document. The difference is only what stands in an element position: a path names an array element "*" and a block by its slug, where a pointer into a document carries a 0-based index. So "/items/*/title" is written at "/items/0/title", and "/layout/sections/hero" at "/layout/sections/0". Inside a rich text field that substitution does not apply: a path there names the node type, and a block node its slug, where a pointer enters the stored state at "root" and walks "children" by an index counted over every child at that level, not over the blocks among them, with the node's own fields under "fields". So "/content/block/practice-note/variant" is written at "/content/root/children/7/fields/variant".
+When the response contains a rich text field, the response also carries a "nodeProperties" entry: the properties each node type must carry. Build every rich text node from it. Upload nodes have no schema path.
 
-Fields Payload maintains (id, _status, createdAt, updatedAt) are never listed and cannot be written. Fields marked readOnly are listed but refused on write.`,
+id, _status, createdAt and updatedAt are not listed and cannot be written. A field marked "readOnly" cannot be written either.`;
+const PATHS_LIMIT = 400;
+/**
+* Describes each requested path independently and returns a per-path error
+* object instead of failing the call, so a client exploring several branches
+* keeps the nodes that resolved. `expand` replaces the requested paths with
+* every node reachable from the root and adds a truncation notice past
+* {@link REACHABLE_PATHS_LIMIT}.
+*/ const describeSchema = defineMcpxTool({
+	name: "describeSchema",
+	description: 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 to describe.",
-			global: "Global to describe."
-		}),
-		paths: z.array(z.string()).optional().describe("Schema paths to describe, e.g. \"/layout/sections/sectionWrapper\". Omit for the collection root."),
-		expand: z.boolean().optional().describe("Return every node reachable from the root in one response. Ignores paths.")
+		...entityShape(scope, "read", "Instead of \"collection\"."),
+		paths: z.array(z.string()).max(PATHS_LIMIT).optional().describe("Schema paths from \"next\". Omit for the top-level node."),
+		expand: z.boolean().optional().describe("Return the top-level node and every node below it in one response, instead of \"paths\".")
 	}),
 	handler: ({ args, scope }) => {
-		const ref = refOf(resolveTarget(scope, args, "read"));
+		const ref = resolveEntity(scope, args, "read");
 		const { config } = scope.req.payload;
 		const describeNode = nodeDescriber(translatorFor(scope.req.i18n));
 		const expanded = args.expand === true ? reachableSchemaPaths(config, ref) : void 0;
-		const nodes = (expanded?.paths ?? (args.paths && args.paths.length > 0 ? args.paths : [""])).map((schemaPath) => {
+		const requested = expanded?.paths ?? (args.paths && args.paths.length > 0 ? args.paths : [""]);
+		const failures = [];
+		const nodes = requested.map((schemaPath) => {
 			try {
 				return describeNode(config, ref, schemaPath);
 			} catch (error) {
+				if (error instanceof SchemaError) return {
+					error: error.message,
+					schemaPath
+				};
+				failures.push(error);
 				return {
-					error: error instanceof Error ? error.message : "Unknown error",
+					error: "Internal error",
 					schemaPath
 				};
 			}
 		});
+		if (failures.length > 0) scope.req.payload.logger.error({
+			err: failures[0],
+			msg: `[payloadcms-mcpx] Describing ${String(failures.length)} schema paths failed.`
+		});
 		const nodeTypes = nodes.flatMap((node) => (node.fields ?? []).flatMap((field) => field.nodes ?? []));
 		if (nodeTypes.length > 0) nodes.push({ nodeProperties: nodePropertiesFor(nodeTypes) });
 		if (expanded?.truncated) nodes.push({ error: `Result truncated after ${String(400)} nodes. Request explicit paths instead.` });
-		return Promise.resolve(jsonResult(nodes));
+		return jsonResult(nodes);
 	}
 });
 //#endregion

package/dist/tools/document.mjs

@@ -0,0 +1,84 @@
+import { errorResult } from "../result.mjs";
+import { slugsFor } from "./shared.mjs";
+import { APIError, Forbidden, NotFound } from "payload";
+//#region src/tools/document.ts
+/**
+* A raw input shape leaves no top-level `.refine` to express "exactly one of
+* collection and global", so the rule is enforced here, with a message naming
+* the offending arguments.
+*/ const resolveEntity = (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 found = scope.req.payload.collections[collection];
+		if (!allowedSlugs.collections.includes(collection) || !found) throw new Forbidden(scope.req.t);
+		return {
+			kind: "collection",
+			slug: collection,
+			config: found.config
+		};
+	}
+	const slug = global;
+	const found = scope.req.payload.globals.config.find((candidate) => candidate.slug === slug);
+	if (!allowedSlugs.globals.includes(slug) || !found) throw new Forbidden(scope.req.t);
+	return {
+		kind: "global",
+		slug,
+		config: found
+	};
+};
+/**
+* Resolves the entity and checks `id` against it. A collection document needs
+* one; a global is a singleton and must not carry one. The schema cannot
+* express that, so it is checked here and stated on the `id` parameter.
+*/ const resolveDocument = (scope, args, operation) => {
+	const target = resolveEntity(scope, args, operation);
+	if (target.kind === "global") {
+		if (args.id !== void 0) throw new APIError(`"id" must be omitted when "global" is "${target.slug}"; a global is a singleton.`, 400);
+		return target;
+	}
+	if (args.id === void 0) throw new APIError(`"id" is required when "collection" is "${target.slug}".`, 400);
+	return {
+		...target,
+		id: args.id
+	};
+};
+/** What a response names its subject by: a document's id, or a global's slug. */ const identityOf = (target, id) => target.kind === "collection" ? { id } : { global: target.slug };
+const sameInstant = (left, right) => (typeof left === "string" || left instanceof Date) && new Date(left).getTime() === new Date(right).getTime();
+/** Refuses a write when the document changed since the client read it. */ const staleReadResult = (doc, expectedUpdatedAt, message) => expectedUpdatedAt !== void 0 && !sameInstant(doc["updatedAt"], expectedUpdatedAt) ? errorResult(message, { updatedAt: doc["updatedAt"] }) : void 0;
+/**
+* Reads the current draft in a fixed locale with no fallback, which is the
+* shape that may be written back or validated without mixing locales.
+*/ const readDraft = async (scope, args) => {
+	const { payload } = scope.req;
+	const privileged = args.privileged === true;
+	const shared = {
+		depth: 0,
+		draft: true,
+		...args.locale === void 0 ? {} : {
+			locale: args.locale,
+			fallbackLocale: false
+		},
+		overrideAccess: privileged,
+		showHiddenFields: privileged,
+		req: scope.req
+	};
+	if (args.target.kind === "collection") {
+		const doc = await payload.findByID({
+			...shared,
+			collection: args.target.slug,
+			id: args.target.id,
+			disableErrors: true
+		});
+		if (!doc) throw new NotFound(scope.req.t);
+		return doc;
+	}
+	return await payload.findGlobal({
+		...shared,
+		slug: args.target.slug
+	});
+};
+//#endregion
+export { identityOf, readDraft, resolveDocument, resolveEntity, staleReadResult };

package/dist/tools/find-documents.mjs

@@ -1,47 +1,57 @@
+import { defineMcpxTool } from "../define-tool.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 { stripAdminHidden } from "../schema/admin-hidden.mjs";
+import "../schema/index.mjs";
+import { READ_LOCALE_DESCRIPTION, depthShape, localeOf, localeShape, slugEnum } from "./shared.mjs";
+import { resolveEntity } from "./document.mjs";
+import { assertQueryable } from "./query-paths.mjs";
+import { mcpxReadRequest } from "./read-request.mjs";
 import { z } from "zod";
 /**
 * Collection-only: a global is a singleton, so there is nothing to list.
 *
-* The query goes to Payload with `overrideAccess: false`, so the collection's
-* own access control decides what comes back. `limit` and `depth` are bounded
-* by the configured limits in the schema itself, which puts the ceiling in
-* front of the client rather than silently clamping behind it.
+* The query uses `overrideAccess: false`, so the collection's own access
+* control decides what comes back. The schema bounds `limit` and `depth` by the
+* configured limits, so the client sees the ceiling instead of being clamped
+* silently.
 */ 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.`,
+	description: `Finds documents in a collection. Returns one page of "docs" with paging totals. "where" is a Payload query, e.g. {"title":{"contains":"home"}}, with dots for nested fields, e.g. "items.heading". A "where" or "sort" on a hidden field, or through a relationship into a collection this key cannot read, is refused.`,
 	annotations: {
 		readOnlyHint: true,
 		openWorldHint: false
 	},
-	isEnabled: (scope) => scope.readable.length > 0,
+	isEnabled: (scope) => scope.collections.readable.length > 0,
 	inputSchema: (scope) => ({
-		collection: slugEnum(scope.readable).describe("Collection to search."),
-		where: z.record(z.string(), z.unknown()).optional().describe("Payload where query."),
-		sort: z.string().optional().describe("Sort field, prefix with \"-\" for descending."),
-		limit: z.number().int().min(1).max(scope.limits.maxLimit).optional().describe(`Documents per page. Default 10, at most ${String(scope.limits.maxLimit)}.`),
-		page: z.number().int().min(1).optional().describe("Page number, from 1."),
+		collection: slugEnum(scope.collections.readable),
+		where: z.record(z.string(), z.unknown()).optional(),
+		sort: z.string().optional().describe("e.g. \"-updatedAt\" for descending."),
+		limit: z.number().int().min(1).max(scope.limits.maxLimit).optional().describe("Default 10."),
+		page: z.number().int().min(1).optional(),
 		...depthShape(scope),
 		select: z.record(z.string(), z.unknown()).optional().describe("Fields to return, e.g. {\"title\":true}."),
 		...localeShape(scope, {
 			required: false,
-			description: "Locale to read. Defaults to the default locale."
+			description: READ_LOCALE_DESCRIPTION
 		}),
-		draft: z.boolean().optional().describe("Include the latest drafts. Default true.")
+		draft: z.boolean().optional().describe("Default true: latest drafts.")
 	}),
 	handler: async ({ args, scope }) => {
-		resolveTarget(scope, { collection: args.collection }, "read");
+		resolveEntity(scope, { collection: args.collection }, "read");
 		const locale = localeOf(scope, args.locale);
+		assertQueryable(scope, {
+			collection: args.collection,
+			where: args.where,
+			sort: args.sort,
+			locale
+		});
 		const result = await scope.req.payload.find({
 			collection: args.collection,
 			depth: args.depth ?? 0,
 			draft: args.draft ?? true,
 			limit: args.limit ?? 10,
 			overrideAccess: false,
-			req: scope.req,
+			req: mcpxReadRequest(scope),
 			...args.page === void 0 ? {} : { page: args.page },
 			...args.sort === void 0 ? {} : { sort: args.sort },
 			...args.where === void 0 ? {} : { where: args.where },
@@ -49,7 +59,10 @@ import { z } from "zod";
 			...locale === void 0 ? {} : { locale }
 		});
 		return jsonResult({
-			docs: result.docs,
+			docs: result.docs.map((doc) => stripAdminHidden(scope.req.payload.config, {
+				kind: "collection",
+				slug: args.collection
+			}, doc)),
 			totalDocs: result.totalDocs,
 			page: result.page,
 			totalPages: result.totalPages,

package/dist/tools/find-versions.mjs

@@ -1,18 +1,26 @@
+import { defineMcpxTool } from "../define-tool.mjs";
 import { jsonResult } from "../result.mjs";
-import { idShape, localeOf, localeShape, slugsFor, targetShape } from "./shared.mjs";
-import { requireIdFor, resolveTarget } from "./target.mjs";
-import { defineMcpxTool } from "../types.mjs";
+import { draftVersionSlugs, entityShape, idShape, localeOf, localeShape, slugsFor, widen } from "./shared.mjs";
+import { resolveDocument } from "./document.mjs";
 import { queryVersions } from "./versions.mjs";
+import { APIError } from "payload";
+import { hasDraftsEnabled } from "payload/shared";
 import { z } from "zod";
+//#region src/tools/find-versions.ts
+const DESCRIPTION = `Lists the versions of one document or global, newest first, autosaves included. Returns per version "versionId", "createdAt", "updatedAt", "status", "latest", "autosave" and, where set, "publishedLocale", without the content. Read a version with getDocument "versionId", or compare it with "diffFrom".`;
+const statusShape = (scope) => {
+	const { collections, globals } = draftVersionSlugs(scope);
+	if (collections.length + globals.length === 0) return widen({});
+	return widen({ status: z.enum(["published", "draft"]).optional() });
+};
 /**
 * Bodies are left out so a long history stays small; `getDocument` reads one
 * when it is needed. The document's `read` access is checked first, then
-* Payload's `readVersions`.
+* Payload's `readVersions`. Only entities with `versions: true` in the plugin
+* options are reachable.
 */ const findVersions = defineMcpxTool({
 	name: "findVersions",
-	description: `Lists the version history of one document or global, newest first. Returns metadata only; read a version's body with getDocument and "versionId", or what changed with "diffFrom".
-
-Pass exactly one of "collection" and "global". "id" is required with "collection" and must be omitted with "global". Autosave versions are listed too, marked "autosave".`,
+	description: DESCRIPTION,
 	annotations: {
 		readOnlyHint: true,
 		openWorldHint: false
@@ -22,25 +30,21 @@ Pass exactly one of "collection" and "global". "id" is required with "collection
 		return collections.length + globals.length > 0;
 	},
 	inputSchema: (scope) => ({
-		...targetShape(scope, "versions", {
-			collection: "Collection holding the document.",
-			global: "Global whose history to list."
-		}),
+		...entityShape(scope, "versions"),
 		...idShape(scope, "versions"),
-		limit: z.number().int().min(1).max(scope.limits.maxLimit).optional().describe(`Versions per page. Default 10, at most ${String(scope.limits.maxLimit)}.`),
-		page: z.number().int().min(1).optional().describe("Page number, from 1."),
-		status: z.enum(["published", "draft"]).optional().describe("Only versions with this status."),
+		limit: z.number().int().min(1).max(scope.limits.maxLimit).optional().describe("Default 10."),
+		page: z.number().int().min(1).optional(),
+		...statusShape(scope),
 		...localeShape(scope, {
 			required: false,
-			description: "Locale whose status to report. Defaults to the default locale."
+			description: "Locale whose \"status\" is reported. Defaults to the default locale."
 		})
 	}),
 	handler: async ({ args, scope }) => {
-		const target = resolveTarget(scope, args, "versions");
-		const id = requireIdFor(target, args.id);
+		const target = resolveDocument(scope, args, "versions");
+		if (args.status !== void 0 && !hasDraftsEnabled(target.config)) throw new APIError(`"${target.slug}" has no drafts, so its versions carry no status.`, 400);
 		const result = await queryVersions(scope, {
 			target,
-			id,
 			depth: 0,
 			locale: localeOf(scope, args.locale)
 		}, {