@abinnovision/payloadcms-mcpx 2.0.0-beta.13 → 2.0.0-beta.15

package/dist/plugin.d.mts

@@ -1,7 +1,8 @@
 import { McpxPluginOptions } from "./types.mjs";
 //#region src/plugin.d.ts
 /**
- * Mounts the MCP, upload and download endpoints, adds the API key collection
+ * Mounts the MCP, upload and download endpoints, and the confirmation
+ * endpoints where a collection exposes `delete`. Adds the API key collection
  * and installs the draft guard on every collection and global.
  */
 export declare const mcpxPlugin: (options: McpxPluginOptions) => import("payload").Plugin;

package/dist/plugin.mjs

@@ -1,4 +1,5 @@
 import { createApiKeysCollection } from "./api-keys/collection.mjs";
+import { confirmationEndpoints } from "./endpoint/confirmations.mjs";
 import { createMcpxHandler, methodNotAllowed } from "./endpoint/handler.mjs";
 import { createDownloadHandler, createUploadHandler } from "./endpoint/upload.mjs";
 import { normalizeOptions } from "./options.mjs";
@@ -6,7 +7,8 @@ import { installDraftGuards, installGlobalDraftGuards } from "./write/draft-guar
 import { definePlugin } from "payload";
 //#region src/plugin.ts
 /**
-* Mounts the MCP, upload and download endpoints, adds the API key collection
+* Mounts the MCP, upload and download endpoints, and the confirmation
+* endpoints where a collection exposes `delete`. Adds the API key collection
 * and installs the draft guard on every collection and global.
 */ const mcpxPlugin = definePlugin({
 	slug: "@abinnovision/payloadcms-mcpx",
@@ -45,7 +47,8 @@ import { definePlugin } from "payload";
 					path: `${normalized.endpointPath}/file`,
 					method: "get",
 					handler: createDownloadHandler(normalized)
-				}
+				},
+				...normalized.confirmations ? confirmationEndpoints(normalized) : []
 			]
 		};
 	}

package/dist/tools/builtin.mjs

@@ -1,4 +1,5 @@
 import { createDocument } from "./create-document.mjs";
+import { deleteDocument } from "./delete-document.mjs";
 import { describeSchema } from "./describe-schema.mjs";
 import { findDocuments } from "./find-documents.mjs";
 import { findVersions } from "./find-versions.mjs";
@@ -6,6 +7,7 @@ import { getDocument } from "./get-document.mjs";
 import { listCapabilities } from "./list-capabilities.mjs";
 import { patchDocument } from "./patch-document.mjs";
 import { publishDocument } from "./publish-document.mjs";
+import { createRunConfirmed } from "./run-confirmed.mjs";
 import { validateDocument } from "./validate-document.mjs";
 //#region src/tools/builtin.ts
 /**
@@ -22,7 +24,9 @@ import { validateDocument } from "./validate-document.mjs";
 	patchDocument,
 	createDocument,
 	validateDocument,
-	publishDocument
+	publishDocument,
+	deleteDocument,
+	createRunConfirmed(() => BUILTIN_TOOLS)
 ];
 //#endregion
 export { BUILTIN_TOOLS };

package/dist/tools/create-document.mjs

@@ -7,8 +7,8 @@ import { assertAcceptsFile, fileShape, fileWriteRefusal, uploadHandoff, uploaded
 import { liveWriteSentence, localeOf, localeShape, patchOnlySlugs, slugEnum, slugsFor } from "./shared.mjs";
 import { readDraft, resolveEntity } from "./document.mjs";
 import { stripRowIds } from "../write/row-ids.mjs";
-import { APIError } from "payload";
 import { z } from "zod";
+import { APIError } from "payload";
 //#region src/tools/create-document.ts
 const uploadSentence = (scope) => {
 	const slugs = patchOnlySlugs(scope);

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/list-capabilities.mjs

@@ -37,7 +37,7 @@ const translateLabel = (scope, label, fallback) => {
 		const collections = scope.exposure.collections.flatMap((entry) => {
 			const capability = scope.capabilities.collections[entry.slug];
 			const collection = payload.collections[entry.slug];
-			if (!capability || !collection || !(capability.read || capability.write)) return [];
+			if (!capability || !collection || !capability.read) return [];
 			const { config } = collection;
 			const description = translate(config.admin.description);
 			return [{
@@ -60,7 +60,7 @@ const translateLabel = (scope, label, fallback) => {
 		const globals = scope.exposure.globals.flatMap((entry) => {
 			const capability = scope.capabilities.globals[entry.slug];
 			const config = payload.globals.config.find((candidate) => candidate.slug === entry.slug);
-			if (!capability || !config || !(capability.read || capability.write)) return [];
+			if (!capability || !config || !capability.read) return [];
 			const description = translate(config.admin.description);
 			return [{
 				slug: entry.slug,

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/tools/validate-document.mjs

@@ -4,8 +4,8 @@ import { collectPublishBlockers } from "../write/publish-blockers.mjs";
 import { entityShape, idShape, localeOf, localeShape } from "./shared.mjs";
 import { collectLocaleBlockers, identityOf, readDraft, resolveDocument } from "./document.mjs";
 /**
-* Gated on write rather than read, because publish blockers only mean something
-* to a caller who can act on them.
+* Gated on write, which implies 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 covers every

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
@@ -36,7 +36,7 @@ export interface McpxCollectionOptions {
   /**
    * Expose `patchDocument`, `validateDocument` and `createDocument`. An upload
    * collection is created in only where MCP accepts its files. Without drafts
-   * a write changes live content. Default `true`.
+   * a write changes live content. Needs `read`. Default `true` while `read` is.
    */
   write?: boolean;
   /**
@@ -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 set to it move
+   * documents to trash without approval; it needs `trash`. Needs `read`.
+   * 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.