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

package/README.md

@@ -44,6 +44,9 @@ export default buildConfig({
         posts: { read: true, write: true },
         tags: true, // shorthand for { read: true }
       },
+      globals: {
+        "site-settings": { read: true, write: true },
+      },
       limits: { maxLimit: 25, maxDepth: 1 },
     }),
   ],
@@ -56,8 +59,8 @@ The plugin adds:
   JSON responses; `GET`/`DELETE` answer 405),
 - an `mcpx-api-keys` collection (admin group "MCP") holding the keys and their
   capability checkboxes,
-- a draft guard on every collection, so any write carrying the MCP request
-  marker lands as a draft, including writes made by custom tools.
+- a draft guard on every collection and global, so any write carrying the MCP
+  request marker lands as a draft, including writes made by custom tools.
 
 ## API keys
 
@@ -118,19 +121,20 @@ Claude Desktop (no direct HTTP header support) via `mcp-remote`:
 
 ## Tools
 
-The surface is fixed at seven tools plus your custom ones. `tools/list`
-reflects the key: write tools disappear for read-only keys, and every
-`collection` enum contains only the slugs the key may touch.
+The surface is fixed at seven tools plus your custom ones; exposing a global
+adds an argument, never a tool. `tools/list` reflects the key: write tools
+disappear for read-only keys, and every `collection` and `global` enum contains
+only the slugs the key may touch.
 
 | Tool               | Purpose                                                     | Key arguments                                                                                |
 | ------------------ | ----------------------------------------------------------- | -------------------------------------------------------------------------------------------- |
 | `listCapabilities` | What this key may do; call first to orient.                 | none                                                                                         |
-| `describeSchema`   | Field shape of one node; `next` lists the drill-down paths. | `collection`, `paths?`, `expand?`                                                            |
+| `describeSchema`   | Field shape of one node; `next` lists the drill-down paths. | `collection` \| `global`, `paths?`, `expand?`                                                |
 | `findDocuments`    | Query documents.                                            | `collection`, `where?`, `sort?`, `limit?`, `page?`, `depth?`, `select?`, `locale?`, `draft?` |
-| `getDocument`      | Read one document or a subtree of it.                       | `collection`, `id`, `path?` (JSON pointer), `depth?`, `locale?`, `draft?`                    |
-| `patchDocument`    | Apply RFC 6902 operations to the current draft.             | `collection`, `id`, `locale`, `patches`, `expectedUpdatedAt?`                                |
+| `getDocument`      | Read one document or a subtree of it.                       | `collection` + `id` \| `global`, `path?` (JSON pointer), `depth?`, `locale?`, `draft?`       |
+| `patchDocument`    | Apply RFC 6902 operations to the current draft.             | `collection` + `id` \| `global`, `locale`, `patches`, `expectedUpdatedAt?`                   |
 | `createDocument`   | Create a draft from a minimal seed.                         | `collection`, `locale`, `data`                                                               |
-| `validateDocument` | Publish blockers without writing.                           | `collection`, `id`, `locale`                                                                 |
+| `validateDocument` | Publish blockers without writing.                           | `collection` + `id` \| `global`, `locale`                                                    |
 
 Rules the tools enforce and explain in their own descriptions:
 
@@ -161,13 +165,55 @@ Rules the tools enforce and explain in their own descriptions:
   `deletedAt`) are never listed and never writable; `readOnly` fields are
   listed but refused on write.
 
+## Globals
+
+A global is exposed the same way a collection is, and reached through the same
+tools rather than tools of its own:
+
+```ts
+mcpxPlugin({
+  collections: { pages: { read: true, write: true } },
+  globals: { "site-settings": { read: true, write: true } },
+});
+```
+
+Two rules follow from a global being a singleton, and because JSON Schema cannot
+state either one, both are enforced in the handler and repeated in every
+affected tool description:
+
+- Pass exactly **one** of `collection` and `global`.
+- `id` is required with `collection` and must be omitted with `global`.
+
+Refusals name the offending argument and the slug, so one failed call teaches
+the rule. `findDocuments` and `createDocument` stay collection-only: there is
+nothing to list and nothing to create when the document always exists. They
+reject a `global` argument by name.
+
+Globals get their own `capabilities.globals.<name>` checkbox group, a separate
+namespace from `capabilities.collections.<name>`, so a global may share a
+camelCase name with a collection. Keys issued before a global was exposed have
+no such group, and an absent checkbox reads as `false`, so they stay closed to
+every global until one is ticked.
+
+Globals always carry `updatedAt` — Payload appends it and there is no
+`timestamps: false` for globals — so `expectedUpdatedAt` behaves as it does for
+collections. The one exception is a global that has never been saved: it has no
+`updatedAt` to compare against, so the first write must omit
+`expectedUpdatedAt`, and supplying one is refused as a concurrency failure.
+
+If `tools/list` omits `global` entirely, no global is exposed to that key; the
+argument only appears once one is. A deployment that uses no globals sees the
+tool schemas exactly as they were.
+
 ## Drafts and publish blockers
 
 Draft-only writing is enforced on the Payload operation, not in the tool
 handlers: a `beforeOperation` hook forces `draft: true` and strips `_status`
 from every write carrying the MCP request marker, so custom tools and anything
 else writing through the same request are covered too. A `beforeChange` hook
-refuses any write that would still not land as a draft.
+refuses any write that would still not land as a draft. Globals expose the same
+`beforeOperation` interception point at the same position in the operation, so
+they are guarded exactly as strongly as collections, exposed or not.
 
 Publish blockers are advisory. Payload skips validation on draft saves (unless
 `versions.drafts.validate` is set), so after every write the plugin re-runs
@@ -224,6 +270,10 @@ Builtin tools reject them instead.
 | `collections.<slug>.read`            | `true`                         | Expose `describeSchema`, `findDocuments`, `getDocument`.                                                           |
 | `collections.<slug>.write`           | `false`                        | Expose `patchDocument`, `createDocument`, `validateDocument`. Requires `versions.drafts` unless `allowLiveWrites`. |
 | `collections.<slug>.allowLiveWrites` | `false`                        | Permit writes to a collection without drafts (they land live).                                                     |
+| `globals`                            | `{}`                           | Allow-list of globals. `true` means `{ read: true }`.                                                              |
+| `globals.<slug>.read`                | `true`                         | Expose `describeSchema`, `getDocument`.                                                                            |
+| `globals.<slug>.write`               | `false`                        | Expose `patchDocument`, `validateDocument`. Requires `versions.drafts` unless `allowLiveWrites`.                   |
+| `globals.<slug>.allowLiveWrites`     | `false`                        | Permit writes to a global without drafts (they land live).                                                         |
 | `userCollection`                     | `config.admin.user` or `users` | Auth collection the keys act as.                                                                                   |
 | `apiKeys.slug`                       | `mcpx-api-keys`                | Slug of the generated key collection.                                                                              |
 | `apiKeys.overrideCollection`         | none                           | Final override applied to the generated collection.                                                                |
@@ -247,15 +297,14 @@ key of every user.
 - The endpoint authenticates with Bearer keys only; admin JWTs and cookies are
   ignored. Keys cannot authenticate REST or GraphQL.
 - Every operation runs under the linked user with `overrideAccess: false`.
-- Not covered in v1: `delete` (no tool exists and none is generated), globals,
-  uploads. Custom tools are trusted code and can do what the linked user may.
+- Not covered in v1: `delete` (no tool exists and none is generated), uploads.
+  Custom tools are trusted code and can do what the linked user may.
 
 ## Non-goals of v1 / roadmap
 
-Globals, deletes, uploads, markdown authoring for rich text, row addressing by
-id instead of index, cross-locale publish blockers, pagination of
-`describeSchema` with `expand`, and a handler-level timeout are all deliberate
-omissions for now.
+Deletes, uploads, markdown authoring for rich text, row addressing by id
+instead of index, cross-locale publish blockers, pagination of `describeSchema`
+with `expand`, and a handler-level timeout are all deliberate omissions for now.
 
 ## License
 

package/dist/api-keys/fields.mjs

@@ -56,9 +56,10 @@ const checkbox = (name, description) => ({
 	}
 ];
 /**
-* One checkbox per exposed operation, grouped per collection and per custom
-* tool. Only operations the plugin config exposes get a checkbox, so a key can
-* never enable more than the config allows. Everything defaults to off.
+* One checkbox per exposed operation, grouped per collection, per global and
+* per custom tool. Only operations the plugin config exposes get a checkbox, so
+* a key can never enable more than the config allows. Everything defaults to
+* off, which is why a key issued before a capability existed stays closed to it.
 */ const createCapabilityFields = (options) => {
 	const collectionGroups = options.collections.map((collection) => ({
 		name: collection.fieldName,
@@ -66,16 +67,30 @@ const checkbox = (name, description) => ({
 		label: collection.slug,
 		fields: [...collection.read ? [checkbox("read", "Describe, find and read documents.")] : [], ...collection.write ? [checkbox("write", "Create, patch and validate drafts.")] : []]
 	}));
-	const toolCheckboxes = options.tools.map((tool) => checkbox(tool.name, tool.description));
-	const groups = [...collectionGroups.length > 0 ? [{
-		name: "collections",
-		type: "group",
-		fields: collectionGroups
-	}] : [], ...toolCheckboxes.length > 0 ? [{
-		name: "tools",
+	const globalGroups = options.globals.map((global) => ({
+		name: global.fieldName,
 		type: "group",
-		fields: toolCheckboxes
-	}] : []];
+		label: global.slug,
+		fields: [...global.read ? [checkbox("read", "Describe and read this global.")] : [], ...global.write ? [checkbox("write", "Patch and validate this global's draft.")] : []]
+	}));
+	const toolCheckboxes = options.tools.map((tool) => checkbox(tool.name, tool.description));
+	const groups = [
+		...collectionGroups.length > 0 ? [{
+			name: "collections",
+			type: "group",
+			fields: collectionGroups
+		}] : [],
+		...globalGroups.length > 0 ? [{
+			name: "globals",
+			type: "group",
+			fields: globalGroups
+		}] : [],
+		...toolCheckboxes.length > 0 ? [{
+			name: "tools",
+			type: "group",
+			fields: toolCheckboxes
+		}] : []
+	];
 	if (groups.length === 0) return [];
 	return [{
 		name: CAPABILITIES_FIELD,

package/dist/capabilities.mjs

@@ -8,6 +8,7 @@ const flag = (group, name) => isRecord(group) && group[name] === true;
 * issued before a capability existed stay closed.
 */ const resolveCapabilities = (options, keyCapabilities) => {
 	const collectionsGroup = isRecord(keyCapabilities) ? keyCapabilities["collections"] : void 0;
+	const globalsGroup = isRecord(keyCapabilities) ? keyCapabilities["globals"] : void 0;
 	const toolsGroup = isRecord(keyCapabilities) ? keyCapabilities["tools"] : void 0;
 	const collections = {};
 	for (const collection of options.collections) {
@@ -17,14 +18,26 @@ const flag = (group, name) => isRecord(group) && group[name] === true;
 			write: collection.write && flag(group, "write")
 		};
 	}
+	const globals = {};
+	for (const global of options.globals) {
+		const group = isRecord(globalsGroup) ? globalsGroup[global.fieldName] : void 0;
+		globals[global.slug] = {
+			read: global.read && flag(group, "read"),
+			write: global.write && flag(group, "write")
+		};
+	}
 	const tools = {};
 	for (const tool of options.tools) tools[tool.name] = flag(toolsGroup, tool.name);
 	return {
 		collections,
+		globals,
 		tools
 	};
 };
-const readableSlugs = (capabilities) => Object.entries(capabilities.collections).filter(([, value]) => value.read).map(([slug]) => slug);
-const writableSlugs = (capabilities) => Object.entries(capabilities.collections).filter(([, value]) => value.write).map(([slug]) => slug);
+const pick = (entries, operation) => Object.entries(entries).filter(([, value]) => value[operation]).map(([slug]) => slug);
+const readableSlugs = (capabilities) => pick(capabilities.collections, "read");
+const writableSlugs = (capabilities) => pick(capabilities.collections, "write");
+const readableGlobalSlugs = (capabilities) => pick(capabilities.globals, "read");
+const writableGlobalSlugs = (capabilities) => pick(capabilities.globals, "write");
 //#endregion
-export { CAPABILITIES_FIELD, readableSlugs, resolveCapabilities, writableSlugs };
+export { CAPABILITIES_FIELD, readableGlobalSlugs, readableSlugs, resolveCapabilities, writableGlobalSlugs, writableSlugs };

package/dist/endpoint/handler.mjs

@@ -1,4 +1,4 @@
-import { readableSlugs, resolveCapabilities, writableSlugs } from "../capabilities.mjs";
+import { readableGlobalSlugs, readableSlugs, resolveCapabilities, writableGlobalSlugs, writableSlugs } from "../capabilities.mjs";
 import { resolveApiKeyAuth } from "../auth/resolve.mjs";
 import { jsonRpcError } from "./result.mjs";
 import { createMcpServer } from "./server.mjs";
@@ -12,6 +12,8 @@ const buildScope = (req, options, capabilities) => {
 		capabilities,
 		readable: readableSlugs(capabilities),
 		writable: writableSlugs(capabilities),
+		readableGlobals: readableGlobalSlugs(capabilities),
+		writableGlobals: writableGlobalSlugs(capabilities),
 		locales: localization ? localization.localeCodes : null,
 		defaultLocale: localization ? localization.defaultLocale : null
 	};

package/dist/endpoint/server.mjs

@@ -18,7 +18,7 @@ import { z } from "zod";
 	const server = new McpServer({
 		name: options.serverInfo.name,
 		version: options.serverInfo.version
-	}, { instructions: "Start with listCapabilities, then describeSchema for the collection you work on. Writes always land as drafts; a human publishes." });
+	}, { instructions: "Start with listCapabilities, then describeSchema for the collection or global you work on. Writes always land as drafts; a human publishes." });
 	const guarded = (run) => async () => {
 		try {
 			return await run();

package/dist/index.d.mts

@@ -1,5 +1,5 @@
-import { McpxAuthResult, McpxCollectionCapabilities, McpxCollectionOptions, McpxPluginOptions, McpxRequestContext, McpxResolvedCapabilities, McpxTool, McpxToolExtra, defineMcpxTool } from "./types.mjs";
+import { McpxAuthResult, McpxCollectionCapabilities, McpxCollectionOptions, McpxGlobalOptions, McpxPluginOptions, McpxRequestContext, McpxResolvedCapabilities, McpxTool, McpxToolExtra, defineMcpxTool } from "./types.mjs";
 import { mcpxPlugin } from "./plugin.mjs";
 import { isMcpxRequest } from "./write/draft-guard.mjs";
 import { PublishBlocker } from "./write/publish-blockers.mjs";
-export { type McpxAuthResult, type McpxCollectionCapabilities, type McpxCollectionOptions, type McpxPluginOptions, type McpxRequestContext, type McpxResolvedCapabilities, type McpxTool, type McpxToolExtra, type PublishBlocker, defineMcpxTool, isMcpxRequest, mcpxPlugin };
+export { type McpxAuthResult, type McpxCollectionCapabilities, type McpxCollectionOptions, type McpxGlobalOptions, type McpxPluginOptions, type McpxRequestContext, type McpxResolvedCapabilities, type McpxTool, type McpxToolExtra, type PublishBlocker, defineMcpxTool, isMcpxRequest, mcpxPlugin };

package/dist/options.d.mts

@@ -0,0 +1,2 @@
+import "./types.mjs";
+import "payload";

package/dist/options.mjs

@@ -30,6 +30,19 @@ const assertWritable = (collection, options) => {
 	if (collection.timestamps === false) fail(`Collection "${slug}" has timestamps disabled, which write tools need for concurrency checks.`);
 	if (!options.hasDrafts && !options.allowLiveWrites) fail(`Collection "${slug}" has no drafts. Enable versions.drafts or set allowLiveWrites.`);
 };
+/**
+* Refuses globals that must never be reachable. Globals cannot be auth or
+* upload entities, so only Payload's own reserved namespace is left to guard.
+*/ const assertGlobalExposable = (global) => {
+	if (global.slug.startsWith("payload-")) fail(`Global "${global.slug}" cannot be exposed.`);
+};
+/**
+* `GlobalConfig` has no `timestamps` option and `sanitizeGlobal` always appends
+* `createdAt`/`updatedAt`, so the concurrency check the collection path guards
+* for is always available here. Drafts are the only requirement left.
+*/ const assertGlobalWritable = (global, options) => {
+	if (!options.hasDrafts && !options.allowLiveWrites) fail(`Global "${global.slug}" has no drafts. Enable versions.drafts or set allowLiveWrites.`);
+};
 const normalizeCollections = (config, options, apiKeysSlug) => {
 	const collections = config.collections ?? [];
 	const fieldNames = /* @__PURE__ */ new Set();
@@ -54,6 +67,30 @@ const normalizeCollections = (config, options, apiKeysSlug) => {
 		return [normalized];
 	});
 };
+const normalizeGlobals = (config, options) => {
+	const globals = config.globals ?? [];
+	const fieldNames = /* @__PURE__ */ new Set();
+	return Object.entries(options.globals ?? {}).flatMap(([slug, raw]) => {
+		if (raw === void 0) return [];
+		const global = globals.find((candidate) => candidate.slug === slug);
+		if (!global) return fail(`Exposed global "${slug}" does not exist.`);
+		assertGlobalExposable(global);
+		const settings = raw === true ? {} : raw;
+		const hasDrafts = hasDraftsEnabled(global);
+		const normalized = {
+			slug,
+			read: settings.read ?? true,
+			write: settings.write ?? false,
+			allowLiveWrites: settings.allowLiveWrites ?? false,
+			hasDrafts,
+			fieldName: toCamelCase(slug)
+		};
+		if (normalized.write) assertGlobalWritable(global, normalized);
+		if (fieldNames.has(normalized.fieldName)) fail(`Global "${slug}" maps to capability field "${normalized.fieldName}", which another exposed global already uses.`);
+		fieldNames.add(normalized.fieldName);
+		return [normalized];
+	});
+};
 const assertUserCollection = (config, slug) => {
 	const collection = (config.collections ?? []).find((candidate) => candidate.slug === slug);
 	if (!collection) fail(`User collection "${slug}" does not exist.`);
@@ -91,6 +128,7 @@ const normalizeLimits = (limits) => {
 	assertTools(tools);
 	return {
 		collections: normalizeCollections(config, options, apiKeysSlug),
+		globals: normalizeGlobals(config, options),
 		userCollection,
 		apiKeysSlug,
 		endpointPath: options.endpoint?.path ?? DEFAULT_ENDPOINT_PATH,

package/dist/plugin.d.mts

@@ -2,7 +2,7 @@ import { McpxPluginOptions } from "./types.mjs";
 //#region src/plugin.d.ts
 /**
  * Mounts the MCP endpoint, adds the API key collection and installs the
- * draft guard on every collection.
+ * draft guard on every collection and global.
  */
 declare const mcpxPlugin: (options: McpxPluginOptions) => import("payload").Plugin;
 //#endregion

package/dist/plugin.mjs

@@ -1,12 +1,12 @@
 import { createApiKeysCollection } from "./api-keys/collection.mjs";
 import { createMcpxHandler, methodNotAllowed } from "./endpoint/handler.mjs";
 import { normalizeOptions } from "./options.mjs";
-import { installDraftGuards } from "./write/draft-guard.mjs";
+import { installDraftGuards, installGlobalDraftGuards } from "./write/draft-guard.mjs";
 import { definePlugin } from "payload";
 //#region src/plugin.ts
 /**
 * Mounts the MCP endpoint, adds the API key collection and installs the
-* draft guard on every collection.
+* draft guard on every collection and global.
 */ const mcpxPlugin = definePlugin({
 	slug: "@abinnovision/payloadcms-mcpx",
 	order: 100,
@@ -17,6 +17,7 @@ import { definePlugin } from "payload";
 		return {
 			...config,
 			collections: installDraftGuards([...config.collections ?? [], apiKeysCollection]),
+			globals: installGlobalDraftGuards(config.globals ?? []),
 			endpoints: [
 				...config.endpoints ?? [],
 				{

package/dist/schema/describe.mjs

@@ -1,4 +1,4 @@
-import { blockOf, blockSlugsOf, collectionOf, describeFields, findBlocksField, joinPath, splitPath } from "./walk.mjs";
+import { blockOf, blockSlugsOf, describeFields, findBlocksField, joinPath, splitPath, targetOf } from "./walk.mjs";
 //#region src/schema/describe.ts
 const blocksDescriptors = (fields) => describeFields(fields).filter((descriptor) => descriptor.type === "blocks");
 /**
@@ -8,8 +8,8 @@ const blocksDescriptors = (fields) => describeFields(fields).filter((descriptor)
 * the blocks it accepts, so `/layout/sections/sectionWrapper/modules/hero`
 * reaches `hero` as it exists under `pages` specifically. The slug sits where
 * a pointer into a document would carry the element's index.
-*/ const fieldsAtSchemaPath = (config, collection, schemaPath) => {
-	let fields = collection.flattenedFields;
+*/ const fieldsAtSchemaPath = (config, target, schemaPath) => {
+	let fields = target.flattenedFields;
 	let blockType;
 	let remaining = splitPath(schemaPath);
 	while (remaining.length > 0) {
@@ -34,24 +34,25 @@ const blocksDescriptors = (fields) => describeFields(fields).filter((descriptor)
 	};
 };
 /**
-* Describes a collection root, or one block reached through a schema path.
-*/ const describeNode = (config, collection, schemaPath = "") => {
-	const { blockType, fields } = fieldsAtSchemaPath(config, collectionOf(config, collection), schemaPath);
+* Describes a collection or global root, or one block reached through a schema
+* path.
+*/ const describeNode = (config, ref, schemaPath = "") => {
+	const { blockType, fields } = fieldsAtSchemaPath(config, targetOf(config, ref), schemaPath);
 	const descriptors = describeFields(fields);
 	const next = descriptors.flatMap((descriptor) => (descriptor.blocks ?? []).map((slug) => `${schemaPath}${descriptor.path}/${slug}`));
 	return {
 		...blockType === void 0 ? {} : { blockType },
-		collection,
+		...ref.kind === "collection" ? { collection: ref.slug } : { global: ref.slug },
 		fields: descriptors,
 		...next.length > 0 ? { next } : {},
 		schemaPath
 	};
 };
 /**
-* Every schema path reachable from a collection root, capped at
+* Every schema path reachable from an entity root, capped at
 * {@link REACHABLE_PATHS_LIMIT}. `truncated` tells the caller the cap was hit
 * and explicit paths are the way to go deeper.
-*/ const reachableSchemaPaths = (config, collection) => {
+*/ const reachableSchemaPaths = (config, ref) => {
 	const seen = [];
 	let truncated = false;
 	const walk = (schemaPath, visited) => {
@@ -60,7 +61,7 @@ const blocksDescriptors = (fields) => describeFields(fields).filter((descriptor)
 			return;
 		}
 		seen.push(schemaPath);
-		for (const descriptor of describeNode(config, collection, schemaPath).fields) for (const slug of descriptor.blocks ?? []) {
+		for (const descriptor of describeNode(config, ref, schemaPath).fields) for (const slug of descriptor.blocks ?? []) {
 			if (visited.includes(slug)) continue;
 			walk(`${schemaPath}${descriptor.path}/${slug}`, [...visited, slug]);
 		}

package/dist/schema/pointer.mjs

@@ -1,4 +1,4 @@
-import { blockOf, blockSlugsOf, collectionOf, describeFields, findBlocksField, joinPath, splitPath } from "./walk.mjs";
+import { blockOf, blockSlugsOf, describeFields, findBlocksField, joinPath, splitPath, targetOf } from "./walk.mjs";
 //#region src/schema/pointer.ts
 const isIndexSegment = (segment) => segment === "-" || /^\d+$/.test(segment);
 const partMatches = (part, segment) => segment !== void 0 && (part === "*" ? isIndexSegment(segment) : part === segment);
@@ -32,7 +32,7 @@ const partMatches = (part, segment) => segment !== void 0 && (part === "*" ? isI
 * can only be resolved by reading `blockType` off `sections[3]`, since a blocks
 * field admits many shapes at the same index.
 */ const resolveDataPointer = (config, target) => {
-	let fields = collectionOf(config, target.collection).flattenedFields;
+	let fields = targetOf(config, target.ref).flattenedFields;
 	let data = target.doc;
 	let blockType;
 	let segments = splitPath(target.pointer);

package/dist/schema/walk.d.mts

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

package/dist/schema/walk.mjs

@@ -109,10 +109,10 @@ const withRows = (descriptor, field) => ({
 		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 { JSON_POINTER_PATTERN, RESERVED_FIELD_NAMES, blockOf, blockSlugsOf, collectionOf, describeFields, findBlocksField, joinPath, pointerFromPayloadPath, 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,14 +25,14 @@ 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,
+				fields: target.config.flattenedFields,
 				prefix: []
 			}
 		}, seed);
@@ -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,6 +8,8 @@ const describeSchema = {
 	name: "describeSchema",
 	description: `Describes the writable shape of a document, one node at a time.
 
+Pass exactly one of "collection" and "global". A global is a singleton: it has no id, is not listed by findDocuments and cannot be created.
+
 Call it with no "paths" to get a collection's own fields. Every "blocks" field stops there and lists the block slugs it accepts instead of nesting them; each node's "next" lists the ready-to-use paths for those blocks, so pass any entry of "next" as a "paths" element to descend, e.g. "/layout/sections/sectionWrapper" and then "/layout/sections/sectionWrapper/modules/hero". A block is described as it exists at that position, because the same block can accept different children elsewhere.
 
 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".
@@ -16,19 +19,22 @@ Fields Payload maintains (id, _status, createdAt, updatedAt) are never listed an
 		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."),
+		...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,