@abinnovision/payloadcms-mcpx 1.0.0-beta.10

package/dist/write/draft-guard.mjs

@@ -0,0 +1,113 @@
+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([
+	"where",
+	"publishAllLocales",
+	"publishSpecificLocale",
+	"unpublishAllLocales",
+	"duplicateFromID",
+	"selectedLocales",
+	"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.
+*
+* `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) => {
+	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["draft"] = true;
+	next["autosave"] = false;
+	next["overrideLock"] = false;
+	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 refuseUnlessDraft = (req, slug, 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 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
+* exist. Applied to the built collection list so nothing can join later
+* without being covered.
+*/ const installDraftGuards = (collections) => collections.map((collection) => ({
+	...collection,
+	hooks: {
+		...collection.hooks,
+		beforeOperation: [...collection.hooks?.beforeOperation ?? [], forceDraftWrite],
+		...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, forceDraftWriteGlobal, installDraftGuards, installGlobalDraftGuards, isMcpxRequest, refusePublish, refusePublishGlobal };

package/dist/write/patch.mjs

@@ -0,0 +1,219 @@
+import { JSON_POINTER_PATTERN, RESERVED_FIELD_NAMES, blockOf, describeAddressableFields, findBlocksField, splitPath } from "../schema/walk.mjs";
+import { validateWriteValue } from "../schema/shape.mjs";
+import { resolveDataPointer } from "../schema/pointer.mjs";
+import { z } from "zod";
+import { Pointer, applyPatch } from "rfc6902";
+//#region src/write/patch.ts
+/**
+* One RFC 6902 operation as accepted by `patchDocument`.
+*/ const PATCH_OPERATION_SCHEMA = z.object({
+	from: z.string().regex(JSON_POINTER_PATTERN).optional(),
+	op: z.enum([
+		"add",
+		"copy",
+		"move",
+		"remove",
+		"replace",
+		"test"
+	]),
+	path: z.string().regex(JSON_POINTER_PATTERN),
+	value: z.unknown().optional()
+}).describe("An RFC 6902 operation.");
+/**
+* Whether a pointer touches a field Payload maintains.
+*/ const isReservedPointer = (pointer) => pointer.split("/").slice(1).some((segment) => RESERVED_FIELD_NAMES.has(segment));
+/**
+* The pointer an operation removes a value from, if it removes one at all.
+*/ const droppedPointer = (operation) => {
+	if (operation.op === "remove") return operation.path;
+	return operation.op === "move" ? operation.from : void 0;
+};
+/**
+* Whether a pointer addresses a list element rather than a field.
+*/ const isElementPointer = (pointer) => {
+	const last = pointer.split("/").pop() ?? "";
+	return last === "-" || /^\d+$/.test(last);
+};
+const isPlainObject = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+/**
+* A Lexical editor state. Its nodes manage their own ids, so it is never
+* descended into.
+*/ const isRichTextState = (value) => isPlainObject(value["root"]) && Array.isArray(value["root"]["children"]);
+/**
+* Visits every row in a value: a plain object that carries `blockType` or
+* sits directly inside an array. Rich text states manage their own nodes and
+* are never descended into.
+*/ const walkRows = (value, visit, isRow = false) => {
+	if (Array.isArray(value)) {
+		for (const entry of value) walkRows(entry, visit, true);
+		return;
+	}
+	if (!isPlainObject(value) || isRichTextState(value)) return;
+	if (isRow || typeof value["blockType"] === "string") visit(value);
+	for (const entry of Object.values(value)) walkRows(entry, visit);
+};
+/**
+* Keeps a row id only when the stored document already has it and no earlier
+* row in the write claimed it; every other id is dropped so Payload assigns a
+* fresh one.
+*
+* A kept id makes Payload update the row in place, which preserves the other
+* locales of any localized field inside it. A duplicated id (a copied row) or
+* an id from elsewhere would violate a SQL primary key, so those never pass.
+*/ const reconcileRowIds = (next, stored) => {
+	const known = /* @__PURE__ */ new Set();
+	walkRows(stored, (row) => {
+		if (row["id"] !== void 0) known.add(row["id"]);
+	});
+	const seen = /* @__PURE__ */ new Set();
+	walkRows(next, (row) => {
+		const id = row["id"];
+		if (id === void 0) return;
+		if (known.has(id) && !seen.has(id)) {
+			seen.add(id);
+			return;
+		}
+		delete row["id"];
+	});
+};
+/**
+* Drops every row id from a copy of `value`. Used on create, where no stored
+* row exists and any incoming id is client-invented.
+*/ const stripRowIds = (value) => {
+	const next = structuredClone(value);
+	walkRows(next, (row) => {
+		delete row["id"];
+	});
+	return next;
+};
+/**
+* Applies a patch to a deep copy of the document, so a failing operation
+* leaves the original untouched and nothing partial is ever written.
+*/ const applyPatchToCopy = (doc, patches) => {
+	const next = structuredClone(doc);
+	const prepared = patches.map((operation) => {
+		const cloned = "value" in operation ? {
+			...operation,
+			value: structuredClone(operation.value)
+		} : operation;
+		if (cloned.op === "replace" && !isElementPointer(cloned.path) && Pointer.fromJSON(cloned.path).get(next) === void 0) return {
+			...cloned,
+			op: "add"
+		};
+		return cloned;
+	});
+	const problems = applyPatch(next, prepared).flatMap((error, index) => error ? [`patches[${String(index)}]: ${error.message}`] : []);
+	if (problems.length > 0) return { problems };
+	reconcileRowIds(next, doc);
+	return { next };
+};
+/**
+* Checks every operation against the schema before any is applied.
+*
+* A partially applied batch is worse than a refused one, so this returns all
+* problems and the caller applies nothing unless the list is empty.
+*/ const findPatchProblems = (config, target) => target.patches.flatMap((operation, index) => {
+	const at = `patches[${String(index)}]`;
+	const pointers = [operation.path, ..."from" in operation && operation.from ? [operation.from] : []];
+	if (pointers.includes("")) return [`${at}: an empty pointer addresses the whole document. Address a field instead.`];
+	const reserved = pointers.find(isReservedPointer);
+	if (reserved !== void 0) return [`${at}: "${reserved}" addresses a field Payload maintains. Drafts are the only thing this tool writes, and id, _status, createdAt and updatedAt are not writable.`];
+	const dropped = droppedPointer(operation);
+	if (dropped !== void 0 && !isElementPointer(dropped)) return [`${at}: "${dropped}" is a field, not a list element, and removing it would do nothing. The patched document is written whole, and Payload keeps any field absent from a write rather than clearing it. Use "replace" with null to clear a field, or with [] to empty a list.`];
+	const value = "value" in operation ? operation.value : void 0;
+	try {
+		const moved = "from" in operation && operation.from ? Pointer.fromJSON(operation.from).get(target.doc) : void 0;
+		for (const pointer of pointers) {
+			const resolution = resolveDataPointer(config, {
+				addedValue: value ?? moved,
+				doc: target.doc,
+				pointer,
+				ref: target.ref
+			});
+			if (pointer === operation.path && value !== void 0) return validateWriteValue(config, {
+				pointer,
+				resolution
+			}, value).map((problem) => `${at}: ${problem}`);
+		}
+		return [];
+	} catch (error) {
+		return [`${at}: ${error instanceof Error ? error.message : "invalid"}`];
+	}
+});
+/**
+* Keys Payload manages on a row that travel back into the write unchanged.
+*/ const ROW_KEYS = /* @__PURE__ */ new Set([
+	"blockName",
+	"blockType",
+	"id"
+]);
+/**
+* Picks the keys the schema walker describes out of `value`, descending into
+* groups, named tabs, arrays and blocks. Everything Payload maintains or
+* derives (`_status`, timestamps, join and virtual fields, upload base fields)
+* is left out, so the write-back carries only what a client could have set.
+*/ const pickDescribed = (config, value, at) => {
+	const { fields, prefix, isRow } = at;
+	const relative = describeAddressableFields(fields).flatMap((descriptor) => {
+		const parts = splitPath(descriptor.path);
+		return prefix.every((part, offset) => part === parts[offset]) ? [{
+			descriptor,
+			parts: parts.slice(prefix.length)
+		}] : [];
+	});
+	const result = {};
+	if (isRow) {
+		for (const key of ROW_KEYS) if (key in value) result[key] = value[key];
+	}
+	for (const [key, entry] of Object.entries(value)) {
+		const candidates = relative.filter(({ parts }) => parts[0] === key);
+		if (candidates.length === 0) continue;
+		const exact = candidates.find(({ parts }) => parts.length === 1);
+		if (exact?.descriptor.type === "blocks" && Array.isArray(entry)) {
+			const field = findBlocksField(fields, splitPath(exact.descriptor.path));
+			result[key] = entry.map((row) => {
+				const block = field && isPlainObject(row) && typeof row["blockType"] === "string" ? blockOf(config, field, row["blockType"]) : void 0;
+				return block && isPlainObject(row) ? pickDescribed(config, row, {
+					fields: block.flattenedFields,
+					prefix: [],
+					isRow: true
+				}) : row;
+			});
+			continue;
+		}
+		if (exact) {
+			result[key] = entry;
+			continue;
+		}
+		if (candidates.some(({ parts }) => parts[1] === "*")) {
+			result[key] = Array.isArray(entry) ? entry.map((row) => isPlainObject(row) ? pickDescribed(config, row, {
+				fields,
+				prefix: [
+					...prefix,
+					key,
+					"*"
+				],
+				isRow: true
+			}) : row) : entry;
+			continue;
+		}
+		result[key] = isPlainObject(entry) ? pickDescribed(config, entry, {
+			fields,
+			prefix: [...prefix, key],
+			isRow: false
+		}) : entry;
+	}
+	return result;
+};
+/**
+* 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, target, doc) => {
+	return pickDescribed(config, doc, {
+		fields: target.flattenedFields,
+		prefix: [],
+		isRow: false
+	});
+};
+//#endregion
+export { PATCH_OPERATION_SCHEMA, applyPatchToCopy, buildWriteData, droppedPointer, findPatchProblems, isElementPointer, isReservedPointer, stripRowIds };

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

@@ -0,0 +1,15 @@
+import "../tools/target.mjs";
+import { PayloadRequest } from "payload";
+//#region src/write/publish-blockers.d.ts
+/**
+ * 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 type { PublishBlocker };

package/dist/write/publish-blockers.mjs

@@ -0,0 +1,74 @@
+import { pointerFromPayloadPath } from "../schema/walk.mjs";
+import { beforeChangeTraverseFields, beforeValidateTraverseFields } from "payload";
+//#region src/write/publish-blockers.ts
+/**
+* Runs Payload's own field validation over a draft without saving anything.
+*
+* Draft saves skip validation unless `versions.drafts.validate` is set, so an
+* agent building a document incrementally gets no signal until a human presses
+* Publish. This is the same traversal a real save runs, exported from
+* `payload`, called with `skipValidation: false` so it collects into `errors`
+* instead of throwing. The `beforeValidate` pass runs first because some field
+* hooks (Lexical's) prepare state in `context` that their `beforeChange`
+* counterpart depends on.
+*
+* Nothing is written: `data` is a copy, the context is a scratch copy and the
+* locale merge actions are discarded. `overrideAccess` is true because the
+* question is "could this be published", not "may this client write it".
+*
+* 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 { doc, entity } = target;
+	const id = doc["id"];
+	const errors = [];
+	const data = {
+		...structuredClone(doc),
+		_status: "published"
+	};
+	const context = { ...req.context };
+	const shared = {
+		collection: entity.kind === "collection" ? entity.config : null,
+		context,
+		data,
+		doc,
+		global: entity.kind === "global" ? entity.config : null,
+		operation: "update",
+		overrideAccess: true,
+		parentIndexPath: "",
+		parentIsLocalized: false,
+		parentPath: "",
+		parentSchemaPath: "",
+		req,
+		siblingDoc: doc,
+		...id === void 0 ? {} : { id }
+	};
+	try {
+		await beforeValidateTraverseFields({
+			...shared,
+			fields: entity.config.fields,
+			siblingData: data
+		});
+		await beforeChangeTraverseFields({
+			...shared,
+			docWithLocales: doc,
+			errors,
+			fieldLabelPath: "",
+			fields: entity.config.fields,
+			mergeLocaleActions: [],
+			siblingData: data,
+			siblingDocWithLocales: doc,
+			skipValidation: false
+		});
+	} catch (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) => ({
+		message: error.message,
+		path: pointerFromPayloadPath(error.path),
+		...typeof error.label === "string" ? { field: error.label } : {}
+	}));
+};
+//#endregion
+export { collectPublishBlockers };

package/dist/write/transaction.mjs

@@ -0,0 +1,19 @@
+import { commitTransaction, initTransaction, killTransaction } from "payload";
+//#region src/write/transaction.ts
+/**
+* Runs `fn` inside one database transaction on `req`, so a read followed by a
+* write cannot interleave with another writer. Adapters without transaction
+* support, or a request that already owns one, run `fn` as is.
+*/ const withTransaction = async (req, fn) => {
+	if (!await initTransaction(req)) return await fn();
+	try {
+		const result = await fn();
+		await commitTransaction(req);
+		return result;
+	} catch (error) {
+		await killTransaction(req);
+		throw error;
+	}
+};
+//#endregion
+export { withTransaction };

package/package.json

@@ -0,0 +1,104 @@
+{
+  "$schema": "https://json.schemastore.org/package.json",
+  "name": "@abinnovision/payloadcms-mcpx",
+  "version": "1.0.0-beta.10",
+  "description": "Payload CMS plugin exposing a fixed, schema-aware MCP tool surface with draft-only writes and per-API-key capabilities.",
+  "keywords": [
+    "payload",
+    "payloadcms",
+    "plugin",
+    "mcp",
+    "model-context-protocol"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/abinnovision/payloadcms-commons.git",
+    "directory": "packages/mcpx"
+  },
+  "license": "Apache-2.0",
+  "author": {
+    "name": "abi group GmbH",
+    "email": "info@abigroup.io",
+    "url": "https://abigroup.io"
+  },
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "default": "./dist/index.mjs"
+    },
+    "./client": {
+      "types": "./dist/client/index.d.mts",
+      "default": "./dist/client/index.mjs"
+    }
+  },
+  "files": [
+    "dist",
+    "LICENSE",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsdown",
+    "format:check": "prettier --check 'src/**/*.{ts,tsx}' 'test/**/*.ts' '*.{json{,5},md,y{,a}ml}'",
+    "format:fix": "prettier --write 'src/**/*.{ts,tsx}' 'test/**/*.ts' '*.{json{,5},md,y{,a}ml}'",
+    "lint:check": "eslint 'src/**/*.{ts,tsx}' 'test/**/*.ts'",
+    "lint:fix": "eslint 'src/**/*.{ts,tsx}' 'test/**/*.ts' --fix",
+    "test-integration": "vitest --run --config test/integration/vitest.config.mts",
+    "test-unit": "vitest --run --coverage --config vitest.config.mts",
+    "test-unit:watch": "vitest --config vitest.config.mts",
+    "typecheck": "tsc --noEmit"
+  },
+  "lint-staged": {
+    "{src,test}/**/*.{ts,tsx}": [
+      "eslint --fix",
+      "prettier --write"
+    ],
+    "*.{json{,5},md,y{,a}ml}": "prettier --write"
+  },
+  "prettier": "@abinnovision/prettier-config",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.30.0",
+    "rfc6902": "^5.3.0",
+    "zod": "^4.4.3"
+  },
+  "devDependencies": {
+    "@abinnovision/eslint-config-base": "^3.4.2",
+    "@abinnovision/prettier-config": "^2.2.0",
+    "@arethetypeswrong/core": "^0.18.5",
+    "@payloadcms/db-sqlite": "3.88.0",
+    "@payloadcms/richtext-lexical": "3.88.0",
+    "@payloadcms/ui": "3.88.0",
+    "@swc/core": "^1.16.1",
+    "@types/node": "^26.2.0",
+    "@types/react": "^19.2.18",
+    "@vitest/coverage-v8": "^4.1.10",
+    "eslint": "^10.7.0",
+    "payload": "3.88.0",
+    "prettier": "^3.9.5",
+    "publint": "^0.3.24",
+    "react": "^19.2.8",
+    "react-dom": "^19.2.8",
+    "tsdown": "^0.22.14",
+    "typescript": "^6.0.3",
+    "unplugin-swc": "^1.5.11",
+    "vitest": "^4.1.10"
+  },
+  "peerDependencies": {
+    "@payloadcms/ui": ">=3.88.0 <4",
+    "payload": ">=3.88.0 <4",
+    "react": "^19"
+  },
+  "peerDependenciesMeta": {
+    "@payloadcms/ui": {
+      "optional": true
+    },
+    "react": {
+      "optional": true
+    }
+  },
+  "publishConfig": {
+    "ghpr": true,
+    "npm": true,
+    "npmAccess": "public"
+  }
+}