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

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,124 @@
+import { errorResult } from "../result.mjs";
+import { collectPublishBlockers } from "../write/publish-blockers.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
+	});
+};
+/**
+* {@link collectPublishBlockers} over the draft of each locale, each blocker
+* tagged with its locale. Locales run in turn because hooks share `req`, and
+* the request's locale and fallback locale are restored afterwards.
+*/ const collectLocaleBlockers = async (scope, target, locales) => {
+	const { req } = scope;
+	const { fallbackLocale, locale: requestLocale } = req;
+	const blockers = [];
+	let unavailable = false;
+	for (const locale of locales) try {
+		const doc = await readDraft(scope, {
+			target,
+			locale,
+			privileged: true
+		});
+		const result = await collectPublishBlockers(req, {
+			doc,
+			entity: target
+		});
+		unavailable ||= result.unavailable === true;
+		blockers.push(...result.blockers.map((entry) => ({
+			...entry,
+			locale
+		})));
+	} catch (error) {
+		req.payload.logger.warn(`[payloadcms-mcpx] Could not read the ${target.slug} draft in ${locale}: ${error instanceof Error ? error.message : "unknown error"}`);
+		unavailable = true;
+	}
+	if (requestLocale !== void 0) req.locale = requestLocale;
+	if (fallbackLocale !== void 0) req.fallbackLocale = fallbackLocale;
+	return {
+		blockers,
+		...unavailable ? { unavailable: true } : {}
+	};
+};
+//#endregion
+export { collectLocaleBlockers, 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 that keep Payload versions 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)
 		}, {

package/dist/tools/get-document.mjs

@@ -1,28 +1,32 @@
+import { defineMcpxTool } from "../define-tool.mjs";
 import { errorResult, jsonResult } from "../result.mjs";
-import { JSON_POINTER_PATTERN, findRichTextField, splitPath } from "../schema/walk.mjs";
+import { JSON_POINTER_PATTERN, prototypeSegmentProblem, splitPath } from "../schema/path.mjs";
+import { findRichTextField } from "../schema/walk.mjs";
+import { SchemaError } from "../schema/errors.mjs";
 import { lexicalOutline } from "../schema/outline.mjs";
 import { resolveDataPointer } from "../schema/pointer.mjs";
 import "../schema/index.mjs";
-import { depthShape, idSchema, idShape, localeOf, localeShape, slugsFor, targetShape } from "./shared.mjs";
-import { refOf, requireIdFor, resolveTarget } from "./target.mjs";
-import { defineMcpxTool } from "../types.mjs";
+import { downloadHandoff, downloadSlugs } from "../upload/file.mjs";
+import { READ_LOCALE_DESCRIPTION, depthShape, entityShape, idSchema, idShape, localeOf, localeShape, slugsFor, widen } from "./shared.mjs";
+import { identityOf, resolveDocument } from "./document.mjs";
 import { diffDocuments, loadPublished, loadVersion, readLive } from "./versions.mjs";
 import { APIError } from "payload";
 import { z } from "zod";
 import { Pointer } from "rfc6902";
 //#region src/tools/get-document.ts
 const OUTLINE_ERROR = "\"outline\" applies to a rich text field; give \"path\" for one.";
-const DESCRIPTION = `Reads one document, or one subtree of it when "path" is given as a JSON pointer such as "/layout/sections/2". Returns the latest draft by default. Read before patching: the response carries "updatedAt" for expectedUpdatedAt and the indices pointers need.
+const VERSION_PARAGRAPH = `
 
-Pass exactly one of "collection" and "global". "id" is required with "collection" and must be omitted with "global", because a global is a singleton.
-
-Set "outline" on a rich text "path" to get a compact positional listing of its nodes instead of the raw editor state.
-
-On an entity with versions, "versionId" (from findVersions) reads that version instead. "diffFrom" returns the RFC 6902 operations turning a version, or "published" (the newest version with published status, regardless of locale), into the document read, in the pointer syntax patchDocument takes and limited to "path" when given. To revert, pass the old version as "versionId" and the latest one from findVersions as "diffFrom", then apply the patch with patchDocument.`;
-/** Refuses `versionId` and `diffFrom` where they cannot apply. */ const assertVersionArgs = (scope, target, args) => {
+"versionId" and "diffFrom" work where findVersions does. To revert, call getDocument with the old version as "versionId", the version findVersions marks "latest" as "diffFrom" and the locale you will write, then apply the returned "patch" with patchDocument.`;
+const DESCRIPTION = `Reads one document or global, or with "path" only the value at that pointer. Returns the latest draft by default, with the "updatedAt" a write takes as "expectedUpdatedAt".`;
+const exposesVersions = (scope) => {
+	const { collections, globals } = slugsFor(scope, "versions");
+	return collections.length + globals.length > 0;
+};
+const assertVersionArgs = (scope, target, args) => {
 	if (args.versionId === void 0 && args.diffFrom === void 0) return;
 	const { collections, globals } = slugsFor(scope, "versions");
-	if (!(target.kind === "collection" ? collections : globals).includes(target.slug)) throw new APIError(`"${target.slug}" keeps no versions.`, 400);
+	if (!(target.kind === "collection" ? collections : globals).includes(target.slug)) throw new APIError(`"${target.slug}" does not expose version history.`, 400);
 	if (args.versionId !== void 0 && args.draft !== void 0) throw new APIError("Pass either \"versionId\" or \"draft\", not both.", 400);
 	if (args.diffFrom !== void 0 && args.outline) throw new APIError("\"outline\" cannot be combined with \"diffFrom\".", 400);
 };
@@ -36,39 +40,57 @@ const diffResult = async (scope, read, diff, doc) => {
 		patch: diffDocuments(from.version, doc, diff.pointer)
 	});
 };
+const versionShape = (scope) => {
+	if (!exposesVersions(scope)) return widen({});
+	return widen({
+		versionId: idSchema.optional().describe("From findVersions. Not with \"draft\"."),
+		diffFrom: idSchema.optional().describe("Version id, or \"published\" for the newest version published in any locale. Returns {from, to, patch}, the JSON Patch from that version to what is read.")
+	});
+};
+const downloadShape = (scope) => {
+	const slugs = downloadSlugs(scope);
+	return widen(slugs.length === 0 ? {} : { download: z.literal(true).optional().describe(`Only for ${slugs.join(", ")}. Adds "download": GET its "url" with its "headers" once, within 5 minutes, for the file. Not with "path", "versionId" or "diffFrom".`) });
+};
+const assertDownloadArgs = (scope, target, args) => {
+	if (target.kind === "global" || !downloadSlugs(scope).includes(target.slug)) throw new APIError(`"${target.slug}" has no file to download.`, 400);
+	if (args.path !== void 0 || args.versionId !== void 0 || args.diffFrom !== void 0) throw new APIError("\"download\" cannot be combined with \"path\", \"versionId\" or \"diffFrom\".", 400);
+};
+const withDownload = async (scope, doc, target) => typeof doc["filename"] === "string" ? jsonResult({
+	...doc,
+	download: await downloadHandoff(scope, target)
+}) : errorResult("This document has no file to download.");
 /**
 * With `path` the handler returns the subtree plus the `id`, `_status` and
-* `updatedAt` a client needs to write back, so a caller reading one branch
-* still gets the timestamp `expectedUpdatedAt` wants without a second call.
+* `updatedAt` a client needs to write back, so reading one branch still gives
+* the `expectedUpdatedAt` timestamp without a second call.
 */ const getDocument = defineMcpxTool({
 	name: "getDocument",
-	description: DESCRIPTION,
+	description: (scope) => exposesVersions(scope) ? DESCRIPTION + VERSION_PARAGRAPH : DESCRIPTION,
 	annotations: {
 		readOnlyHint: true,
 		openWorldHint: false
 	},
-	isEnabled: (scope) => scope.readable.length + scope.readableGlobals.length > 0,
+	isEnabled: (scope) => scope.collections.readable.length + scope.globals.readable.length > 0,
 	inputSchema: (scope) => ({
-		...targetShape(scope, "read", {
-			collection: "Collection holding the document.",
-			global: "Global to read."
-		}),
+		...entityShape(scope, "read"),
 		...idShape(scope, "read"),
-		path: z.string().regex(JSON_POINTER_PATTERN).optional().describe("JSON pointer to return only a subtree, e.g. \"/layout/sections/0\"."),
+		path: z.string().regex(JSON_POINTER_PATTERN).optional().describe("e.g. \"/layout/sections/0\"."),
 		...depthShape(scope),
 		...localeShape(scope, {
 			required: false,
-			description: "Locale to read. Defaults to the default locale."
+			description: READ_LOCALE_DESCRIPTION
 		}),
-		draft: z.boolean().optional().describe("Return the latest draft. Default true."),
-		outline: z.boolean().optional().describe("For a rich text field, return a compact positional outline instead of the editor state. Requires \"path\"."),
-		versionId: idSchema.optional().describe("Version to read instead of the document, from findVersions. Only for entities with versions; not with \"draft\"."),
-		diffFrom: idSchema.optional().describe("Version id, or \"published\" for the newest published version in any locale, to diff from. Returns {from, to, patch} instead of the document. Only for entities with versions.")
+		draft: z.boolean().optional().describe("Default true. false reads the published version."),
+		outline: z.boolean().optional().describe("With \"path\" at a rich text field: list each node's pointer, type, \"version\" and text."),
+		...versionShape(scope),
+		...downloadShape(scope)
 	}),
 	handler: async ({ args, scope }) => {
-		const target = resolveTarget(scope, args, "read");
-		const id = requireIdFor(target, args.id);
+		const target = resolveDocument(scope, args, "read");
 		assertVersionArgs(scope, target, args);
+		if (args.download) assertDownloadArgs(scope, target, args);
+		const prototyped = args.path ? prototypeSegmentProblem(args.path) : void 0;
+		if (prototyped !== void 0) return errorResult(prototyped);
 		let pointer;
 		try {
 			pointer = args.path ? Pointer.fromJSON(args.path) : void 0;
@@ -77,7 +99,6 @@ const diffResult = async (scope, read, diff, doc) => {
 		}
 		const read = {
 			target,
-			id,
 			depth: args.depth ?? 0,
 			locale: localeOf(scope, args.locale)
 		};
@@ -90,12 +111,17 @@ const diffResult = async (scope, read, diff, doc) => {
 		}, doc);
 		if (pointer === void 0) {
 			if (args.outline) return errorResult(OUTLINE_ERROR);
-			return jsonResult(doc);
+			return args.download && args.id !== void 0 ? await withDownload(scope, doc, {
+				collection: target.slug,
+				id: args.id,
+				draft: args.draft ?? true,
+				locale: read.locale ?? null
+			}) : jsonResult(doc);
 		}
 		const path = pointer.toString();
 		const value = pointer.get(doc);
 		const envelope = {
-			...target.kind === "collection" ? { id } : { global: target.slug },
+			...identityOf(target, args.id),
 			status: doc["_status"],
 			updatedAt: doc["updatedAt"],
 			path
@@ -109,10 +135,11 @@ const diffResult = async (scope, read, diff, doc) => {
 			resolution = resolveDataPointer(scope.req.payload.config, {
 				doc,
 				pointer: path,
-				ref: refOf(target)
+				ref: target
 			});
 		} catch (error) {
-			return errorResult(error instanceof Error ? error.message : OUTLINE_ERROR);
+			if (!(error instanceof SchemaError)) throw error;
+			return errorResult(error.message);
 		}
 		const field = resolution.descriptor?.type === "richText" && !resolution.lexical ? findRichTextField(resolution.fields, splitPath(resolution.descriptor.path)) : void 0;
 		if (!field) return errorResult(OUTLINE_ERROR);