@abinnovision/payloadcms-mcpx 1.0.0-beta.3 → 1.0.0-beta.5

package/dist/schema/walk.d.mts

@@ -0,0 +1 @@
+import "payload";

package/dist/schema/walk.mjs

@@ -11,13 +11,22 @@ import { fieldIsHiddenOrDisabled, fieldIsVirtual } from "payload/shared";
 	"updatedAt"
 ]);
 /**
-* Joins path segments, attaching the array marker to its field rather than
-* separating it, so an array subfield reads `items[].title`.
-*/ const joinPath = (parts) => parts.reduce((path, part) => part === "[]" ? `${path}[]` : path ? `${path}.${part}` : part, "");
+* Shape a JSON Pointer must have to be parseable at all.
+*/ const JSON_POINTER_PATTERN = /^(\/([^~/]|~[01])*)*$/;
 /**
-* Splits a descriptor path back into pointer-comparable segments, with the
-* array marker as a segment of its own.
-*/ const splitPath = (path) => path.split(".").flatMap((part) => part.endsWith("[]") ? [part.slice(0, -2), "[]"] : [part]);
+* 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.
@@ -83,7 +92,7 @@ const withRows = (descriptor, field) => ({
 	const readOnly = parentReadOnly || isReadOnly(field);
 	const path = [...prefix, field.name];
 	if (field.type === "tab" || field.type === "group") return describeFields(field.flattenedFields, path, readOnly);
-	if (field.type === "array") return describeFields(field.flattenedFields, [...path, "[]"], readOnly);
+	if (field.type === "array") return describeFields(field.flattenedFields, [...path, "*"], readOnly);
 	if (field.type === "blocks") return [withRows({
 		...describeBase(field, joinPath(path), readOnly),
 		blocks: blockSlugsOf(field)
@@ -97,13 +106,13 @@ const withRows = (descriptor, field) => ({
 		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));
+		if (field.type === "array" && path[1] === "*") return findBlocksField(field.flattenedFields, path.slice(2));
 	}
 };
-const collectionOf = (config, collection) => {
-	const found = config.collections.find((candidate) => candidate.slug === collection);
-	if (!found) throw new Error(`Unknown collection "${collection}".`);
+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 { RESERVED_FIELD_NAMES, blockOf, blockSlugsOf, collectionOf, describeFields, findBlocksField, joinPath, splitPath, staticDescription };
+export { JSON_POINTER_PATTERN, RESERVED_FIELD_NAMES, blockOf, blockSlugsOf, describeFields, findBlocksField, joinPath, pointerFromPayloadPath, splitPath, staticDescription, targetOf };

package/dist/tools/create-document.mjs

@@ -1,5 +1,6 @@
 import { errorResult, jsonResult } from "../endpoint/result.mjs";
-import { collectionEnum, ensureAllowed, localeOf, localeShape, readDraft } from "./shared.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";
@@ -16,7 +17,7 @@ const createDocument = {
 	},
 	isEnabled: (scope) => scope.writable.length > 0,
 	inputSchema: (scope) => ({
-		collection: collectionEnum(scope.writable).describe("Collection to create the document in."),
+		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."
@@ -24,15 +25,15 @@ const createDocument = {
 		data: z.record(z.string(), z.unknown()).describe("Initial field values, as describeSchema lists them.")
 	}),
 	handler: async (args, scope) => {
-		const collection = ensureAllowed(scope, args.collection, "write");
+		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: collection.flattenedFields,
-				prefix: ""
+				fields: target.config.flattenedFields,
+				prefix: []
 			}
 		}, seed);
 		if (problems.length > 0) return errorResult("Nothing was created.", { problems });
@@ -45,15 +46,15 @@ const createDocument = {
 			req: scope.req,
 			...locale === void 0 ? {} : { locale }
 		});
-		const saved = await readDraft(scope, {
-			collection: args.collection,
+		const saved = await readTarget(scope, {
+			target,
 			id: created["id"],
 			locale,
 			privileged: true
 		});
 		const publishBlockers = await collectPublishBlockers(scope.req, {
-			collection,
-			doc: saved
+			doc: saved,
+			entity: target
 		});
 		return jsonResult({
 			id: saved["id"],

package/dist/tools/describe-schema.mjs

@@ -1,5 +1,6 @@
 import { jsonResult } from "../endpoint/result.mjs";
-import { collectionEnum, ensureAllowed } from "./shared.mjs";
+import { targetShape } from "./shared.mjs";
+import { refOf, resolveTarget } from "./target.mjs";
 import { describeNode, reachableSchemaPaths } from "../schema/describe.mjs";
 import { z } from "zod";
 //#region src/tools/describe-schema.ts
@@ -7,28 +8,33 @@ const describeSchema = {
 	name: "describeSchema",
 	description: `Describes the writable shape of a document, one node at a time.
 
-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.
+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.
 
-Field paths are dotted and already resolved through anything that does not nest in the stored document. To turn one into a patchDocument pointer, replace each "." with "/", add a leading "/", and replace each "[]" with a 0-based index. Note a path here names a block by its slug where a pointer names it by its index.
+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.
+
+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 > 0,
+	isEnabled: (scope) => scope.readable.length + scope.readableGlobals.length > 0,
 	inputSchema: (scope) => ({
-		collection: collectionEnum(scope.readable).describe("Collection to describe."),
-		paths: z.array(z.string()).optional().describe("Schema paths to describe, e.g. \"layout.sections.sectionWrapper\". Omit for the collection root."),
+		...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) => {
-		ensureAllowed(scope, args.collection, "read");
+		const ref = refOf(resolveTarget(scope, args, "read"));
 		const { config } = scope.req.payload;
-		const expanded = args.expand === true ? reachableSchemaPaths(config, args.collection) : void 0;
+		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, args.collection, schemaPath);
+				return describeNode(config, ref, schemaPath);
 			} catch (error) {
 				return {
 					error: error instanceof Error ? error.message : "Unknown error",

package/dist/tools/find-documents.mjs

@@ -1,5 +1,6 @@
 import { jsonResult } from "../endpoint/result.mjs";
-import { collectionEnum, depthShape, ensureAllowed, localeOf, localeShape } from "./shared.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 = {
@@ -11,7 +12,7 @@ const findDocuments = {
 	},
 	isEnabled: (scope) => scope.readable.length > 0,
 	inputSchema: (scope) => ({
-		collection: collectionEnum(scope.readable).describe("Collection to search."),
+		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)}.`),
@@ -25,7 +26,7 @@ const findDocuments = {
 		draft: z.boolean().optional().describe("Include the latest drafts. Default true.")
 	}),
 	handler: async (args, scope) => {
-		ensureAllowed(scope, args.collection, "read");
+		resolveTarget(scope, { collection: args.collection }, "read");
 		const locale = localeOf(scope, args.locale);
 		const result = await scope.req.payload.find({
 			collection: args.collection,

package/dist/tools/get-document.mjs

@@ -1,20 +1,27 @@
+import { JSON_POINTER_PATTERN } from "../schema/walk.mjs";
 import { errorResult, jsonResult } from "../endpoint/result.mjs";
-import { collectionEnum, depthShape, ensureAllowed, idSchema, localeOf, localeShape } from "./shared.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.`,
+	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 > 0,
+	isEnabled: (scope) => scope.readable.length + scope.readableGlobals.length > 0,
 	inputSchema: (scope) => ({
-		collection: collectionEnum(scope.readable).describe("Collection holding the document."),
-		id: idSchema,
-		path: z.string().optional().describe("JSON pointer to return only a subtree, e.g. \"/layout/sections/0\"."),
+		...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,
@@ -23,17 +30,24 @@ const getDocument = {
 		draft: z.boolean().optional().describe("Return the latest draft. Default true.")
 	}),
 	handler: async (args, scope) => {
-		ensureAllowed(scope, args.collection, "read");
+		const target = resolveTarget(scope, args, "read");
+		const id = requireIdFor(target, args.id);
 		const locale = localeOf(scope, args.locale);
-		const doc = await scope.req.payload.findByID({
-			collection: args.collection,
-			id: args.id,
+		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 {
@@ -42,7 +56,7 @@ const getDocument = {
 			return errorResult(`"${args.path}" is not a valid JSON pointer.`);
 		}
 		return jsonResult({
-			id: doc["id"],
+			...target.kind === "collection" ? { id: doc["id"] } : { global: target.slug },
 			status: doc["_status"],
 			updatedAt: doc["updatedAt"],
 			path: args.path,

package/dist/tools/list-capabilities.mjs

@@ -1,11 +1,13 @@
+import { staticDescription } from "../schema/walk.mjs";
 import { jsonResult } from "../endpoint/result.mjs";
 import { translateLabel } from "./shared.mjs";
-import { staticDescription } from "../schema/walk.mjs";
 import { hasDraftValidationEnabled } from "payload/shared";
 //#region src/tools/list-capabilities.ts
 const listCapabilities = {
 	name: "listCapabilities",
-	description: `Lists what this key may do: the collections it can read or write, their draft behaviour and id type, the configured locales, the limits in force and the custom tools available. Call it first to orient; nothing here changes with the content model.`,
+	description: `Lists what this key may do: the collections and globals it can read or write, their draft behaviour and id type, the configured locales, the limits in force and the custom tools available. Call it first to orient; nothing here changes with the content model.
+
+A global is a singleton: it has no id, is not listed by findDocuments and cannot be created. Address one with the "global" argument where a collection document would take "collection" and "id".`,
 	annotations: {
 		readOnlyHint: true,
 		openWorldHint: false
@@ -34,8 +36,24 @@ const listCapabilities = {
 				idType: collection.customIDType ?? payload.db.defaultIDType
 			}];
 		});
+		const globals = scope.options.globals.flatMap((entry) => {
+			const capability = scope.capabilities.globals[entry.slug];
+			const config = payload.globals.config.find((candidate) => candidate.slug === entry.slug);
+			if (!capability || !config || !(capability.read || capability.write)) return [];
+			const description = staticDescription(config.admin.description);
+			return [{
+				slug: entry.slug,
+				label: translateLabel(scope, config.label, entry.slug),
+				...description === void 0 ? {} : { description },
+				read: capability.read,
+				write: capability.write,
+				drafts: entry.hasDrafts,
+				draftValidation: hasDraftValidationEnabled(config)
+			}];
+		});
 		return Promise.resolve(jsonResult({
 			collections,
+			...globals.length > 0 ? { globals } : {},
 			locales: scope.locales ? {
 				codes: scope.locales,
 				default: scope.defaultLocale

package/dist/tools/patch-document.mjs

@@ -1,5 +1,6 @@
 import { errorResult, jsonResult } from "../endpoint/result.mjs";
-import { collectionEnum, ensureAllowed, idSchema, localeOf, localeShape, readDraft } from "./shared.mjs";
+import { idShape, localeOf, localeShape, readTarget, targetShape } from "./shared.mjs";
+import { refOf, requireIdFor, resolveTarget } from "./target.mjs";
 import { PATCH_OPERATION_SCHEMA, applyPatchToCopy, buildWriteData, findPatchProblems, isElementPointer } from "../write/patch.mjs";
 import { collectPublishBlockers } from "../write/publish-blockers.mjs";
 import { withTransaction } from "../write/transaction.mjs";
@@ -8,9 +9,11 @@ import { Pointer } from "rfc6902";
 //#region src/tools/patch-document.ts
 const DESCRIPTION = `Applies RFC 6902 JSON Patch operations to one document.
 
+Pass exactly one of "collection" and "global". "id" is required with "collection" and must be omitted with "global", because a global is a singleton.
+
 The write always lands as a draft and is never published, whatever it contains; publishing stays a human action in the admin panel.
 
-Only the fields describeSchema lists can be addressed. A pointer that does not resolve is refused with the fields that are valid at that point, and nothing is applied unless every operation in the batch validates first. Use describeSchema to find a field's path, then turn it into a pointer by replacing "." with "/" and each "[]" with a 0-based index.
+Only the fields describeSchema lists can be addressed. A pointer that does not resolve is refused with the fields that are valid at that point, and nothing is applied unless every operation in the batch validates first. describeSchema reports field paths in this same pointer syntax; a path becomes a pointer into a document by replacing each "*" and each block slug with its 0-based index.
 
 Adding a block requires "blockType" on the value. Append with "/-" as the last segment. To clear a field use "replace" with null; an array or blocks field refuses null and is emptied with [] instead. "remove" is only for list elements, because a field left out of a write is kept rather than cleared. Read the document first to learn the indices, and pass its "updatedAt" as expectedUpdatedAt so a concurrent edit is refused rather than overwritten.
 
@@ -48,10 +51,13 @@ const patchDocument = {
 		idempotentHint: false,
 		openWorldHint: false
 	},
-	isEnabled: (scope) => scope.writable.length > 0,
+	isEnabled: (scope) => scope.writable.length + scope.writableGlobals.length > 0,
 	inputSchema: (scope) => ({
-		collection: collectionEnum(scope.writable).describe("Collection holding the document."),
-		id: idSchema,
+		...targetShape(scope, "write", {
+			collection: "Collection holding the document.",
+			global: "Global to patch."
+		}),
+		...idShape(scope, "write"),
 		...localeShape(scope, {
 			required: true,
 			description: "Locale the patch applies to. Localized fields write here only."
@@ -60,47 +66,55 @@ const patchDocument = {
 		expectedUpdatedAt: z.string().optional().describe("The updatedAt read before patching. The write is refused if the document has changed since.")
 	}),
 	handler: async (args, scope) => {
-		const collection = ensureAllowed(scope, args.collection, "write");
+		const target = resolveTarget(scope, args, "write");
+		const id = requireIdFor(target, args.id);
 		const { payload } = scope.req;
 		const locale = localeOf(scope, args.locale);
 		return await withTransaction(scope.req, async () => {
-			const doc = await readDraft(scope, {
-				collection: args.collection,
-				id: args.id,
+			const doc = await readTarget(scope, {
+				target,
+				id,
 				locale
 			});
 			if (args.expectedUpdatedAt !== void 0 && !sameInstant(doc["updatedAt"], args.expectedUpdatedAt)) return errorResult("The document changed since you read it. Read it again and re-apply the patch.", { updatedAt: doc["updatedAt"] });
 			const problems = findPatchProblems(payload.config, {
-				collection: args.collection,
 				doc,
-				patches: args.patches
+				patches: args.patches,
+				ref: refOf(target)
 			});
 			if (problems.length > 0) return errorResult("No operation was applied.", { problems });
 			const applied = applyPatchToCopy(doc, args.patches);
 			if ("problems" in applied) return errorResult("No operation was applied.", { problems: applied.problems });
-			await payload.update({
-				collection: args.collection,
-				id: args.id,
-				data: buildWriteData(payload.config, collection, applied.next),
+			const write = {
+				data: buildWriteData(payload.config, target.config, applied.next),
 				depth: 0,
 				draft: true,
 				overrideAccess: false,
 				req: scope.req,
 				...locale === void 0 ? {} : { locale }
+			};
+			if (target.kind === "collection") await payload.update({
+				...write,
+				collection: target.slug,
+				id
+			});
+			else await payload.updateGlobal({
+				...write,
+				slug: target.slug
 			});
-			const saved = await readDraft(scope, {
-				collection: args.collection,
-				id: args.id,
+			const saved = await readTarget(scope, {
+				target,
+				id,
 				locale,
 				privileged: true
 			});
 			const notApplied = notAppliedPointers(args.patches, applied.next, saved);
 			const publishBlockers = await collectPublishBlockers(scope.req, {
-				collection,
-				doc: saved
+				doc: saved,
+				entity: target
 			});
 			return jsonResult({
-				id: saved["id"],
+				...target.kind === "collection" ? { id: saved["id"] } : { global: target.slug },
 				status: saved["_status"],
 				updatedAt: saved["updatedAt"],
 				...publishBlockers.length > 0 ? { publishBlockers } : {},

package/dist/tools/shared.mjs

@@ -1,8 +1,39 @@
-import { Forbidden, NotFound } from "payload";
+import { NotFound } from "payload";
 import { z } from "zod";
 //#region src/tools/shared.ts
-const collectionEnum = (slugs) => z.enum(slugs);
+const slugEnum = (slugs) => z.enum(slugs);
 const idSchema = z.union([z.string(), z.number()]).describe("Document id.");
+const slugsFor = (scope, operation) => ({
+	collections: operation === "read" ? scope.readable : scope.writable,
+	globals: operation === "read" ? scope.readableGlobals : scope.writableGlobals
+});
+/**
+* The `collection` and `global` arguments.
+*
+* When the key can reach no global, `global` is left out of the shape entirely
+* and `collection` stays required, mirroring how {@link localeShape} omits
+* `locale` when localization is off. A deployment without globals therefore
+* sees exactly the schema it saw before. Only the mixed case makes either
+* argument optional, and the handler enforces the exclusivity there.
+*/ const targetShape = (scope, operation, descriptions) => {
+	const { collections, globals } = slugsFor(scope, operation);
+	if (globals.length === 0) return { collection: slugEnum(collections).describe(descriptions.collection) };
+	if (collections.length === 0) return { global: slugEnum(globals).describe(descriptions.global) };
+	return {
+		collection: slugEnum(collections).optional().describe(descriptions.collection),
+		global: slugEnum(globals).optional().describe(descriptions.global)
+	};
+};
+/**
+* The `id` argument, which only a collection document has. Omitted when the key
+* can reach no collection, required when it can reach no global, and optional
+* in between, where `requireIdFor` enforces the dependency.
+*/ const idShape = (scope, operation) => {
+	const { collections, globals } = slugsFor(scope, operation);
+	if (collections.length === 0) return {};
+	if (globals.length === 0) return { id: idSchema };
+	return { id: idSchema.optional().describe("Document id. Required with \"collection\"; must be omitted with \"global\".") };
+};
 /**
 * The `locale` argument, present only when localization is configured.
 */ const localeShape = (scope, options) => {
@@ -12,15 +43,6 @@ const idSchema = z.union([z.string(), z.number()]).describe("Document id.");
 };
 const depthShape = (scope) => ({ depth: z.number().int().min(0).max(scope.options.limits.maxDepth).optional().describe(`Relationship population depth. Default 0, at most ${String(scope.options.limits.maxDepth)}.`) });
 /**
-* Throws unless the key may perform `operation` on `slug`. The input schema
-* already limits the enum, so this only guards against a stale tool list.
-*/ const ensureAllowed = (scope, slug, operation) => {
-	const allowed = operation === "read" ? scope.readable : scope.writable;
-	const collection = scope.req.payload.collections[slug];
-	if (!allowed.includes(slug) || !collection) throw new Forbidden(scope.req.t);
-	return collection.config;
-};
-/**
 * The locale to operate on: the explicit argument, else the request's, else
 * the default. `undefined` when localization is off.
 */ const localeOf = (scope, locale) => {
@@ -31,23 +53,34 @@ const depthShape = (scope) => ({ depth: z.number().int().min(0).max(scope.option
 /**
 * 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 doc = await scope.req.payload.findByID({
-		collection: args.collection,
-		id: args.id,
+*/ 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: args.privileged === true,
-		showHiddenFields: args.privileged === true,
-		disableErrors: true,
+		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
 	});
-	if (!doc) throw new NotFound(scope.req.t);
-	return doc;
 };
 /**
 * Resolves a collection label for the request's language.
@@ -62,4 +95,4 @@ const depthShape = (scope) => ({ depth: z.number().int().min(0).max(scope.option
 	return fallback;
 };
 //#endregion
-export { collectionEnum, depthShape, ensureAllowed, idSchema, localeOf, localeShape, readDraft, translateLabel };
+export { depthShape, idSchema, idShape, localeOf, localeShape, readTarget, slugEnum, targetShape, translateLabel };

package/dist/tools/target.d.mts

@@ -0,0 +1,3 @@
+import "./types.mjs";
+import "../schema/walk.mjs";
+import "payload";

package/dist/tools/target.mjs

@@ -0,0 +1,49 @@
+import { APIError, Forbidden } from "payload";
+//#region src/tools/target.ts
+const refOf = (target) => ({
+	kind: target.kind,
+	slug: target.slug
+});
+/**
+* Resolves the `collection`/`global` arguments to one entity and checks the key
+* may perform `operation` on it.
+*
+* A tool's `inputSchema` returns a raw shape, which leaves no top-level
+* `.refine` to express "exactly one of collection and global". The rule is
+* enforced here instead, with a message naming the offending arguments so one
+* failed call teaches it.
+*/ const resolveTarget = (scope, args, operation) => {
+	const { collection, global } = args;
+	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 allowed = operation === "read" ? scope.readable : scope.writable;
+		const found = scope.req.payload.collections[collection];
+		if (!allowed.includes(collection) || !found) throw new Forbidden(scope.req.t);
+		return {
+			kind: "collection",
+			slug: collection,
+			config: found.config
+		};
+	}
+	const slug = global;
+	const allowed = operation === "read" ? scope.readableGlobals : scope.writableGlobals;
+	const found = scope.req.payload.globals.config.find((candidate) => candidate.slug === slug);
+	if (!allowed.includes(slug) || !found) throw new Forbidden(scope.req.t);
+	return {
+		kind: "global",
+		slug,
+		config: found
+	};
+};
+/**
+* Checks `id` against the resolved target. A collection document needs one; a
+* global is a singleton and must not carry one. The schema cannot express the
+* dependency, so it is stated here and in every affected tool description.
+*/ const requireIdFor = (target, id) => {
+	if (target.kind === "collection" && id === void 0) throw new APIError(`"id" is required when "collection" is "${target.slug}".`, 400);
+	if (target.kind === "global" && id !== void 0) throw new APIError(`"id" must be omitted when "global" is "${target.slug}"; a global is a singleton.`, 400);
+	return target.kind === "collection" ? id : void 0;
+};
+//#endregion
+export { refOf, requireIdFor, resolveTarget };

package/dist/tools/types.d.mts

@@ -0,0 +1,5 @@
+import "../types.mjs";
+import "../options.mjs";
+import { PayloadRequest } from "payload";
+import { z } from "zod";
+import { CallToolResult, ToolAnnotations } from "@modelcontextprotocol/sdk/types.js";