@abinnovision/payloadcms-mcpx 1.0.0-beta.8 → 1.0.0

package/dist/tools/shared.mjs

@@ -1,48 +1,102 @@
+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.");
-const slugsFor = (scope, operation) => ({
-	collections: operation === "read" ? scope.readable : scope.writable,
-	globals: operation === "read" ? scope.readableGlobals : scope.writableGlobals
+/**
+* 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)];
+};
+/**
+* Slugs this key may write whose writes land live rather than as a draft. An
+* entity without versions has no draft to land on, so `write: "live"` there
+* makes every write a live one. Empty for every key that can only write drafts.
+*/ const liveWriteSlugs = (scope) => slugsWhere(scope, isLiveWrite, {
+	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 `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.
+* 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.`}`;
+};
+/** 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
+		};
+		case "read": return {
+			collections: scope.readable,
+			globals: scope.readableGlobals
+		};
+		case "write": return {
+			collections: scope.writable,
+			globals: scope.writableGlobals
+		};
+	}
+};
+/**
+* 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 { collection: slugEnum(collections).describe(descriptions.collection) };
-	if (collections.length === 0) return { global: slugEnum(globals).describe(descriptions.global) };
-	return {
+	if (globals.length === 0) return widen({ collection: slugEnum(collections).describe(descriptions.collection) });
+	if (collections.length === 0) return widen({ global: slugEnum(globals).describe(descriptions.global) });
+	return widen({
 		collection: slugEnum(collections).optional().describe(descriptions.collection),
 		global: slugEnum(globals).optional().describe(descriptions.global)
-	};
+	});
 };
 /**
-* 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 {};
-	if (globals.length === 0) return { id: idSchema };
-	return { id: idSchema.optional().describe("Document id. Required with \"collection\"; must be omitted with \"global\".") };
+	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) => {
-	if (!scope.locales) return {};
+const localeShape = (scope, options) => {
+	if (!scope.locales) return widen({});
 	const locale = z.enum(scope.locales);
-	return { locale: (options.required ? locale : locale.optional()).describe(options.description) };
+	return widen({ locale: (options.required ? locale : locale.optional()).describe(options.description) });
 };
-const depthShape = (scope) => ({ depth: z.number().int().min(0).max(scope.options.limits.maxDepth).optional().describe(`Relationship population depth. Default 0, at most ${String(scope.options.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.
@@ -83,9 +137,7 @@ const depthShape = (scope) => ({ depth: z.number().int().min(0).max(scope.option
 		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,
@@ -94,4 +146,4 @@ const depthShape = (scope) => ({ depth: z.number().int().min(0).max(scope.option
 	return translateStatic(resolved, i18n) ?? fallback;
 };
 //#endregion
-export { depthShape, idSchema, idShape, localeOf, localeShape, readTarget, slugEnum, targetShape, translateLabel };
+export { depthShape, draftSentence, idSchema, idShape, localeOf, localeShape, patchOnlySlugs, readTarget, sameInstant, slugEnum, slugsFor, targetShape, translateLabel };

package/dist/tools/target.mjs

@@ -1,3 +1,4 @@
+import { slugsFor } from "./shared.mjs";
 import { APIError, Forbidden } from "payload";
 //#region src/tools/target.ts
 const refOf = (target) => ({
@@ -5,21 +6,17 @@ 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);
 	if (collection !== void 0 && global !== void 0) throw new APIError("Pass either \"collection\" or \"global\", not both.", 400);
 	if (collection === void 0 && global === void 0) throw new APIError("One of \"collection\" or \"global\" is required. Call listCapabilities to see which slugs are available.", 400);
 	if (collection !== void 0) {
-		const allowed = operation === "read" ? scope.readable : scope.writable;
 		const found = scope.req.payload.collections[collection];
-		if (!allowed.includes(collection) || !found) throw new Forbidden(scope.req.t);
+		if (!allowedSlugs.collections.includes(collection) || !found) throw new Forbidden(scope.req.t);
 		return {
 			kind: "collection",
 			slug: collection,
@@ -27,9 +24,8 @@ const refOf = (target) => ({
 		};
 	}
 	const slug = global;
-	const allowed = operation === "read" ? scope.readableGlobals : scope.writableGlobals;
 	const found = scope.req.payload.globals.config.find((candidate) => candidate.slug === slug);
-	if (!allowed.includes(slug) || !found) throw new Forbidden(scope.req.t);
+	if (!allowedSlugs.globals.includes(slug) || !found) throw new Forbidden(scope.req.t);
 	return {
 		kind: "global",
 		slug,

package/dist/tools/validate-document.mjs

@@ -1,17 +1,24 @@
-import { jsonResult } from "../endpoint/result.mjs";
+import { jsonResult } from "../result.mjs";
 import { idShape, localeOf, localeShape, readTarget, targetShape } from "./shared.mjs";
 import { requireIdFor, resolveTarget } from "./target.mjs";
+import { defineMcpxTool } from "../types.mjs";
 import { collectPublishBlockers } from "../write/publish-blockers.mjs";
-//#region src/tools/validate-document.ts
-const validateDocument = {
+/**
+* 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".
 
-Pass exactly one of "collection" and "global". "id" is required with "collection" and must be omitted with "global", because a global is a singleton.`,
-	annotations: {
-		readOnlyHint: true,
-		openWorldHint: false
-	},
+Pass exactly one of "collection" and "global". "id" is required with "collection" and must be omitted with "global", because a global is a singleton.
+
+Nothing is written, but the check runs the same field-level beforeValidate and beforeChange hooks a save would, so a hook with side effects fires. "publishBlockersUnavailable" means the check itself failed, so the empty list says nothing.`,
+	annotations: { openWorldHint: false },
 	isEnabled: (scope) => scope.writable.length + scope.writableGlobals.length > 0,
 	inputSchema: (scope) => ({
 		...targetShape(scope, "write", {
@@ -24,7 +31,7 @@ Pass exactly one of "collection" and "global". "id" is required with "collection
 			description: "Locale to validate."
 		})
 	}),
-	handler: async (args, scope) => {
+	handler: async ({ args, scope }) => {
 		const target = resolveTarget(scope, args, "write");
 		const id = requireIdFor(target, args.id);
 		const locale = localeOf(scope, args.locale);
@@ -39,7 +46,7 @@ Pass exactly one of "collection" and "global". "id" is required with "collection
 			locale,
 			privileged: true
 		});
-		const publishBlockers = await collectPublishBlockers(scope.req, {
+		const validation = await collectPublishBlockers(scope.req, {
 			doc,
 			entity: target
 		});
@@ -47,9 +54,10 @@ Pass exactly one of "collection" and "global". "id" is required with "collection
 			...target.kind === "collection" ? { id: doc["id"] } : { global: target.slug },
 			status: doc["_status"],
 			updatedAt: doc["updatedAt"],
-			publishBlockers
+			publishBlockers: validation.blockers,
+			...validation.unavailable ? { publishBlockersUnavailable: true } : {}
 		});
 	}
-};
+});
 //#endregion
 export { validateDocument };

package/dist/types.d.mts

@@ -12,74 +12,132 @@ declare module "payload" {
   }
 }
 /**
- * What an exposed collection offers to MCP clients. A key can only enable
- * what the config exposes here.
+ * 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;
+/** 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`. Default
-   * `false`. Requires `versions.drafts` unless `allowLiveWrites` is set.
+   * Expose `patchDocument`, `validateDocument` and, unless this is an upload
+   * collection, `createDocument`, 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
- * {@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;
   /**
-   * Expose `patchDocument` and `validateDocument`. Default `false`. Requires
-   * `versions.drafts` unless `allowLiveWrites` is set.
+   * Expose `patchDocument` and `validateDocument`, and how far those writes
+   * reach. Default `false`.
    */
-  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`.
-   */
-  allowLiveWrites?: boolean;
+  write?: McpxWriteMode;
 }
 type McpxToolExtra = RequestHandlerExtra<ServerRequest, ServerNotification>;
+/** 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;
+}
+/** What a tool knows about the current request. */
+interface McpxToolScope {
+  req: PayloadRequest;
+  capabilities: McpxResolvedCapabilities;
+  readable: string[];
+  writable: string[];
+  publishable: string[];
+  readableGlobals: string[];
+  writableGlobals: string[];
+  publishableGlobals: string[];
+  /** `null` when localization is off. */
+  locales: null | string[];
+  defaultLocale: null | string;
+  limits: {
+    maxLimit: number;
+    maxDepth: number;
+  };
+  exposure: {
+    collections: McpxExposedEntity[];
+    globals: McpxExposedEntity[];
+  };
+}
 /**
- * A custom tool. It is gated by its own checkbox on every API key and runs
- * with `req.user` resolved from the key and `req.context.mcpx` set.
+ * 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> {
+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;
-  inputSchema?: Shape;
+  /** Built per request so it can state what this key's writes actually do. */
+  description: string | ((scope: McpxToolScope) => string);
   annotations?: ToolAnnotations;
+  /**
+   * 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;
+  /**
+   * 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: {
-    args: z.infer<z.ZodObject<Shape>>;
+    args: Args;
+    scope: McpxToolScope;
+    /** Shorthand for `scope.req`. */
     req: PayloadRequest;
     extra: McpxToolExtra;
   }): CallToolResult | Promise<CallToolResult>;
 }
+/** Argument type erased, so a registry can hold tools of differing shapes. */
+type McpxAnyTool = McpxTool<z.ZodRawShape, never>;
+/** Fixed shape; arguments inferred from it. */
+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. */
+declare function defineMcpxTool<Shape extends z.ZodRawShape>(tool: McpxTool<Shape> & {
+  inputSchema: (scope: McpxToolScope) => Shape;
+}): McpxAnyTool;
 /**
- * Identity helper that infers the argument type of a custom tool's handler
- * from its input schema.
- */
-declare const defineMcpxTool: <Shape extends z.ZodRawShape>(tool: McpxTool<Shape>) => McpxTool<Shape>;
-/**
- * Outcome of resolving an API key. `user` must carry `collection`.
+ * 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;
 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>>;
@@ -90,6 +148,11 @@ type McpxPluginOptions = {
   apiKeys?: {
     /** Slug of the generated API key collection. Default `mcpx-api-keys`. */
     slug?: string;
+    /**
+     * Add a "Connect a client" tab to saved keys, holding ready-to-paste MCP
+     * client config. Default `true`. The snippets contain the key in full.
+     */
+    setupGuide?: boolean;
     /** Final override applied to the generated collection. */
     overrideCollection?: (collection: CollectionConfig) => CollectionConfig;
   };
@@ -103,7 +166,7 @@ type McpxPluginOptions = {
     /** Upper bound for `depth` on reads. Default 1. */
     maxDepth?: number;
   };
-  tools?: McpxTool[];
+  tools?: McpxAnyTool[];
   auth?: {
     /** Replace or wrap the default key resolution. Return `null` for 401. */
     resolve?: (args: {
@@ -116,21 +179,31 @@ type McpxPluginOptions = {
     version?: string;
   };
 };
+/** What a key may do with one entity. Globals reuse this shape. */
 interface McpxCollectionCapabilities {
   read: boolean;
   write: boolean;
+  /** 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. */
+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 { McpxAuthResult, McpxCollectionCapabilities, McpxCollectionOptions, McpxGlobalOptions, McpxPluginOptions, McpxRequestContext, McpxResolvedCapabilities, McpxTool, McpxToolExtra, defineMcpxTool };
+export { McpxAnyTool, McpxAuthResult, McpxCollectionCapabilities, McpxCollectionOptions, McpxExposedEntity, McpxGlobalOptions, McpxPluginOptions, McpxRequestContext, McpxResolvedCapabilities, McpxTool, McpxToolExtra, McpxToolScope, McpxWriteMode, PublishBlocker, defineMcpxTool };

package/dist/types.mjs

@@ -1,7 +1,6 @@
 //#region src/types.ts
-/**
-* Identity helper that infers the argument type of a custom tool's handler
-* from its input schema.
-*/ const defineMcpxTool = (tool) => tool;
+function defineMcpxTool(tool) {
+	return tool;
+}
 //#endregion
 export { defineMcpxTool };

package/dist/version.mjs

@@ -1,6 +1,6 @@
 //#region src/version.ts
 /**
 * Package version injected at build time; sources under Vitest report "dev".
-*/ const MCPX_VERSION = "0.0.0";
+*/ const MCPX_VERSION = "1.0.0";
 //#endregion
 export { MCPX_VERSION };

package/dist/write/draft-guard.mjs

@@ -1,10 +1,9 @@
+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 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",
@@ -14,26 +13,28 @@ 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) => {
+* Writing it here rather than in the tool keeps the tool honest, since this is
+* the only thing that can grant a publish.
+*
+* 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") {
 		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;
@@ -42,52 +43,54 @@ import { hasDraftsEnabled } from "payload/shared";
 const forceDraftWrite = (hookArgs) => {
 	const { args, operation, req } = hookArgs;
 	if (!isMcpxRequest(req) || operation !== "create" && operation !== "update") return args;
-	return scrubWriteArgs(args);
+	const publishing = operation === "update" && hasPublishIntent(args.data);
+	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 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.
+* 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 { operation, req } = hookArgs;
 	const args = hookArgs.args;
 	if (!isMcpxRequest(req) || operation !== "update") return args;
-	return scrubWriteArgs(args);
+	return scrubWriteArgs(args, hasPublishIntent(args["data"]));
 };
 /**
-* 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) => {
+* 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;
-	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 expected = publishing ? "published" : "draft";
+	if (status === expected) return;
+	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 }) => {
-	refuseUnlessDraft(req, 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;
-	refuseUnlessDraft(req, global.slug, next);
+	refuseUnlessExpected(req, 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 +113,4 @@ const refusePublish = ({ collection, data, req }) => {
 	}
 }));
 //#endregion
-export { forceDraftWrite, forceDraftWriteGlobal, installDraftGuards, installGlobalDraftGuards, isMcpxRequest, refusePublish, refusePublishGlobal };
+export { forceDraftWrite, forceDraftWriteGlobal, installDraftGuards, installGlobalDraftGuards, refusePublish, refusePublishGlobal };