@abinnovision/payloadcms-mcpx 1.0.0-beta.10

package/dist/schema/shape.mjs

@@ -0,0 +1,208 @@
+import { lexicalSubSchema } from "./lexical.mjs";
+import { blockOf, blockSlugsOf, describeAddressableFields, findBlocksField, findRichTextField, splitPath } from "./walk.mjs";
+//#region src/schema/shape.ts
+/**
+* Keys Payload manages on a row that a client may echo back harmlessly.
+*/ const TOLERATED_VALUE_KEYS = /* @__PURE__ */ new Set([
+	"blockName",
+	"blockType",
+	"id"
+]);
+const isPlainObject = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+/**
+* Checks the fields a single Lexical node carries against the schema its
+* feature declares for that node type.
+*
+* A node with nothing to declare, and one whose sub-fields cannot be named at
+* a position, are both left alone.
+*/ const checkNodeFields = (scope, field, node) => {
+	const sub = lexicalSubSchema(field, node.type);
+	if (!sub) return;
+	const data = node.fields;
+	if (!isPlainObject(data)) {
+		scope.problems.push(`${scope.pointer}: a "${node.type}" node carries a "fields" object.`);
+		return;
+	}
+	const nested = {
+		...scope,
+		pointer: `${scope.pointer}/fields`,
+		prefix: []
+	};
+	if (sub.kind === "fields") {
+		checkValue({
+			...nested,
+			fields: sub.fields
+		}, data);
+		return;
+	}
+	const slug = data["blockType"];
+	const block = typeof slug === "string" ? blockOf(scope.config, sub.blocksField, slug) : void 0;
+	if (!block) {
+		scope.problems.push(`${scope.pointer}/fields: "${String(slug)}" is not allowed here. Allowed: ${blockSlugsOf(sub.blocksField).join(", ")}`);
+		return;
+	}
+	checkValue({
+		...nested,
+		fields: block.flattenedFields
+	}, data);
+};
+/**
+* Checks an editor state against what the field's editor can actually
+* produce: every node type, and the fields each node carries.
+*
+* Payload does not: the Lexical validator runs node validations only for the
+* few node types that register one, so a `heading` inside a field whose
+* editor has no heading feature is stored without complaint and only fails
+* later, at render or when the document is reopened in the admin editor. A key
+* a node's fields do not declare is dropped just as silently. The same holds
+* one level down, for the node properties a feature narrows: an `h3` in an
+* editor restricted to `h4` is stored as readily as an `h4`.
+*/ const checkRichText = (scope, editor, value) => {
+	if (!isPlainObject(value) || !isPlainObject(value["root"])) {
+		scope.problems.push(`${scope.pointer}: expected a Lexical editor state with a "root".`);
+		return;
+	}
+	const walk = (nodes, pointer) => {
+		if (!Array.isArray(nodes)) return;
+		nodes.forEach((node, index) => {
+			const at = `${pointer}/${String(index)}`;
+			if (!isPlainObject(node) || typeof node["type"] !== "string") {
+				scope.problems.push(`${at}: every node needs a "type".`);
+				return;
+			}
+			if (!editor.allowed.includes(node["type"])) {
+				scope.problems.push(`${at}: "${node["type"]}" is not available in this field's editor. Allowed: ${editor.allowed.join(", ")}`);
+				return;
+			}
+			for (const [property, values] of Object.entries(editor.nodeOptions?.[node["type"]] ?? {})) {
+				const value = node[property];
+				if (typeof value === "string" && !values.includes(value)) scope.problems.push(`${at}/${property}: "${value}" is not available for a "${node["type"]}" node in this field's editor. Allowed: ${values.join(", ")}`);
+			}
+			if (editor.field) checkNodeFields({
+				...scope,
+				pointer: at
+			}, editor.field, {
+				fields: node["fields"],
+				type: node["type"]
+			});
+			walk(node["children"], `${at}/children`);
+		});
+	};
+	walk(value["root"]["children"], `${scope.pointer}/root/children`);
+};
+const checkLeafValue = (scope, descriptor, value) => {
+	if (descriptor.readOnly) {
+		scope.problems.push(`${scope.pointer}: this field is read-only and cannot be written.`);
+		return;
+	}
+	if (descriptor.type === "richText") {
+		checkRichText(scope, {
+			allowed: descriptor.nodes ?? [],
+			field: findRichTextField(scope.fields, splitPath(descriptor.path)),
+			nodeOptions: descriptor.nodeOptions
+		}, value);
+		return;
+	}
+	if (descriptor.type !== "blocks") return;
+	if (!Array.isArray(value)) {
+		scope.problems.push(`${scope.pointer}: expected an array of blocks.`);
+		return;
+	}
+	const field = findBlocksField(scope.fields, splitPath(descriptor.path));
+	if (!field) return;
+	value.forEach((row, index) => {
+		const slug = isPlainObject(row) ? row["blockType"] : void 0;
+		const block = typeof slug === "string" ? blockOf(scope.config, field, slug) : void 0;
+		if (!block) {
+			scope.problems.push(`${scope.pointer}/${String(index)}: "${String(slug)}" is not allowed here. Allowed: ${blockSlugsOf(field).join(", ")}`);
+			return;
+		}
+		checkValue({
+			...scope,
+			fields: block.flattenedFields,
+			pointer: `${scope.pointer}/${String(index)}`,
+			prefix: []
+		}, row);
+	});
+};
+/**
+* Walks an incoming value against the schema, reporting every shape problem
+* rather than the first.
+*
+* Shape only: unknown field names, unknown block slugs, read-only fields, and
+* rich text nodes or node properties the field's editor cannot produce.
+* Required-ness, row counts, lengths, enum membership and relationship
+* existence stay with Payload, which already checks them and reports them per
+* field. Without this pass a misspelled field inside a new block would be
+* stripped in silence.
+*/ const checkValue = (scope, value) => {
+	if (!isPlainObject(value)) return;
+	const prefixParts = scope.prefix;
+	const relative = describeAddressableFields(scope.fields).flatMap((descriptor) => {
+		const parts = splitPath(descriptor.path);
+		return prefixParts.every((part, offset) => part === parts[offset]) ? [{
+			descriptor,
+			parts: parts.slice(prefixParts.length)
+		}] : [];
+	});
+	for (const [key, entry] of Object.entries(value)) {
+		if (TOLERATED_VALUE_KEYS.has(key)) continue;
+		const candidates = relative.filter(({ parts }) => parts[0] === key);
+		const pointer = `${scope.pointer}/${key}`;
+		if (candidates.length === 0) {
+			scope.problems.push(`${pointer}: no such field. Available: ${[...new Set(relative.map(({ parts }) => parts[0]))].join(", ")}`);
+			continue;
+		}
+		const exact = candidates.find(({ parts }) => parts.length === 1);
+		if (exact) {
+			checkLeafValue({
+				...scope,
+				pointer
+			}, exact.descriptor, entry);
+			continue;
+		}
+		if (candidates.some(({ parts }) => parts[1] === "*")) {
+			if (!Array.isArray(entry)) {
+				scope.problems.push(`${pointer}: expected an array.`);
+				continue;
+			}
+			entry.forEach((row, index) => {
+				checkValue({
+					...scope,
+					pointer: `${pointer}/${String(index)}`,
+					prefix: [
+						...prefixParts,
+						key,
+						"*"
+					]
+				}, row);
+			});
+			continue;
+		}
+		checkValue({
+			...scope,
+			pointer,
+			prefix: [...prefixParts, key]
+		}, entry);
+	}
+};
+/**
+* Shape problems with a value about to be written at a resolved pointer.
+*/ const validateWriteValue = (config, target, value) => {
+	const problems = [];
+	const scope = {
+		config,
+		fields: target.resolution.fields,
+		pointer: target.pointer,
+		prefix: target.resolution.prefix,
+		problems
+	};
+	if (target.resolution.descriptor) {
+		checkLeafValue(scope, target.resolution.descriptor, value);
+		return problems;
+	}
+	checkValue(scope, value);
+	return problems;
+};
+//#endregion
+export { validateWriteValue };

package/dist/schema/walk.d.mts

@@ -0,0 +1,3 @@
+import "./lexical.mjs";
+import "../i18n.mjs";
+import "payload";

package/dist/schema/walk.mjs

@@ -0,0 +1,165 @@
+import { allowedNodeTypes, nodeOptions } from "./lexical.mjs";
+import { translateAny } from "../i18n.mjs";
+import { fieldIsHiddenOrDisabled, fieldIsVirtual } from "payload/shared";
+//#region src/schema/walk.ts
+/**
+* Fields Payload maintains, which a client may neither address nor supply.
+*/ const RESERVED_FIELD_NAMES = /* @__PURE__ */ new Set([
+	"_status",
+	"createdAt",
+	"deletedAt",
+	"id",
+	"updatedAt"
+]);
+/**
+* Shape a JSON Pointer must have to be parseable at all.
+*/ const JSON_POINTER_PATTERN = /^(\/([^~/]|~[01])*)*$/;
+/**
+* Joins segments into a JSON Pointer, so the segments `items`, `*`, `title`
+* read as one path to a subfield of every element of `items`. No segments is
+* the root pointer, `""`.
+*/ const joinPath = (parts) => parts.map((part) => `/${part.replace(/~/g, "~0").replace(/\//g, "~1")}`).join("");
+/**
+* Splits a JSON Pointer into its segments, unescaping `~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, "~"));
+/**
+* Restates a path Payload reports on a validation error (`layout.0.title`) as
+* a JSON Pointer, so everything this plugin hands back addresses documents the
+* same way. Payload's path already carries real indices, so it maps directly.
+*/ const pointerFromPayloadPath = (path) => path ? joinPath(path.split(".")) : "";
+/**
+* Blocks a blocks field accepts, by slug. On a flattened field, whichever of
+* `blockReferences` and `blocks` was declared carries the definitions.
+*/ const blockSlugsOf = (field) => [...new Set((field.blockReferences ?? field.blocks).map((block) => typeof block === "string" ? block : block.slug))];
+/**
+* Resolves one of a blocks field's slugs to its definition.
+*
+* A definition inlined on the field wins over the shared registry. 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.
+* The registry (`config.blocks`) is the fallback for slugs referenced by name.
+*/ const blockOf = (config, field, slug) => {
+	const declared = field.blockReferences ?? field.blocks;
+	const inline = declared.find((block) => typeof block !== "string" && block.slug === slug);
+	if (inline) return inline;
+	return declared.includes(slug) ? config.blocks?.find((block) => block.slug === slug) : void 0;
+};
+const isSkipped = (field) => !("name" in field) || field.type === "join" || RESERVED_FIELD_NAMES.has(field.name) || fieldIsVirtual(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);
+	return {
+		path,
+		type: field.type,
+		...description === void 0 ? {} : { description },
+		..."required" in field && field.required ? { required: true } : {},
+		..."localized" in field && field.localized ? { localized: true } : {},
+		...readOnly ? { readOnly: true } : {}
+	};
+};
+const describeLeaf = (field, at) => {
+	const descriptor = describeBase(field, at);
+	if (field.type === "select" || field.type === "radio") descriptor.options = field.options.map((option) => typeof option === "string" ? option : option.value);
+	if (field.type === "relationship" || field.type === "upload") descriptor.relationTo = field.relationTo;
+	if ((field.type === "select" || field.type === "relationship" || field.type === "upload") && field.hasMany === true) descriptor.hasMany = true;
+	if ((field.type === "text" || field.type === "textarea") && field.maxLength !== void 0) descriptor.maxLength = field.maxLength;
+	if ((field.type === "text" || field.type === "textarea") && field.minLength !== void 0) descriptor.minLength = field.minLength;
+	if (field.type === "number" && field.max !== void 0) descriptor.max = field.max;
+	if (field.type === "number" && field.min !== void 0) descriptor.min = field.min;
+	if (field.type === "richText") {
+		descriptor.nodes = allowedNodeTypes(field);
+		const options = nodeOptions(field, descriptor.nodes);
+		if (options) descriptor.nodeOptions = options;
+	}
+	return descriptor;
+};
+const withRows = (descriptor, field) => ({
+	...descriptor,
+	...field.minRows === void 0 ? {} : { minRows: field.minRows },
+	...field.maxRows === void 0 ? {} : { maxRows: field.maxRows }
+});
+/**
+* Whether a descriptor stands for a construct that only holds other fields.
+*
+* These describe a position rather than a value, so everything that resolves a
+* path to something writable skips them; only {@link describeNode} reports
+* them, 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, which has already merged every
+* construct that exists only in the admin UI (unnamed tabs, unnamed groups,
+* `row`, `collapsible`) and dropped `ui` fields. 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 instead
+* of descending, which keeps a node proportional to the number of blocks it
+* allows rather than to the size of their definitions.
+*
+* `translate` resolves each `admin.description` to the request's language.
+* Callers that walk for paths alone leave it out and get the language-agnostic
+* default, so a missing argument costs language selection, never the
+* description itself.
+*/ const describeFields = (fields, translate = translateAny) => {
+	const walk = (current, prefix, parentReadOnly) => current.flatMap((field) => {
+		if (isSkipped(field)) return [];
+		const readOnly = parentReadOnly || isReadOnly(field);
+		const path = [...prefix, field.name];
+		const at = {
+			path: joinPath(path),
+			readOnly,
+			translate
+		};
+		if (field.type === "tab" || field.type === "group") {
+			const own = describeBase(field, at);
+			return [...isInformative(own) ? [own] : [], ...walk(field.flattenedFields, path, readOnly)];
+		}
+		if (field.type === "array") return [withRows(describeBase(field, at), field), ...walk(field.flattenedFields, [...path, "*"], readOnly)];
+		if (field.type === "blocks") return [withRows({
+			...describeBase(field, at),
+			blocks: blockSlugsOf(field)
+		}, field)];
+		return [describeLeaf(field, at)];
+	});
+	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 describeNode} reports one.
+*/ const describeAddressableFields = (fields) => describeFields(fields).filter((descriptor) => !isContainer(descriptor));
+/**
+* Locates the blocks field that a resolved descriptor path refers to.
+*/ const findBlocksField = (fields, path) => {
+	for (const field of fields) {
+		if (!("name" in field) || field.name !== path[0]) continue;
+		if (field.type === "blocks" && path.length === 1) return field;
+		if (field.type === "tab" || field.type === "group") return findBlocksField(field.flattenedFields, path.slice(1));
+		if (field.type === "array" && path[1] === "*") return findBlocksField(field.flattenedFields, path.slice(2));
+	}
+};
+/**
+* Locates the rich text field that a resolved descriptor path refers to, so
+* its editor can be introspected for the fields its nodes carry.
+*/ const findRichTextField = (fields, path) => {
+	for (const field of fields) {
+		if (!("name" in field) || field.name !== path[0]) continue;
+		if (field.type === "richText" && path.length === 1) return field;
+		if (field.type === "tab" || field.type === "group") return findRichTextField(field.flattenedFields, path.slice(1));
+		if (field.type === "array" && path[1] === "*") return findRichTextField(field.flattenedFields, path.slice(2));
+	}
+};
+const targetOf = (config, ref) => {
+	const found = ref.kind === "collection" ? config.collections.find((candidate) => candidate.slug === ref.slug) : config.globals.find((candidate) => candidate.slug === ref.slug);
+	if (!found) throw new Error(`Unknown ${ref.kind} "${ref.slug}".`);
+	return found;
+};
+//#endregion
+export { JSON_POINTER_PATTERN, RESERVED_FIELD_NAMES, blockOf, blockSlugsOf, describeAddressableFields, describeFields, findBlocksField, findRichTextField, joinPath, pointerFromPayloadPath, splitPath, targetOf };

package/dist/tools/create-document.mjs

@@ -0,0 +1,68 @@
+import { errorResult, jsonResult } from "../endpoint/result.mjs";
+import { localeOf, localeShape, readTarget, slugEnum } from "./shared.mjs";
+import { resolveTarget } from "./target.mjs";
+import { validateWriteValue } from "../schema/shape.mjs";
+import { stripRowIds } from "../write/patch.mjs";
+import { collectPublishBlockers } from "../write/publish-blockers.mjs";
+import { z } from "zod";
+//#region src/tools/create-document.ts
+const createDocument = {
+	name: "createDocument",
+	description: `Creates a new document as a draft from a minimal seed. Only the fields describeSchema lists may appear in "data"; unknown keys are refused with the valid siblings. The draft may be incomplete: the response lists "publishBlockers", which patchDocument can then work through. Use this when no document exists yet; prefer patching an existing draft otherwise.`,
+	annotations: {
+		readOnlyHint: false,
+		destructiveHint: false,
+		idempotentHint: false,
+		openWorldHint: false
+	},
+	isEnabled: (scope) => scope.writable.length > 0,
+	inputSchema: (scope) => ({
+		collection: slugEnum(scope.writable).describe("Collection to create the document in."),
+		...localeShape(scope, {
+			required: true,
+			description: "Locale the localized fields of the seed belong to."
+		}),
+		data: z.record(z.string(), z.unknown()).describe("Initial field values, as describeSchema lists them.")
+	}),
+	handler: async (args, scope) => {
+		const target = resolveTarget(scope, { collection: args.collection }, "write");
+		const { payload } = scope.req;
+		const locale = localeOf(scope, args.locale);
+		const { id: _ignored, ...seed } = args.data;
+		const problems = validateWriteValue(payload.config, {
+			pointer: "",
+			resolution: {
+				fields: target.config.flattenedFields,
+				prefix: []
+			}
+		}, seed);
+		if (problems.length > 0) return errorResult("Nothing was created.", { problems });
+		const created = await payload.create({
+			collection: args.collection,
+			data: stripRowIds(seed),
+			depth: 0,
+			draft: true,
+			overrideAccess: false,
+			req: scope.req,
+			...locale === void 0 ? {} : { locale }
+		});
+		const saved = await readTarget(scope, {
+			target,
+			id: created["id"],
+			locale,
+			privileged: true
+		});
+		const publishBlockers = await collectPublishBlockers(scope.req, {
+			doc: saved,
+			entity: target
+		});
+		return jsonResult({
+			id: saved["id"],
+			status: saved["_status"],
+			updatedAt: saved["updatedAt"],
+			...publishBlockers.length > 0 ? { publishBlockers } : {}
+		});
+	}
+};
+//#endregion
+export { createDocument };

package/dist/tools/describe-schema.mjs

@@ -0,0 +1,54 @@
+import { translatorFor } from "../i18n.mjs";
+import { jsonResult } from "../endpoint/result.mjs";
+import { targetShape } from "./shared.mjs";
+import { refOf, resolveTarget } from "./target.mjs";
+import { nodeDescriber, reachableSchemaPaths } from "../schema/describe.mjs";
+import { z } from "zod";
+//#region src/tools/describe-schema.ts
+const describeSchema = {
+	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.
+
+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".
+
+Fields Payload maintains (id, _status, createdAt, updatedAt) are never listed and cannot be written. Fields marked readOnly are listed but refused on write.`,
+	annotations: {
+		readOnlyHint: true,
+		openWorldHint: false
+	},
+	isEnabled: (scope) => scope.readable.length + scope.readableGlobals.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.")
+	}),
+	handler: (args, scope) => {
+		const ref = refOf(resolveTarget(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) => {
+			try {
+				return describeNode(config, ref, schemaPath);
+			} catch (error) {
+				return {
+					error: error instanceof Error ? error.message : "Unknown error",
+					schemaPath
+				};
+			}
+		});
+		if (expanded?.truncated) nodes.push({ error: `Result truncated after ${String(400)} nodes. Request explicit paths instead.` });
+		return Promise.resolve(jsonResult(nodes));
+	}
+};
+//#endregion
+export { describeSchema };

package/dist/tools/find-documents.mjs

@@ -0,0 +1,55 @@
+import { jsonResult } from "../endpoint/result.mjs";
+import { depthShape, localeOf, localeShape, slugEnum } from "./shared.mjs";
+import { resolveTarget } from "./target.mjs";
+import { z } from "zod";
+//#region src/tools/find-documents.ts
+const findDocuments = {
+	name: "findDocuments",
+	description: `Finds documents in a collection. "where" is a Payload query object, e.g. {"title":{"contains":"home"}} or {"and":[...]}; "select" picks fields, e.g. {"title":true}. Drafts are included by default so unpublished work is visible. Keep depth at 0 unless populated relationships are needed; ids are enough for writes.`,
+	annotations: {
+		readOnlyHint: true,
+		openWorldHint: false
+	},
+	isEnabled: (scope) => scope.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.options.limits.maxLimit).optional().describe(`Documents per page. Default 10, at most ${String(scope.options.limits.maxLimit)}.`),
+		page: z.number().int().min(1).optional().describe("Page number, from 1."),
+		...depthShape(scope),
+		select: z.record(z.string(), z.unknown()).optional().describe("Fields to return, e.g. {\"title\":true}."),
+		...localeShape(scope, {
+			required: false,
+			description: "Locale to read. Defaults to the default locale."
+		}),
+		draft: z.boolean().optional().describe("Include the latest drafts. Default true.")
+	}),
+	handler: async (args, scope) => {
+		resolveTarget(scope, { collection: args.collection }, "read");
+		const locale = localeOf(scope, args.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,
+			...args.page === void 0 ? {} : { page: args.page },
+			...args.sort === void 0 ? {} : { sort: args.sort },
+			...args.where === void 0 ? {} : { where: args.where },
+			...args.select === void 0 ? {} : { select: args.select },
+			...locale === void 0 ? {} : { locale }
+		});
+		return jsonResult({
+			docs: result.docs,
+			totalDocs: result.totalDocs,
+			page: result.page,
+			totalPages: result.totalPages,
+			limit: result.limit,
+			hasNextPage: result.hasNextPage
+		});
+	}
+};
+//#endregion
+export { findDocuments };

package/dist/tools/get-document.mjs

@@ -0,0 +1,68 @@
+import { JSON_POINTER_PATTERN } from "../schema/walk.mjs";
+import { errorResult, jsonResult } from "../endpoint/result.mjs";
+import { depthShape, idShape, localeOf, localeShape, targetShape } from "./shared.mjs";
+import { requireIdFor, resolveTarget } from "./target.mjs";
+import { z } from "zod";
+import { Pointer } from "rfc6902";
+//#region src/tools/get-document.ts
+const getDocument = {
+	name: "getDocument",
+	description: `Reads one document, or one subtree of it when "path" is given as a JSON pointer such as "/layout/sections/2". Returns the latest draft by default. Read before patching: the response carries "updatedAt" for expectedUpdatedAt and the indices pointers need.
+
+Pass exactly one of "collection" and "global". "id" is required with "collection" and must be omitted with "global", because a global is a singleton.`,
+	annotations: {
+		readOnlyHint: true,
+		openWorldHint: false
+	},
+	isEnabled: (scope) => scope.readable.length + scope.readableGlobals.length > 0,
+	inputSchema: (scope) => ({
+		...targetShape(scope, "read", {
+			collection: "Collection holding the document.",
+			global: "Global to 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\"."),
+		...depthShape(scope),
+		...localeShape(scope, {
+			required: false,
+			description: "Locale to read. Defaults to the default locale."
+		}),
+		draft: z.boolean().optional().describe("Return the latest draft. Default true.")
+	}),
+	handler: async (args, scope) => {
+		const target = resolveTarget(scope, args, "read");
+		const id = requireIdFor(target, args.id);
+		const locale = localeOf(scope, args.locale);
+		const shared = {
+			depth: args.depth ?? 0,
+			draft: args.draft ?? true,
+			overrideAccess: false,
+			req: scope.req,
+			...locale === void 0 ? {} : { locale }
+		};
+		const doc = await (target.kind === "collection" ? scope.req.payload.findByID({
+			...shared,
+			collection: target.slug,
+			id
+		}) : scope.req.payload.findGlobal({
+			...shared,
+			slug: target.slug
+		}));
+		if (args.path === void 0 || args.path === "") return jsonResult(doc);
+		let value;
+		try {
+			value = Pointer.fromJSON(args.path).get(doc);
+		} catch {
+			return errorResult(`"${args.path}" is not a valid JSON pointer.`);
+		}
+		return jsonResult({
+			...target.kind === "collection" ? { id: doc["id"] } : { global: target.slug },
+			status: doc["_status"],
+			updatedAt: doc["updatedAt"],
+			path: args.path,
+			value
+		});
+	}
+};
+//#endregion
+export { getDocument };

package/dist/tools/index.mjs

@@ -0,0 +1,23 @@
+import { createDocument } from "./create-document.mjs";
+import { describeSchema } from "./describe-schema.mjs";
+import { findDocuments } from "./find-documents.mjs";
+import { getDocument } from "./get-document.mjs";
+import { listCapabilities } from "./list-capabilities.mjs";
+import { patchDocument } from "./patch-document.mjs";
+import { validateDocument } from "./validate-document.mjs";
+//#region src/tools/index.ts
+/**
+* The builtin tools in registration order. The surface is fixed: adding a
+* collection, block or field never changes it. Typed over `never` because
+* each tool validates its own arguments through its input schema.
+*/ const BUILTIN_TOOLS = [
+	listCapabilities,
+	describeSchema,
+	findDocuments,
+	getDocument,
+	patchDocument,
+	createDocument,
+	validateDocument
+];
+//#endregion
+export { BUILTIN_TOOLS };