@abinnovision/payloadcms-mcpx 2.0.0-beta.9 → 2.0.0

package/dist/tools/shared.mjs

@@ -1,10 +1,10 @@
-import { canCreate, isLiveWrite } from "../capabilities.mjs";
+import { acceptsFiles } from "../upload/file.mjs";
 import { z } from "zod";
 //#region src/tools/shared.ts
 /**
-* An out-of-scope slug fails schema validation before a handler runs, so a
+* A value outside the list fails schema validation before a handler runs, so a
 * client only ever sees what its key may touch.
-*/ const slugEnum = (slugs) => z.enum(slugs);
+*/ const stringEnum = (values) => z.enum(values);
 /**
 * Payload's id type follows the adapter, so both forms are handed on as read.
 */ const idSchema = z.union([z.string(), z.number()]);
@@ -14,62 +14,50 @@ const slugsOf = (scope, key) => ({
 });
 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)];
+	return {
+		collections: pick(scope.exposure.collections, allowed.collections),
+		globals: pick(scope.exposure.globals, allowed.globals)
+	};
 };
 /**
-* 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.collections.writable,
-	globals: []
-});
+* Collections this key may write but not create in: upload collections whose
+* files MCP does not accept. Nothing creates a global either way.
+*/ const patchOnlySlugs = (scope) => {
+	const creatable = slugsFor(scope, "create").collections;
+	return scope.collections.writable.filter((slug) => !creatable.includes(slug));
+};
 const widen = (branch) => branch;
 /**
 * The one list the shape helpers and {@link resolveEntity} both read.
 */ const slugsFor = (scope, operation) => {
 	switch (operation) {
-		case "create": return {
-			collections: slugsWhere(scope, canCreate, {
-				collections: scope.collections.writable,
-				globals: []
-			}),
+		case "create": return slugsWhere(scope, (entity) => entity.write && (!entity.isUpload || acceptsFiles(scope, entity.slug)), {
+			collections: scope.collections.writable,
+			globals: []
+		});
+		case "delete": return {
+			collections: scope.collections.deletable,
 			globals: []
 		};
 		case "publish": return slugsOf(scope, "publishable");
 		case "read": return slugsOf(scope, "readable");
-		case "versions": return {
-			collections: slugsWhere(scope, (entity) => entity.hasVersions, {
-				collections: scope.collections.readable,
-				globals: []
-			}),
-			globals: slugsWhere(scope, (entity) => entity.hasVersions, {
-				collections: [],
-				globals: scope.globals.readable
-			})
-		};
+		case "versions": return slugsWhere(scope, (entity) => entity.hasVersions, slugsOf(scope, "readable"));
 		case "write": return slugsOf(scope, "writable");
 	}
 };
 /**
-* The slugs of {@link slugsFor} `"versions"` that also have drafts. Only they
-* have `_status` on their versions, so only they can be queried by status.
-*/ const draftVersionSlugs = (scope) => {
-	const { collections, globals } = slugsFor(scope, "versions");
-	return {
-		collections: slugsWhere(scope, (entity) => entity.hasDrafts, {
-			collections,
-			globals: []
-		}),
-		globals: slugsWhere(scope, (entity) => entity.hasDrafts, {
-			collections: [],
-			globals
-		})
-	};
+* Whether `operation` reaches any collection or global.
+*/ const reaches = (scope, operation) => {
+	const { collections, globals } = slugsFor(scope, operation);
+	return collections.length + globals.length > 0;
 };
 /**
 * Slugs reachable by `operation` whose writes go live, because they have no
 * draft to write.
-*/ const liveWriteSlugs = (scope, operation) => slugsWhere(scope, isLiveWrite, slugsFor(scope, operation));
+*/ const liveWriteSlugs = (scope, operation) => {
+	const { collections, globals } = slugsWhere(scope, (entity) => entity.liveWrite, slugsFor(scope, operation));
+	return [...collections, ...globals];
+};
 /**
 * Stated on the tools that write, since a client calling them must know before
 * the call which writes are public.
@@ -84,11 +72,11 @@ const widen = (branch) => branch;
 * `globalRule` states that rule on `global` for a tool without an `id`.
 */ const entityShape = (scope, operation, globalRule) => {
 	const { collections, globals } = slugsFor(scope, operation);
-	if (globals.length === 0) return widen({ collection: slugEnum(collections) });
-	if (collections.length === 0) return widen({ global: slugEnum(globals) });
-	const global = slugEnum(globals).optional();
+	if (globals.length === 0) return widen({ collection: stringEnum(collections) });
+	if (collections.length === 0) return widen({ global: stringEnum(globals) });
+	const global = stringEnum(globals).optional();
 	return widen({
-		collection: slugEnum(collections).optional(),
+		collection: stringEnum(collections).optional(),
 		global: globalRule === void 0 ? global : global.describe(globalRule)
 	});
 };
@@ -106,7 +94,7 @@ const widen = (branch) => branch;
 */ const READ_LOCALE_DESCRIPTION = "Default: the default locale. A value missing in this locale is shown from the default locale.";
 const localeShape = (scope, options) => {
 	if (!scope.localization) return widen({});
-	const enumerated = z.enum(scope.localization.locales);
+	const enumerated = stringEnum(scope.localization.locales);
 	const locale = options.required ? enumerated : enumerated.optional();
 	return widen({ locale: options.description === void 0 ? locale : locale.describe(options.description) });
 };
@@ -115,6 +103,25 @@ const localeShape = (scope, options) => {
 * 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("Default 0. A relationship into a collection this key cannot read stays an id.") });
 /**
+* For the writes that refuse a document changed since the client read it.
+*/ const expectedUpdatedAtShape = { expectedUpdatedAt: z.string().optional().describe("\"updatedAt\" from your last read. Refused if the document changed since.") };
+/**
+* `limit` is bounded by the configured ceiling, so the client sees it instead
+* of being clamped silently.
+*/ const pageShape = (scope) => ({
+	limit: z.number().int().min(1).max(scope.limits.maxLimit).optional().describe("Default 10."),
+	page: z.number().int().min(1).optional()
+});
+/**
+* The paging fields of a result.
+*/ const pageFields = (result) => ({
+	totalDocs: result.totalDocs,
+	page: result.page,
+	totalPages: result.totalPages,
+	limit: result.limit,
+	hasNextPage: result.hasNextPage
+});
+/**
 * The locale to operate on: the explicit argument, else the request's, else
 * the default. `undefined` when localization is off.
 */ const localeOf = (scope, locale) => {
@@ -124,4 +131,4 @@ const localeShape = (scope, options) => {
 	return requested && locales.includes(requested) ? requested : defaultLocale;
 };
 //#endregion
-export { READ_LOCALE_DESCRIPTION, depthShape, draftVersionSlugs, entityShape, idSchema, idShape, liveWriteSentence, liveWriteSlugs, localeOf, localeShape, patchOnlySlugs, slugEnum, slugsFor, widen };
+export { READ_LOCALE_DESCRIPTION, depthShape, entityShape, expectedUpdatedAtShape, idSchema, idShape, liveWriteSentence, liveWriteSlugs, localeOf, localeShape, pageFields, pageShape, patchOnlySlugs, reaches, slugsFor, slugsWhere, stringEnum, widen };

package/dist/tools/validate-document.mjs

@@ -1,11 +1,11 @@
 import { defineMcpxTool } from "../define-tool.mjs";
 import { jsonResult } from "../result.mjs";
-import { entityShape, idShape, localeOf, localeShape } from "./shared.mjs";
 import { collectPublishBlockers } from "../write/publish-blockers.mjs";
-import { collectLocaleBlockers, identityOf, readDraft, resolveDocument } from "./document.mjs";
+import { entityShape, idShape, localeOf, localeShape, reaches } from "./shared.mjs";
+import { collectLocaleBlockers, documentSummary, 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
@@ -15,7 +15,7 @@ import { collectLocaleBlockers, identityOf, readDraft, resolveDocument } from ".
 	name: "validateDocument",
 	description: `Lists what still blocks publishing one document or global, without saving. Checks one locale when "locale" is given, otherwise every locale. Returns "publishBlockers", each with a pointer and a message, and a "locale" when every locale was checked. An empty list means it can be published, unless "publishBlockersUnavailable" is true: then the check itself failed. The check runs the field hooks a save runs.`,
 	annotations: { openWorldHint: false },
-	isEnabled: (scope) => scope.collections.writable.length + scope.globals.writable.length > 0,
+	isEnabled: (scope) => reaches(scope, "write"),
 	inputSchema: (scope) => ({
 		...entityShape(scope, "write"),
 		...idShape(scope, "write"),
@@ -39,9 +39,7 @@ import { collectLocaleBlockers, identityOf, readDraft, resolveDocument } from ".
 			entity: target
 		});
 		return jsonResult({
-			...identityOf(target, doc["id"]),
-			status: doc["_status"],
-			updatedAt: doc["updatedAt"],
+			...documentSummary(target, doc),
 			publishBlockers: validation.blockers,
 			...validation.unavailable ? { publishBlockersUnavailable: true } : {}
 		});

package/dist/tools/versions.mjs

@@ -1,3 +1,4 @@
+import { definedProps, isPlainObject } from "../guards.mjs";
 import { stripAdminHidden } from "../schema/admin-hidden.mjs";
 import "../schema/index.mjs";
 import { mcpxReadRequest } from "./read-request.mjs";
@@ -21,8 +22,10 @@ const NEWEST_FIRST = ["-updatedAt", "-id"];
 		draft: options.draft,
 		overrideAccess: false,
 		req: mcpxReadRequest(scope),
-		...options.select === void 0 ? {} : { select: options.select },
-		...read.locale === void 0 ? {} : { locale: read.locale }
+		...definedProps({
+			select: options.select,
+			locale: read.locale
+		})
 	};
 	const doc = await (read.target.kind === "collection" ? scope.req.payload.findByID({
 		...shared,
@@ -51,7 +54,7 @@ const assertReadable = async (scope, read) => {
 * `parent` comes back as a raw id or, populated, as the document itself.
 */ const isVersionOf = (version, id) => {
 	const parent = version["parent"];
-	const parentId = typeof parent === "object" && parent !== null ? parent["id"] : parent;
+	const parentId = isPlainObject(parent) ? parent["id"] : parent;
 	return (typeof parentId === "string" || typeof parentId === "number") && String(parentId) === String(id);
 };
 /**
@@ -68,7 +71,7 @@ const assertReadable = async (scope, read) => {
 		disableErrors: true,
 		overrideAccess: false,
 		req: mcpxReadRequest(scope),
-		...read.locale === void 0 ? {} : { locale: read.locale }
+		...definedProps({ locale: read.locale })
 	};
 	const version = await (read.target.kind === "collection" ? payload.findVersionByID({
 		...shared,
@@ -96,8 +99,10 @@ const assertReadable = async (scope, read) => {
 		overrideAccess: false,
 		req: mcpxReadRequest(scope),
 		where,
-		...options.page === void 0 ? {} : { page: options.page },
-		...read.locale === void 0 ? {} : { locale: read.locale }
+		...definedProps({
+			page: options.page,
+			locale: read.locale
+		})
 	};
 	return await (read.target.kind === "collection" ? scope.req.payload.findVersions({
 		...shared,

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
@@ -12,17 +12,6 @@ declare module "payload" {
     "@abinnovision/payloadcms-mcpx": McpxPluginOptions;
   }
 }
-/**
- * How far an exposed entity lets MCP writes reach.
- *
- * - `false`: no write tool touches it.
- * - `"draft"`: writes land as drafts and nothing MCP does changes what the
- *   public sees. Requires `versions.drafts`.
- * - `"live"`: MCP may change live content. On an entity with drafts that
- *   exposes `publishDocument`. On one without, there is no draft, so the write
- *   itself is permitted and lands live.
- */
-export type McpxWriteMode = "draft" | "live" | false;
 /**
  * What an entity exposes. The config names the entities that are reachable and
  * only takes capabilities away; a key's checkboxes decide per key. `true` is
@@ -34,9 +23,10 @@ export interface McpxCollectionOptions {
    */
   read?: boolean;
   /**
-   * Expose `patchDocument`, `validateDocument` and, unless this is an upload
-   * collection, `createDocument`. Without drafts a write changes live
-   * content. Default `true`.
+   * Expose `patchDocument`, `validateDocument`, `createDocument` and
+   * `duplicateDocument`. An upload collection is created in only where MCP
+   * accepts its files, and is never duplicated. Without drafts
+   * a write changes live content. Needs `read`. Default `true` while `read` is.
    */
   write?: boolean;
   /**
@@ -45,20 +35,28 @@ 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.
+ * What the config exposes, before an API key's checkboxes narrow it. The
+ * operations are the config's side of {@link McpxEntityCapabilities}: `write`
+ * covers draft and live writes, and `publish` is only true where drafts exist.
  */
-export interface McpxExposedEntity {
+export interface McpxExposedEntity extends McpxEntityCapabilities {
   slug: string;
-  read: boolean;
-  write: McpxWriteMode;
   hasDrafts: boolean;
   /**
    * The entity has Payload `versions`, with or without drafts, and is
@@ -66,7 +64,11 @@ export interface McpxExposedEntity {
    */
   hasVersions: boolean;
   /**
-   * An upload document is a file, and no tool here can supply one.
+   * Writes go live immediately, as the entity keeps no drafts.
+   */
+  liveWrite: boolean;
+  /**
+   * An upload document is a file, which only an upload grant can supply.
    */
   isUpload: boolean;
   /**
@@ -75,12 +77,13 @@ export interface McpxExposedEntity {
   fieldName: string;
 }
 /**
- * The slugs a key may read, write and publish.
+ * The slugs a key may read, write, publish and delete.
  */
 export interface McpxScopeSlugs {
   readable: string[];
   writable: string[];
   publishable: string[];
+  deletable: string[];
 }
 /**
  * What a tool knows about the current request.
@@ -101,17 +104,27 @@ export interface McpxToolScope {
     maxLimit: number;
     maxDepth: number;
   };
+  /**
+   * Whether files can be uploaded at all: the KV is database-backed and no
+   * custom `auth.resolve` is configured. Confirmations need the same.
+   */
+  uploads: boolean;
+  /**
+   * `null` when `diagnostics` is off.
+   */
+  diagnostics: null | {
+    name: string;
+    version: string;
+  };
   exposure: {
     collections: McpxExposedEntity[];
     globals: McpxExposedEntity[];
   };
 }
 /**
- * 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.
    */
@@ -133,15 +146,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.
@@ -183,8 +284,9 @@ export type McpxPluginOptions = {
      */
     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.
+     * Add a "Connect a client" button to saved keys, opening a drawer with
+     * ready-to-paste MCP client config. Default `true`. The snippets contain
+     * the key in full.
      */
     setupGuide?: boolean;
     /**
@@ -224,24 +326,37 @@ export type McpxPluginOptions = {
     name?: string;
     version?: string;
   };
+  /**
+   * Expose the server version plus repository and issue links to clients. Default `true`.
+   */
+  diagnostics?: boolean;
 };
 /**
- * What a key may do with one entity. Globals reuse this shape.
+ * One entity's operations, as the config exposes them or as a key may use
+ * them. Globals reuse this shape.
  */
-export interface McpxCollectionCapabilities {
+export interface McpxEntityCapabilities {
   read: boolean;
   write: boolean;
   /**
    * 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.
  */
 export interface McpxResolvedCapabilities {
-  collections: Record<string, McpxCollectionCapabilities>;
-  globals: Record<string, McpxCollectionCapabilities>;
+  collections: Record<string, McpxEntityCapabilities>;
+  globals: Record<string, McpxEntityCapabilities>;
   tools: Record<string, boolean>;
 }
 /**