@abinnovision/payloadcms-mcpx 2.0.0-beta.12 → 2.0.0-beta.14

package/dist/tools/delete-document.mjs

@@ -0,0 +1,157 @@
+import { defineMcpxTool } from "../define-tool.mjs";
+import { errorResult, jsonResult } from "../result.mjs";
+import { translateStatic } from "../i18n.mjs";
+import { entityShape, idShape, slugsFor } from "./shared.mjs";
+import { resolveDocument, staleReadResult } from "./document.mjs";
+import { withTrashIntent } from "../write/publish-intent.mjs";
+import { withTransaction } from "../write/transaction.mjs";
+import { z } from "zod";
+import { Forbidden, NotFound, combineQueries, executeAccess } from "payload";
+import { formatAdminURL } from "payload/shared";
+//#region src/tools/delete-document.ts
+const DESCRIPTION = `Asks to delete one document. This call deletes nothing: it returns a "confirmation" with an "id" and a "url". Give the url to the user, who approves or rejects in the admin panel, then pass the id to runConfirmed, which deletes. Refused when the document is unknown, already in trash, changed since "expectedUpdatedAt" or not deletable by the user.`;
+const permanenceSentence = (scope) => {
+	const permanent = slugsFor(scope, "delete").collections.filter((slug) => scope.req.payload.collections[slug]?.config.trash !== true);
+	if (permanent.length === 0) return " Documents move to trash.";
+	const sentence = ` Deletes in ${permanent.join(", ")} are permanent.`;
+	return permanent.length === slugsFor(scope, "delete").collections.length ? sentence : `${sentence} Other documents move to trash.`;
+};
+const unattendedSentence = (scope) => {
+	const unattended = slugsFor(scope, "delete").collections.filter((slug) => scope.capabilities.collections[slug]?.deleteUnattended === true);
+	return unattended.length === 0 ? "" : ` Exception: in ${unattended.join(", ")} this call moves the document to trash at once and returns the delete result, with no confirmation.`;
+};
+const mayDelete = async (req, target) => {
+	const { config } = target;
+	const data = config.trash ? { deletedAt: (/* @__PURE__ */ new Date()).toISOString() } : {};
+	const rules = config.trash ? [config.access.delete, config.access.update] : [config.access.delete];
+	let where = { id: { equals: target.id } };
+	for (const rule of rules) {
+		const result = await executeAccess({
+			id: target.id,
+			data,
+			disableErrors: true,
+			req
+		}, rule);
+		if (result === false) return false;
+		if (typeof result === "object") where = combineQueries(where, result);
+	}
+	const { totalDocs } = await req.payload.count({
+		collection: target.slug,
+		where,
+		overrideAccess: true,
+		trash: true,
+		req
+	});
+	return totalDocs > 0;
+};
+/**
+* Deletes one collection document once the key's user approved the call. The
+* first call only checks and stores it; `runConfirmed` runs it again with the
+* stored arguments, pinned to the `updatedAt` read here. Available where the
+* config exposes `delete` and the key has the `delete` checkbox.
+*/ const deleteDocument = defineMcpxTool({
+	name: "deleteDocument",
+	description: (scope) => `${DESCRIPTION}${permanenceSentence(scope)}${unattendedSentence(scope)}`,
+	annotations: {
+		destructiveHint: true,
+		openWorldHint: false
+	},
+	isEnabled: (scope) => scope.uploads && scope.collections.deletable.length > 0,
+	inputSchema: (scope) => ({
+		...entityShape(scope, "delete"),
+		...idShape(scope, "delete"),
+		expectedUpdatedAt: z.string().optional().describe("\"updatedAt\" from your last read. Refused if the document changed since."),
+		reason: z.string().max(500).optional().describe("Why, shown to the user who approves.")
+	}),
+	confirm: {
+		label: "Delete documents",
+		summarize: async ({ args }, req) => {
+			const slug = String(args["collection"]);
+			const id = args["id"];
+			const config = req.payload.collections[slug]?.config;
+			const titleField = config?.admin.useAsTitle;
+			const read = async (draft) => config ? await req.payload.findByID({
+				collection: slug,
+				id,
+				depth: 0,
+				draft,
+				overrideAccess: false,
+				disableErrors: true,
+				req
+			}) : null;
+			const titleOf = (doc) => {
+				const value = titleField === void 0 ? void 0 : doc?.[titleField];
+				return typeof value === "string" && value !== "" ? value : void 0;
+			};
+			const published = await read(false);
+			const live = titleOf(published);
+			const latest = titleOf(await read(true));
+			const title = live === void 0 ? latest : latest !== void 0 && latest !== live ? `${live} (draft: ${latest})` : live;
+			const status = published?.["_status"];
+			return {
+				label: (typeof config?.labels.singular === "function" ? void 0 : translateStatic(config?.labels.singular, req.i18n)) ?? slug,
+				...title === void 0 ? {} : { title },
+				...typeof status === "string" ? { status } : {},
+				id: String(id),
+				href: formatAdminURL({
+					adminRoute: req.payload.config.routes.admin,
+					path: `/collections/${slug}/${String(id)}`
+				}),
+				permanent: config?.trash !== true,
+				...typeof args["reason"] === "string" ? { reason: args["reason"] } : {}
+			};
+		}
+	},
+	handler: async ({ args, scope, confirmation }) => {
+		const target = resolveDocument(scope, args, "delete");
+		const { req } = scope;
+		const { payload } = req;
+		const trash = target.config.trash ?? false;
+		return await withTransaction(req, async () => {
+			const doc = await payload.findByID({
+				collection: target.slug,
+				id: target.id,
+				depth: 0,
+				draft: true,
+				trash: true,
+				overrideAccess: false,
+				disableErrors: true,
+				req
+			});
+			if (!doc) throw new NotFound(req.t);
+			if (doc["deletedAt"]) return errorResult("The document is already in the trash. Emptying the trash is not available.");
+			const stale = staleReadResult(doc, args.expectedUpdatedAt, "The document changed since you read it. Read it again before deleting.");
+			if (stale) return stale;
+			if (!await mayDelete(req, target)) throw new Forbidden(req.t);
+			const unattended = trash && scope.capabilities.collections[target.slug]?.deleteUnattended === true;
+			if (!confirmation.confirmed && !unattended) return await confirmation.request({
+				...args,
+				expectedUpdatedAt: new Date(doc["updatedAt"]).toISOString()
+			});
+			if (trash) await payload.update({
+				collection: target.slug,
+				id: target.id,
+				data: withTrashIntent({ deletedAt: (/* @__PURE__ */ new Date()).toISOString() }),
+				depth: 0,
+				overrideAccess: false,
+				overrideLock: false,
+				req
+			});
+			else await payload.delete({
+				collection: target.slug,
+				id: target.id,
+				depth: 0,
+				overrideAccess: false,
+				overrideLock: false,
+				req
+			});
+			return jsonResult({
+				collection: target.slug,
+				id: target.id,
+				movedToTrash: trash
+			});
+		});
+	}
+});
+//#endregion
+export { deleteDocument };

package/dist/tools/find-versions.mjs

@@ -3,9 +3,9 @@ import { jsonResult } from "../result.mjs";
 import { draftVersionSlugs, entityShape, idShape, localeOf, localeShape, slugsFor, widen } from "./shared.mjs";
 import { resolveDocument } from "./document.mjs";
 import { queryVersions } from "./versions.mjs";
+import { z } from "zod";
 import { APIError } from "payload";
 import { hasDraftsEnabled } from "payload/shared";
-import { z } from "zod";
 //#region src/tools/find-versions.ts
 const DESCRIPTION = `Lists the versions of one document or global, newest first, autosaves included. Returns per version "versionId", "createdAt", "updatedAt", "status", "latest", "autosave" and, where set, "publishedLocale", without the content. Read a version with getDocument "versionId", or compare it with "diffFrom".`;
 const statusShape = (scope) => {

package/dist/tools/get-document.mjs

@@ -10,8 +10,8 @@ import { downloadHandoff, downloadSlugs } from "../upload/file.mjs";
 import { READ_LOCALE_DESCRIPTION, depthShape, entityShape, idSchema, idShape, localeOf, localeShape, slugsFor, widen } from "./shared.mjs";
 import { identityOf, resolveDocument } from "./document.mjs";
 import { diffDocuments, loadPublished, loadVersion, readLive } from "./versions.mjs";
-import { APIError } from "payload";
 import { z } from "zod";
+import { APIError } from "payload";
 import { Pointer } from "rfc6902";
 //#region src/tools/get-document.ts
 const OUTLINE_ERROR = "\"outline\" applies to a rich text field; give \"path\" for one.";

package/dist/tools/patch-document.mjs

@@ -7,11 +7,11 @@ import { collectPublishBlockers } from "../write/publish-blockers.mjs";
 import { assertAcceptsFile, fileShape, fileSlugs, fileWriteRefusal, uploadHandoff, uploadedFile } from "../upload/file.mjs";
 import { entityShape, idShape, liveWriteSentence, localeOf, localeShape } from "./shared.mjs";
 import { identityOf, readDraft, resolveDocument, staleReadResult } from "./document.mjs";
-import { applyPatchOperations, isElementPointer } from "../write/patch.mjs";
 import { withTransaction } from "../write/transaction.mjs";
+import { applyPatchOperations, isElementPointer } from "../write/patch.mjs";
 import { buildWriteData } from "../write/write-data.mjs";
-import { APIError, Forbidden, NotFound } from "payload";
 import { z } from "zod";
+import { APIError, Forbidden, NotFound } from "payload";
 import { Pointer } from "rfc6902";
 //#region src/tools/patch-document.ts
 const DESCRIPTION = (scope) => `Applies JSON Patch operations to one document or global, e.g. {"op":"replace","path":"/title","value":"Home"}. If any operation fails, nothing is written and the response lists the problems.

package/dist/tools/publish-document.mjs

@@ -2,8 +2,8 @@ import { defineMcpxTool } from "../define-tool.mjs";
 import { jsonResult } from "../result.mjs";
 import { entityShape, idShape, localeOf, localeShape } from "./shared.mjs";
 import { collectLocaleBlockers, identityOf, readDraft, resolveDocument, staleReadResult } from "./document.mjs";
-import { withTransaction } from "../write/transaction.mjs";
 import { withPublishIntent } from "../write/publish-intent.mjs";
+import { withTransaction } from "../write/transaction.mjs";
 import { z } from "zod";
 /**
 * Publishes a draft. Available where the config exposes `publish` on an entity

package/dist/tools/run-confirmed.mjs

@@ -0,0 +1,126 @@
+import { defineMcpxTool, isToolEnabled, toolInputSchema } from "../define-tool.mjs";
+import { grantKvSlug } from "../grants/grant.mjs";
+import { claimConfirmation, readConfirmation } from "../grants/confirmation.mjs";
+import { jsonResult } from "../result.mjs";
+import { z } from "zod";
+import { APIError } from "payload";
+//#region src/tools/run-confirmed.ts
+const DESCRIPTION = `Runs calls that returned a "confirmation", once the user approved them in the admin panel. Returns one result per id, in the order given: "done" with the call's "result", "pending" while it awaits a decision, "skipped" with a "reason" when it no longer passes its checks, or "refused" when it was rejected, expired, already run or is unknown. A pending id stays usable; no other id can run again.`;
+const NO_LONGER_ALLOWED = "This key no longer allows this call.";
+const CONFIRMED = {
+	confirmed: true,
+	request: () => Promise.reject(/* @__PURE__ */ new Error("A confirmed run cannot request a confirmation."))
+};
+const parseResult = (result) => {
+	const [first] = result.content;
+	try {
+		return first?.type === "text" ? JSON.parse(first.text) : {};
+	} catch {
+		return { text: first?.type === "text" ? first.text : void 0 };
+	}
+};
+const execute = async (tool, confirmation, scope, extra) => {
+	const { req } = scope;
+	const args = toolInputSchema(tool, scope).safeParse(confirmation.args);
+	if (!args.success) return {
+		status: "skipped",
+		reason: NO_LONGER_ALLOWED
+	};
+	const { fallbackLocale, locale } = req;
+	req.locale = confirmation.locale;
+	req.fallbackLocale = confirmation.fallbackLocale;
+	try {
+		const result = await tool.handler({
+			args: args.data,
+			scope,
+			req,
+			extra,
+			confirmation: CONFIRMED
+		});
+		const data = parseResult(result);
+		return result.isError === true ? {
+			status: "skipped",
+			reason: String(data["error"])
+		} : {
+			status: "done",
+			result: data
+		};
+	} catch (error) {
+		if (error instanceof APIError && error.isPublic) return {
+			status: "skipped",
+			reason: error.message
+		};
+		req.payload.logger.error({
+			err: error,
+			msg: "[payloadcms-mcpx] Confirmed call failed."
+		});
+		return {
+			status: "skipped",
+			reason: "Internal error"
+		};
+	} finally {
+		if (locale !== void 0) req.locale = locale;
+		if (fallbackLocale !== void 0) req.fallbackLocale = fallbackLocale;
+	}
+};
+const claimApproved = async (req, slug, apiKeyId, id) => {
+	const { payload } = req;
+	try {
+		const confirmation = await readConfirmation(payload, slug, apiKeyId, id);
+		if (confirmation?.state === "pending") return { status: "pending" };
+		return confirmation?.state === "approved" && await claimConfirmation(payload, slug, apiKeyId, id, confirmation.exp) ? confirmation : { status: "refused" };
+	} catch (error) {
+		payload.logger.error({
+			err: error,
+			msg: "[payloadcms-mcpx] Could not claim a confirmed call."
+		});
+		return {
+			status: "skipped",
+			reason: "Internal error"
+		};
+	}
+};
+/**
+* Runs approved calls of the confirmable tools in `tools`, which is read per
+* call so the list may include this tool. Registered when the key may call one
+* of them. Each call claims its entry first, so it runs at most once.
+*/ const createRunConfirmed = (tools) => defineMcpxTool({
+	name: "runConfirmed",
+	description: DESCRIPTION,
+	annotations: {
+		destructiveHint: true,
+		openWorldHint: false
+	},
+	isEnabled: (scope) => tools().some((tool) => tool.confirm !== void 0 && isToolEnabled(tool, scope)),
+	inputSchema: { ids: z.array(z.string().max(64)).min(1).max(50).describe("\"id\" of each \"confirmation\".") },
+	handler: async ({ args, scope, extra }) => {
+		const { req } = scope;
+		const { payload } = req;
+		const slug = grantKvSlug(payload.config);
+		const apiKeyId = req.context.mcpx?.apiKeyId;
+		if (slug === void 0 || apiKeyId === void 0) throw new Error("Confirmations need a database KV and a key.");
+		const outcomes = [];
+		for (const id of args.ids) {
+			const confirmation = await claimApproved(req, slug, apiKeyId, id);
+			if (!("tool" in confirmation)) {
+				outcomes.push({
+					id,
+					...confirmation
+				});
+				continue;
+			}
+			const tool = tools().find((candidate) => candidate.name === confirmation.tool && candidate.confirm !== void 0);
+			const result = tool && isToolEnabled(tool, scope) ? await execute(tool, confirmation, scope, extra) : {
+				status: "skipped",
+				reason: NO_LONGER_ALLOWED
+			};
+			outcomes.push({
+				id,
+				...result
+			});
+		}
+		return jsonResult({ results: outcomes });
+	}
+});
+//#endregion
+export { createRunConfirmed };

package/dist/tools/shared.mjs

@@ -36,6 +36,10 @@ const widen = (branch) => branch;
 			}),
 			globals: []
 		};
+		case "delete": return {
+			collections: scope.collections.deletable,
+			globals: []
+		};
 		case "publish": return slugsOf(scope, "publishable");
 		case "read": return slugsOf(scope, "readable");
 		case "versions": return {

package/dist/types.d.mts

@@ -1,6 +1,6 @@
 import { DocumentId } from "./entity.mjs";
-import { CollectionConfig, CollectionSlug, GlobalSlug, PayloadRequest, TypedUser } from "payload";
 import { z } from "zod";
+import { CollectionConfig, CollectionSlug, GlobalSlug, PayloadRequest, TypedUser } from "payload";
 import { RequestHandlerExtra } from "@modelcontextprotocol/sdk/shared/protocol.js";
 import { CallToolResult, ServerNotification, ServerRequest, ToolAnnotations } from "@modelcontextprotocol/sdk/types.js";
 //#region src/types.d.ts
@@ -45,12 +45,20 @@ export interface McpxCollectionOptions {
    * `false` keeps writes as drafts and is refused where there are none.
    */
   publish?: boolean;
+  /**
+   * Expose `deleteDocument`, which deletes one document once the key's user
+   * approved the call in the admin panel. On a collection with `trash` it
+   * moves the document to trash. `"unattended"` also lets a key with its own
+   * checkbox move documents to trash without approval; it needs `trash`.
+   * Default `false`.
+   */
+  delete?: boolean | "unattended";
 }
 /**
- * The same options. A singleton, so neither `findDocuments` nor
- * `createDocument` reaches one.
+ * The same options without `delete`. A singleton, so neither `findDocuments`,
+ * `createDocument` nor `deleteDocument` reaches one.
  */
-export type McpxGlobalOptions = McpxCollectionOptions;
+export type McpxGlobalOptions = Omit<McpxCollectionOptions, "delete">;
 export type McpxToolExtra = RequestHandlerExtra<ServerRequest, ServerNotification>;
 /**
  * What the config exposes, before an API key's checkboxes narrow it.
@@ -65,6 +73,14 @@ export interface McpxExposedEntity {
    * readable. Says nothing about drafts; see `hasDrafts`.
    */
   hasVersions: boolean;
+  /**
+   * The config exposes `deleteDocument`. Always `false` on a global.
+   */
+  delete: boolean;
+  /**
+   * The config lets a key move documents to trash without approval.
+   */
+  deleteUnattended: boolean;
   /**
    * An upload document is a file, which only an upload grant can supply.
    */
@@ -81,6 +97,7 @@ export interface McpxScopeSlugs {
   readable: string[];
   writable: string[];
   publishable: string[];
+  deletable: string[];
 }
 /**
  * What a tool knows about the current request.
@@ -103,7 +120,7 @@ export interface McpxToolScope {
   };
   /**
    * Whether files can be uploaded at all: the KV is database-backed and no
-   * custom `auth.resolve` is configured.
+   * custom `auth.resolve` is configured. Confirmations need the same.
    */
   uploads: boolean;
   /**
@@ -119,11 +136,9 @@ export interface McpxToolScope {
   };
 }
 /**
- * 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.
+ * What every tool declares, apart from `confirm` and the handler.
  */
-export interface McpxTool<Shape extends z.ZodRawShape = z.ZodRawShape, Args = z.infer<z.ZodObject<Shape>>> {
+interface McpxToolBase<Shape extends z.ZodRawShape> {
   /**
    * camelCase, unique, not one of the builtin tool names.
    */
@@ -145,15 +160,103 @@ export interface McpxTool<Shape extends z.ZodRawShape = z.ZodRawShape, Args = z.
    * instead of stripped.
    */
   inputSchema?: Shape | ((scope: McpxToolScope) => z.ZodRawShape);
-  handler(ctx: {
-    args: Args;
-    scope: McpxToolScope;
-    /**
-     * Shorthand for `scope.req`.
-     */
-    req: PayloadRequest;
-    extra: McpxToolExtra;
-  }): CallToolResult | Promise<CallToolResult>;
+}
+/**
+ * What a handler receives.
+ */
+export interface McpxToolContext<Args> {
+  args: Args;
+  scope: McpxToolScope;
+  /**
+   * Shorthand for `scope.req`.
+   */
+  req: PayloadRequest;
+  extra: McpxToolExtra;
+}
+/**
+ * Handed to the handler of a tool with `confirm`. Internal for now.
+ */
+export interface McpxConfirmation {
+  /**
+   * `true` when `runConfirmed` runs an approved call.
+   */
+  confirmed: boolean;
+  /**
+   * Stores the call with `args` for the key's user to approve and returns
+   * the result that hands its id and URL to the client. Throws in a
+   * confirmed run.
+   */
+  request: (args: Record<string, unknown>) => Promise<CallToolResult>;
+}
+/**
+ * A tool as `defineMcpxTool` takes it. `Confirm` is inferred from `confirm`,
+ * so only a tool that sets it gets `confirmation` in its handler.
+ */
+export type McpxToolDefinition<Shape extends z.ZodRawShape, Args, Confirm extends McpxToolConfirm | undefined> = McpxToolBase<Shape> & {
+  /**
+   * Internal: only builtin tools are confirmable for now. The handler gets
+   * `confirmation`: a call outside a confirmed run stores itself through
+   * `confirmation.request`, the key's user approves it in the admin panel,
+   * and `runConfirmed` runs the handler again with `confirmation.confirmed`
+   * set.
+   */
+  confirm?: Confirm;
+  handler(ctx: McpxToolContext<Args> & (Confirm extends McpxToolConfirm ? {
+    confirmation: McpxConfirmation;
+  } : unknown)): CallToolResult | Promise<CallToolResult>;
+};
+/**
+ * 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.
+ */
+export type McpxTool<Shape extends z.ZodRawShape = z.ZodRawShape, Args = z.infer<z.ZodObject<Shape>>> = McpxToolDefinition<Shape, Args, undefined> | (McpxToolDefinition<Shape, Args, McpxToolConfirm> & {
+  confirm: McpxToolConfirm;
+});
+/**
+ * How the admin panel shows one stored call of a confirmable tool.
+ */
+export interface McpxConfirmationSummary {
+  /**
+   * What the call acts on, such as a collection's label.
+   */
+  label: string;
+  /**
+   * `undefined` when the target cannot be read.
+   */
+  title?: string;
+  /**
+   * The target's `_status`, where it has drafts.
+   */
+  status?: string;
+  id?: string;
+  /**
+   * Admin path that opens the target.
+   */
+  href?: string;
+  /**
+   * The call cannot be undone.
+   */
+  permanent: boolean;
+  /**
+   * Written by the client, so shown as such.
+   */
+  reason?: string;
+}
+/**
+ * Internal for now; see {@link McpxTool.confirm}.
+ */
+export interface McpxToolConfirm {
+  /**
+   * Heading of the tool's group in the admin panel.
+   */
+  label: string;
+  /**
+   * Read at view time with the access of the key's user.
+   */
+  summarize(call: {
+    args: Record<string, unknown>;
+  }, req: PayloadRequest): Promise<McpxConfirmationSummary>;
 }
 /**
  * Argument type erased, so a registry can hold tools of differing shapes.
@@ -251,6 +354,14 @@ export interface McpxCollectionCapabilities {
    * Only ever true where the config lets writes publish and drafts exist.
    */
   publish: boolean;
+  /**
+   * Always `false` on a global.
+   */
+  delete: boolean;
+  /**
+   * Moves to trash without approval. Only ever true where `delete` is.
+   */
+  deleteUnattended: boolean;
 }
 /**
  * In force for one request: the plugin config and the key checkboxes together.

package/dist/upload/file.mjs

@@ -1,9 +1,12 @@
+import { grantKvSlug, issueGrant } from "../grants/grant.mjs";
 import { errorResult, jsonResult } from "../result.mjs";
-import { issueGrant, uploadKvSlug } from "./grant.mjs";
+import { SchemaError } from "../schema/errors.mjs";
+import { resolveDataPointer } from "../schema/pointer.mjs";
+import "../schema/index.mjs";
 import { collectPublishBlockers } from "../write/publish-blockers.mjs";
+import { z } from "zod";
 import { APIError } from "payload";
 import { hasDraftValidationEnabled, hasDraftsEnabled, validateMimeType } from "payload/shared";
-import { z } from "zod";
 //#region src/upload/file.ts
 const MAX_BYTES = 26214400;
 const FILENAME = /^[^/\\\p{Cc}]+$/u;
@@ -77,22 +80,38 @@ const sharesPublishedFile = async (req, entity, id) => {
 	})]);
 	return latest?.["_status"] === "draft" && published?.["_status"] === "published" && latest["filename"] === published["filename"];
 };
+const isClientWritable = (scope, target, path) => {
+	try {
+		const resolution = resolveDataPointer(scope.req.payload.config, {
+			ref: target.entity,
+			doc: target.data,
+			pointer: path
+		});
+		return resolution.readOnly !== true && resolution.descriptor?.readOnly !== true;
+	} catch (error) {
+		if (error instanceof SchemaError) return false;
+		throw error;
+	}
+};
 /**
 * Refuses a file write Payload would turn into data loss: a replace that
 * deletes the published file, or a write that fails validation after the old
 * file is gone. Payload validates only after it moves files, so the merged
-* data is validated here first wherever Payload will validate it.
+* data is validated here first wherever Payload will validate it, keeping only
+* failures the client can fix. Once the bytes are attached, Payload validates
+* with every hook and the file.
 */ const fileWriteRefusal = async (scope, target) => {
 	const { entity, id } = target;
 	if (id !== void 0 && await sharesPublishedFile(scope.req, entity, id)) return errorResult("The file was not replaced: the latest draft still uses the published file, which the replace would delete. Publish or discard the draft first.");
-	if (hasDraftsEnabled(entity.config) && !hasDraftValidationEnabled(entity.config)) return;
-	const { blockers } = await collectPublishBlockers(scope.req, {
+	if (uploadedFile(scope.req) !== void 0 || hasDraftsEnabled(entity.config) && !hasDraftValidationEnabled(entity.config)) return;
+	const { blockers: found } = await collectPublishBlockers(scope.req, {
 		doc: {
 			...target.data,
 			...id === void 0 ? {} : { id }
 		},
 		entity
 	});
+	const blockers = found.filter((blocker) => isClientWritable(scope, target, blocker.path));
 	return blockers.length === 0 ? void 0 : errorResult("Nothing was written: the document fails validation.", { validationErrors: blockers });
 };
 const handoffUrl = (req, path) => {
@@ -102,7 +121,7 @@ const handoffUrl = (req, path) => {
 	return url.toString();
 };
 const grantContext = (req) => {
-	const slug = uploadKvSlug(req.payload.config);
+	const slug = grantKvSlug(req.payload.config);
 	const apiKeyId = req.context.mcpx?.apiKeyId;
 	if (slug === void 0 || apiKeyId === void 0) throw new Error("A handoff was offered without a database KV or key.");
 	return {

package/dist/write/draft-guard.mjs

@@ -1,4 +1,4 @@
-import { hasPublishIntent, takePublishIntent } from "./publish-intent.mjs";
+import { hasPublishIntent, hasTrashIntent, takePublishIntent, takeTrashIntent, withTrashIntent } from "./publish-intent.mjs";
 import { isMcpxRequest } from "../request.mjs";
 import { APIError } from "payload";
 import { hasDraftsEnabled } from "payload/shared";
@@ -11,16 +11,17 @@ const STRIPPED_ARGS = /* @__PURE__ */ new Set([
 	"selectedLocales",
 	"overwriteExistingFiles"
 ]);
-const scrubWriteArgs = (args, publishing) => {
+const scrubWriteArgs = (args, intent) => {
+	const publishing = intent === "publish";
 	const next = Object.fromEntries(Object.entries(args).filter(([key]) => !STRIPPED_ARGS.has(key) && (publishing || key !== "publishSpecificLocale")));
 	if (next["data"] && typeof next["data"] === "object") {
-		const { _status: _ignoredStatus, deletedAt: _ignoredDeletedAt, ...data } = next["data"];
+		const { _status: _ignoredStatus, deletedAt, ...data } = next["data"];
 		next["data"] = publishing ? {
 			...data,
 			_status: "published"
-		} : data;
+		} : intent === "trash" ? withTrashIntent({ deletedAt }) : data;
 	}
-	next["draft"] = !publishing;
+	next["draft"] = intent === void 0;
 	next["autosave"] = false;
 	next["overrideLock"] = false;
 	next["trash"] = false;
@@ -29,8 +30,8 @@ const scrubWriteArgs = (args, publishing) => {
 const forceDraftWrite = (hookArgs) => {
 	const { args, operation, req } = hookArgs;
 	if (!isMcpxRequest(req) || operation !== "create" && operation !== "update") return args;
-	const publishing = operation === "update" && hasPublishIntent(args.data);
-	return scrubWriteArgs(args, publishing);
+	const intent = operation !== "update" ? void 0 : hasPublishIntent(args.data) ? "publish" : hasTrashIntent(args.data) ? "trash" : void 0;
+	return scrubWriteArgs(args, intent);
 };
 /**
 * The global counterpart of {@link forceDraftWrite}. `updateGlobal` reads
@@ -46,11 +47,12 @@ const forceDraftWrite = (hookArgs) => {
 		req.payload.logger.warn(`[payloadcms-mcpx] Refused a write to ${global.slug} that did not ask for a draft save.`);
 		throw new APIError("MCP clients may only write drafts. This write was refused because it would not have been saved as one. Use publishDocument to publish.", 403);
 	}
-	return scrubWriteArgs(args, publishing);
+	return scrubWriteArgs(args, publishing ? "publish" : void 0);
 };
 const refuseUnlessExpected = (req, slug, data) => {
 	const publishing = takePublishIntent(data);
-	if (!isMcpxRequest(req)) return;
+	const trashing = takeTrashIntent(data);
+	if (!isMcpxRequest(req) || trashing) return;
 	const status = data._status;
 	const expected = publishing ? "published" : "draft";
 	if (status === expected) return;