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

package/dist/tools/validate-document.mjs

@@ -1,17 +1,24 @@
-import { jsonResult } from "../endpoint/result.mjs";
+import { jsonResult } from "../result.mjs";
 import { idShape, localeOf, localeShape, readTarget, targetShape } from "./shared.mjs";
 import { requireIdFor, resolveTarget } from "./target.mjs";
+import { defineMcpxTool } from "../types.mjs";
 import { collectPublishBlockers } from "../write/publish-blockers.mjs";
-//#region src/tools/validate-document.ts
-const validateDocument = {
+/**
+* Gated on write rather than 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 runs over
+* every field rather than the subset the user can read. It carries no
+* `readOnlyHint`, because the traversal fires field hooks.
+*/ const validateDocument = defineMcpxTool({
 	name: "validateDocument",
 	description: `Reports what still prevents a human from publishing the draft, without writing anything. The same list patchDocument returns after a write; use it to check work or to answer "is this ready".
 
-Pass exactly one of "collection" and "global". "id" is required with "collection" and must be omitted with "global", because a global is a singleton.`,
-	annotations: {
-		readOnlyHint: true,
-		openWorldHint: false
-	},
+Pass exactly one of "collection" and "global". "id" is required with "collection" and must be omitted with "global", because a global is a singleton.
+
+Nothing is written, but the check runs the same field-level beforeValidate and beforeChange hooks a save would, so a hook with side effects fires. "publishBlockersUnavailable" means the check itself failed, so the empty list says nothing.`,
+	annotations: { openWorldHint: false },
 	isEnabled: (scope) => scope.writable.length + scope.writableGlobals.length > 0,
 	inputSchema: (scope) => ({
 		...targetShape(scope, "write", {
@@ -24,7 +31,7 @@ Pass exactly one of "collection" and "global". "id" is required with "collection
 			description: "Locale to validate."
 		})
 	}),
-	handler: async (args, scope) => {
+	handler: async ({ args, scope }) => {
 		const target = resolveTarget(scope, args, "write");
 		const id = requireIdFor(target, args.id);
 		const locale = localeOf(scope, args.locale);
@@ -39,7 +46,7 @@ Pass exactly one of "collection" and "global". "id" is required with "collection
 			locale,
 			privileged: true
 		});
-		const publishBlockers = await collectPublishBlockers(scope.req, {
+		const validation = await collectPublishBlockers(scope.req, {
 			doc,
 			entity: target
 		});
@@ -47,9 +54,10 @@ Pass exactly one of "collection" and "global". "id" is required with "collection
 			...target.kind === "collection" ? { id: doc["id"] } : { global: target.slug },
 			status: doc["_status"],
 			updatedAt: doc["updatedAt"],
-			publishBlockers
+			publishBlockers: validation.blockers,
+			...validation.unavailable ? { publishBlockersUnavailable: true } : {}
 		});
 	}
-};
+});
 //#endregion
 export { validateDocument };

package/dist/types.d.mts

@@ -12,74 +12,132 @@ declare module "payload" {
   }
 }
 /**
- * What an exposed collection offers to MCP clients. A key can only enable
- * what the config exposes here.
+ * 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 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.
  */
+type McpxWriteMode = "draft" | "live" | false;
+/** A key can only enable what the config exposes here. */
 interface McpxCollectionOptions {
-  /** Expose `describeSchema`, `findDocuments` and `getDocument`. Default `true`. */
+  /** Expose `describeSchema`, `findDocuments`, `getDocument`. Default `true`. */
   read?: boolean;
   /**
-   * Expose `patchDocument`, `createDocument` and `validateDocument`. Default
-   * `false`. Requires `versions.drafts` unless `allowLiveWrites` is set.
+   * Expose `patchDocument`, `validateDocument` and, unless this is an upload
+   * collection, `createDocument`, and how far those writes reach. Default
+   * `false`.
    */
-  write?: boolean;
-  /**
-   * Permit writes to a collection without drafts. Such writes land on the live
-   * document because there is no draft to land on. Default `false`.
-   */
-  allowLiveWrites?: boolean;
+  write?: McpxWriteMode;
 }
-/**
- * What an exposed global offers to MCP clients. Structurally the same as
- * {@link McpxCollectionOptions}, kept separate because the tools it names
- * differ: a global is a singleton, so neither `findDocuments` nor
- * `createDocument` reaches one.
- */
+/** A singleton, so neither `findDocuments` nor `createDocument` reaches one. */
 interface McpxGlobalOptions {
   /** Expose `describeSchema` and `getDocument`. Default `true`. */
   read?: boolean;
   /**
-   * Expose `patchDocument` and `validateDocument`. Default `false`. Requires
-   * `versions.drafts` unless `allowLiveWrites` is set.
+   * Expose `patchDocument` and `validateDocument`, and how far those writes
+   * reach. Default `false`.
    */
-  write?: boolean;
-  /**
-   * Permit writes to a global without drafts. Such writes land on the live
-   * document because there is no draft to land on. Default `false`.
-   */
-  allowLiveWrites?: boolean;
+  write?: McpxWriteMode;
 }
 type McpxToolExtra = RequestHandlerExtra<ServerRequest, ServerNotification>;
+/** What the config exposes, before an API key's checkboxes narrow it. */
+interface McpxExposedEntity {
+  slug: string;
+  read: boolean;
+  write: McpxWriteMode;
+  hasDrafts: 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. */
+  fieldName: string;
+}
+/** What a tool knows about the current request. */
+interface McpxToolScope {
+  req: PayloadRequest;
+  capabilities: McpxResolvedCapabilities;
+  readable: string[];
+  writable: string[];
+  publishable: string[];
+  readableGlobals: string[];
+  writableGlobals: string[];
+  publishableGlobals: string[];
+  /** `null` when localization is off. */
+  locales: null | string[];
+  defaultLocale: null | string;
+  limits: {
+    maxLimit: number;
+    maxDepth: number;
+  };
+  exposure: {
+    collections: McpxExposedEntity[];
+    globals: McpxExposedEntity[];
+  };
+}
 /**
- * A custom tool. It is gated by its own checkbox on every API key and runs
- * with `req.user` resolved from the key and `req.context.mcpx` set.
+ * 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.
  */
-interface McpxTool<Shape extends z.ZodRawShape = z.ZodRawShape> {
+interface McpxTool<Shape extends z.ZodRawShape = z.ZodRawShape, Args = z.infer<z.ZodObject<Shape>>> {
   /** camelCase, unique, not one of the builtin tool names. */
   name: string;
-  description: string;
-  inputSchema?: Shape;
+  /** Built per request so it can state what this key's writes actually do. */
+  description: string | ((scope: McpxToolScope) => string);
   annotations?: ToolAnnotations;
+  /**
+   * A tool that is not enabled never appears in `tools/list`. Defaults to the
+   * tool's own checkbox on the API key; defining it replaces that check rather
+   * than adding to it.
+   */
+  isEnabled?: (scope: McpxToolScope) => boolean;
+  /**
+   * 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.
+   */
+  inputSchema?: Shape | ((scope: McpxToolScope) => z.ZodRawShape);
   handler(ctx: {
-    args: z.infer<z.ZodObject<Shape>>;
+    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. */
+type McpxAnyTool = McpxTool<z.ZodRawShape, never>;
+/** Fixed shape; arguments inferred from it. */
+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. */
+declare function defineMcpxTool<Shape extends z.ZodRawShape>(tool: McpxTool<Shape> & {
+  inputSchema: (scope: McpxToolScope) => Shape;
+}): McpxAnyTool;
 /**
- * Identity helper that infers the argument type of a custom tool's handler
- * from its input schema.
- */
-declare const defineMcpxTool: <Shape extends z.ZodRawShape>(tool: McpxTool<Shape>) => McpxTool<Shape>;
-/**
- * Outcome of resolving an API key. `user` must carry `collection`.
+ * Per-request shape built from helpers that erase to `z.ZodRawShape`, as the
+ * builtins do. Nothing to infer from, so state the arguments instead.
  */
+declare function defineMcpxTool<Args>(tool: McpxTool<z.ZodRawShape, Args> & {
+  inputSchema: (scope: McpxToolScope) => z.ZodRawShape;
+}): McpxAnyTool;
 interface McpxAuthResult {
+  /** Must carry `collection`. */
   user: TypedUser;
   apiKeyId: number | string;
   /** The `capabilities` group as stored on the key document. */
   capabilities: unknown;
 }
+/**
+ * Everything the plugin accepts. `collections` is the only required option.
+ *
+ * A type alias rather than an interface: `definePlugin` constrains its options
+ * to `Record<string, unknown>`, which interfaces do not satisfy.
+ */
 type McpxPluginOptions = {
   /** Allow-list of collections. `true` is shorthand for `{ read: true }`. */
   collections: Partial<Record<CollectionSlug, McpxCollectionOptions | true>>;
@@ -108,7 +166,7 @@ type McpxPluginOptions = {
     /** Upper bound for `depth` on reads. Default 1. */
     maxDepth?: number;
   };
-  tools?: McpxTool[];
+  tools?: McpxAnyTool[];
   auth?: {
     /** Replace or wrap the default key resolution. Return `null` for 401. */
     resolve?: (args: {
@@ -121,21 +179,31 @@ type McpxPluginOptions = {
     version?: string;
   };
 };
+/** What a key may do with one entity. Globals reuse this shape. */
 interface McpxCollectionCapabilities {
   read: boolean;
   write: boolean;
+  /** Only ever true where the config sets `write: "live"` and drafts exist. */
+  publish: boolean;
 }
-/**
- * Capabilities in force for one request: plugin config AND key checkboxes.
- */
+/** In force for one request: plugin config AND key checkboxes. */
 interface McpxResolvedCapabilities {
   collections: Record<string, McpxCollectionCapabilities>;
   globals: Record<string, McpxCollectionCapabilities>;
   tools: Record<string, boolean>;
 }
+/** Stamped on `req.context.mcpx`; see {@link isMcpxRequest}. */
 interface McpxRequestContext {
   apiKeyId: number | string;
   capabilities: McpxResolvedCapabilities;
 }
+/** One reason a human could not publish the draft as it stands. */
+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
-export { McpxAuthResult, McpxCollectionCapabilities, McpxCollectionOptions, McpxGlobalOptions, McpxPluginOptions, McpxRequestContext, McpxResolvedCapabilities, McpxTool, McpxToolExtra, defineMcpxTool };
+export { McpxAnyTool, McpxAuthResult, McpxCollectionCapabilities, McpxCollectionOptions, McpxExposedEntity, McpxGlobalOptions, McpxPluginOptions, McpxRequestContext, McpxResolvedCapabilities, McpxTool, McpxToolExtra, McpxToolScope, McpxWriteMode, PublishBlocker, defineMcpxTool };

package/dist/types.mjs

@@ -1,7 +1,6 @@
 //#region src/types.ts
-/**
-* Identity helper that infers the argument type of a custom tool's handler
-* from its input schema.
-*/ const defineMcpxTool = (tool) => tool;
+function defineMcpxTool(tool) {
+	return tool;
+}
 //#endregion
 export { defineMcpxTool };

package/dist/version.mjs

@@ -1,6 +1,6 @@
 //#region src/version.ts
 /**
 * Package version injected at build time; sources under Vitest report "dev".
-*/ const MCPX_VERSION = "0.0.0";
+*/ const MCPX_VERSION = "1.0.0";
 //#endregion
 export { MCPX_VERSION };

package/dist/write/draft-guard.mjs

@@ -1,10 +1,9 @@
+import { hasPublishIntent, takePublishIntent } from "./publish-intent.mjs";
+import { isMcpxRequest } from "../request.mjs";
 import { APIError } from "payload";
 import { hasDraftsEnabled } from "payload/shared";
 //#region src/write/draft-guard.ts
-/**
-* Operation arguments that widen or redirect a write. Cleared on every MCP
-* create and update so a tool cannot smuggle them in.
-*/ const STRIPPED_ARGS = /* @__PURE__ */ new Set([
+/** Cleared on every MCP write, publishes included, so none can be smuggled in. */ const STRIPPED_ARGS = /* @__PURE__ */ new Set([
 	"where",
 	"publishAllLocales",
 	"publishSpecificLocale",
@@ -14,26 +13,28 @@ import { hasDraftsEnabled } from "payload/shared";
 	"overwriteExistingFiles"
 ]);
 /**
-* Whether a request originated from the MCP endpoint. The endpoint stamps
-* `req.context.mcpx`, which travels into every local API call made with the
-* same `req`, including those made by custom tools.
-*/ const isMcpxRequest = (req) => req.context.mcpx !== void 0;
-/**
-* Forces every MCP write into a draft save.
+* 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.
-* This runs as `beforeOperation`, before Payload reads any of these arguments,
-* so it holds for every create and update on an MCP request, not only the
-* builtin tools. Deletes are not guarded in v1; custom tools that delete are
-* the integrator's responsibility.
-*/ const scrubWriteArgs = (args) => {
+* 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)));
 	if (next["data"] && typeof next["data"] === "object") {
 		const { _status: _ignoredStatus, deletedAt: _ignoredDeletedAt, ...data } = next["data"];
-		next["data"] = data;
+		next["data"] = publishing ? {
+			...data,
+			_status: "published"
+		} : data;
 	}
-	next["draft"] = true;
+	next["draft"] = !publishing;
 	next["autosave"] = false;
 	next["overrideLock"] = false;
 	next["trash"] = false;
@@ -42,52 +43,54 @@ import { hasDraftsEnabled } from "payload/shared";
 const forceDraftWrite = (hookArgs) => {
 	const { args, operation, req } = hookArgs;
 	if (!isMcpxRequest(req) || operation !== "create" && operation !== "update") return args;
-	return scrubWriteArgs(args);
+	const publishing = operation === "update" && hasPublishIntent(args.data);
+	return scrubWriteArgs(args, publishing);
 };
 /**
-* The global counterpart of {@link forceDraftWrite}. Payload invokes a global's
-* `beforeOperation` with the whole argument bag and assigns the result back,
-* exactly as the collection path does and before it reads `draft`,
-* `publishAllLocales` or `data._status`, so the guard has the same reach here:
-* every MCP write to a global, builtin tool or custom.
-*
-* The global operation union has no `create` member because a global always
-* exists, so only `update` is intercepted. `STRIPPED_ARGS` covers the three
-* publish vectors `updateGlobal` accepts; the rest of the set does not exist on
-* that signature and filtering it is a harmless no-op. `slug` survives the
-* filter, so the operation still knows what it is updating.
+* 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.
 */ const forceDraftWriteGlobal = (hookArgs) => {
 	const { operation, req } = hookArgs;
 	const args = hookArgs.args;
 	if (!isMcpxRequest(req) || operation !== "update") return args;
-	return scrubWriteArgs(args);
+	return scrubWriteArgs(args, hasPublishIntent(args["data"]));
 };
 /**
-* Refuses an MCP write that would still not land as a draft. An alarm rather
-* than the guarantee: `forceDraftWrite` should make it unreachable. It throws
-* instead of correcting `_status` because Payload has already chosen the write
-* branch by the time a `beforeChange` hook runs.
-*/ const refuseUnlessDraft = (req, slug, data) => {
+* 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 publishing = takePublishIntent(data);
 	if (!isMcpxRequest(req)) return;
 	const status = data._status;
-	if (status === "draft") return;
-	req.payload.logger.warn(`[payloadcms-mcpx] Refused a write to ${slug} that would not have been a draft (_status: ${String(status)}).`);
-	throw new APIError("MCP clients may only write drafts. This write was refused because it would not have been saved as one.", 403);
+	const expected = publishing ? "published" : "draft";
+	if (status === expected) return;
+	req.payload.logger.warn(`[payloadcms-mcpx] Refused a write to ${slug} that would not have been a ${expected} (_status: ${String(status)}).`);
+	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);
 };
-const refusePublish = ({ collection, data, req }) => {
-	refuseUnlessDraft(req, collection.slug, data);
+/**
+* Installs {@link refuseUnlessExpected} on every collection write. Returns
+* `data` unchanged when the write is allowed; the hook exists for its throw.
+*/ const refusePublish = ({ collection, data, req }) => {
+	refuseUnlessExpected(req, collection.slug, data);
 	return data;
 };
-/** The global counterpart of {@link refusePublish}. */ const refusePublishGlobal = ({ data, global, req }) => {
+const refusePublishGlobal = ({ data, global, req }) => {
 	const next = data;
-	refuseUnlessDraft(req, global.slug, next);
+	refuseUnlessExpected(req, global.slug, next);
 	return next;
 };
 /**
 * 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.
+* without being covered. Both are appended last, so a user hook cannot win.
 */ const installDraftGuards = (collections) => collections.map((collection) => ({
 	...collection,
 	hooks: {
@@ -110,4 +113,4 @@ const refusePublish = ({ collection, data, req }) => {
 	}
 }));
 //#endregion
-export { forceDraftWrite, forceDraftWriteGlobal, installDraftGuards, installGlobalDraftGuards, isMcpxRequest, refusePublish, refusePublishGlobal };
+export { forceDraftWrite, forceDraftWriteGlobal, installDraftGuards, installGlobalDraftGuards, refusePublish, refusePublishGlobal };