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

package/dist/api-keys/fields.mjs

@@ -16,7 +16,7 @@ const checkbox = (name, description) => ({
 	defaultValue: false,
 	admin: { description }
 });
-/** Name of the `ui` field the "Connect a client" tab renders. */ const SETUP_GUIDE_FIELD = "setupGuide";
+const SETUP_GUIDE_FIELD = "setupGuide";
 /**
 * Fields every key carries. Key generation and the HMAC index live in the
 * collection-level `beforeChange` hook (see `collection.ts`), because sibling
@@ -58,13 +58,11 @@ const checkbox = (name, description) => ({
 	}
 ];
 /**
-* Wraps the key fields and the setup guide in unnamed tabs, so the wide
-* snippets get the full form width without pushing the key itself out of view.
-* Unnamed on purpose: named tabs would nest the data and move `capabilities`
-* off the document root, which capability resolution reads.
+* Wraps the key fields and the setup guide in unnamed tabs, so wide snippets
+* get the full form width. Named tabs would nest the data and move
+* `capabilities` off the document root, which capability resolution reads.
 *
-* The guide tab is conditioned on the update operation. On create there is no
-* key to hand out, and a tab leading to an empty panel is worse than no tab.
+* The guide tab only shows on update: on create there is no key to hand out.
 */ const withSetupGuideTab = (keyFields, options) => {
 	if (!options.setupGuide) return keyFields;
 	return [{
@@ -81,7 +79,7 @@ const checkbox = (name, description) => ({
 				admin: {
 					disableListColumn: true,
 					components: { Field: {
-						path: "@abinnovision/payloadcms-mcpx/client",
+						path: "@abinnovision/payloadcms-mcpx/admin",
 						exportName: "McpxSetupGuide",
 						clientProps: { endpointPath: options.endpointPath }
 					} }
@@ -91,21 +89,14 @@ const checkbox = (name, description) => ({
 	}];
 };
 /**
-* One checkbox per exposed operation, grouped per collection, per global and
-* per custom tool, generated from the same {@link createCapabilityMatrix}
-* descriptor the admin component draws, so a cell can never appear without a
-* field behind it. 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.
+* One checkbox per operation the config exposes, grouped per collection, global
+* and custom tool, built from {@link createCapabilityMatrix}. Everything
+* defaults to off, so a key issued before a capability existed stays closed.
 *
-* An entity without versions gets no `publish` checkbox even under
-* `write: "live"`: there is no draft to promote there, the write itself is the
-* live change, and a second checkbox would only make `write` a dead setting.
-*
-* The group renders as a matrix rather than as nested boxes; see
-* `src/client/capability-matrix.tsx`. The descriptions below therefore reach
-* the screen on the matrix column headers, and survive here for a consumer who
-* replaces the component through `apiKeys.overrideCollection`.
+* An entity without drafts gets no `publish` checkbox, even where
+* writes are on: the write is already live, so the box would make `write` a
+* dead setting. The admin renders the group as a matrix; the checkboxes serve
+* consumers who replace that component through `apiKeys.overrideCollection`.
 */ const createCapabilityFields = (options) => {
 	const matrix = createCapabilityMatrix(options);
 	const entityGroups = (rows) => rows.map((row) => ({
@@ -141,7 +132,7 @@ const checkbox = (name, description) => ({
 		admin: {
 			description: CAPABILITIES_DESCRIPTION,
 			components: { Field: {
-				path: "@abinnovision/payloadcms-mcpx/client",
+				path: "@abinnovision/payloadcms-mcpx/admin",
 				exportName: "McpxCapabilityMatrix",
 				clientProps: {
 					matrix,
@@ -153,4 +144,4 @@ const checkbox = (name, description) => ({
 	}];
 };
 //#endregion
-export { SETUP_GUIDE_FIELD, createCapabilityFields, createKeyFields, withSetupGuideTab };
+export { createCapabilityFields, createKeyFields, withSetupGuideTab };

package/dist/auth/resolve.mjs

@@ -1,3 +1,4 @@
+import { isPlainObject } from "../guards.mjs";
 import { hashApiKey } from "../api-keys/key.mjs";
 //#region src/auth/resolve.ts
 const BEARER = /^Bearer\s+(\S+)\s*$/i;
@@ -10,6 +11,14 @@ const parseBearer = (headers) => {
 	if (!header) return null;
 	return BEARER.exec(header.trim())?.[1] ?? null;
 };
+const isId = (value) => typeof value === "string" || typeof value === "number";
+/**
+* Whether a resolved auth, from the default or a custom resolver, may become
+* `req.user`: a user of the configured user collection with an id, and a key id.
+*/ const isValidAuthResult = (auth, options) => {
+	if (!isPlainObject(auth) || !isPlainObject(auth["user"])) return false;
+	return isId(auth["user"]["id"]) && auth["user"]["collection"] === options.userCollection && isId(auth["apiKeyId"]);
+};
 /**
 * Resolves the bearer key of a request to the user it acts as.
 *
@@ -37,14 +46,23 @@ const parseBearer = (headers) => {
 	const userId = relationId(keyDoc?.user);
 	if (!keyDoc || keyDoc.enabled !== true || userId === void 0) return null;
 	const userCollection = payload.collections[options.userCollection];
-	const user = await payload.findByID({
+	const lookup = {
 		collection: options.userCollection,
 		id: userId,
-		depth: userCollection?.config.auth.depth ?? 0,
 		overrideAccess: true,
 		disableErrors: true
-	});
-	const lockUntil = typeof user?.["lockUntil"] === "string" ? Date.parse(user["lockUntil"]) : NaN;
+	};
+	const [user, lock] = await Promise.all([payload.findByID({
+		...lookup,
+		depth: userCollection?.config.auth.depth ?? 0
+	}), payload.findByID({
+		...lookup,
+		depth: 0,
+		showHiddenFields: true,
+		select: { lockUntil: true }
+	})]);
+	const storedLock = lock?.["lockUntil"];
+	const lockUntil = typeof storedLock === "string" || storedLock instanceof Date ? new Date(storedLock).getTime() : NaN;
 	if (!user || user["_verified"] === false || lockUntil > Date.now()) return null;
 	return {
 		user: {
@@ -57,4 +75,4 @@ const parseBearer = (headers) => {
 	};
 };
 //#endregion
-export { parseBearer, resolveApiKeyAuth };
+export { isValidAuthResult, parseBearer, resolveApiKeyAuth };

package/dist/{tools/names.mjs → builtin-tool-names.mjs}

@@ -1,4 +1,4 @@
-//#region src/tools/names.ts
+//#region src/builtin-tool-names.ts
 /**
 * Names of the builtin tools. Custom tools must not reuse them.
 */ const BUILTIN_TOOL_NAMES = [
@@ -6,6 +6,7 @@
 	"describeSchema",
 	"findDocuments",
 	"getDocument",
+	"findVersions",
 	"patchDocument",
 	"createDocument",
 	"validateDocument",

package/dist/capabilities.mjs

@@ -1,62 +1,54 @@
+import { isPlainObject } from "./guards.mjs";
 //#region src/capabilities.ts
 /** Group field holding the capability checkboxes on an API key document. */ const CAPABILITIES_FIELD = "capabilities";
-/** Whatever the write lands on; {@link isLiveWrite} tells the two apart. */ const canWrite = (entity) => entity.write !== false;
-/** The config lets MCP change live content and there is a draft to promote. */ const canPublish = (entity) => entity.write === "live" && entity.hasDrafts;
+/** Covers draft and live writes; {@link isLiveWrite} separates them. */ const canWrite = (entity) => entity.write !== false;
+/** The config lets MCP change live content and a draft exists to promote. */ const canPublish = (entity) => entity.write === "live" && entity.hasDrafts;
 /**
 * An upload document is a file, and no tool here carries one. Its own fields
 * stay patchable; the first version is made in the admin panel.
 */ const canCreate = (entity) => canWrite(entity) && !entity.isUpload;
 /**
-* With no versions there is no draft to land on, so `write: "live"` permits the
-* write at all and every write is live.
+* Without drafts there is no draft stage, so every write is live.
 */ const isLiveWrite = (entity) => entity.write === "live" && !entity.hasDrafts;
-const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
-const flag = (group, name) => isRecord(group) && group[name] === true;
-/**
-* Publishing is an extension of writing, never a capability of its own: a key
-* that may publish may also edit the draft it publishes. Both checkboxes are
-* therefore required, on top of the config exposing publishing at all.
-*/ const publishFlag = (entity, group) => canPublish(entity) && flag(group, "write") && flag(group, "publish");
+const flag = (group, name) => isPlainObject(group) && group[name] === true;
+const publishFlag = (entity, group) => canPublish(entity) && flag(group, "write") && flag(group, "publish");
 /**
 * Capabilities in force for a key: the plugin config decides what can exist,
 * the key's checkboxes decide what does. A missing checkbox is `false`, so keys
 * 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) {
-		const group = isRecord(collectionsGroup) ? collectionsGroup[collection.fieldName] : void 0;
-		collections[collection.slug] = {
-			read: collection.read && flag(group, "read"),
-			write: canWrite(collection) && flag(group, "write"),
-			publish: publishFlag(collection, group)
-		};
-	}
-	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: canWrite(global) && flag(group, "write"),
-			publish: publishFlag(global, group)
-		};
-	}
+	const groupOf = (name) => isPlainObject(keyCapabilities) ? keyCapabilities[name] : void 0;
+	const resolveEntities = (entities, namespaceGroup) => {
+		const resolved = {};
+		for (const entity of entities) {
+			const group = isPlainObject(namespaceGroup) ? namespaceGroup[entity.fieldName] : void 0;
+			resolved[entity.slug] = {
+				read: entity.read && flag(group, "read"),
+				write: canWrite(entity) && flag(group, "write"),
+				publish: publishFlag(entity, group)
+			};
+		}
+		return resolved;
+	};
+	const toolsGroup = groupOf("tools");
 	const tools = {};
 	for (const tool of options.tools) tools[tool.name] = flag(toolsGroup, tool.name);
 	return {
-		collections,
-		globals,
+		collections: resolveEntities(options.collections, groupOf("collections")),
+		globals: resolveEntities(options.globals, groupOf("globals")),
 		tools
 	};
 };
-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 publishableSlugs = (capabilities) => pick(capabilities.collections, "publish");
-const readableGlobalSlugs = (capabilities) => pick(capabilities.globals, "read");
-const writableGlobalSlugs = (capabilities) => pick(capabilities.globals, "write");
-const publishableGlobalSlugs = (capabilities) => pick(capabilities.globals, "publish");
+/**
+* The slugs tools use to narrow their enums. Taken from the output of
+* {@link resolveCapabilities}, so config and checkbox are already applied.
+*/ const scopeSlugs = (entries) => {
+	const slugsWith = (operation) => Object.entries(entries).filter(([, value]) => value[operation]).map(([slug]) => slug);
+	return {
+		readable: slugsWith("read"),
+		writable: slugsWith("write"),
+		publishable: slugsWith("publish")
+	};
+};
 //#endregion
-export { CAPABILITIES_FIELD, canCreate, canPublish, canWrite, isLiveWrite, publishableGlobalSlugs, publishableSlugs, readableGlobalSlugs, readableSlugs, resolveCapabilities, writableGlobalSlugs, writableSlugs };
+export { CAPABILITIES_FIELD, canCreate, canPublish, canWrite, isLiveWrite, resolveCapabilities, scopeSlugs };

package/dist/define-tool.d.mts

@@ -0,0 +1,19 @@
+import { McpxAnyTool, McpxTool, McpxToolScope } from "./types.mjs";
+import { z } from "zod";
+//#region src/define-tool.d.ts
+/** 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;
+//#endregion

package/dist/{types.mjs → define-tool.mjs}

@@ -1,4 +1,4 @@
-//#region src/types.ts
+//#region src/define-tool.ts
 function defineMcpxTool(tool) {
 	return tool;
 }

package/dist/endpoint/errors.mjs

@@ -1,5 +1,5 @@
 import { errorResult } from "../result.mjs";
-import { pointerFromPayloadPath } from "../schema/walk.mjs";
+import { pointerFromPayloadPath } from "../schema/path.mjs";
 import "../schema/index.mjs";
 import { APIError, ValidationError } from "payload";
 //#region src/endpoint/errors.ts
@@ -22,11 +22,10 @@ import { APIError, ValidationError } from "payload";
 	});
 };
 /**
-* Payload's public errors keep their message and status; a `ValidationError`
-* also surfaces its per-field detail, with each field's path restated as a
-* JSON Pointer so it reads like every other path this plugin reports. Anything
-* else is logged and reported as an internal error so no stack or driver
-* message leaks to the client.
+* Payload's public errors keep their message and status. A `ValidationError`
+* also surfaces its per-field detail, with each path as a JSON Pointer like
+* every other path this plugin reports. Anything else is logged and reported as
+* an internal error, so no stack or driver message reaches the client.
 */ const toToolError = (error, logger) => {
 	if (error instanceof ValidationError) return errorResult(error.message, {
 		status: error.status,

package/dist/endpoint/handler.mjs

@@ -1,22 +1,38 @@
-import { publishableGlobalSlugs, publishableSlugs, readableGlobalSlugs, readableSlugs, resolveCapabilities, writableGlobalSlugs, writableSlugs } from "../capabilities.mjs";
+import { resolveCapabilities, scopeSlugs } from "../capabilities.mjs";
+import { isValidAuthResult, resolveApiKeyAuth } from "../auth/resolve.mjs";
 import { jsonRpcError } from "./errors.mjs";
-import { resolveApiKeyAuth } from "../auth/resolve.mjs";
 import { createMcpServer } from "./server.mjs";
 import { WebStandardStreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/webStandardStreamableHttp.js";
 //#region src/endpoint/handler.ts
-const buildScope = (req, options, capabilities) => {
+const BODY_BYTES_LIMIT = 4194304;
+const BATCH_MESSAGES_LIMIT = 10;
+const readBody = async (req) => {
+	if (Number(req.headers.get("content-length")) > BODY_BYTES_LIMIT) return null;
+	if (!req.body) return;
+	const decoder = new TextDecoder();
+	let text = "";
+	let size = 0;
+	for await (const chunk of req.body) {
+		size += chunk.byteLength;
+		if (size > BODY_BYTES_LIMIT) return null;
+		text += decoder.decode(chunk, { stream: true });
+	}
+	return text + decoder.decode();
+};
+/**
+* The scope the tools of one request see: the key's resolved capabilities, the
+* slugs they reach, and the locales and limits of the config.
+*/ const buildScope = (req, options, capabilities) => {
 	const { localization } = req.payload.config;
 	return {
 		req,
 		capabilities,
-		readable: readableSlugs(capabilities),
-		writable: writableSlugs(capabilities),
-		publishable: publishableSlugs(capabilities),
-		readableGlobals: readableGlobalSlugs(capabilities),
-		writableGlobals: writableGlobalSlugs(capabilities),
-		publishableGlobals: publishableGlobalSlugs(capabilities),
-		locales: localization ? localization.localeCodes : null,
-		defaultLocale: localization ? localization.defaultLocale : null,
+		collections: scopeSlugs(capabilities.collections),
+		globals: scopeSlugs(capabilities.globals),
+		localization: localization ? {
+			locales: localization.localeCodes,
+			defaultLocale: localization.defaultLocale
+		} : null,
 		limits: options.limits,
 		exposure: {
 			collections: options.collections,
@@ -44,12 +60,15 @@ const buildScope = (req, options, capabilities) => {
 		req,
 		resolveDefault
 	}) : await resolveDefault();
-	if (!auth) return jsonRpcError({
-		status: 401,
-		code: -32001,
-		message: "Unauthorized: a valid API key is required.",
-		headers: { "www-authenticate": "Bearer" }
-	});
+	if (!isValidAuthResult(auth, options)) {
+		if (auth) req.payload.logger.error("[payloadcms-mcpx] auth.resolve returned an invalid result: it needs a user of the user collection with an id, and an apiKeyId.");
+		return jsonRpcError({
+			status: 401,
+			code: -32001,
+			message: "Unauthorized: a valid API key is required.",
+			headers: { "www-authenticate": "Bearer" }
+		});
+	}
 	const capabilities = resolveCapabilities(options, auth.capabilities);
 	req.user = auth.user;
 	req.context = {
@@ -61,7 +80,13 @@ const buildScope = (req, options, capabilities) => {
 	};
 	let parsedBody;
 	try {
-		parsedBody = await req.json?.();
+		const text = await readBody(req);
+		if (text === null) return jsonRpcError({
+			status: 413,
+			code: -32e3,
+			message: `Request body too large: the limit is ${String(BODY_BYTES_LIMIT / 1024 / 1024)} MB.`
+		});
+		parsedBody = text === void 0 ? void 0 : JSON.parse(text);
 	} catch {
 		return jsonRpcError({
 			status: 400,
@@ -74,6 +99,11 @@ const buildScope = (req, options, capabilities) => {
 		code: -32600,
 		message: "Invalid request: a JSON body is required."
 	});
+	if (Array.isArray(parsedBody) && parsedBody.length > BATCH_MESSAGES_LIMIT) return jsonRpcError({
+		status: 400,
+		code: -32600,
+		message: `Invalid request: a batch may hold at most ${String(BATCH_MESSAGES_LIMIT)} messages.`
+	});
 	const server = createMcpServer(buildScope(req, options, capabilities), options);
 	const transport = new WebStandardStreamableHTTPServerTransport({ enableJsonResponse: true });
 	await server.connect(transport);
@@ -89,4 +119,4 @@ const buildScope = (req, options, capabilities) => {
 	}
 };
 //#endregion
-export { createMcpxHandler, methodNotAllowed };
+export { buildScope, createMcpxHandler, methodNotAllowed };

package/dist/endpoint/server.mjs

@@ -1,44 +1,90 @@
 import { toToolError } from "./errors.mjs";
-import { draftSentence } from "../tools/shared.mjs";
+import { liveWriteSlugs } from "../tools/shared.mjs";
 import { BUILTIN_TOOLS } from "../tools/builtin.mjs";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { z } from "zod";
 //#region src/endpoint/server.ts
-/** Strict, so an unknown argument is rejected by name rather than stripped. */ const toolInputSchema = (tool, scope) => z.strictObject(typeof tool.inputSchema === "function" ? tool.inputSchema(scope) : tool.inputSchema ?? {});
-/** May be built from the scope, to name the targets this key writes live. */ const toolDescription = (tool, scope) => typeof tool.description === "function" ? tool.description(scope) : tool.description;
+/** Strict, so an unknown argument is rejected by name instead of stripped. */ const toolInputSchema = (tool, scope) => z.strictObject(typeof tool.inputSchema === "function" ? tool.inputSchema(scope) : tool.inputSchema ?? {});
+const toolDescription = (tool, scope) => typeof tool.description === "function" ? tool.description(scope) : tool.description;
 /** A tool that does not decide for itself is gated by its own checkbox. */ const isToolEnabled = (tool, scope) => tool.isEnabled ? tool.isEnabled(scope) : scope.capabilities.tools[tool.name] === true;
+const WORKFLOW = [
+	{
+		tools: ["listCapabilities"],
+		does: "what this key may access"
+	},
+	{
+		tools: ["describeSchema"],
+		does: "the fields"
+	},
+	{
+		tools: ["findDocuments", "getDocument"],
+		does: "the content and its \"updatedAt\""
+	},
+	{
+		tools: ["patchDocument", "createDocument"],
+		does: "the write"
+	},
+	{
+		tools: ["validateDocument"],
+		does: "what blocks publishing"
+	},
+	{
+		tools: ["publishDocument"],
+		does: "make the draft public"
+	}
+];
+const PATHS = `describeSchema takes and returns schema paths. Every other "path", and "from" in a patch operation, is a pointer into a document, with a 0-based index where a schema path has "*" for an array element or a block slug: "/layout/sections/sectionWrapper/identifier" is "/layout/sections/0/identifier". In rich text a pointer enters the rich text state: "/content/block/callout/tone" is "/content/root/children/3/fields/tone". getDocument "outline" gives the index.`;
+const DRAFTS = "Writes are saved as drafts, except in collections and globals without drafts, which patchDocument names: those go live immediately.";
+const DRAFTS_ONLY = "Every write is saved as a draft.";
+/** The workflow for the tools this key has, and what its writes reach. */ const serverInstructions = (scope) => {
+	const enabled = new Set(BUILTIN_TOOLS.filter((tool) => isToolEnabled(tool, scope)).map((tool) => tool.name));
+	const steps = WORKFLOW.flatMap(({ tools, does }) => {
+		const present = tools.filter((name) => enabled.has(name));
+		return present.length === 0 ? [] : [`${present.join(" or ")}: ${does}.`];
+	}).map((step, index) => `${String(index + 1)}. ${step}`);
+	const publishing = enabled.has("publishDocument") ? "" : " This key cannot publish. A person publishes drafts in the admin panel.";
+	const drafts = liveWriteSlugs(scope, "write").length === 0 ? DRAFTS_ONLY : DRAFTS;
+	const writes = enabled.has("patchDocument") ? `\n\n${drafts}${publishing}` : "";
+	const paths = enabled.has("describeSchema") ? `\n\n${PATHS}` : "";
+	return `Call the tools in this order:\n${steps.join("\n")}${paths}${writes}`;
+};
 /**
 * One server per request. Builtin and configured tools take the same route,
 * each registered against the key's capabilities, so `tools/list` shows exactly
-* what the key may call.
+* what the key may call. The tool handlers of one JSON-RPC batch run one at a time,
+* so a failed call cannot roll back a write another call reported as done.
 */ const createMcpServer = (scope, options) => {
 	const { req } = scope;
 	const { logger } = req.payload;
+	let queue = Promise.resolve();
 	const server = new McpServer({
 		name: options.serverInfo.name,
 		version: options.serverInfo.version
-	}, { instructions: `Start with listCapabilities, then describeSchema for the collection or global you work on. ${draftSentence(scope)}` });
-	const guarded = (run) => async () => {
-		try {
-			return await run();
-		} catch (error) {
-			return toToolError(error, logger);
-		}
-	};
+	}, { instructions: serverInstructions(scope) });
 	for (const tool of [...BUILTIN_TOOLS, ...options.tools]) {
 		if (!isToolEnabled(tool, scope)) continue;
 		server.registerTool(tool.name, {
 			description: toolDescription(tool, scope),
 			inputSchema: toolInputSchema(tool, scope),
 			...tool.annotations ? { annotations: tool.annotations } : {}
-		}, (args, extra) => guarded(() => tool.handler({
-			args,
-			scope,
-			req,
-			extra
-		}))());
+		}, (args, extra) => {
+			const result = queue.then(async () => {
+				try {
+					return await tool.handler({
+						args,
+						scope,
+						req,
+						extra
+					});
+				} catch (error) {
+					return toToolError(error, logger);
+				}
+			});
+			queue = result.catch(() => void 0);
+			return result;
+		});
 	}
 	return server;
 };
 //#endregion
-export { createMcpServer, isToolEnabled, toolDescription, toolInputSchema };
+export { createMcpServer, isToolEnabled, toolInputSchema };

package/dist/entity.d.mts

@@ -0,0 +1,9 @@
+import "payload";
+//#region src/entity.d.ts
+/**
+ * The id type follows the database adapter and a collection's own `id` field,
+ * so one project can have both. Payload's `DefaultDocumentIDType` narrows to
+ * the project default, so it cannot be used here.
+ */
+export type DocumentId = number | string;
+//#endregion

package/dist/guards.mjs

@@ -0,0 +1,5 @@
+//#region src/guards.ts
+const isPlainObject = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+/** An own property only, so a client-chosen key never reads the prototype. */ const ownValue = (record, key) => record !== void 0 && Object.hasOwn(record, key) ? record[key] : void 0;
+//#endregion
+export { isPlainObject, ownValue };

package/dist/i18n.mjs

@@ -1,27 +1,27 @@
 //#region src/i18n.ts
 const stringRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value) && Object.values(value).every((entry) => typeof entry === "string") ? value : void 0;
-/** Treats an empty value as absent, so the fallback chain continues. */ const pick = (record, language) => {
+const pick = (record, language) => {
 	for (const code of Array.isArray(language) ? language : [language]) {
 		const entry = record[code];
 		if (entry !== void 0 && entry.trim() !== "") return entry;
 	}
 };
 /**
-* Resolves a static label or `admin.description` to the one string a client
-* can use: the request's language, then the fallback language configured for
-* the deployment, then whichever entry the record declares first.
+* Resolves a static label or `admin.description` to one string: the request's
+* language, then the configured fallback language, then the first entry the
+* record declares.
 *
 * Anything that is not a string or a string-valued record is dropped. A
-* description written as a function or a React component is an admin-UI
-* construct that may reach client-only i18n, so it is never invoked here.
+* function or React component description may reach client-only i18n, so it is
+* never invoked.
 */ const translateStatic = (value, language) => {
 	if (typeof value === "string") return value.trim() === "" ? void 0 : value;
 	const record = stringRecord(value);
 	if (!record) return;
 	return pick(record, language.language) ?? pick(record, language.fallbackLanguage) ?? Object.values(record).find((entry) => entry.trim() !== "");
 };
-/** Bound to one request's language, so a walk carries no request of its own. */ const translatorFor = (i18n) => (value) => translateStatic(value, i18n);
-/** For callers with no request: both keys miss, so the first entry wins. */ const translateAny = translatorFor({
+const translatorFor = (i18n) => (value) => translateStatic(value, i18n);
+/** For callers with no request. Both languages miss, so the first entry wins. */ const translateAny = translatorFor({
 	fallbackLanguage: "",
 	language: ""
 });

package/dist/index.d.mts

@@ -1,5 +1,8 @@
-import { McpxAnyTool, McpxAuthResult, McpxCollectionCapabilities, McpxCollectionOptions, McpxExposedEntity, McpxGlobalOptions, McpxPluginOptions, McpxRequestContext, McpxResolvedCapabilities, McpxTool, McpxToolExtra, McpxToolScope, McpxWriteMode, PublishBlocker, defineMcpxTool } from "./types.mjs";
+import { DocumentId } from "./entity.mjs";
+import { McpxAnyTool, McpxAuthResult, McpxCollectionCapabilities, McpxCollectionOptions, McpxExposedEntity, McpxGlobalOptions, McpxPluginOptions, McpxRequestContext, McpxResolvedCapabilities, McpxScopeSlugs, McpxTool, McpxToolExtra, McpxToolScope, McpxWriteMode } from "./types.mjs";
+import { defineMcpxTool } from "./define-tool.mjs";
 import { mcpxPlugin } from "./plugin.mjs";
 import { isMcpxRequest } from "./request.mjs";
 import { errorResult, jsonResult } from "./result.mjs";
-export { McpxAnyTool, McpxAuthResult, McpxCollectionCapabilities, McpxCollectionOptions, McpxExposedEntity, McpxGlobalOptions, McpxPluginOptions, McpxRequestContext, McpxResolvedCapabilities, McpxTool, McpxToolExtra, McpxToolScope, McpxWriteMode, PublishBlocker, defineMcpxTool, errorResult, isMcpxRequest, jsonResult, mcpxPlugin };
+import { mcpxReadRequest } from "./tools/read-request.mjs";
+export { type McpxAnyTool, type McpxAuthResult, type McpxCollectionCapabilities, type McpxCollectionOptions, type DocumentId as McpxDocumentId, type McpxExposedEntity, type McpxGlobalOptions, type McpxPluginOptions, type McpxRequestContext, type McpxResolvedCapabilities, type McpxScopeSlugs, type McpxTool, type McpxToolExtra, type McpxToolScope, type McpxWriteMode, defineMcpxTool, errorResult, isMcpxRequest, jsonResult, mcpxPlugin, mcpxReadRequest };

package/dist/index.mjs

@@ -1,5 +1,6 @@
+import { defineMcpxTool } from "./define-tool.mjs";
 import { errorResult, jsonResult } from "./result.mjs";
-import { defineMcpxTool } from "./types.mjs";
+import { mcpxReadRequest } from "./tools/read-request.mjs";
 import { isMcpxRequest } from "./request.mjs";
 import { mcpxPlugin } from "./plugin.mjs";
-export { defineMcpxTool, errorResult, isMcpxRequest, jsonResult, mcpxPlugin };
+export { defineMcpxTool, errorResult, isMcpxRequest, jsonResult, mcpxPlugin, mcpxReadRequest };