@abinnovision/payloadcms-mcpx 1.0.0-beta.11 → 1.0.0-beta.13

package/dist/types.d.mts

@@ -1,7 +1,7 @@
 import { CollectionConfig, CollectionSlug, GlobalSlug, PayloadRequest, TypedUser } from "payload";
 import { z } from "zod";
-import { CallToolResult, ServerNotification, ServerRequest, ToolAnnotations } from "@modelcontextprotocol/sdk/types.js";
 import { RequestHandlerExtra } from "@modelcontextprotocol/sdk/shared/protocol.js";
+import { CallToolResult, ServerNotification, ServerRequest, ToolAnnotations } from "@modelcontextprotocol/sdk/types.js";
 //#region src/types.d.ts
 declare module "payload" {
   interface RequestContext {
@@ -11,6 +11,17 @@ declare module "payload" {
     "@abinnovision/payloadcms-mcpx": McpxPluginOptions;
   }
 }
+/**
+ * How far an exposed entity lets MCP writes reach.
+ *
+ * - `false`: no write tool touches it.
+ * - `"draft"`: writes land as drafts and nothing MCP does changes what the
+ *   public sees. Requires `versions.drafts`.
+ * - `"live"`: MCP may change live content. On an entity with drafts that means
+ *   `publishDocument` is exposed; on one without, where there is no draft to
+ *   land on, it means the write itself is permitted and lands live.
+ */
+type McpxWriteMode = "draft" | "live" | false;
 /**
  * What an exposed collection offers to MCP clients. A key can only enable
  * what the config exposes here.
@@ -21,15 +32,10 @@ interface McpxCollectionOptions {
    */
   read?: boolean;
   /**
-   * Expose `patchDocument`, `createDocument` and `validateDocument`. Default
-   * `false`. Requires `versions.drafts` unless `allowLiveWrites` is set.
+   * Expose `patchDocument`, `createDocument` and `validateDocument`, and how
+   * far those writes reach. Default `false`.
    */
-  write?: boolean;
-  /**
-   * Permit writes to a collection without drafts. Such writes land on the live
-   * document because there is no draft to land on. Default `false`.
-   */
-  allowLiveWrites?: boolean;
+  write?: McpxWriteMode;
 }
 /**
  * What an exposed global offers to MCP clients. Structurally the same as
@@ -41,15 +47,10 @@ interface McpxGlobalOptions {
   /** Expose `describeSchema` and `getDocument`. Default `true`. */
   read?: boolean;
   /**
-   * Expose `patchDocument` and `validateDocument`. Default `false`. Requires
-   * `versions.drafts` unless `allowLiveWrites` is set.
-   */
-  write?: boolean;
-  /**
-   * Permit writes to a global without drafts. Such writes land on the live
-   * document because there is no draft to land on. Default `false`.
+   * Expose `patchDocument` and `validateDocument`, and how far those writes
+   * reach. Default `false`.
    */
-  allowLiveWrites?: boolean;
+  write?: McpxWriteMode;
 }
 type McpxToolExtra = RequestHandlerExtra<ServerRequest, ServerNotification>;
 /**
@@ -59,8 +60,7 @@ type McpxToolExtra = RequestHandlerExtra<ServerRequest, ServerNotification>;
 interface McpxExposedEntity {
   slug: string;
   read: boolean;
-  write: boolean;
-  allowLiveWrites: boolean;
+  write: McpxWriteMode;
   hasDrafts: boolean;
   /** Name of the capability group on the key document. */
   fieldName: string;
@@ -72,12 +72,14 @@ interface McpxExposedEntity {
 interface McpxToolScope {
   req: PayloadRequest;
   capabilities: McpxResolvedCapabilities;
-  /** Collection slugs the key may read / write. */
+  /** Collection slugs the key may read / write / publish. */
   readable: string[];
   writable: string[];
-  /** Global slugs the key may read / write. */
+  publishable: string[];
+  /** Global slugs the key may read / write / publish. */
   readableGlobals: string[];
   writableGlobals: string[];
+  publishableGlobals: string[];
   /** Configured locale codes, or `null` when localization is off. */
   locales: null | string[];
   defaultLocale: null | string;
@@ -103,7 +105,11 @@ interface McpxToolScope {
 interface McpxTool<Shape extends z.ZodRawShape = z.ZodRawShape, Args = z.infer<z.ZodObject<Shape>>> {
   /** camelCase, unique, not one of the builtin tool names. */
   name: string;
-  description: string;
+  /**
+   * Fixed text, or text built per request so it can state what this key's
+   * writes actually do.
+   */
+  description: string | ((scope: McpxToolScope) => string);
   annotations?: ToolAnnotations;
   /**
    * Whether this key may call the tool; a tool that is not enabled never
@@ -210,6 +216,11 @@ type McpxPluginOptions = {
 interface McpxCollectionCapabilities {
   read: boolean;
   write: boolean;
+  /**
+   * Whether the key may publish this entity's draft. Only ever true where the
+   * config sets `write: "live"` and the entity has drafts.
+   */
+  publish: boolean;
 }
 /**
  * Capabilities in force for one request: plugin config AND key checkboxes.
@@ -223,5 +234,15 @@ interface McpxRequestContext {
   apiKeyId: number | string;
   capabilities: McpxResolvedCapabilities;
 }
+/**
+ * One reason a human could not publish the draft as it stands.
+ */
+interface PublishBlocker {
+  /** Resolved field label path, e.g. "Layout > Block 2 (Hero) > Title". */
+  field?: string;
+  message: string;
+  /** JSON Pointer to the offending value, e.g. "/layout/2/title". */
+  path: string;
+}
 //#endregion
-export { McpxAnyTool, McpxAuthResult, McpxCollectionCapabilities, McpxCollectionOptions, McpxExposedEntity, McpxGlobalOptions, McpxPluginOptions, McpxRequestContext, McpxResolvedCapabilities, McpxTool, McpxToolExtra, McpxToolScope, defineMcpxTool };
+export { McpxAnyTool, McpxAuthResult, McpxCollectionCapabilities, McpxCollectionOptions, McpxExposedEntity, McpxGlobalOptions, McpxPluginOptions, McpxRequestContext, McpxResolvedCapabilities, McpxTool, McpxToolExtra, McpxToolScope, McpxWriteMode, PublishBlocker, defineMcpxTool };

package/dist/write/draft-guard.mjs

@@ -1,9 +1,11 @@
+import { claimPublishIntent, isClaimedPublish } from "./publish-intent.mjs";
+import { isMcpxRequest } from "../request.mjs";
 import { APIError } from "payload";
 import { hasDraftsEnabled } from "payload/shared";
 //#region src/write/draft-guard.ts
 /**
 * Operation arguments that widen or redirect a write. Cleared on every MCP
-* create and update so a tool cannot smuggle them in.
+* create and update, publishes included, so a tool cannot smuggle them in.
 */ const STRIPPED_ARGS = /* @__PURE__ */ new Set([
 	"where",
 	"publishAllLocales",
@@ -14,80 +16,113 @@ import { hasDraftsEnabled } from "payload/shared";
 	"overwriteExistingFiles"
 ]);
 /**
-* Whether a request originated from the MCP endpoint. The endpoint stamps
-* `req.context.mcpx`, which travels into every local API call made with the
-* same `req`, including those made by custom tools.
-*/ const isMcpxRequest = (req) => req.context.mcpx !== void 0;
-/**
-* Forces every MCP write into a draft save.
+* Forces every MCP write into a draft save, unless it is the one write
+* `publishDocument` asked for.
 *
 * `draft` alone is not enough: Payload's update path only saves a draft when
 * `data._status !== "published"`, so `_status` is dropped and left to Payload.
 * This runs as `beforeOperation`, before Payload reads any of these arguments,
 * so it holds for every create and update on an MCP request, not only the
 * builtin tools. Deletes are not guarded in v1; custom tools that delete are
-* the integrator's responsibility.
-*/ const scrubWriteArgs = (args) => {
+* the integrator's responsibility. `restoreVersion` and `duplicate` are outside
+* the operation filter too — `restoreVersion` is caught by `refusePublish`
+* because it runs the collection's `beforeChange` hooks, and anything going
+* straight to `payload.db` bypasses all of this.
+*
+* On a claimed publish the argument scrubbing is unchanged — the whole
+* `STRIPPED_ARGS` list still goes, `deletedAt` still goes, autosave, locks and
+* trash are still forced off. Only `draft` and `_status` differ. Writing
+* `_status` here rather than in the tool keeps the tool honest: it asks to
+* publish, and this is the only thing that can grant it.
+*/ const scrubWriteArgs = (args, publishing) => {
 	const next = Object.fromEntries(Object.entries(args).filter(([key]) => !STRIPPED_ARGS.has(key)));
 	if (next["data"] && typeof next["data"] === "object") {
 		const { _status: _ignoredStatus, deletedAt: _ignoredDeletedAt, ...data } = next["data"];
-		next["data"] = data;
+		next["data"] = publishing ? {
+			...data,
+			_status: "published"
+		} : data;
 	}
-	next["draft"] = true;
+	next["draft"] = !publishing;
 	next["autosave"] = false;
 	next["overrideLock"] = false;
 	next["trash"] = false;
 	return next;
 };
 const forceDraftWrite = (hookArgs) => {
-	const { args, operation, req } = hookArgs;
+	const { args, collection, operation, req } = hookArgs;
 	if (!isMcpxRequest(req) || operation !== "create" && operation !== "update") return args;
-	return scrubWriteArgs(args);
+	const publishing = operation === "update" && claimPublishIntent({
+		kind: "collection",
+		slug: collection.slug,
+		id: args.id
+	});
+	return scrubWriteArgs(args, publishing);
 };
 /**
-* The global counterpart of {@link forceDraftWrite}. Payload invokes a global's
-* `beforeOperation` with the whole argument bag and assigns the result back,
-* exactly as the collection path does and before it reads `draft`,
-* `publishAllLocales` or `data._status`, so the guard has the same reach here:
-* every MCP write to a global, builtin tool or custom.
+* The global counterpart of {@link forceDraftWrite}, with one important
+* difference: Payload's `updateGlobal` destructures `draft`,
+* `publishAllLocales`, `publishSpecificLocale`, `unpublishAllLocales` and
+* `overrideLock` *before* it runs `beforeOperation`, and re-reads only `data`
+* afterwards. Setting those here is a no-op. What still lands is `data`, and
+* that is what the global draft guarantee actually rests on: `_status` is
+* stripped, so a rogue `updateGlobal({ draft: false })` reaches
+* {@link refusePublishGlobal} with no status and is refused there. The alarm,
+* not the correction, is load-bearing for globals.
+*
+* The publish branch matters for the same reason. `publishDocument` passes
+* `draft: false` at the call site because the hook cannot, and this hook must
+* put `_status` back rather than strip it.
 *
 * The global operation union has no `create` member because a global always
-* exists, so only `update` is intercepted. `STRIPPED_ARGS` covers the three
-* publish vectors `updateGlobal` accepts; the rest of the set does not exist on
-* that signature and filtering it is a harmless no-op. `slug` survives the
-* filter, so the operation still knows what it is updating.
+* exists, so only `update` is intercepted.
 */ const forceDraftWriteGlobal = (hookArgs) => {
-	const { operation, req } = hookArgs;
+	const { global, operation, req } = hookArgs;
 	const args = hookArgs.args;
 	if (!isMcpxRequest(req) || operation !== "update") return args;
-	return scrubWriteArgs(args);
+	const publishing = claimPublishIntent({
+		kind: "global",
+		slug: global.slug
+	});
+	return scrubWriteArgs(args, publishing);
 };
 /**
-* Refuses an MCP write that would still not land as a draft. An alarm rather
-* than the guarantee: `forceDraftWrite` should make it unreachable. It throws
-* instead of correcting `_status` because Payload has already chosen the write
-* branch by the time a `beforeChange` hook runs.
-*/ const refuseUnlessDraft = (req, slug, data) => {
+* Refuses an MCP write that would still not land as a draft, and — on the one
+* operation that claimed a publish intent — refuses anything that would not
+* land as a publish. An alarm rather than the guarantee for collections, where
+* `forceDraftWrite` should make it unreachable; the guarantee itself for
+* globals, per {@link forceDraftWriteGlobal}. It throws instead of correcting
+* `_status` because Payload has already chosen the write branch by the time a
+* `beforeChange` hook runs.
+*/ const refuseUnlessExpected = (req, target, data) => {
 	if (!isMcpxRequest(req)) return;
 	const status = data._status;
-	if (status === "draft") return;
-	req.payload.logger.warn(`[payloadcms-mcpx] Refused a write to ${slug} that would not have been a draft (_status: ${String(status)}).`);
-	throw new APIError("MCP clients may only write drafts. This write was refused because it would not have been saved as one.", 403);
+	const publishing = isClaimedPublish(target.kind, target.slug);
+	const expected = publishing ? "published" : "draft";
+	if (status === expected) return;
+	req.payload.logger.warn(`[payloadcms-mcpx] Refused a write to ${target.slug} that would not have been a ${expected} (_status: ${String(status)}).`);
+	throw new APIError(publishing ? "This publish was refused because it would not have saved a published document." : "MCP clients may only write drafts. This write was refused because it would not have been saved as one. Use publishDocument to publish.", 403);
 };
 const refusePublish = ({ collection, data, req }) => {
-	refuseUnlessDraft(req, collection.slug, data);
+	refuseUnlessExpected(req, {
+		kind: "collection",
+		slug: collection.slug
+	}, data);
 	return data;
 };
 /** The global counterpart of {@link refusePublish}. */ const refusePublishGlobal = ({ data, global, req }) => {
 	const next = data;
-	refuseUnlessDraft(req, global.slug, next);
+	refuseUnlessExpected(req, {
+		kind: "global",
+		slug: global.slug
+	}, next);
 	return next;
 };
 /**
 * Attaches the draft guard to every collection: `forceDraftWrite` everywhere
 * (it is a no-op outside MCP requests) and `refusePublish` wherever drafts
 * exist. Applied to the built collection list so nothing can join later
-* without being covered.
+* without being covered. Both are appended last, so a user hook cannot win.
 */ const installDraftGuards = (collections) => collections.map((collection) => ({
 	...collection,
 	hooks: {
@@ -110,4 +145,4 @@ const refusePublish = ({ collection, data, req }) => {
 	}
 }));
 //#endregion
-export { forceDraftWrite, forceDraftWriteGlobal, installDraftGuards, installGlobalDraftGuards, isMcpxRequest, refusePublish, refusePublishGlobal };
+export { forceDraftWrite, forceDraftWriteGlobal, installDraftGuards, installGlobalDraftGuards, refusePublish, refusePublishGlobal };

package/dist/write/patch.mjs

@@ -1,24 +1,45 @@
-import { JSON_POINTER_PATTERN, RESERVED_FIELD_NAMES, blockOf, describeAddressableFields, findBlocksField, splitPath } from "../schema/walk.mjs";
-import { validateWriteValue } from "../schema/shape.mjs";
+import { JSON_POINTER_PATTERN, RESERVED_FIELD_NAMES, blockOf, describeAddressableFields, findBlocksField, joinPath, splitPath } from "../schema/walk.mjs";
 import { resolveDataPointer } from "../schema/pointer.mjs";
+import { validateWriteValue } from "../schema/shape.mjs";
+import "../schema/index.mjs";
 import { z } from "zod";
 import { Pointer, applyPatch } from "rfc6902";
 //#region src/write/patch.ts
+const POINTER = z.string().regex(JSON_POINTER_PATTERN);
 /**
-* One RFC 6902 operation as accepted by `patchDocument`.
-*/ const PATCH_OPERATION_SCHEMA = z.object({
-	from: z.string().regex(JSON_POINTER_PATTERN).optional(),
-	op: z.enum([
-		"add",
-		"copy",
-		"move",
-		"remove",
-		"replace",
-		"test"
-	]),
-	path: z.string().regex(JSON_POINTER_PATTERN),
-	value: z.unknown().optional()
-}).describe("An RFC 6902 operation.");
+* One RFC 6902 operation as accepted by `patchDocument`. Discriminated on `op`
+* so an operation carries only the members RFC 6902 defines for it.
+*/ const PATCH_OPERATION_SCHEMA = z.discriminatedUnion("op", [
+	z.strictObject({
+		op: z.literal("add"),
+		path: POINTER,
+		value: z.unknown()
+	}),
+	z.strictObject({
+		op: z.literal("remove"),
+		path: POINTER
+	}),
+	z.strictObject({
+		op: z.literal("replace"),
+		path: POINTER,
+		value: z.unknown()
+	}),
+	z.strictObject({
+		from: POINTER,
+		op: z.literal("move"),
+		path: POINTER
+	}),
+	z.strictObject({
+		from: POINTER,
+		op: z.literal("copy"),
+		path: POINTER
+	}),
+	z.strictObject({
+		op: z.literal("test"),
+		path: POINTER,
+		value: z.unknown()
+	})
+]).describe("An RFC 6902 operation.");
 /**
 * Whether a pointer touches a field Payload maintains.
 */ const isReservedPointer = (pointer) => pointer.split("/").slice(1).some((segment) => RESERVED_FIELD_NAMES.has(segment));
@@ -87,59 +108,112 @@ const isPlainObject = (value) => typeof value === "object" && value !== null &&
 	return next;
 };
 /**
-* Applies a patch to a deep copy of the document, so a failing operation
-* leaves the original untouched and nothing partial is ever written.
-*/ const applyPatchToCopy = (doc, patches) => {
-	const next = structuredClone(doc);
-	const prepared = patches.map((operation) => {
-		const cloned = "value" in operation ? {
-			...operation,
-			value: structuredClone(operation.value)
-		} : operation;
-		if (cloned.op === "replace" && !isElementPointer(cloned.path) && Pointer.fromJSON(cloned.path).get(next) === void 0) return {
-			...cloned,
-			op: "add"
-		};
-		return cloned;
-	});
-	const problems = applyPatch(next, prepared).flatMap((error, index) => error ? [`patches[${String(index)}]: ${error.message}`] : []);
-	if (problems.length > 0) return { problems };
-	reconcileRowIds(next, doc);
-	return { next };
+* The operation as it is applied: values are cloned so the written document
+* never shares references with the caller's operations, and a `replace` of a
+* field the target locale has no value for becomes an `add`, which is what
+* RFC 6902 requires when nothing is there to replace.
+*/ const prepare = (operation, doc) => {
+	const cloned = "value" in operation ? {
+		...operation,
+		value: structuredClone(operation.value)
+	} : operation;
+	return cloned.op === "replace" && !isElementPointer(cloned.path) && Pointer.fromJSON(cloned.path).get(doc) === void 0 ? {
+		...cloned,
+		op: "add"
+	} : cloned;
 };
 /**
-* Checks every operation against the schema before any is applied.
-*
-* A partially applied batch is worse than a refused one, so this returns all
-* problems and the caller applies nothing unless the list is empty.
-*/ const findPatchProblems = (config, target) => target.patches.flatMap((operation, index) => {
-	const at = `patches[${String(index)}]`;
-	const pointers = [operation.path, ..."from" in operation && operation.from ? [operation.from] : []];
-	if (pointers.includes("")) return [`${at}: an empty pointer addresses the whole document. Address a field instead.`];
+* The value an operation writes at its path: the one it carries, or the one it
+* takes from `from`. A `remove` writes nothing.
+*/ const effectiveValue = (operation, doc) => {
+	if ("value" in operation) return operation.value;
+	return "from" in operation ? Pointer.fromJSON(operation.from).get(doc) : void 0;
+};
+/**
+* Whether a resolved pointer lands in a read-only field. A pointer that stops
+* short of one addresses a subtree, and the fields beneath it decide.
+*/ const resolvesReadOnly = (resolution) => {
+	if (resolution.descriptor) return resolution.descriptor.readOnly === true;
+	const below = describeAddressableFields(resolution.fields).filter((descriptor) => resolution.prefix.every((part, offset) => part === splitPath(descriptor.path)[offset]));
+	return below.length > 0 && below.every((descriptor) => descriptor.readOnly);
+};
+/**
+* Whether the pointer addresses something read-only. An element carries no
+* descriptor of its own, so the field it belongs to is read one segment up.
+*/ const isReadOnlyPointer = (config, target) => resolvesReadOnly(resolveDataPointer(config, {
+	doc: target.doc,
+	pointer: isElementPointer(target.pointer) ? joinPath(splitPath(target.pointer).slice(0, -1)) : target.pointer,
+	ref: target.ref
+}));
+/**
+* Checks one operation against the schema, in the state the document is in
+* when that operation runs. Both pointers must resolve, whatever the operation
+* writes at its path must pass write validation, and what it drops must not sit
+* in a read-only field.
+*/ const findOperationProblems = (config, target) => {
+	const { doc, operation, ref } = target;
+	const pointers = [operation.path, ..."from" in operation ? [operation.from] : []];
+	if (pointers.includes("")) return ["an empty pointer addresses the whole document. Address a field instead."];
 	const reserved = pointers.find(isReservedPointer);
-	if (reserved !== void 0) return [`${at}: "${reserved}" addresses a field Payload maintains. Drafts are the only thing this tool writes, and id, _status, createdAt and updatedAt are not writable.`];
+	if (reserved !== void 0) return [`"${reserved}" addresses a field Payload maintains. This tool only ever writes drafts, and id, _status, createdAt and updatedAt are not writable; use publishDocument to publish.`];
 	const dropped = droppedPointer(operation);
-	if (dropped !== void 0 && !isElementPointer(dropped)) return [`${at}: "${dropped}" is a field, not a list element, and removing it would do nothing. The patched document is written whole, and Payload keeps any field absent from a write rather than clearing it. Use "replace" with null to clear a field, or with [] to empty a list.`];
-	const value = "value" in operation ? operation.value : void 0;
+	if (dropped !== void 0 && !isElementPointer(dropped)) return [`"${dropped}" is a field, not a list element, and removing it would do nothing. The patched document is written whole, and Payload keeps any field absent from a write rather than clearing it. Use "replace" with null to clear a field, or with [] to empty a list.`];
 	try {
-		const moved = "from" in operation && operation.from ? Pointer.fromJSON(operation.from).get(target.doc) : void 0;
+		const value = effectiveValue(operation, doc);
+		if (value !== void 0 && operation.op !== "test" && isReadOnlyPointer(config, {
+			doc,
+			pointer: operation.path,
+			ref
+		})) return [`"${operation.path}" is read-only and cannot be written.`];
+		if (dropped !== void 0 && isReadOnlyPointer(config, {
+			doc,
+			pointer: dropped,
+			ref
+		})) return [`"${dropped}" sits in a read-only field and cannot be removed.`];
 		for (const pointer of pointers) {
 			const resolution = resolveDataPointer(config, {
-				addedValue: value ?? moved,
-				doc: target.doc,
+				addedValue: value,
+				doc,
 				pointer,
-				ref: target.ref
+				ref
 			});
-			if (pointer === operation.path && value !== void 0) return validateWriteValue(config, {
-				pointer,
-				resolution
-			}, value).map((problem) => `${at}: ${problem}`);
+			if (pointer === operation.path && value !== void 0) {
+				const problems = validateWriteValue(config, {
+					pointer,
+					resolution
+				}, value);
+				if (problems.length > 0) return problems;
+			}
 		}
 		return [];
 	} catch (error) {
-		return [`${at}: ${error instanceof Error ? error.message : "invalid"}`];
+		return [error instanceof Error ? error.message : "invalid"];
+	}
+};
+/**
+* Validates and applies every operation against one evolving copy of the
+* document, so an operation that depends on an earlier one resolves against
+* the shape it actually modifies.
+*
+* The copy means a failing operation leaves the original untouched, and the
+* caller writes nothing unless the whole batch came back applied, so a
+* partially applied batch is never persisted.
+*/ const applyPatchOperations = (config, target) => {
+	const next = structuredClone(target.doc);
+	for (const [index, operation] of target.patches.entries()) {
+		const at = `patches[${String(index)}]`;
+		const problems = findOperationProblems(config, {
+			doc: next,
+			operation,
+			ref: target.ref
+		});
+		if (problems.length > 0) return { problems: problems.map((problem) => `${at}: ${problem}`) };
+		const [error] = applyPatch(next, [prepare(operation, next)]);
+		if (error) return { problems: [`${at}: ${error.message}`] };
 	}
-});
+	reconcileRowIds(next, target.doc);
+	return { next };
+};
 /**
 * Keys Payload manages on a row that travel back into the write unchanged.
 */ const ROW_KEYS = /* @__PURE__ */ new Set([
@@ -216,4 +290,4 @@ const isPlainObject = (value) => typeof value === "object" && value !== null &&
 	});
 };
 //#endregion
-export { PATCH_OPERATION_SCHEMA, applyPatchToCopy, buildWriteData, droppedPointer, findPatchProblems, isElementPointer, isReservedPointer, stripRowIds };
+export { PATCH_OPERATION_SCHEMA, applyPatchOperations, buildWriteData, droppedPointer, isElementPointer, isReservedPointer, stripRowIds };

package/dist/write/publish-blockers.mjs

@@ -1,4 +1,5 @@
 import { pointerFromPayloadPath } from "../schema/walk.mjs";
+import "../schema/index.mjs";
 import { beforeChangeTraverseFields, beforeValidateTraverseFields } from "payload";
 //#region src/write/publish-blockers.ts
 /**
@@ -18,6 +19,9 @@ import { beforeChangeTraverseFields, beforeValidateTraverseFields } from "payloa
 *
 * Limits: only the locale the doc was read in is checked, and field-level
 * `beforeChange` hooks run again, which is safe only for pure ones.
+*
+* `unavailable` marks a traversal that threw, which is not the same answer as
+* a document with nothing wrong with it.
 */ const collectPublishBlockers = async (req, target) => {
 	const { doc, entity } = target;
 	const id = doc["id"];
@@ -62,13 +66,16 @@ import { beforeChangeTraverseFields, beforeValidateTraverseFields } from "payloa
 		});
 	} catch (error) {
 		req.payload.logger.warn(`[payloadcms-mcpx] Could not validate the ${entity.slug} draft: ${error instanceof Error ? error.message : "unknown error"}`);
-		return [];
+		return {
+			blockers: [],
+			unavailable: true
+		};
 	}
-	return errors.map((error) => ({
+	return { blockers: errors.map((error) => ({
 		message: error.message,
 		path: pointerFromPayloadPath(error.path),
 		...typeof error.label === "string" ? { field: error.label } : {}
-	}));
+	})) };
 };
 //#endregion
 export { collectPublishBlockers };

package/dist/write/publish-intent.mjs

@@ -0,0 +1,39 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+//#region src/write/publish-intent.ts
+const store = new AsyncLocalStorage();
+/** Runs `fn` with `intent` in force. */ const withPublishIntent = async (intent, fn) => await store.run({
+	...intent,
+	claimed: false
+}, fn);
+const activeFor = (target) => {
+	const active = store.getStore();
+	return active && active.kind === target.kind && active.slug === target.slug && active.id === target.id ? active : void 0;
+};
+/**
+* Claims the intent for one operation, which `beforeOperation` does so that a
+* re-entrant write to the same document — an `afterChange` hook calling
+* `payload.update`, say — cannot ride along on it. Only the first operation to
+* ask gets it.
+*/ const claimPublishIntent = (target) => {
+	const active = activeFor(target);
+	if (!active || active.claimed) return false;
+	active.claimed = true;
+	return true;
+};
+/**
+* Whether this change belongs to the operation that claimed the intent, which
+* is what lets the `beforeChange` alarm accept a published status.
+*
+* The id is deliberately not compared here. A `beforeChange` hook reads it from
+* the loaded document, where Payload has already coerced it to the collection's
+* id type, while the claim above saw the raw tool argument; comparing the two
+* would refuse a legitimate publish over `1` versus `"1"`. Nothing is lost: a
+* nested write to another document of the same collection during the publish
+* cannot claim the intent, so `forceDraftWrite` has already stripped its
+* `_status` and it fails the alarm on that.
+*/ const isClaimedPublish = (kind, slug) => {
+	const active = store.getStore();
+	return active?.kind === kind && active.slug === slug && active.claimed;
+};
+//#endregion
+export { claimPublishIntent, isClaimedPublish, withPublishIntent };

package/dist/write/transaction.mjs

@@ -2,8 +2,14 @@ import { commitTransaction, initTransaction, killTransaction } from "payload";
 //#region src/write/transaction.ts
 /**
 * Runs `fn` inside one database transaction on `req`, so a read followed by a
-* write cannot interleave with another writer. Adapters without transaction
+* write is committed or rolled back together. Adapters without transaction
 * support, or a request that already owns one, run `fn` as is.
+*
+* Atomicity, not isolation: neither SQLite nor Postgres at read committed locks
+* the row on the read, so an `expectedUpdatedAt` check remains best effort. Nor
+* is this safe across the tool calls of one JSON-RPC batch, which share a
+* request: the second caller joins the first's transaction, so one tool's
+* rollback takes the other's work with it.
 */ const withTransaction = async (req, fn) => {
 	if (!await initTransaction(req)) return await fn();
 	try {

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "@abinnovision/payloadcms-mcpx",
-  "version": "1.0.0-beta.11",
+  "version": "1.0.0-beta.13",
   "description": "Payload CMS plugin exposing a fixed, schema-aware MCP tool surface with draft-only writes and per-API-key capabilities.",
   "keywords": [
     "payload",

package/dist/i18n.d.mts

@@ -1 +0,0 @@
-import { PayloadRequest } from "payload";

package/dist/schema/lexical.d.mts

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

package/dist/schema/walk.d.mts

@@ -1,3 +0,0 @@
-import "./lexical.mjs";
-import "../i18n.mjs";
-import "payload";

package/dist/tools/target.d.mts

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