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

package/dist/tools/read-request.mjs

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

package/dist/tools/shared.mjs

@@ -1,149 +1,118 @@
-import { canCreate, canPublish, isLiveWrite } from "../capabilities.mjs";
-import { translateStatic } from "../i18n.mjs";
-import { NotFound } from "payload";
+import { canCreate, isLiveWrite } from "../capabilities.mjs";
 import { z } from "zod";
 //#region src/tools/shared.ts
 /**
 * An out-of-scope slug fails schema validation before a handler runs, so a
 * client only ever sees what its key may touch.
 */ const slugEnum = (slugs) => z.enum(slugs);
-/** Payload's id type follows the adapter, so both forms are handed on as read. */ const idSchema = z.union([z.string(), z.number()]).describe("Document id.");
+/** Payload's id type follows the adapter, so both forms are handed on as read. */ const idSchema = z.union([z.string(), z.number()]);
+const slugsOf = (scope, key) => ({
+	collections: scope.collections[key],
+	globals: scope.globals[key]
+});
 const slugsWhere = (scope, predicate, allowed) => {
 	const pick = (entities, slugs) => entities.filter((entity) => slugs.includes(entity.slug) && predicate(entity)).map((entity) => entity.slug);
 	return [...pick(scope.exposure.collections, allowed.collections), ...pick(scope.exposure.globals, allowed.globals)];
 };
 /**
-* Slugs this key may write whose writes land live rather than as a draft. An
-* entity without versions has no draft to land on, so `write: "live"` there
-* makes every write a live one. Empty for every key that can only write drafts.
-*/ const liveWriteSlugs = (scope) => slugsWhere(scope, isLiveWrite, {
-	collections: scope.writable,
-	globals: scope.writableGlobals
-});
-/**
 * Slugs this key may write but never create in, because their documents are
 * files. Collection-only, since nothing creates a global either way.
 */ const patchOnlySlugs = (scope) => slugsWhere(scope, (entity) => !canCreate(entity), {
-	collections: scope.writable,
+	collections: scope.collections.writable,
 	globals: []
 });
-/** Slugs this key may write and, separately, publish. */ const publishableWriteSlugs = (scope) => slugsWhere(scope, canPublish, {
-	collections: scope.publishable,
-	globals: scope.publishableGlobals
-});
-/**
-* What a write actually does for this key, and what it takes to make it public.
-* A live-write slug has no draft and no publish step; a publishable one has
-* both. Stated per key so a client is never told its writes are drafts while
-* they are not, nor that publishing is out of reach when it is not.
-*/ const draftSentence = (scope) => {
-	const live = liveWriteSlugs(scope);
-	const publishable = publishableWriteSlugs(scope);
-	return `${live.length === 0 ? "Every write lands as a draft." : `Writes land as drafts, except for ${live.join(", ")}, which have no drafts: a write there changes the live document immediately.`} ${publishable.length === 0 ? "Nothing this key writes is ever published; publishing stays a human action in the admin panel." : `Publish a draft with publishDocument, which this key may do for ${publishable.join(", ")}. Publishing anything else stays a human action in the admin panel.`}`;
-};
-/** The value a client read back is a string; what it meets may be a Date. */ const sameInstant = (left, right) => typeof left === "string" && new Date(left).getTime() === new Date(right).getTime();
-/** Unchecked, because the runtime shape really does vary; `Branch` guards it. */ const widen = (branch) => branch;
-/** The one list the shape helpers and {@link resolveTarget} both read. */ const slugsFor = (scope, operation) => {
+const widen = (branch) => branch;
+/** The one list the shape helpers and {@link resolveEntity} both read. */ const slugsFor = (scope, operation) => {
 	switch (operation) {
 		case "create": return {
 			collections: slugsWhere(scope, canCreate, {
-				collections: scope.writable,
+				collections: scope.collections.writable,
 				globals: []
 			}),
 			globals: []
 		};
-		case "publish": return {
-			collections: scope.publishable,
-			globals: scope.publishableGlobals
-		};
-		case "read": return {
-			collections: scope.readable,
-			globals: scope.readableGlobals
-		};
-		case "write": return {
-			collections: scope.writable,
-			globals: scope.writableGlobals
+		case "publish": return slugsOf(scope, "publishable");
+		case "read": return slugsOf(scope, "readable");
+		case "versions": return {
+			collections: slugsWhere(scope, (entity) => entity.hasVersions, {
+				collections: scope.collections.readable,
+				globals: []
+			}),
+			globals: slugsWhere(scope, (entity) => entity.hasVersions, {
+				collections: [],
+				globals: scope.globals.readable
+			})
 		};
+		case "write": return slugsOf(scope, "writable");
 	}
 };
 /**
+* The slugs of {@link slugsFor} `"versions"` that also have drafts. Only they
+* have `_status` on their versions, so only they can be queried by status.
+*/ const draftVersionSlugs = (scope) => {
+	const { collections, globals } = slugsFor(scope, "versions");
+	return {
+		collections: slugsWhere(scope, (entity) => entity.hasDrafts, {
+			collections,
+			globals: []
+		}),
+		globals: slugsWhere(scope, (entity) => entity.hasDrafts, {
+			collections: [],
+			globals
+		})
+	};
+};
+/** Slugs reachable by `operation` whose writes go live, because they have no draft to write. */ const liveWriteSlugs = (scope, operation) => slugsWhere(scope, isLiveWrite, slugsFor(scope, operation));
+/**
+* Stated on the tools that write, since a client calling them must know before
+* the call which writes are public.
+*/ const liveWriteSentence = (scope, operation) => {
+	const live = liveWriteSlugs(scope, operation);
+	return live.length === 0 ? "Every write is saved as a draft." : `Writes to ${live.join(", ")} go live immediately. Every other write is saved as a draft.`;
+};
+/**
 * With no reachable global, `global` is left out and `collection` stays
 * required, so a deployment without globals sees an unchanged schema. Only the
 * mixed case makes either optional, and the handler enforces exclusivity there.
-*/ const targetShape = (scope, operation, descriptions) => {
+* `globalRule` states that rule on `global` for a tool without an `id`.
+*/ const entityShape = (scope, operation, globalRule) => {
 	const { collections, globals } = slugsFor(scope, operation);
-	if (globals.length === 0) return widen({ collection: slugEnum(collections).describe(descriptions.collection) });
-	if (collections.length === 0) return widen({ global: slugEnum(globals).describe(descriptions.global) });
+	if (globals.length === 0) return widen({ collection: slugEnum(collections) });
+	if (collections.length === 0) return widen({ global: slugEnum(globals) });
+	const global = slugEnum(globals).optional();
 	return widen({
-		collection: slugEnum(collections).optional().describe(descriptions.collection),
-		global: slugEnum(globals).optional().describe(descriptions.global)
+		collection: slugEnum(collections).optional(),
+		global: globalRule === void 0 ? global : global.describe(globalRule)
 	});
 };
 /**
 * Only a collection document has one. Optional in the mixed case, where
-* `requireIdFor` enforces the dependency.
+* `resolveDocument` enforces the dependency and the description states it.
 */ const idShape = (scope, operation) => {
 	const { collections, globals } = slugsFor(scope, operation);
 	if (collections.length === 0) return widen({});
 	if (globals.length === 0) return widen({ id: idSchema });
-	return widen({ id: idSchema.optional().describe("Document id. Required with \"collection\"; must be omitted with \"global\".") });
+	return widen({ id: idSchema.optional().describe("Required with \"collection\", omitted with \"global\".") });
 };
+/** For the reads that fall back to the default locale, unlike the writes. */ const READ_LOCALE_DESCRIPTION = "Default: the default locale. A value missing in this locale is shown from the default locale.";
 const localeShape = (scope, options) => {
-	if (!scope.locales) return widen({});
-	const locale = z.enum(scope.locales);
-	return widen({ locale: (options.required ? locale : locale.optional()).describe(options.description) });
+	if (!scope.localization) return widen({});
+	const enumerated = z.enum(scope.localization.locales);
+	const locale = options.required ? enumerated : enumerated.optional();
+	return widen({ locale: options.description === void 0 ? locale : locale.describe(options.description) });
 };
 /**
 * Defaults to 0 rather than Payload's own default: a client usually wants ids
 * it can write back, and populating a relation costs a query.
-*/ const depthShape = (scope) => ({ depth: z.number().int().min(0).max(scope.limits.maxDepth).optional().describe(`Relationship population depth. Default 0, at most ${String(scope.limits.maxDepth)}.`) });
+*/ const depthShape = (scope) => ({ depth: z.number().int().min(0).max(scope.limits.maxDepth).optional().describe("Default 0. A relationship into a collection this key cannot read stays an id.") });
 /**
 * The locale to operate on: the explicit argument, else the request's, else
 * the default. `undefined` when localization is off.
 */ const localeOf = (scope, locale) => {
-	if (!scope.locales) return;
+	if (!scope.localization) return;
+	const { locales, defaultLocale } = scope.localization;
 	const requested = locale ?? scope.req.locale;
-	return (requested && scope.locales.includes(requested) ? requested : scope.defaultLocale) ?? 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 readTarget = 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.id,
-			disableErrors: true
-		});
-		if (!doc) throw new NotFound(scope.req.t);
-		return doc;
-	}
-	return await payload.findGlobal({
-		...shared,
-		slug: args.target.slug
-	});
-};
-const translateLabel = (scope, label, fallback) => {
-	const { i18n, t } = scope.req;
-	const resolved = typeof label === "function" ? label({
-		i18n,
-		t
-	}) : label;
-	return translateStatic(resolved, i18n) ?? fallback;
+	return requested && locales.includes(requested) ? requested : defaultLocale;
 };
 //#endregion
-export { depthShape, draftSentence, idSchema, idShape, localeOf, localeShape, patchOnlySlugs, readTarget, sameInstant, slugEnum, slugsFor, targetShape, translateLabel };
+export { READ_LOCALE_DESCRIPTION, depthShape, draftVersionSlugs, entityShape, idSchema, idShape, liveWriteSentence, liveWriteSlugs, localeOf, localeShape, patchOnlySlugs, slugEnum, slugsFor, widen };

package/dist/tools/validate-document.mjs

@@ -1,48 +1,35 @@
+import { defineMcpxTool } from "../define-tool.mjs";
 import { jsonResult } from "../result.mjs";
-import { idShape, localeOf, localeShape, readTarget, targetShape } from "./shared.mjs";
-import { requireIdFor, resolveTarget } from "./target.mjs";
-import { defineMcpxTool } from "../types.mjs";
+import { entityShape, idShape, localeOf, localeShape } from "./shared.mjs";
+import { identityOf, readDraft, resolveDocument } from "./document.mjs";
 import { collectPublishBlockers } from "../write/publish-blockers.mjs";
 /**
-* Gated on write rather than read, because publish blockers only mean
-* something to a caller who can act on them.
+* Gated on write rather than read, because publish blockers only mean something
+* to a caller who can act on them.
 *
 * It reads the document twice on purpose: once under the key's own access to
-* refuse a caller who may not see it, then privileged, so the check runs over
-* every field rather than the subset the user can read. It carries no
-* `readOnlyHint`, because the traversal fires field hooks.
+* refuse a caller who may not see it, then privileged, so the check covers every
+* field and not only those the user can read. It has no `readOnlyHint` because
+* the traversal fires field hooks.
 */ const validateDocument = defineMcpxTool({
 	name: "validateDocument",
-	description: `Reports what still prevents a human from publishing the draft, without writing anything. The same list patchDocument returns after a write; use it to check work or to answer "is this ready".
-
-Pass exactly one of "collection" and "global". "id" is required with "collection" and must be omitted with "global", because a global is a singleton.
-
-Nothing is written, but the check runs the same field-level beforeValidate and beforeChange hooks a save would, so a hook with side effects fires. "publishBlockersUnavailable" means the check itself failed, so the empty list says nothing.`,
+	description: `Lists what still blocks publishing one document or global, without saving. Returns "publishBlockers", each with a pointer and a message. An empty list means it can be published, unless "publishBlockersUnavailable" is true: then the check itself failed. The check runs the field hooks a save runs.`,
 	annotations: { openWorldHint: false },
-	isEnabled: (scope) => scope.writable.length + scope.writableGlobals.length > 0,
+	isEnabled: (scope) => scope.collections.writable.length + scope.globals.writable.length > 0,
 	inputSchema: (scope) => ({
-		...targetShape(scope, "write", {
-			collection: "Collection holding the document.",
-			global: "Global to validate."
-		}),
+		...entityShape(scope, "write"),
 		...idShape(scope, "write"),
-		...localeShape(scope, {
-			required: true,
-			description: "Locale to validate."
-		})
+		...localeShape(scope, { required: true })
 	}),
 	handler: async ({ args, scope }) => {
-		const target = resolveTarget(scope, args, "write");
-		const id = requireIdFor(target, args.id);
+		const target = resolveDocument(scope, args, "write");
 		const locale = localeOf(scope, args.locale);
-		await readTarget(scope, {
+		await readDraft(scope, {
 			target,
-			id,
 			locale
 		});
-		const doc = await readTarget(scope, {
+		const doc = await readDraft(scope, {
 			target,
-			id,
 			locale,
 			privileged: true
 		});
@@ -51,7 +38,7 @@ Nothing is written, but the check runs the same field-level beforeValidate and b
 			entity: target
 		});
 		return jsonResult({
-			...target.kind === "collection" ? { id: doc["id"] } : { global: target.slug },
+			...identityOf(target, doc["id"]),
 			status: doc["_status"],
 			updatedAt: doc["updatedAt"],
 			publishBlockers: validation.blockers,

package/dist/tools/versions.mjs

@@ -0,0 +1,127 @@
+import { stripAdminHidden } from "../schema/admin-hidden.mjs";
+import "../schema/index.mjs";
+import { mcpxReadRequest } from "./read-request.mjs";
+import { hasDraftsEnabled } from "payload/shared";
+import { Pointer, createPatch } from "rfc6902";
+//#region src/tools/versions.ts
+const NOISE = [
+	"id",
+	"globalType",
+	"createdAt",
+	"updatedAt",
+	"_status"
+];
+const NEWEST_FIRST = ["-updatedAt", "-id"];
+/** The document or global as the key's user sees it, without `admin.hidden` fields. */ const readLive = async (scope, read, options) => {
+	const shared = {
+		depth: read.depth,
+		draft: options.draft,
+		overrideAccess: false,
+		req: mcpxReadRequest(scope),
+		...options.select === void 0 ? {} : { select: options.select },
+		...read.locale === void 0 ? {} : { locale: read.locale }
+	};
+	const doc = await (read.target.kind === "collection" ? scope.req.payload.findByID({
+		...shared,
+		collection: read.target.slug,
+		id: read.target.id
+	}) : scope.req.payload.findGlobal({
+		...shared,
+		slug: read.target.slug
+	}));
+	return stripAdminHidden(scope.req.payload.config, read.target, doc);
+};
+const withoutHidden = (scope, read, stored) => ({
+	...stored,
+	version: stripAdminHidden(scope.req.payload.config, read.target, stored.version)
+});
+const assertReadable = async (scope, read) => {
+	await readLive(scope, {
+		...read,
+		depth: 0
+	}, {
+		draft: true,
+		select: {}
+	});
+};
+/** `parent` comes back as a raw id or, populated, as the document itself. */ const isVersionOf = (version, id) => {
+	const parent = version["parent"];
+	const parentId = typeof parent === "object" && parent !== null ? parent["id"] : parent;
+	return (typeof parentId === "string" || typeof parentId === "number") && String(parentId) === String(id);
+};
+/**
+* Reads one version, or `null` when it does not exist, is not readable, or
+* belongs to another document. `findVersionByID` knows nothing of the document
+* the caller asked about, so the parent check is what keeps one readable
+* document from opening the history of another.
+*/ const loadVersion = async (scope, read, versionId) => {
+	await assertReadable(scope, read);
+	const { payload } = scope.req;
+	const shared = {
+		id: versionId,
+		depth: read.depth,
+		disableErrors: true,
+		overrideAccess: false,
+		req: mcpxReadRequest(scope),
+		...read.locale === void 0 ? {} : { locale: read.locale }
+	};
+	const version = await (read.target.kind === "collection" ? payload.findVersionByID({
+		...shared,
+		collection: read.target.slug
+	}) : payload.findGlobalVersionByID({
+		...shared,
+		slug: read.target.slug
+	}));
+	if (!version) return null;
+	if (read.target.kind === "collection" && !isVersionOf(version, read.target.id)) return null;
+	return withoutHidden(scope, read, version);
+};
+/** One page of a document's or global's history, newest first. */ const queryVersions = async (scope, read, options) => {
+	await assertReadable(scope, read);
+	const where = {
+		...read.target.kind === "collection" ? { parent: { equals: read.target.id } } : {},
+		...options.status === void 0 ? {} : { "version._status": { equals: options.status } }
+	};
+	const shared = {
+		depth: read.depth,
+		limit: options.limit,
+		sort: NEWEST_FIRST,
+		overrideAccess: false,
+		req: mcpxReadRequest(scope),
+		where,
+		...options.page === void 0 ? {} : { page: options.page },
+		...read.locale === void 0 ? {} : { locale: read.locale }
+	};
+	return await (read.target.kind === "collection" ? scope.req.payload.findVersions({
+		...shared,
+		collection: read.target.slug
+	}) : scope.req.payload.findGlobalVersions({
+		...shared,
+		slug: read.target.slug
+	}));
+};
+/** The newest version whose status is published, or `null` if none is. */ const loadPublished = async (scope, read) => {
+	if (!hasDraftsEnabled(read.target.config)) return null;
+	const [newest] = (await queryVersions(scope, read, {
+		status: "published",
+		limit: 1
+	})).docs;
+	return newest ? withoutHidden(scope, read, newest) : null;
+};
+const strip = (doc) => Object.fromEntries(Object.entries(doc).filter(([key]) => !NOISE.includes(key)));
+/**
+* The RFC 6902 operations turning `from` into `to`, limited to the subtree at
+* `pointer`. Op paths stay absolute, so they apply as `patchDocument` ops.
+*/ const diffDocuments = (from, to, pointer = Pointer.fromJSON("")) => {
+	const wrap = (doc) => {
+		const value = pointer.get(strip(doc));
+		return value === void 0 ? {} : { value };
+	};
+	const path = pointer.toString();
+	return createPatch(wrap(from), wrap(to)).map((op) => ({
+		...op,
+		path: `${path}${op.path.slice(6)}`
+	}));
+};
+//#endregion
+export { diffDocuments, isVersionOf, loadPublished, loadVersion, queryVersions, readLive };

package/dist/types.d.mts

@@ -1,3 +1,4 @@
+import { DocumentId } from "./entity.mjs";
 import { CollectionConfig, CollectionSlug, GlobalSlug, PayloadRequest, TypedUser } from "payload";
 import { z } from "zod";
 import { RequestHandlerExtra } from "@modelcontextprotocol/sdk/shared/protocol.js";
@@ -17,32 +18,41 @@ declare module "payload" {
  * - `false`: no write tool touches it.
  * - `"draft"`: writes land as drafts and nothing MCP does changes what the
  *   public sees. Requires `versions.drafts`.
- * - `"live"`: MCP may change live content. On an entity with drafts that means
- *   `publishDocument` is exposed; on one without, where there is no draft to
- *   land on, it means the write itself is permitted and lands live.
+ * - `"live"`: MCP may change live content. On an entity with drafts that
+ *   exposes `publishDocument`. On one without, there is no draft, so the write
+ *   itself is permitted and lands live.
  */
 export type McpxWriteMode = "draft" | "live" | false;
-/** A key can only enable what the config exposes here. */
+/**
+ * What an entity exposes. The config names the entities that are reachable and
+ * only takes capabilities away; a key's checkboxes decide per key. `true` is
+ * shorthand for `{}`, which exposes everything the entity supports.
+ */
 export interface McpxCollectionOptions {
   /** Expose `describeSchema`, `findDocuments`, `getDocument`. Default `true`. */
   read?: boolean;
   /**
    * Expose `patchDocument`, `validateDocument` and, unless this is an upload
-   * collection, `createDocument`, and how far those writes reach. Default
-   * `false`.
+   * collection, `createDocument`. Without drafts a write changes live
+   * content. Default `true`.
    */
-  write?: McpxWriteMode;
-}
-/** A singleton, so neither `findDocuments` nor `createDocument` reaches one. */
-export interface McpxGlobalOptions {
-  /** Expose `describeSchema` and `getDocument`. Default `true`. */
-  read?: boolean;
+  write?: boolean;
+  /**
+   * Expose `publishDocument`, which promotes a draft to live content. Needs
+   * `versions.drafts` and `write`. Default `true` where the entity has drafts.
+   * `false` keeps writes as drafts and is refused where there are none.
+   */
+  publish?: boolean;
   /**
-   * Expose `patchDocument` and `validateDocument`, and how far those writes
-   * reach. Default `false`.
+   * Expose `findVersions` and the `versionId` and `diffFrom` arguments of
+   * `getDocument` to keys that may read the entity. Default `false`: version
+   * history has no checkbox of its own and follows the key's read, so the
+   * config opts in. `true` needs Payload `versions` and `read`.
    */
-  write?: McpxWriteMode;
+  versions?: boolean;
 }
+/** The same options. A singleton, so neither `findDocuments` nor `createDocument` reaches one. */
+export type McpxGlobalOptions = McpxCollectionOptions;
 export type McpxToolExtra = RequestHandlerExtra<ServerRequest, ServerNotification>;
 /** What the config exposes, before an API key's checkboxes narrow it. */
 export interface McpxExposedEntity {
@@ -50,24 +60,33 @@ export interface McpxExposedEntity {
   read: boolean;
   write: McpxWriteMode;
   hasDrafts: boolean;
+  /**
+   * Payload keeps a version history, with or without drafts, and the config
+   * exposes it. Says nothing about drafts; see `hasDrafts`.
+   */
+  hasVersions: boolean;
   /** An upload document is a file, and no tool here can supply one. */
   isUpload: boolean;
   /** Name of the capability group on the key document. */
   fieldName: string;
 }
+/** The slugs a key may read, write and publish. */
+export interface McpxScopeSlugs {
+  readable: string[];
+  writable: string[];
+  publishable: string[];
+}
 /** What a tool knows about the current request. */
 export interface McpxToolScope {
   req: PayloadRequest;
   capabilities: McpxResolvedCapabilities;
-  readable: string[];
-  writable: string[];
-  publishable: string[];
-  readableGlobals: string[];
-  writableGlobals: string[];
-  publishableGlobals: string[];
+  collections: McpxScopeSlugs;
+  globals: McpxScopeSlugs;
   /** `null` when localization is off. */
-  locales: null | string[];
-  defaultLocale: null | string;
+  localization: null | {
+    locales: string[];
+    defaultLocale: string;
+  };
   limits: {
     maxLimit: number;
     maxDepth: number;
@@ -85,7 +104,7 @@ export interface McpxToolScope {
 export interface McpxTool<Shape extends z.ZodRawShape = z.ZodRawShape, Args = z.infer<z.ZodObject<Shape>>> {
   /** camelCase, unique, not one of the builtin tool names. */
   name: string;
-  /** Built per request so it can state what this key's writes actually do. */
+  /** Built per request so it can state what this key's writes do. */
   description: string | ((scope: McpxToolScope) => string);
   annotations?: ToolAnnotations;
   /**
@@ -97,7 +116,7 @@ export interface McpxTool<Shape extends z.ZodRawShape = z.ZodRawShape, Args = z.
   /**
    * Built per request so enums can be narrowed to what the key may touch.
    * Registered strictly either way: an unknown argument is rejected by name
-   * rather than stripped.
+   * instead of stripped.
    */
   inputSchema?: Shape | ((scope: McpxToolScope) => z.ZodRawShape);
   handler(ctx: {
@@ -110,25 +129,10 @@ export interface McpxTool<Shape extends z.ZodRawShape = z.ZodRawShape, Args = z.
 }
 /** Argument type erased, so a registry can hold tools of differing shapes. */
 export type McpxAnyTool = McpxTool<z.ZodRawShape, never>;
-/** Fixed shape; arguments inferred from it. */
-export declare function defineMcpxTool<Shape extends z.ZodRawShape>(tool: McpxTool<Shape> & {
-  inputSchema?: Shape;
-}): McpxTool<Shape>;
-/** Per-request shape returned as an object literal; arguments inferred from it. */
-export declare function defineMcpxTool<Shape extends z.ZodRawShape>(tool: McpxTool<Shape> & {
-  inputSchema: (scope: McpxToolScope) => Shape;
-}): McpxAnyTool;
-/**
- * Per-request shape built from helpers that erase to `z.ZodRawShape`, as the
- * builtins do. Nothing to infer from, so state the arguments instead.
- */
-export declare function defineMcpxTool<Args>(tool: McpxTool<z.ZodRawShape, Args> & {
-  inputSchema: (scope: McpxToolScope) => z.ZodRawShape;
-}): McpxAnyTool;
 export interface McpxAuthResult {
   /** Must carry `collection`. */
   user: TypedUser;
-  apiKeyId: number | string;
+  apiKeyId: DocumentId;
   /** The `capabilities` group as stored on the key document. */
   capabilities: unknown;
 }
@@ -139,9 +143,9 @@ export interface McpxAuthResult {
  * to `Record<string, unknown>`, which interfaces do not satisfy.
  */
 export type McpxPluginOptions = {
-  /** Allow-list of collections. `true` is shorthand for `{ read: true }`. */
+  /** Allow-list of collections. `true` is shorthand for `{}`. */
   collections: Partial<Record<CollectionSlug, McpxCollectionOptions | true>>;
-  /** Allow-list of globals. `true` is shorthand for `{ read: true }`. */
+  /** Allow-list of globals. `true` is shorthand for `{}`. */
   globals?: Partial<Record<GlobalSlug, McpxGlobalOptions | true>>;
   /** Collection the keys act as. Default `config.admin.user`, then `users`. */
   userCollection?: CollectionSlug;
@@ -168,7 +172,11 @@ export type McpxPluginOptions = {
   };
   tools?: McpxAnyTool[];
   auth?: {
-    /** Replace or wrap the default key resolution. Return `null` for 401. */
+    /**
+     * Replace or wrap the default key resolution. Return `null` for 401. A
+     * result whose user has no `id` or whose `collection` is not the user
+     * collection, or that has no `apiKeyId`, is also answered with 401.
+     */
     resolve?: (args: {
       req: PayloadRequest;
       resolveDefault: () => Promise<McpxAuthResult | null>;
@@ -183,10 +191,10 @@ export type McpxPluginOptions = {
 export interface McpxCollectionCapabilities {
   read: boolean;
   write: boolean;
-  /** Only ever true where the config sets `write: "live"` and drafts exist. */
+  /** Only ever true where the config lets writes publish and drafts exist. */
   publish: boolean;
 }
-/** In force for one request: plugin config AND key checkboxes. */
+/** In force for one request: the plugin config and the key checkboxes together. */
 export interface McpxResolvedCapabilities {
   collections: Record<string, McpxCollectionCapabilities>;
   globals: Record<string, McpxCollectionCapabilities>;
@@ -194,15 +202,7 @@ export interface McpxResolvedCapabilities {
 }
 /** Stamped on `req.context.mcpx`; see {@link isMcpxRequest}. */
 export interface McpxRequestContext {
-  apiKeyId: number | string;
+  apiKeyId: DocumentId;
   capabilities: McpxResolvedCapabilities;
 }
-/** One reason a human could not publish the draft as it stands. */
-export interface PublishBlocker {
-  /** Resolved field label path, e.g. "Layout > Block 2 (Hero) > Title". */
-  field?: string;
-  message: string;
-  /** JSON Pointer to the offending value, e.g. "/layout/2/title". */
-  path: string;
-}
 //#endregion