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

package/dist/api-keys/collection.mjs

@@ -5,7 +5,8 @@ import { generateApiKey, hashApiKey } from "./key.mjs";
 * Generates the key on create and keeps the lookup index in step with it.
 * Runs after field `beforeValidate` fallbacks, so on update `data.apiKey` is the
 * decrypted plaintext of the stored key.
-*/ const keyBeforeChange = ({ data, operation, req }) => {
+*/ const keyBeforeChange = ({ context, data, operation, req }) => {
+	if (context["mcpxTouch"]) return data;
 	if (operation === "create" && typeof data["apiKey"] !== "string") data["apiKey"] = generateApiKey();
 	if (typeof data["apiKey"] === "string") data["apiKeyIndex"] = hashApiKey(req.payload.secret, data["apiKey"]);
 	return data;

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
@@ -34,6 +34,27 @@ const checkbox = (name, description) => ({
 		defaultValue: true,
 		admin: { description: "Disabled keys are refused without revoking them." }
 	},
+	{
+		name: "expiresAt",
+		type: "date",
+		admin: {
+			date: { pickerAppearance: "dayAndTime" },
+			description: "Refused from this time on. Leave empty for no expiry."
+		}
+	},
+	{
+		name: "lastUsedAt",
+		type: "date",
+		access: {
+			create: () => false,
+			update: () => false
+		},
+		admin: {
+			readOnly: true,
+			date: { pickerAppearance: "dayAndTime" },
+			description: "Updated at most once an hour."
+		}
+	},
 	{
 		name: "apiKey",
 		type: "text",
@@ -58,13 +79,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 +100,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 +110,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.
-*
-* 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.
+* 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.
 *
-* 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 +153,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 +165,4 @@ const checkbox = (name, description) => ({
 	}];
 };
 //#endregion
-export { SETUP_GUIDE_FIELD, createCapabilityFields, createKeyFields, withSetupGuideTab };
+export { createCapabilityFields, createKeyFields, withSetupGuideTab };

package/dist/auth/resolve.mjs

@@ -1,6 +1,9 @@
+import { isPlainObject } from "../guards.mjs";
 import { hashApiKey } from "../api-keys/key.mjs";
 //#region src/auth/resolve.ts
 const BEARER = /^Bearer\s+(\S+)\s*$/i;
+const LAST_USED_INTERVAL_MS = 36e5;
+const toTime = (value) => typeof value === "string" || value instanceof Date ? new Date(value).getTime() : NaN;
 const relationId = (value) => {
 	if (typeof value === "string" || typeof value === "number") return value;
 	if (typeof value === "object" && value !== null && "id" in value) return value.id;
@@ -10,6 +13,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.
 *
@@ -30,22 +41,49 @@ const parseBearer = (headers) => {
 		select: {
 			enabled: true,
 			user: true,
-			capabilities: true
+			capabilities: true,
+			expiresAt: true,
+			lastUsedAt: true
 		}
 	});
 	const keyDoc = docs[0];
 	const userId = relationId(keyDoc?.user);
 	if (!keyDoc || keyDoc.enabled !== true || userId === void 0) return null;
+	if (toTime(keyDoc.expiresAt) <= Date.now()) 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 lockUntil = toTime(lock?.["lockUntil"]);
 	if (!user || user["_verified"] === false || lockUntil > Date.now()) return null;
+	const lastUsed = toTime(keyDoc.lastUsedAt);
+	if (Number.isNaN(lastUsed) || Date.now() - lastUsed > LAST_USED_INTERVAL_MS) try {
+		await payload.update({
+			collection: options.apiKeysSlug,
+			id: keyDoc.id,
+			data: { lastUsedAt: (/* @__PURE__ */ new Date()).toISOString() },
+			overrideAccess: true,
+			depth: 0,
+			context: { mcpxTouch: true }
+		});
+	} catch (error) {
+		payload.logger.warn({
+			err: error,
+			msg: "Could not record the last use of an MCP API key"
+		});
+	}
 	return {
 		user: {
 			...user,
@@ -57,4 +95,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 = [

package/dist/capabilities.mjs

@@ -1,62 +1,60 @@
+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;
+/**
+* Group field holding the capability checkboxes on an API key document.
+*/ const CAPABILITIES_FIELD = "capabilities";
+/**
+* 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,23 @@
+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,96 @@
 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;
-/** 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;
+/**
+* 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,7 @@
+//#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 };