@abinnovision/payloadcms-mcpx 1.1.0-beta.5 → 2.0.0-beta.10

package/dist/types.d.mts

@@ -1,3 +1,4 @@
+import { DocumentId } from "./entity.mjs";
 import { CollectionConfig, CollectionSlug, GlobalSlug, PayloadRequest, TypedUser } from "payload";
 import { z } from "zod";
 import { RequestHandlerExtra } from "@modelcontextprotocol/sdk/shared/protocol.js";
@@ -17,57 +18,85 @@ declare module "payload" {
  * - `false`: no write tool touches it.
  * - `"draft"`: writes land as drafts and nothing MCP does changes what the
  *   public sees. Requires `versions.drafts`.
- * - `"live"`: MCP may change live content. On an entity with drafts that means
- *   `publishDocument` is exposed; on one without, where there is no draft to
- *   land on, it means the write itself is permitted and lands live.
+ * - `"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;
-/** A key can only enable what the config exposes here. */
+/**
+ * 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`, and how far those writes reach. Default
-   * `false`.
+   * collection, `createDocument`. Without drafts a write changes live
+   * content. Default `true`.
    */
-  write?: McpxWriteMode;
-}
-/** A singleton, so neither `findDocuments` nor `createDocument` reaches one. */
-export interface McpxGlobalOptions {
-  /** Expose `describeSchema` and `getDocument`. Default `true`. */
-  read?: boolean;
+  write?: boolean;
   /**
-   * Expose `patchDocument` and `validateDocument`, and how far those writes
-   * reach. Default `false`.
+   * Expose `publishDocument`, which promotes a draft to live content. Needs
+   * `versions.drafts` and `write`. Default `true` where the entity has drafts.
+   * `false` keeps writes as drafts and is refused where there are none.
    */
-  write?: McpxWriteMode;
+  publish?: boolean;
 }
+/**
+ * The same options. A singleton, so neither `findDocuments` nor
+ * `createDocument` reaches one.
+ */
+export type McpxGlobalOptions = McpxCollectionOptions;
 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.
+ */
 export interface McpxExposedEntity {
   slug: string;
   read: boolean;
   write: McpxWriteMode;
   hasDrafts: boolean;
-  /** An upload document is a file, and no tool here can supply one. */
+  /**
+   * 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.
+   */
   isUpload: boolean;
-  /** Name of the capability group on the key document. */
+  /**
+   * Name of the capability group on the key document.
+   */
   fieldName: string;
 }
-/** What a tool knows about the current request. */
-export interface McpxToolScope {
-  req: PayloadRequest;
-  capabilities: McpxResolvedCapabilities;
+/**
+ * The slugs a key may read, write and publish.
+ */
+export interface McpxScopeSlugs {
   readable: string[];
   writable: string[];
   publishable: string[];
-  readableGlobals: string[];
-  writableGlobals: string[];
-  publishableGlobals: string[];
-  /** `null` when localization is off. */
-  locales: null | string[];
-  defaultLocale: null | string;
+}
+/**
+ * What a tool knows about the current request.
+ */
+export interface McpxToolScope {
+  req: PayloadRequest;
+  capabilities: McpxResolvedCapabilities;
+  collections: McpxScopeSlugs;
+  globals: McpxScopeSlugs;
+  /**
+   * `null` when localization is off.
+   */
+  localization: null | {
+    locales: string[];
+    defaultLocale: string;
+  };
   limits: {
     maxLimit: number;
     maxDepth: number;
@@ -83,9 +112,13 @@ export interface McpxToolScope {
  * per request, leaving no static shape to infer from.
  */
 export interface McpxTool<Shape extends z.ZodRawShape = z.ZodRawShape, Args = z.infer<z.ZodObject<Shape>>> {
-  /** camelCase, unique, not one of the builtin tool names. */
+  /**
+   * camelCase, unique, not one of the builtin tool names.
+   */
   name: string;
-  /** Built per request so it can state what this key's writes actually do. */
+  /**
+   * Built per request so it can state what this key's writes do.
+   */
   description: string | ((scope: McpxToolScope) => string);
   annotations?: ToolAnnotations;
   /**
@@ -97,39 +130,32 @@ export interface McpxTool<Shape extends z.ZodRawShape = z.ZodRawShape, Args = z.
   /**
    * Built per request so enums can be narrowed to what the key may touch.
    * Registered strictly either way: an unknown argument is rejected by name
-   * rather than stripped.
+   * instead of stripped.
    */
   inputSchema?: Shape | ((scope: McpxToolScope) => z.ZodRawShape);
   handler(ctx: {
     args: Args;
     scope: McpxToolScope;
-    /** Shorthand for `scope.req`. */
+    /**
+     * Shorthand for `scope.req`.
+     */
     req: PayloadRequest;
     extra: McpxToolExtra;
   }): CallToolResult | Promise<CallToolResult>;
 }
-/** Argument type erased, so a registry can hold tools of differing shapes. */
-export type McpxAnyTool = McpxTool<z.ZodRawShape, never>;
-/** Fixed shape; arguments inferred from it. */
-export declare function defineMcpxTool<Shape extends z.ZodRawShape>(tool: McpxTool<Shape> & {
-  inputSchema?: Shape;
-}): McpxTool<Shape>;
-/** Per-request shape returned as an object literal; arguments inferred from it. */
-export declare function defineMcpxTool<Shape extends z.ZodRawShape>(tool: McpxTool<Shape> & {
-  inputSchema: (scope: McpxToolScope) => Shape;
-}): McpxAnyTool;
 /**
- * Per-request shape built from helpers that erase to `z.ZodRawShape`, as the
- * builtins do. Nothing to infer from, so state the arguments instead.
+ * Argument type erased, so a registry can hold tools of differing shapes.
  */
-export declare function defineMcpxTool<Args>(tool: McpxTool<z.ZodRawShape, Args> & {
-  inputSchema: (scope: McpxToolScope) => z.ZodRawShape;
-}): McpxAnyTool;
+export type McpxAnyTool = McpxTool<z.ZodRawShape, never>;
 export interface McpxAuthResult {
-  /** Must carry `collection`. */
+  /**
+   * Must carry `collection`.
+   */
   user: TypedUser;
-  apiKeyId: number | string;
-  /** The `capabilities` group as stored on the key document. */
+  apiKeyId: DocumentId;
+  /**
+   * The `capabilities` group as stored on the key document.
+   */
   capabilities: unknown;
 }
 /**
@@ -139,36 +165,56 @@ export interface McpxAuthResult {
  * to `Record<string, unknown>`, which interfaces do not satisfy.
  */
 export type McpxPluginOptions = {
-  /** Allow-list of collections. `true` is shorthand for `{ read: true }`. */
+  /**
+   * Allow-list of collections. `true` is shorthand for `{}`.
+   */
   collections: Partial<Record<CollectionSlug, McpxCollectionOptions | true>>;
-  /** Allow-list of globals. `true` is shorthand for `{ read: true }`. */
+  /**
+   * 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.
      */
     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[];
   auth?: {
-    /** Replace or wrap the default key resolution. Return `null` for 401. */
+    /**
+     * Replace or wrap the default key resolution. Return `null` for 401. A
+     * result whose user has no `id` or whose `collection` is not the user
+     * collection, or that has no `apiKeyId`, is also answered with 401.
+     */
     resolve?: (args: {
       req: PayloadRequest;
       resolveDefault: () => Promise<McpxAuthResult | null>;
@@ -179,30 +225,30 @@ export type McpxPluginOptions = {
     version?: string;
   };
 };
-/** What a key may do with one entity. Globals reuse this shape. */
+/**
+ * What a key may do with one entity. Globals reuse this shape.
+ */
 export interface McpxCollectionCapabilities {
   read: boolean;
   write: boolean;
-  /** Only ever true where the config sets `write: "live"` and drafts exist. */
+  /**
+   * Only ever true where the config lets writes publish and drafts exist.
+   */
   publish: boolean;
 }
-/** In force for one request: plugin config AND key checkboxes. */
+/**
+ * In force for one request: the plugin config and the key checkboxes together.
+ */
 export interface McpxResolvedCapabilities {
   collections: Record<string, McpxCollectionCapabilities>;
   globals: Record<string, McpxCollectionCapabilities>;
   tools: Record<string, boolean>;
 }
-/** Stamped on `req.context.mcpx`; see {@link isMcpxRequest}. */
+/**
+ * Stamped on `req.context.mcpx`; see {@link isMcpxRequest}.
+ */
 export interface McpxRequestContext {
-  apiKeyId: number | string;
+  apiKeyId: DocumentId;
   capabilities: McpxResolvedCapabilities;
 }
-/** One reason a human could not publish the draft as it stands. */
-export interface PublishBlocker {
-  /** Resolved field label path, e.g. "Layout > Block 2 (Hero) > Title". */
-  field?: string;
-  message: string;
-  /** JSON Pointer to the offending value, e.g. "/layout/2/title". */
-  path: string;
-}
 //#endregion

package/dist/write/draft-guard.mjs

@@ -3,30 +3,16 @@ import { isMcpxRequest } from "../request.mjs";
 import { APIError } from "payload";
 import { hasDraftsEnabled } from "payload/shared";
 //#region src/write/draft-guard.ts
-/** Cleared on every MCP write, publishes included, so none can be smuggled in. */ const STRIPPED_ARGS = /* @__PURE__ */ new Set([
+const STRIPPED_ARGS = /* @__PURE__ */ new Set([
 	"where",
 	"publishAllLocales",
-	"publishSpecificLocale",
 	"unpublishAllLocales",
 	"duplicateFromID",
 	"selectedLocales",
 	"overwriteExistingFiles"
 ]);
-/**
-* Forces every MCP write into a draft save, unless it is the one write
-* `publishDocument` asked for.
-*
-* `draft` alone is not enough: Payload's update path only saves a draft when
-* `data._status !== "published"`, so `_status` is dropped and left to Payload.
-* Writing it here rather than in the tool keeps the tool honest, since this is
-* the only thing that can grant a publish.
-*
-* Not covered: deletes, `duplicate`, files (the local API lifts `file` and
-* `filePath` onto `req` before this runs), and anything going straight to
-* `payload.db`. `restoreVersion` is caught by {@link refusePublish} instead,
-* because it runs the collection's `beforeChange` hooks.
-*/ const scrubWriteArgs = (args, publishing) => {
-	const next = Object.fromEntries(Object.entries(args).filter(([key]) => !STRIPPED_ARGS.has(key)));
+const scrubWriteArgs = (args, publishing) => {
+	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"];
 		next["data"] = publishing ? {
@@ -47,25 +33,22 @@ const forceDraftWrite = (hookArgs) => {
 	return scrubWriteArgs(args, publishing);
 };
 /**
-* The global counterpart of {@link forceDraftWrite}, with one difference that
-* decides where the guarantee lives: `updateGlobal` destructures `draft` and
-* the publish arguments *before* it runs `beforeOperation` and re-reads only
-* `data` afterwards, so setting them here is a no-op. What lands is `data` with
-* `_status` stripped, which makes {@link refusePublishGlobal} the alarm that
-* actually holds the line. `publishDocument` therefore passes `draft: false` at
-* the call site, and this hook puts `_status` back rather than stripping it.
+* The global counterpart of {@link forceDraftWrite}. `updateGlobal` reads
+* `draft` and the publish arguments before this hook runs, so only changes to
+* `data` take effect. A write to a global with drafts that did not ask for a
+* draft save is therefore refused here, and `_status` is restored for a publish.
 */ const forceDraftWriteGlobal = (hookArgs) => {
-	const { operation, req } = hookArgs;
+	const { global, operation, req } = hookArgs;
 	const args = hookArgs.args;
 	if (!isMcpxRequest(req) || operation !== "update") return args;
-	return scrubWriteArgs(args, hasPublishIntent(args["data"]));
+	const publishing = hasPublishIntent(args["data"]);
+	if (!publishing && args["draft"] !== true && hasDraftsEnabled(global)) {
+		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);
 };
-/**
-* Throws instead of correcting `_status`, because Payload has already chosen
-* the write branch by the time a `beforeChange` hook runs. Unreachable for a
-* collection if {@link forceDraftWrite} did its job; the guarantee itself for a
-* global. Last hook that needs the marker, so it takes it off.
-*/ const refuseUnlessExpected = (req, slug, data) => {
+const refuseUnlessExpected = (req, slug, data) => {
 	const publishing = takePublishIntent(data);
 	if (!isMcpxRequest(req)) return;
 	const status = data._status;
@@ -75,8 +58,8 @@ const forceDraftWrite = (hookArgs) => {
 	throw new APIError(publishing ? "This publish was refused because it would not have saved a published document." : "MCP clients may only write drafts. This write was refused because it would not have been saved as one. Use publishDocument to publish.", 403);
 };
 /**
-* Installs {@link refuseUnlessExpected} on every collection write. Returns
-* `data` unchanged when the write is allowed; the hook exists for its throw.
+* Runs {@link refuseUnlessExpected} on every collection write. Returns `data`
+* unchanged; the hook exists for its throw.
 */ const refusePublish = ({ collection, data, req }) => {
 	refuseUnlessExpected(req, collection.slug, data);
 	return data;
@@ -88,9 +71,9 @@ const refusePublishGlobal = ({ data, global, req }) => {
 };
 /**
 * Attaches the draft guard to every collection: `forceDraftWrite` everywhere
-* (it is a no-op outside MCP requests) and `refusePublish` wherever drafts
-* exist. Applied to the built collection list so nothing can join later
-* without being covered. Both are appended last, so a user hook cannot win.
+* (it does nothing outside MCP requests) and `refusePublish` wherever drafts
+* exist. It runs on the final collection list, so no collection escapes it, and
+* both hooks are appended last, so a user hook cannot override them.
 */ const installDraftGuards = (collections) => collections.map((collection) => ({
 	...collection,
 	hooks: {
@@ -100,10 +83,9 @@ const refusePublishGlobal = ({ data, global, req }) => {
 	}
 }));
 /**
-* Attaches the guard to every global, exposed or not, for the same reason
-* `installDraftGuards` covers every collection: a custom tool running on an MCP
-* request must not be able to publish through a global the plugin config never
-* mentioned.
+* Attaches the guard to every global, exposed or not: a custom tool running on
+* an MCP request must not be able to publish through a global the plugin config
+* never mentioned.
 */ const installGlobalDraftGuards = (globals) => globals.map((global) => ({
 	...global,
 	hooks: {