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

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,29 +12,21 @@ 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
  * shorthand for `{}`, which exposes everything the entity supports.
  */
 export interface McpxCollectionOptions {
-  /** Expose `describeSchema`, `findDocuments`, `getDocument`. Default `true`. */
+  /**
+   * Expose `describeSchema`, `findDocuments`, `getDocument`. Default `true`.
+   */
   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;
   /**
@@ -43,39 +35,67 @@ 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. */
-export type McpxGlobalOptions = McpxCollectionOptions;
+/**
+ * The same options without `delete`. A singleton, so neither `findDocuments`,
+ * `createDocument` nor `deleteDocument` reaches one.
+ */
+export type McpxGlobalOptions = Omit<McpxCollectionOptions, "delete">;
 export type McpxToolExtra = RequestHandlerExtra<ServerRequest, ServerNotification>;
-/** What the config exposes, before an API key's checkboxes narrow it. */
-export interface McpxExposedEntity {
+/**
+ * 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 extends McpxEntityCapabilities {
   slug: string;
-  read: boolean;
-  write: McpxWriteMode;
   hasDrafts: boolean;
   /**
    * The entity has Payload `versions`, with or without drafts, and is
    * readable. Says nothing about drafts; see `hasDrafts`.
    */
   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;
-  /** Name of the capability group on the key document. */
+  /**
+   * Name of the capability group on the key document.
+   */
   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. */
+/**
+ * What a tool knows about the current request.
+ */
 export interface McpxToolScope {
   req: PayloadRequest;
   capabilities: McpxResolvedCapabilities;
   collections: McpxScopeSlugs;
   globals: McpxScopeSlugs;
-  /** `null` when localization is off. */
+  /**
+   * `null` when localization is off.
+   */
   localization: null | {
     locales: string[];
     defaultLocale: string;
@@ -84,20 +104,34 @@ 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>>> {
-  /** camelCase, unique, not one of the builtin tool names. */
+interface McpxToolBase<Shape extends z.ZodRawShape> {
+  /**
+   * camelCase, unique, not one of the builtin tool names.
+   */
   name: string;
-  /** Built per request so it can state what this key's writes do. */
+  /**
+   * Built per request so it can state what this key's writes do.
+   */
   description: string | ((scope: McpxToolScope) => string);
   annotations?: ToolAnnotations;
   /**
@@ -112,21 +146,117 @@ 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>;
 }
-/** Argument type erased, so a registry can hold tools of differing shapes. */
+/**
+ * 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.
+ */
 export type McpxAnyTool = McpxTool<z.ZodRawShape, never>;
 export interface McpxAuthResult {
-  /** Must carry `collection`. */
+  /**
+   * Must carry `collection`.
+   */
   user: TypedUser;
   apiKeyId: DocumentId;
-  /** The `capabilities` group as stored on the key document. */
+  /**
+   * The `capabilities` group as stored on the key document.
+   */
   capabilities: unknown;
 }
 /**
@@ -136,31 +266,48 @@ export interface McpxAuthResult {
  * to `Record<string, unknown>`, which interfaces do not satisfy.
  */
 export type McpxPluginOptions = {
-  /** Allow-list of collections. `true` is shorthand for `{}`. */
+  /**
+   * Allow-list of collections. `true` is shorthand for `{}`.
+   */
   collections: Partial<Record<CollectionSlug, McpxCollectionOptions | true>>;
-  /** Allow-list of globals. `true` is shorthand for `{}`. */
+  /**
+   * Allow-list of globals. `true` is shorthand for `{}`.
+   */
   globals?: Partial<Record<GlobalSlug, McpxGlobalOptions | true>>;
-  /** Collection the keys act as. Default `config.admin.user`, then `users`. */
+  /**
+   * Collection the keys act as. Default `config.admin.user`, then `users`.
+   */
   userCollection?: CollectionSlug;
   apiKeys?: {
-    /** Slug of the generated API key collection. Default `mcpx-api-keys`. */
+    /**
+     * 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.
+     * 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;
-    /** Final override applied to the generated collection. */
+    /**
+     * Final override applied to the generated collection.
+     */
     overrideCollection?: (collection: CollectionConfig) => CollectionConfig;
   };
   endpoint?: {
-    /** Endpoint path below the API route. Default `/mcpx`. */
+    /**
+     * Endpoint path below the API route. Default `/mcpx`.
+     */
     path?: string;
   };
   limits?: {
-    /** Upper bound for `findDocuments.limit`. Default 25. */
+    /**
+     * Upper bound for `findDocuments.limit`. Default 25.
+     */
     maxLimit?: number;
-    /** Upper bound for `depth` on reads. Default 1. */
+    /**
+     * Upper bound for `depth` on reads. Default 1.
+     */
     maxDepth?: number;
   };
   tools?: McpxAnyTool[];
@@ -179,21 +326,42 @@ 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. */
-export interface McpxCollectionCapabilities {
+/**
+ * One entity's operations, as the config exposes them or as a key may use
+ * them. Globals reuse this shape.
+ */
+export interface McpxEntityCapabilities {
   read: boolean;
   write: boolean;
-  /** Only ever true where the config lets writes publish and drafts exist. */
+  /**
+   * 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. */
+/**
+ * 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>;
 }
-/** Stamped on `req.context.mcpx`; see {@link isMcpxRequest}. */
+/**
+ * Stamped on `req.context.mcpx`; see {@link isMcpxRequest}.
+ */
 export interface McpxRequestContext {
   apiKeyId: DocumentId;
   capabilities: McpxResolvedCapabilities;

package/dist/upload/file.mjs

@@ -0,0 +1,177 @@
+import { grantContext, issueGrant } from "../grants/grant.mjs";
+import { publicOrigin } from "../request.mjs";
+import { errorResult, jsonResult } from "../result.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";
+//#region src/upload/file.ts
+const MAX_BYTES = 26214400;
+const FILENAME = /^[^/\\\p{Cc}]+$/u;
+const MIME_TYPE = /^[\w.+-]+\/[\w.+-]+$/;
+const uploadedFiles = /* @__PURE__ */ new WeakMap();
+const fileSchema = (maxBytes) => z.strictObject({
+	filename: z.string().max(255).regex(FILENAME),
+	mimeType: z.string().max(255).regex(MIME_TYPE),
+	size: z.number().int().min(1).max(maxBytes)
+});
+/**
+* The largest file accepted: Payload's `upload.limits.fileSize` if set, and
+* never more than 25 MB, since the body is buffered.
+*/ const uploadMaxBytes = (config) => Math.min(config.upload.limits?.fileSize ?? MAX_BYTES, MAX_BYTES);
+const allowedMimeTypes = (scope, slug) => {
+	if (!scope.uploads || !scope.collections.writable.includes(slug)) return [];
+	const entity = scope.exposure.collections.find((candidate) => candidate.slug === slug);
+	const config = scope.req.payload.collections[slug]?.config;
+	return entity?.isUpload === true && Array.isArray(config?.upload.mimeTypes) ? config.upload.mimeTypes : [];
+};
+/**
+* Whether this key may send a file to `slug`: a writable upload collection
+* that sets `upload.mimeTypes`.
+*/ const acceptsFiles = (scope, slug) => allowedMimeTypes(scope, slug).length > 0;
+/**
+* The collections this key may send files to.
+*/ const fileSlugs = (scope) => scope.collections.writable.filter((slug) => acceptsFiles(scope, slug));
+/**
+* The `file` argument, present only when the key may send a file somewhere.
+*/ const fileShape = (scope, description) => {
+	const slugs = fileSlugs(scope);
+	return slugs.length === 0 ? {} : { file: fileSchema(uploadMaxBytes(scope.req.payload.config)).optional().describe(description(slugs.join(", "))) };
+};
+/**
+* Throws for a `file` sent to an entity that does not accept one, or declared
+* with a type outside its `upload.mimeTypes`. Payload stores the declared
+* type, so it is held to the same list as the content.
+*/ const assertAcceptsFile = (scope, target, file) => {
+	const mimeTypes = target.kind === "global" ? [] : allowedMimeTypes(scope, target.slug);
+	if (mimeTypes.length === 0) throw new APIError(`"${target.slug}" does not accept files through MCP: it is not an upload collection, or it sets no upload.mimeTypes.`, 400);
+	if (!validateMimeType(file.mimeType, mimeTypes)) throw new APIError(`"${target.slug}" accepts only ${mimeTypes.join(", ")}, not "${file.mimeType}".`, 400);
+};
+/**
+* Attaches the claimed bytes to the request the tool runs on.
+*/ const setUploadedFile = (req, file) => {
+	uploadedFiles.set(req, file);
+};
+/**
+* The bytes for this call, or `undefined` before they were sent.
+*/ const uploadedFile = (req) => uploadedFiles.get(req);
+const sharesPublishedFile = async (req, entity, id) => {
+	if (!hasDraftsEnabled(entity.config)) return false;
+	const read = {
+		collection: entity.slug,
+		id,
+		depth: 0,
+		overrideAccess: true,
+		disableErrors: true,
+		select: {
+			filename: true,
+			_status: true
+		},
+		req
+	};
+	const [latest, published] = await Promise.all([req.payload.findByID({
+		...read,
+		draft: true
+	}), req.payload.findByID({
+		...read,
+		draft: false
+	})]);
+	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, 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 (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) => {
+	const url = new URL(publicOrigin(req));
+	url.pathname = `${new URL(req.url ?? "").pathname.replace(/\/+$/, "")}/${path}`;
+	return url.toString();
+};
+/**
+* Stores the call as a grant and returns where to PUT its file. Nothing else
+* is written: the PUT runs the same call again with the bytes attached.
+*/ const uploadHandoff = async (scope, call) => {
+	const { req } = scope;
+	const { payload } = req;
+	const { slug, apiKeyId } = grantContext(req);
+	const url = handoffUrl(req, "upload");
+	const { id, exp } = await issueGrant(payload, slug, {
+		kind: "upload",
+		apiKeyId,
+		tool: call.tool,
+		args: call.args,
+		file: call.args.file,
+		locale: req.locale ?? null,
+		fallbackLocale: req.fallbackLocale ?? null
+	});
+	return jsonResult({ upload: {
+		url,
+		method: "PUT",
+		headers: {
+			"content-type": call.args.file.mimeType,
+			"x-mcpx-grant": id
+		},
+		expiresAt: new Date(exp).toISOString(),
+		maxBytes: uploadMaxBytes(payload.config)
+	} });
+};
+/**
+* The upload collections whose files this key may download. A collection
+* with its own top-level `download` field is left out, since the handoff
+* would overwrite it in the result.
+*/ const downloadSlugs = (scope) => scope.uploads ? scope.collections.readable.filter((slug) => scope.exposure.collections.find((candidate) => candidate.slug === slug)?.isUpload === true && !scope.req.payload.collections[slug]?.config.flattenedFields.some((field) => field.name === "download")) : [];
+/**
+* Stores a grant for the file of a document just read and returns where to
+* GET it.
+*/ const downloadHandoff = async (scope, target) => {
+	const { req } = scope;
+	const { slug, apiKeyId } = grantContext(req);
+	const url = handoffUrl(req, "file");
+	const { id, exp } = await issueGrant(req.payload, slug, {
+		kind: "download",
+		apiKeyId,
+		...target,
+		fallbackLocale: req.fallbackLocale ?? null
+	});
+	return {
+		url,
+		method: "GET",
+		headers: { "x-mcpx-grant": id },
+		expiresAt: new Date(exp).toISOString()
+	};
+};
+//#endregion
+export { acceptsFiles, assertAcceptsFile, downloadHandoff, downloadSlugs, fileShape, fileSlugs, fileWriteRefusal, setUploadedFile, uploadHandoff, uploadMaxBytes, uploadedFile };

package/dist/version.mjs

@@ -1,6 +1,8 @@
 //#region src/version.ts
 /**
 * Package version injected at build time; sources under Vitest report "dev".
-*/ const MCPX_VERSION = "1.0.0";
+*/ const MCPX_VERSION = "2.0.0";
+const MCPX_REPOSITORY_URL = "https://github.com/abinnovision/payloadcms-commons/tree/main/packages/mcpx";
+const MCPX_ISSUES_URL = "https://github.com/abinnovision/payloadcms-commons/issues";
 //#endregion
-export { MCPX_VERSION };
+export { MCPX_ISSUES_URL, MCPX_REPOSITORY_URL, MCPX_VERSION };