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

package/dist/tools/get-document.mjs

@@ -6,7 +6,11 @@ import { requireIdFor, resolveTarget } from "./target.mjs";
 import { defineMcpxTool } from "../types.mjs";
 import { z } from "zod";
 import { Pointer } from "rfc6902";
-const getDocument = defineMcpxTool({
+/**
+* With `path` the handler returns the subtree plus the `id`, `_status` and
+* `updatedAt` a client needs to write back, so a caller reading one branch
+* still gets the timestamp `expectedUpdatedAt` wants without a second call.
+*/ const getDocument = defineMcpxTool({
 	name: "getDocument",
 	description: `Reads one document, or one subtree of it when "path" is given as a JSON pointer such as "/layout/sections/2". Returns the latest draft by default. Read before patching: the response carries "updatedAt" for expectedUpdatedAt and the indices pointers need.
 

package/dist/tools/list-capabilities.mjs

@@ -1,11 +1,18 @@
+import { canCreate } from "../capabilities.mjs";
 import { jsonResult } from "../result.mjs";
 import { translatorFor } from "../i18n.mjs";
 import { translateLabel } from "./shared.mjs";
 import { defineMcpxTool } from "../types.mjs";
 import { hasDraftValidationEnabled } from "payload/shared";
-const listCapabilities = defineMcpxTool({
+/**
+* Registered for every key, including one with no capabilities ticked, so a
+* client always has something to call and gets an empty surface described
+* rather than an empty tool list. The response is assembled from the request
+* scope and the sanitized config, never from the content model, so it stays the
+* same size as a deployment grows.
+*/ const listCapabilities = defineMcpxTool({
 	name: "listCapabilities",
-	description: `Lists what this key may do: the collections and globals it can read or write, their draft behaviour and id type, the configured locales, the limits in force and the custom tools available. Call it first to orient; nothing here changes with the content model.
+	description: `Lists what this key may do: the collections and globals it can read or write, whether a collection can also be created in, their draft behaviour and id type, the configured locales, the limits in force and the custom tools available. Call it first to orient; nothing here changes with the content model.
 
 A global is a singleton: it has no id, is not listed by findDocuments and cannot be created. Address one with the "global" argument where a collection document would take "collection" and "id".`,
 	annotations: {
@@ -32,6 +39,7 @@ A global is a singleton: it has no id, is not listed by findDocuments and cannot
 				...description === void 0 ? {} : { description },
 				read: capability.read,
 				write: capability.write,
+				create: capability.write && canCreate(entry),
 				publish: capability.publish,
 				drafts: entry.hasDrafts,
 				draftValidation: hasDraftValidationEnabled(config),

package/dist/tools/patch-document.mjs

@@ -42,7 +42,13 @@ const isPlainObject = (value) => typeof value === "object" && value !== null &&
 	const actual = pointer.get(saved);
 	return survives(expected, actual) ? [] : [operation.path];
 });
-const patchDocument = defineMcpxTool({
+/**
+* The handler validates the whole batch against the schema and the current
+* document before it writes anything, runs the write in a transaction, then
+* re-reads the saved document to report which pointers survived and what still
+* blocks publishing. Nothing here decides where the write lands: the draft
+* guard does that on the Payload operation.
+*/ const patchDocument = defineMcpxTool({
 	name: "patchDocument",
 	description: DESCRIPTION,
 	annotations: {

package/dist/tools/publish-document.mjs

@@ -5,7 +5,11 @@ import { defineMcpxTool } from "../types.mjs";
 import { withTransaction } from "../write/transaction.mjs";
 import { withPublishIntent } from "../write/publish-intent.mjs";
 import { z } from "zod";
-const publishDocument = defineMcpxTool({
+/**
+* The only tool that changes live content, available where the config sets
+* `write: "live"` on a versioned entity and the key has both the `write` and
+* `publish` checkboxes.
+*/ const publishDocument = defineMcpxTool({
 	name: "publishDocument",
 	description: `Publishes the current draft, which changes what the public sees. This is the only tool that does; every other write lands as a draft. Call validateDocument first: a document that still has publish blockers is refused, and nothing is written.
 
@@ -40,7 +44,7 @@ There is no unpublish: reverting to a draft stays a human action in the admin pa
 			});
 			if (args.expectedUpdatedAt !== void 0 && !sameInstant(doc["updatedAt"], args.expectedUpdatedAt)) return errorResult("The document changed since you read it. Read it again before publishing.", { updatedAt: doc["updatedAt"] });
 			const write = {
-				data: {},
+				data: withPublishIntent({}),
 				depth: 0,
 				draft: false,
 				fallbackLocale: false,
@@ -48,20 +52,14 @@ There is no unpublish: reverting to a draft stays a human action in the admin pa
 				req: scope.req,
 				...locale === void 0 ? {} : { locale }
 			};
-			await withPublishIntent({
-				kind: target.kind,
-				slug: target.slug,
+			if (target.kind === "collection") await payload.update({
+				...write,
+				collection: target.slug,
 				id
-			}, async () => {
-				if (target.kind === "collection") await payload.update({
-					...write,
-					collection: target.slug,
-					id
-				});
-				else await payload.updateGlobal({
-					...write,
-					slug: target.slug
-				});
+			});
+			else await payload.updateGlobal({
+				...write,
+				slug: target.slug
 			});
 			const saved = await readTarget(scope, {
 				target,

package/dist/tools/shared.mjs

@@ -1,10 +1,13 @@
-import { canPublish, isLiveWrite } from "../capabilities.mjs";
+import { canCreate, canPublish, isLiveWrite } from "../capabilities.mjs";
 import { translateStatic } from "../i18n.mjs";
 import { NotFound } from "payload";
 import { z } from "zod";
 //#region src/tools/shared.ts
-const slugEnum = (slugs) => z.enum(slugs);
-const idSchema = z.union([z.string(), z.number()]).describe("Document id.");
+/**
+* An out-of-scope slug fails schema validation before a handler runs, so a
+* client only ever sees what its key may touch.
+*/ const slugEnum = (slugs) => z.enum(slugs);
+/** Payload's id type follows the adapter, so both forms are handed on as read. */ const idSchema = z.union([z.string(), z.number()]).describe("Document id.");
 const slugsWhere = (scope, predicate, allowed) => {
 	const pick = (entities, slugs) => entities.filter((entity) => slugs.includes(entity.slug) && predicate(entity)).map((entity) => entity.slug);
 	return [...pick(scope.exposure.collections, allowed.collections), ...pick(scope.exposure.globals, allowed.globals)];
@@ -17,33 +20,38 @@ const slugsWhere = (scope, predicate, allowed) => {
 	collections: scope.writable,
 	globals: scope.writableGlobals
 });
+/**
+* Slugs this key may write but never create in, because their documents are
+* files. Collection-only, since nothing creates a global either way.
+*/ const patchOnlySlugs = (scope) => slugsWhere(scope, (entity) => !canCreate(entity), {
+	collections: scope.writable,
+	globals: []
+});
 /** Slugs this key may write and, separately, publish. */ const publishableWriteSlugs = (scope) => slugsWhere(scope, canPublish, {
 	collections: scope.publishable,
 	globals: scope.publishableGlobals
 });
 /**
-* The sentence the write tools and the server instructions end on: what a write
-* actually does for this key, and what it takes to make it public. The three
-* groups are distinct — a live-write slug has no draft and no publish step, a
-* publishable one has both — so a client is never told its writes are drafts
-* while they are not, nor that publishing is out of reach when it is not.
+* What a write actually does for this key, and what it takes to make it public.
+* A live-write slug has no draft and no publish step; a publishable one has
+* both. Stated per key so a client is never told its writes are drafts while
+* they are not, nor that publishing is out of reach when it is not.
 */ const draftSentence = (scope) => {
 	const live = liveWriteSlugs(scope);
 	const publishable = publishableWriteSlugs(scope);
 	return `${live.length === 0 ? "Every write lands as a draft." : `Writes land as drafts, except for ${live.join(", ")}, which have no drafts: a write there changes the live document immediately.`} ${publishable.length === 0 ? "Nothing this key writes is ever published; publishing stays a human action in the admin panel." : `Publish a draft with publishDocument, which this key may do for ${publishable.join(", ")}. Publishing anything else stays a human action in the admin panel.`}`;
 };
-/**
-* Whether two timestamps name the same instant, which is how
-* `expectedUpdatedAt` is compared: the value a client read back is a string,
-* and what it is compared against may be a Date.
-*/ const sameInstant = (left, right) => typeof left === "string" && new Date(left).getTime() === new Date(right).getTime();
-/**
-* Widens one branch to the superset a handler sees. The widening itself is
-* unchecked — the runtime shape really does vary — so `Branch` checks what it
-* can around it.
-*/ const widen = (branch) => branch;
-const slugsFor = (scope, operation) => {
+/** The value a client read back is a string; what it meets may be a Date. */ const sameInstant = (left, right) => typeof left === "string" && new Date(left).getTime() === new Date(right).getTime();
+/** Unchecked, because the runtime shape really does vary; `Branch` guards it. */ const widen = (branch) => branch;
+/** The one list the shape helpers and {@link resolveTarget} both read. */ const slugsFor = (scope, operation) => {
 	switch (operation) {
+		case "create": return {
+			collections: slugsWhere(scope, canCreate, {
+				collections: scope.writable,
+				globals: []
+			}),
+			globals: []
+		};
 		case "publish": return {
 			collections: scope.publishable,
 			globals: scope.publishableGlobals
@@ -59,13 +67,9 @@ const slugsFor = (scope, operation) => {
 	}
 };
 /**
-* The `collection` and `global` arguments.
-*
-* When the key can reach no global, `global` is left out of the shape entirely
-* and `collection` stays required, mirroring how {@link localeShape} omits
-* `locale` when localization is off. A deployment without globals therefore
-* sees exactly the schema it saw before. Only the mixed case makes either
-* argument optional, and the handler enforces the exclusivity there.
+* With no reachable global, `global` is left out and `collection` stays
+* required, so a deployment without globals sees an unchanged schema. Only the
+* mixed case makes either optional, and the handler enforces exclusivity there.
 */ const targetShape = (scope, operation, descriptions) => {
 	const { collections, globals } = slugsFor(scope, operation);
 	if (globals.length === 0) return widen({ collection: slugEnum(collections).describe(descriptions.collection) });
@@ -76,23 +80,23 @@ const slugsFor = (scope, operation) => {
 	});
 };
 /**
-* The `id` argument, which only a collection document has. Omitted when the key
-* can reach no collection, required when it can reach no global, and optional
-* in between, where `requireIdFor` enforces the dependency.
+* Only a collection document has one. Optional in the mixed case, where
+* `requireIdFor` enforces the dependency.
 */ const idShape = (scope, operation) => {
 	const { collections, globals } = slugsFor(scope, operation);
 	if (collections.length === 0) return widen({});
 	if (globals.length === 0) return widen({ id: idSchema });
 	return widen({ id: idSchema.optional().describe("Document id. Required with \"collection\"; must be omitted with \"global\".") });
 };
-/**
-* The `locale` argument, present only when localization is configured.
-*/ const localeShape = (scope, options) => {
+const localeShape = (scope, options) => {
 	if (!scope.locales) return widen({});
 	const locale = z.enum(scope.locales);
 	return widen({ locale: (options.required ? locale : locale.optional()).describe(options.description) });
 };
-const depthShape = (scope) => ({ depth: z.number().int().min(0).max(scope.limits.maxDepth).optional().describe(`Relationship population depth. Default 0, at most ${String(scope.limits.maxDepth)}.`) });
+/**
+* Defaults to 0 rather than Payload's own default: a client usually wants ids
+* it can write back, and populating a relation costs a query.
+*/ const depthShape = (scope) => ({ depth: z.number().int().min(0).max(scope.limits.maxDepth).optional().describe(`Relationship population depth. Default 0, at most ${String(scope.limits.maxDepth)}.`) });
 /**
 * The locale to operate on: the explicit argument, else the request's, else
 * the default. `undefined` when localization is off.
@@ -133,9 +137,7 @@ const depthShape = (scope) => ({ depth: z.number().int().min(0).max(scope.limits
 		slug: args.target.slug
 	});
 };
-/**
-* Resolves a collection label for the request's language.
-*/ const translateLabel = (scope, label, fallback) => {
+const translateLabel = (scope, label, fallback) => {
 	const { i18n, t } = scope.req;
 	const resolved = typeof label === "function" ? label({
 		i18n,
@@ -144,4 +146,4 @@ const depthShape = (scope) => ({ depth: z.number().int().min(0).max(scope.limits
 	return translateStatic(resolved, i18n) ?? fallback;
 };
 //#endregion
-export { depthShape, draftSentence, idSchema, idShape, localeOf, localeShape, readTarget, sameInstant, slugEnum, slugsFor, targetShape, translateLabel };
+export { depthShape, draftSentence, idSchema, idShape, localeOf, localeShape, patchOnlySlugs, readTarget, sameInstant, slugEnum, slugsFor, targetShape, translateLabel };

package/dist/tools/target.mjs

@@ -6,13 +6,9 @@ const refOf = (target) => ({
 	slug: target.slug
 });
 /**
-* Resolves the `collection`/`global` arguments to one entity and checks the key
-* may perform `operation` on it.
-*
-* A tool's `inputSchema` returns a raw shape, which leaves no top-level
-* `.refine` to express "exactly one of collection and global". The rule is
-* enforced here instead, with a message naming the offending arguments so one
-* failed call teaches it.
+* A raw input shape leaves no top-level `.refine` to express "exactly one of
+* collection and global", so the rule is enforced here, with a message naming
+* the offending arguments.
 */ const resolveTarget = (scope, args, operation) => {
 	const { collection, global } = args;
 	const allowedSlugs = slugsFor(scope, operation);

package/dist/tools/validate-document.mjs

@@ -3,7 +3,15 @@ import { idShape, localeOf, localeShape, readTarget, targetShape } from "./share
 import { requireIdFor, resolveTarget } from "./target.mjs";
 import { defineMcpxTool } from "../types.mjs";
 import { collectPublishBlockers } from "../write/publish-blockers.mjs";
-const validateDocument = defineMcpxTool({
+/**
+* Gated on write rather than read, because publish blockers only mean
+* something to a caller who can act on them.
+*
+* It reads the document twice on purpose: once under the key's own access to
+* refuse a caller who may not see it, then privileged, so the check runs over
+* every field rather than the subset the user can read. It carries no
+* `readOnlyHint`, because the traversal fires field hooks.
+*/ const validateDocument = defineMcpxTool({
 	name: "validateDocument",
 	description: `Reports what still prevents a human from publishing the draft, without writing anything. The same list patchDocument returns after a write; use it to check work or to answer "is this ready".
 

package/dist/types.d.mts

@@ -22,27 +22,18 @@ declare module "payload" {
  *   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.
- */
+/** A key can only enable what the config exposes here. */
 interface McpxCollectionOptions {
-  /**
-   * Expose `describeSchema`, `findDocuments` and `getDocument`. Default `true`.
-   */
+  /** Expose `describeSchema`, `findDocuments`, `getDocument`. Default `true`. */
   read?: boolean;
   /**
-   * Expose `patchDocument`, `createDocument` and `validateDocument`, and how
-   * far those writes reach. Default `false`.
+   * Expose `patchDocument`, `validateDocument` and, unless this is an upload
+   * collection, `createDocument`, and how far those writes reach. Default
+   * `false`.
    */
   write?: McpxWriteMode;
 }
-/**
- * What an exposed global offers to MCP clients. Structurally the same as
- * {@link McpxCollectionOptions}, kept separate because the tools it names
- * differ: a global is a singleton, so neither `findDocuments` nor
- * `createDocument` reaches one.
- */
+/** A singleton, so neither `findDocuments` nor `createDocument` reaches one. */
 interface McpxGlobalOptions {
   /** Expose `describeSchema` and `getDocument`. Default `true`. */
   read?: boolean;
@@ -53,77 +44,60 @@ interface McpxGlobalOptions {
   write?: McpxWriteMode;
 }
 type McpxToolExtra = RequestHandlerExtra<ServerRequest, ServerNotification>;
-/**
- * A collection or global the plugin config exposes, before an API key's
- * checkboxes narrow it further.
- */
+/** What the config exposes, before an API key's checkboxes narrow it. */
 interface McpxExposedEntity {
   slug: string;
   read: boolean;
   write: McpxWriteMode;
   hasDrafts: boolean;
+  /** An upload document is a file, and no tool here can supply one. */
+  isUpload: boolean;
   /** Name of the capability group on the key document. */
   fieldName: string;
 }
-/**
- * Everything a tool knows about the current request: the authenticated
- * request, what this key may touch and the limits in force.
- */
+/** What a tool knows about the current request. */
 interface McpxToolScope {
   req: PayloadRequest;
   capabilities: McpxResolvedCapabilities;
-  /** Collection slugs the key may read / write / publish. */
   readable: string[];
   writable: string[];
   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. */
+  /** `null` when localization is off. */
   locales: null | string[];
   defaultLocale: null | string;
   limits: {
     maxLimit: number;
     maxDepth: number;
   };
-  /** What the plugin config exposes, before the key's checkboxes apply. */
   exposure: {
     collections: McpxExposedEntity[];
     globals: McpxExposedEntity[];
   };
 }
 /**
- * A tool. The builtins and any tool passed through `options.tools` use this
- * same shape and register through the same loop. Every tool runs with
- * `req.user` resolved from the key and `req.context.mcpx` set.
- *
- * `Args` only needs stating when `inputSchema` is built per request, which
- * leaves no static shape to infer from; a tool with a fixed shape gets its
- * argument type from that shape.
+ * A tool, builtin or custom. Runs with `req.user` resolved from the key and
+ * `req.context.mcpx` set. `Args` only needs stating when `inputSchema` is built
+ * per request, leaving no static shape to infer from.
  */
 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;
-  /**
-   * Fixed text, or text built per request so it can state what this key's
-   * writes actually do.
-   */
+  /** 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
-   * appears in `tools/list`. Defaults to the tool's own checkbox on the API
-   * key, which the builtins replace to derive availability from the key's
-   * collection and global capabilities. Defining it replaces that checkbox
-   * check rather than adding to it.
+   * A tool that is not enabled never appears in `tools/list`. Defaults to the
+   * tool's own checkbox on the API key; defining it replaces that check rather
+   * than adding to it.
    */
   isEnabled?: (scope: McpxToolScope) => boolean;
   /**
-   * A fixed shape, or one built per request so enums can be narrowed to what
-   * the key may touch. Registered strictly either way: an unknown argument is
-   * rejected by name instead of being stripped and the tool answering as if
-   * it had not been passed.
+   * Built per request so enums can be narrowed to what the key may touch.
+   * Registered strictly either way: an unknown argument is rejected by name
+   * rather than stripped.
    */
   inputSchema?: Shape | ((scope: McpxToolScope) => z.ZodRawShape);
   handler(ctx: {
@@ -134,44 +108,36 @@ interface McpxTool<Shape extends z.ZodRawShape = z.ZodRawShape, Args = z.infer<z
     extra: McpxToolExtra;
   }): CallToolResult | Promise<CallToolResult>;
 }
-/**
- * A tool with its argument type erased, which is how a registry holds tools of
- * differing input shapes. Each tool validates its own arguments through its
- * input schema.
- */
+/** Argument type erased, so a registry can hold tools of differing shapes. */
 type McpxAnyTool = McpxTool<z.ZodRawShape, never>;
-/**
- * Defines a tool with a fixed input shape. The handler's arguments are
- * inferred from that shape.
- */
+/** Fixed shape; arguments inferred from it. */
 declare function defineMcpxTool<Shape extends z.ZodRawShape>(tool: McpxTool<Shape> & {
   inputSchema?: Shape;
 }): McpxTool<Shape>;
-/**
- * Defines a tool whose input shape is built per request and returned as an
- * object literal. The handler's arguments are inferred from that literal, so
- * a scope-narrowed enum still types as the value it produces.
- */
+/** Per-request shape returned as an object literal; arguments inferred from it. */
 declare function defineMcpxTool<Shape extends z.ZodRawShape>(tool: McpxTool<Shape> & {
   inputSchema: (scope: McpxToolScope) => Shape;
 }): McpxAnyTool;
 /**
- * Defines a tool whose input shape is assembled from helpers that erase to
- * `z.ZodRawShape`, as the builtins do. Nothing is left to infer from, so the
- * handler's arguments are stated instead: `defineMcpxTool<Args>({ ... })`.
+ * Per-request shape built from helpers that erase to `z.ZodRawShape`, as the
+ * builtins do. Nothing to infer from, so state the arguments instead.
  */
 declare function defineMcpxTool<Args>(tool: McpxTool<z.ZodRawShape, Args> & {
   inputSchema: (scope: McpxToolScope) => z.ZodRawShape;
 }): McpxAnyTool;
-/**
- * Outcome of resolving an API key. `user` must carry `collection`.
- */
 interface McpxAuthResult {
+  /** Must carry `collection`. */
   user: TypedUser;
   apiKeyId: number | string;
   /** The `capabilities` group as stored on the key document. */
   capabilities: unknown;
 }
+/**
+ * Everything the plugin accepts. `collections` is the only required option.
+ *
+ * A type alias rather than an interface: `definePlugin` constrains its options
+ * to `Record<string, unknown>`, which interfaces do not satisfy.
+ */
 type McpxPluginOptions = {
   /** Allow-list of collections. `true` is shorthand for `{ read: true }`. */
   collections: Partial<Record<CollectionSlug, McpxCollectionOptions | true>>;
@@ -213,30 +179,25 @@ type McpxPluginOptions = {
     version?: string;
   };
 };
+/** What a key may do with one entity. Globals reuse this shape. */
 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.
-   */
+  /** Only ever true where the config sets `write: "live"` and drafts exist. */
   publish: boolean;
 }
-/**
- * Capabilities in force for one request: plugin config AND key checkboxes.
- */
+/** In force for one request: plugin config AND key checkboxes. */
 interface McpxResolvedCapabilities {
   collections: Record<string, McpxCollectionCapabilities>;
   globals: Record<string, McpxCollectionCapabilities>;
   tools: Record<string, boolean>;
 }
+/** Stamped on `req.context.mcpx`; see {@link isMcpxRequest}. */
 interface McpxRequestContext {
   apiKeyId: number | string;
   capabilities: McpxResolvedCapabilities;
 }
-/**
- * One reason a human could not publish the draft as it stands.
- */
+/** 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;

package/dist/write/draft-guard.mjs

@@ -1,12 +1,9 @@
-import { claimPublishIntent, isClaimedPublish } from "./publish-intent.mjs";
+import { hasPublishIntent, takePublishIntent } 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, publishes included, so a tool cannot smuggle them in.
-*/ const STRIPPED_ARGS = /* @__PURE__ */ new Set([
+/** Cleared on every MCP write, publishes included, so none can be smuggled in. */ const STRIPPED_ARGS = /* @__PURE__ */ new Set([
 	"where",
 	"publishAllLocales",
 	"publishSpecificLocale",
@@ -21,19 +18,13 @@ import { hasDraftsEnabled } from "payload/shared";
 *
 * `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. `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.
+* Writing it here rather than in the tool keeps the tool honest, since this is
+* the only thing that can grant a publish.
 *
-* 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.
+* Not covered: deletes, `duplicate`, files (the local API lifts `file` and
+* `filePath` onto `req` before this runs), and anything going straight to
+* `payload.db`. `restoreVersion` is caught by {@link refusePublish} instead,
+* because it runs the collection's `beforeChange` hooks.
 */ const scrubWriteArgs = (args, publishing) => {
 	const next = Object.fromEntries(Object.entries(args).filter(([key]) => !STRIPPED_ARGS.has(key)));
 	if (next["data"] && typeof next["data"] === "object") {
@@ -50,72 +41,49 @@ import { hasDraftsEnabled } from "payload/shared";
 	return next;
 };
 const forceDraftWrite = (hookArgs) => {
-	const { args, collection, operation, req } = hookArgs;
+	const { args, operation, req } = hookArgs;
 	if (!isMcpxRequest(req) || operation !== "create" && operation !== "update") return args;
-	const publishing = operation === "update" && claimPublishIntent({
-		kind: "collection",
-		slug: collection.slug,
-		id: args.id
-	});
+	const publishing = operation === "update" && hasPublishIntent(args.data);
 	return scrubWriteArgs(args, publishing);
 };
 /**
-* 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.
+* The global counterpart of {@link forceDraftWrite}, with one difference that
+* decides where the guarantee lives: `updateGlobal` destructures `draft` and
+* the publish arguments *before* it runs `beforeOperation` and re-reads only
+* `data` afterwards, so setting them here is a no-op. What lands is `data` with
+* `_status` stripped, which makes {@link refusePublishGlobal} the alarm that
+* actually holds the line. `publishDocument` therefore passes `draft: false` at
+* the call site, and this hook puts `_status` back rather than stripping it.
 */ const forceDraftWriteGlobal = (hookArgs) => {
-	const { global, operation, req } = hookArgs;
+	const { operation, req } = hookArgs;
 	const args = hookArgs.args;
 	if (!isMcpxRequest(req) || operation !== "update") return args;
-	const publishing = claimPublishIntent({
-		kind: "global",
-		slug: global.slug
-	});
-	return scrubWriteArgs(args, publishing);
+	return scrubWriteArgs(args, hasPublishIntent(args["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) => {
+* Throws instead of correcting `_status`, because Payload has already chosen
+* the write branch by the time a `beforeChange` hook runs. Unreachable for a
+* collection if {@link forceDraftWrite} did its job; the guarantee itself for a
+* global. Last hook that needs the marker, so it takes it off.
+*/ const refuseUnlessExpected = (req, slug, data) => {
+	const publishing = takePublishIntent(data);
 	if (!isMcpxRequest(req)) return;
 	const status = data._status;
-	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)}).`);
+	req.payload.logger.warn(`[payloadcms-mcpx] Refused a write to ${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 }) => {
-	refuseUnlessExpected(req, {
-		kind: "collection",
-		slug: collection.slug
-	}, data);
+/**
+* Installs {@link refuseUnlessExpected} on every collection write. Returns
+* `data` unchanged when the write is allowed; the hook exists for its throw.
+*/ const refusePublish = ({ collection, data, req }) => {
+	refuseUnlessExpected(req, collection.slug, data);
 	return data;
 };
-/** The global counterpart of {@link refusePublish}. */ const refusePublishGlobal = ({ data, global, req }) => {
+const refusePublishGlobal = ({ data, global, req }) => {
 	const next = data;
-	refuseUnlessExpected(req, {
-		kind: "global",
-		slug: global.slug
-	}, next);
+	refuseUnlessExpected(req, global.slug, next);
 	return next;
 };
 /**