@abinnovision/payloadcms-mcpx 1.0.0-beta.4 → 1.0.0-beta.6

package/dist/tools/target.mjs

@@ -0,0 +1,49 @@
+import { APIError, Forbidden } from "payload";
+//#region src/tools/target.ts
+const refOf = (target) => ({
+	kind: target.kind,
+	slug: target.slug
+});
+/**
+* Resolves the `collection`/`global` arguments to one entity and checks the key
+* may perform `operation` on it.
+*
+* A tool's `inputSchema` returns a raw shape, which leaves no top-level
+* `.refine` to express "exactly one of collection and global". The rule is
+* enforced here instead, with a message naming the offending arguments so one
+* failed call teaches it.
+*/ const resolveTarget = (scope, args, operation) => {
+	const { collection, global } = args;
+	if (collection !== void 0 && global !== void 0) throw new APIError("Pass either \"collection\" or \"global\", not both.", 400);
+	if (collection === void 0 && global === void 0) throw new APIError("One of \"collection\" or \"global\" is required. Call listCapabilities to see which slugs are available.", 400);
+	if (collection !== void 0) {
+		const allowed = operation === "read" ? scope.readable : scope.writable;
+		const found = scope.req.payload.collections[collection];
+		if (!allowed.includes(collection) || !found) throw new Forbidden(scope.req.t);
+		return {
+			kind: "collection",
+			slug: collection,
+			config: found.config
+		};
+	}
+	const slug = global;
+	const allowed = operation === "read" ? scope.readableGlobals : scope.writableGlobals;
+	const found = scope.req.payload.globals.config.find((candidate) => candidate.slug === slug);
+	if (!allowed.includes(slug) || !found) throw new Forbidden(scope.req.t);
+	return {
+		kind: "global",
+		slug,
+		config: found
+	};
+};
+/**
+* Checks `id` against the resolved target. A collection document needs one; a
+* global is a singleton and must not carry one. The schema cannot express the
+* dependency, so it is stated here and in every affected tool description.
+*/ const requireIdFor = (target, id) => {
+	if (target.kind === "collection" && id === void 0) throw new APIError(`"id" is required when "collection" is "${target.slug}".`, 400);
+	if (target.kind === "global" && id !== void 0) throw new APIError(`"id" must be omitted when "global" is "${target.slug}"; a global is a singleton.`, 400);
+	return target.kind === "collection" ? id : void 0;
+};
+//#endregion
+export { refOf, requireIdFor, resolveTarget };

package/dist/tools/types.d.mts

@@ -0,0 +1,5 @@
+import "../types.mjs";
+import "../options.mjs";
+import { PayloadRequest } from "payload";
+import { z } from "zod";
+import { CallToolResult, ToolAnnotations } from "@modelcontextprotocol/sdk/types.js";

package/dist/tools/validate-document.mjs

@@ -1,43 +1,50 @@
 import { jsonResult } from "../endpoint/result.mjs";
-import { collectionEnum, ensureAllowed, idSchema, localeOf, localeShape, readDraft } from "./shared.mjs";
+import { idShape, localeOf, localeShape, readTarget, targetShape } from "./shared.mjs";
+import { requireIdFor, resolveTarget } from "./target.mjs";
 import { collectPublishBlockers } from "../write/publish-blockers.mjs";
 //#region src/tools/validate-document.ts
 const validateDocument = {
 	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".`,
+	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
 	},
-	isEnabled: (scope) => scope.writable.length > 0,
+	isEnabled: (scope) => scope.writable.length + scope.writableGlobals.length > 0,
 	inputSchema: (scope) => ({
-		collection: collectionEnum(scope.writable).describe("Collection holding the document."),
-		id: idSchema,
+		...targetShape(scope, "write", {
+			collection: "Collection holding the document.",
+			global: "Global to validate."
+		}),
+		...idShape(scope, "write"),
 		...localeShape(scope, {
 			required: true,
 			description: "Locale to validate."
 		})
 	}),
 	handler: async (args, scope) => {
-		const collection = ensureAllowed(scope, args.collection, "write");
+		const target = resolveTarget(scope, args, "write");
+		const id = requireIdFor(target, args.id);
 		const locale = localeOf(scope, args.locale);
-		await readDraft(scope, {
-			collection: args.collection,
-			id: args.id,
+		await readTarget(scope, {
+			target,
+			id,
 			locale
 		});
-		const doc = await readDraft(scope, {
-			collection: args.collection,
-			id: args.id,
+		const doc = await readTarget(scope, {
+			target,
+			id,
 			locale,
 			privileged: true
 		});
 		const publishBlockers = await collectPublishBlockers(scope.req, {
-			collection,
-			doc
+			doc,
+			entity: target
 		});
 		return jsonResult({
-			id: doc["id"],
+			...target.kind === "collection" ? { id: doc["id"] } : { global: target.slug },
 			status: doc["_status"],
 			updatedAt: doc["updatedAt"],
 			publishBlockers

package/dist/types.d.mts

@@ -1,4 +1,4 @@
-import { CollectionConfig, CollectionSlug, PayloadRequest, TypedUser } from "payload";
+import { CollectionConfig, CollectionSlug, GlobalSlug, PayloadRequest, TypedUser } from "payload";
 import { z } from "zod";
 import { RequestHandlerExtra } from "@modelcontextprotocol/sdk/shared/protocol.js";
 import { CallToolResult, ServerNotification, ServerRequest, ToolAnnotations } from "@modelcontextprotocol/sdk/types.js";
@@ -29,6 +29,26 @@ interface McpxCollectionOptions {
    */
   allowLiveWrites?: boolean;
 }
+/**
+ * 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.
+ */
+interface McpxGlobalOptions {
+  /** Expose `describeSchema` and `getDocument`. Default `true`. */
+  read?: boolean;
+  /**
+   * Expose `patchDocument` and `validateDocument`. Default `false`. Requires
+   * `versions.drafts` unless `allowLiveWrites` is set.
+   */
+  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;
+}
 type McpxToolExtra = RequestHandlerExtra<ServerRequest, ServerNotification>;
 /**
  * A custom tool. It is gated by its own checkbox on every API key and runs
@@ -63,6 +83,8 @@ interface McpxAuthResult {
 type McpxPluginOptions = {
   /** Allow-list of collections. `true` is shorthand for `{ read: true }`. */
   collections: Partial<Record<CollectionSlug, McpxCollectionOptions | true>>;
+  /** Allow-list of globals. `true` is shorthand for `{ read: true }`. */
+  globals?: Partial<Record<GlobalSlug, McpxGlobalOptions | true>>;
   /** Collection the keys act as. Default `config.admin.user`, then `users`. */
   userCollection?: CollectionSlug;
   apiKeys?: {
@@ -103,6 +125,7 @@ interface McpxCollectionCapabilities {
  */
 interface McpxResolvedCapabilities {
   collections: Record<string, McpxCollectionCapabilities>;
+  globals: Record<string, McpxCollectionCapabilities>;
   tools: Record<string, boolean>;
 }
 interface McpxRequestContext {
@@ -110,4 +133,4 @@ interface McpxRequestContext {
   capabilities: McpxResolvedCapabilities;
 }
 //#endregion
-export { McpxAuthResult, McpxCollectionCapabilities, McpxCollectionOptions, McpxPluginOptions, McpxRequestContext, McpxResolvedCapabilities, McpxTool, McpxToolExtra, defineMcpxTool };
+export { McpxAuthResult, McpxCollectionCapabilities, McpxCollectionOptions, McpxGlobalOptions, McpxPluginOptions, McpxRequestContext, McpxResolvedCapabilities, McpxTool, McpxToolExtra, defineMcpxTool };

package/dist/write/draft-guard.mjs

@@ -27,9 +27,7 @@ import { hasDraftsEnabled } from "payload/shared";
 * 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 forceDraftWrite = (hookArgs) => {
-	const { args, operation, req } = hookArgs;
-	if (!isMcpxRequest(req) || operation !== "create" && operation !== "update") return args;
+*/ const scrubWriteArgs = (args) => {
 	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"];
@@ -41,18 +39,50 @@ import { hasDraftsEnabled } from "payload/shared";
 	next["trash"] = false;
 	return next;
 };
+const forceDraftWrite = (hookArgs) => {
+	const { args, operation, req } = hookArgs;
+	if (!isMcpxRequest(req) || operation !== "create" && operation !== "update") return args;
+	return scrubWriteArgs(args);
+};
+/**
+* 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.
+*/ const forceDraftWriteGlobal = (hookArgs) => {
+	const { operation, req } = hookArgs;
+	const args = hookArgs.args;
+	if (!isMcpxRequest(req) || operation !== "update") return args;
+	return scrubWriteArgs(args);
+};
 /**
 * 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 refusePublish = ({ collection, data, req }) => {
-	if (!isMcpxRequest(req)) return data;
+*/ const refuseUnlessDraft = (req, slug, data) => {
+	if (!isMcpxRequest(req)) return;
 	const status = data._status;
-	if (status === "draft") return data;
-	req.payload.logger.warn(`[payloadcms-mcpx] Refused a write to ${collection.slug} that would not have been a draft (_status: ${String(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 refusePublish = ({ collection, data, req }) => {
+	refuseUnlessDraft(req, collection.slug, data);
+	return data;
+};
+/** The global counterpart of {@link refusePublish}. */ const refusePublishGlobal = ({ data, global, req }) => {
+	const next = data;
+	refuseUnlessDraft(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
@@ -66,5 +96,18 @@ import { hasDraftsEnabled } from "payload/shared";
 		...hasDraftsEnabled(collection) ? { beforeChange: [...collection.hooks?.beforeChange ?? [], refusePublish] } : {}
 	}
 }));
+/**
+* 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.
+*/ const installGlobalDraftGuards = (globals) => globals.map((global) => ({
+	...global,
+	hooks: {
+		...global.hooks,
+		beforeOperation: [...global.hooks?.beforeOperation ?? [], forceDraftWriteGlobal],
+		...hasDraftsEnabled(global) ? { beforeChange: [...global.hooks?.beforeChange ?? [], refusePublishGlobal] } : {}
+	}
+}));
 //#endregion
-export { forceDraftWrite, installDraftGuards, isMcpxRequest, refusePublish };
+export { forceDraftWrite, forceDraftWriteGlobal, installDraftGuards, installGlobalDraftGuards, isMcpxRequest, refusePublish, refusePublishGlobal };

package/dist/write/patch.mjs

@@ -126,9 +126,9 @@ const isPlainObject = (value) => typeof value === "object" && value !== null &&
 		for (const pointer of pointers) {
 			const resolution = resolveDataPointer(config, {
 				addedValue: value ?? moved,
-				collection: target.collection,
 				doc: target.doc,
-				pointer
+				pointer,
+				ref: target.ref
 			});
 			if (pointer === operation.path && value !== void 0) return validateWriteValue(config, {
 				pointer,
@@ -208,9 +208,9 @@ const isPlainObject = (value) => typeof value === "object" && value !== null &&
 /**
 * The data handed to `payload.update` after a patch: the patched document
 * reduced to the fields the client may write, plus row identity keys.
-*/ const buildWriteData = (config, collection, doc) => {
+*/ const buildWriteData = (config, target, doc) => {
 	return pickDescribed(config, doc, {
-		fields: collection.flattenedFields,
+		fields: target.flattenedFields,
 		prefix: [],
 		isRow: false
 	});

package/dist/write/publish-blockers.d.mts

@@ -1,3 +1,4 @@
+import "../tools/target.mjs";
 import { PayloadRequest } from "payload";
 //#region src/write/publish-blockers.d.ts
 /**

package/dist/write/publish-blockers.mjs

@@ -19,19 +19,20 @@ import { beforeChangeTraverseFields, beforeValidateTraverseFields } from "payloa
 * Limits: only the locale the doc was read in is checked, and field-level
 * `beforeChange` hooks run again, which is safe only for pure ones.
 */ const collectPublishBlockers = async (req, target) => {
-	const { collection, doc } = target;
+	const { doc, entity } = target;
 	const id = doc["id"];
 	const errors = [];
 	const data = {
 		...structuredClone(doc),
 		_status: "published"
 	};
+	const context = { ...req.context };
 	const shared = {
-		collection,
-		context: { ...req.context },
+		collection: entity.kind === "collection" ? entity.config : null,
+		context,
 		data,
 		doc,
-		global: null,
+		global: entity.kind === "global" ? entity.config : null,
 		operation: "update",
 		overrideAccess: true,
 		parentIndexPath: "",
@@ -45,7 +46,7 @@ import { beforeChangeTraverseFields, beforeValidateTraverseFields } from "payloa
 	try {
 		await beforeValidateTraverseFields({
 			...shared,
-			fields: collection.fields,
+			fields: entity.config.fields,
 			siblingData: data
 		});
 		await beforeChangeTraverseFields({
@@ -53,14 +54,14 @@ import { beforeChangeTraverseFields, beforeValidateTraverseFields } from "payloa
 			docWithLocales: doc,
 			errors,
 			fieldLabelPath: "",
-			fields: collection.fields,
+			fields: entity.config.fields,
 			mergeLocaleActions: [],
 			siblingData: data,
 			siblingDocWithLocales: doc,
 			skipValidation: false
 		});
 	} catch (error) {
-		req.payload.logger.warn(`[payloadcms-mcpx] Could not validate the ${collection.slug} draft: ${error instanceof Error ? error.message : "unknown error"}`);
+		req.payload.logger.warn(`[payloadcms-mcpx] Could not validate the ${entity.slug} draft: ${error instanceof Error ? error.message : "unknown error"}`);
 		return [];
 	}
 	return errors.map((error) => ({

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "@abinnovision/payloadcms-mcpx",
-  "version": "1.0.0-beta.4",
+  "version": "1.0.0-beta.6",
   "description": "Payload CMS plugin exposing a fixed, schema-aware MCP tool surface with draft-only writes and per-API-key capabilities.",
   "keywords": [
     "payload",