@abinnovision/payloadcms-mcpx 2.0.0-beta.15 → 2.0.0-beta.18

package/README.md

@@ -116,19 +116,20 @@ every check.
 
 ## Tools
 
-| Tool               | What it does                                                       | Needs     |
-| ------------------ | ------------------------------------------------------------------ | --------- |
-| `listCapabilities` | Lists what this key may do. Clients call it first.                 | any key   |
-| `describeSchema`   | Describes the fields at one schema path, with the paths below it.  | `read`    |
-| `findDocuments`    | Queries a collection with a Payload `where`, `sort` and `select`.  | `read`    |
-| `getDocument`      | Reads a document, a subtree of it, an old version or a diff.       | `read`    |
-| `findVersions`     | Lists the version history of a document or global, without bodies. | `read`    |
-| `patchDocument`    | Applies JSON Patch operations to the current draft, or a new file. | `write`   |
-| `createDocument`   | Creates a draft from a seed, with a file in an upload collection.  | `write`   |
-| `validateDocument` | Lists what blocks publishing, without saving.                      | `write`   |
-| `publishDocument`  | Publishes the current draft.                                       | `publish` |
-| `deleteDocument`   | Asks to delete a document, which the key's user approves.          | `delete`  |
-| `runConfirmed`     | Runs the approved calls.                                           | `delete`  |
+| Tool                | What it does                                                       | Needs     |
+| ------------------- | ------------------------------------------------------------------ | --------- |
+| `listCapabilities`  | Lists what this key may do. Clients call it first.                 | any key   |
+| `describeSchema`    | Describes the fields at one schema path, with the paths below it.  | `read`    |
+| `findDocuments`     | Queries a collection with a Payload `where`, `sort` and `select`.  | `read`    |
+| `getDocument`       | Reads a document, a subtree of it, an old version or a diff.       | `read`    |
+| `findVersions`      | Lists the version history of a document or global, without bodies. | `read`    |
+| `patchDocument`     | Applies JSON Patch operations to the current draft, or a new file. | `write`   |
+| `createDocument`    | Creates a draft from a seed, with a file in an upload collection.  | `write`   |
+| `duplicateDocument` | Copies a document into a new draft, in every locale.               | `write`   |
+| `validateDocument`  | Lists what blocks publishing, without saving.                      | `write`   |
+| `publishDocument`   | Publishes the current draft.                                       | `publish` |
+| `deleteDocument`    | Asks to delete a document, which the key's user approves.          | `delete`  |
+| `runConfirmed`      | Runs the approved calls.                                           | `delete`  |
 
 Collections and globals use the same tools. A tool that addresses one document takes either
 `collection` and `id`, or `global` alone. [`docs/concepts.md`](./docs/concepts.md#tools) lists

package/dist/builtin-tool-names.mjs

@@ -9,6 +9,7 @@
 	"findVersions",
 	"patchDocument",
 	"createDocument",
+	"duplicateDocument",
 	"validateDocument",
 	"publishDocument",
 	"deleteDocument",

package/dist/endpoint/server.mjs

@@ -33,7 +33,11 @@ const NO_CONFIRMATION = {
 	}
 };
 const WRITE_STEP = {
-	tools: ["patchDocument", "createDocument"],
+	tools: [
+		"patchDocument",
+		"createDocument",
+		"duplicateDocument"
+	],
 	does: "the write"
 };
 const WORKFLOW = [

package/dist/tools/builtin.mjs

@@ -1,6 +1,7 @@
 import { createDocument } from "./create-document.mjs";
 import { deleteDocument } from "./delete-document.mjs";
 import { describeSchema } from "./describe-schema.mjs";
+import { duplicateDocument } from "./duplicate-document.mjs";
 import { findDocuments } from "./find-documents.mjs";
 import { findVersions } from "./find-versions.mjs";
 import { getDocument } from "./get-document.mjs";
@@ -23,6 +24,7 @@ import { validateDocument } from "./validate-document.mjs";
 	findVersions,
 	patchDocument,
 	createDocument,
+	duplicateDocument,
 	validateDocument,
 	publishDocument,
 	deleteDocument,

package/dist/tools/create-document.mjs

@@ -6,6 +6,7 @@ import { collectPublishBlockers } from "../write/publish-blockers.mjs";
 import { assertAcceptsFile, fileShape, fileWriteRefusal, uploadHandoff, uploadedFile } from "../upload/file.mjs";
 import { liveWriteSentence, localeOf, localeShape, patchOnlySlugs, slugEnum, slugsFor } from "./shared.mjs";
 import { readDraft, resolveEntity } from "./document.mjs";
+import { documentLinks } from "./links.mjs";
 import { stripRowIds } from "../write/row-ids.mjs";
 import { z } from "zod";
 import { APIError } from "payload";
@@ -14,10 +15,40 @@ const uploadSentence = (scope) => {
 	const slugs = patchOnlySlugs(scope);
 	return slugs.length === 0 ? "" : ` Documents in ${slugs.join(", ")} are files and cannot be created here. Upload the file in the admin panel, then edit its fields with patchDocument.`;
 };
-const DESCRIPTION = (scope) => `Creates a document in a collection. Use it only when the document does not exist yet. Returns "id", "status", "updatedAt" and, if any, "publishBlockers". "publishBlockersUnavailable" means that check failed. "data" may leave required fields empty for patchDocument to fill later, except in a collection whose listCapabilities entry has "draftValidation" true or "drafts" false. A field describeSchema does not list is refused, and "id" is always assigned.
+const DESCRIPTION = (scope) => `Creates a document in a collection. Use it only when the document does not exist yet. Returns "id", "status", "updatedAt" and, if any, "publishBlockers". "publishBlockersUnavailable" means that check failed. "data" may leave required fields empty for patchDocument to fill later, except in a collection whose listCapabilities entry has "draftValidation" true or "drafts" false. A field describeSchema does not list is refused, and "id" is always assigned. The response links the document with "adminUrl" and "previewUrl".
 
 ${liveWriteSentence(scope, "create")}${uploadSentence(scope)}`;
 /**
+* What createDocument and duplicateDocument return: the new document, re-read
+* privileged in `locale`, with its links and publish blockers.
+*/ const createdResult = async (scope, args) => {
+	const { target, locale } = args;
+	const saved = await readDraft(scope, {
+		target: {
+			...target,
+			id: args.id
+		},
+		locale,
+		privileged: true
+	});
+	const validation = await collectPublishBlockers(scope.req, {
+		doc: saved,
+		entity: target
+	});
+	return jsonResult({
+		id: saved["id"],
+		status: saved["_status"],
+		updatedAt: saved["updatedAt"],
+		...await documentLinks(scope.req, {
+			target,
+			doc: saved,
+			locale
+		}),
+		...validation.blockers.length > 0 ? { publishBlockers: validation.blockers } : {},
+		...validation.unavailable ? { publishBlockersUnavailable: true } : {}
+	});
+};
+/**
 * Collection-only, because a global always exists. A create in an upload
 * collection needs `file`: the call then returns an upload grant, and the PUT
 * to it runs the call again with the bytes.
@@ -88,26 +119,12 @@ ${liveWriteSentence(scope, "create")}${uploadSentence(scope)}`;
 			...locale === void 0 ? {} : { locale },
 			...bytes === void 0 ? {} : { file: bytes }
 		});
-		const saved = await readDraft(scope, {
-			target: {
-				...target,
-				id: created["id"]
-			},
-			locale,
-			privileged: true
-		});
-		const validation = await collectPublishBlockers(scope.req, {
-			doc: saved,
-			entity: target
-		});
-		return jsonResult({
-			id: saved["id"],
-			status: saved["_status"],
-			updatedAt: saved["updatedAt"],
-			...validation.blockers.length > 0 ? { publishBlockers: validation.blockers } : {},
-			...validation.unavailable ? { publishBlockersUnavailable: true } : {}
+		return await createdResult(scope, {
+			target,
+			id: created["id"],
+			locale
 		});
 	}
 });
 //#endregion
-export { createDocument };
+export { createDocument, createdResult };

package/dist/tools/duplicate-document.mjs

@@ -0,0 +1,49 @@
+import { defineMcpxTool } from "../define-tool.mjs";
+import { idSchema, liveWriteSentence, localeOf, slugEnum, slugsFor } from "./shared.mjs";
+import { resolveEntity } from "./document.mjs";
+import { createdResult } from "./create-document.mjs";
+import { withDuplicateIntent } from "../write/publish-intent.mjs";
+import { Forbidden } from "payload";
+//#region src/tools/duplicate-document.ts
+const duplicableSlugs = (scope) => slugsFor(scope, "create").collections.filter((slug) => scope.req.payload.config.collections.find((collection) => collection.slug === slug)?.disableDuplicate !== true && !scope.exposure.collections.some((entity) => entity.slug === slug && entity.isUpload));
+const DESCRIPTION = (scope) => `Copies a document into a new one in the same collection. Use it instead of getDocument and createDocument to copy a document. It copies the latest version, the draft if there is one, in every locale. Unique text fields get " - Copy" appended. Returns the same fields as createDocument. To rename the copy, call patchDocument with the returned "updatedAt".
+
+${liveWriteSentence(scope, "create")}`;
+/**
+* Wraps Payload's duplicate, which checks read access on the source and create
+* access on the copy, and runs the fields' `beforeDuplicate` hooks.
+*/ const duplicateDocument = defineMcpxTool({
+	name: "duplicateDocument",
+	description: DESCRIPTION,
+	annotations: {
+		readOnlyHint: false,
+		destructiveHint: false,
+		idempotentHint: false,
+		openWorldHint: false
+	},
+	isEnabled: (scope) => duplicableSlugs(scope).length > 0,
+	inputSchema: (scope) => ({
+		collection: slugEnum(duplicableSlugs(scope)),
+		id: idSchema
+	}),
+	handler: async ({ args, scope }) => {
+		const target = resolveEntity(scope, { collection: args.collection }, "create");
+		if (target.kind === "global" || !duplicableSlugs(scope).includes(target.slug)) throw new Forbidden(scope.req.t);
+		const created = await scope.req.payload.duplicate({
+			collection: target.slug,
+			id: args.id,
+			data: withDuplicateIntent({}),
+			depth: 0,
+			draft: true,
+			overrideAccess: false,
+			req: scope.req
+		});
+		return await createdResult(scope, {
+			target,
+			id: created["id"],
+			locale: localeOf(scope, void 0)
+		});
+	}
+});
+//#endregion
+export { duplicateDocument };

package/dist/tools/links.mjs

@@ -0,0 +1,52 @@
+import { formatAdminURL } from "payload/shared";
+//#region src/tools/links.ts
+const livePreviewOf = (req, target) => {
+	if (target.config.admin.livePreview) return target.config.admin.livePreview;
+	const root = req.payload.config.admin.livePreview;
+	return (target.kind === "collection" ? root?.collections : root?.globals)?.includes(target.slug) ? root : void 0;
+};
+const previewOf = async (req, args) => {
+	const { target, doc, locale } = args;
+	const { preview } = target.config.admin;
+	if (preview) return await preview(doc, {
+		locale: locale ?? "",
+		req,
+		token: null
+	});
+	const url = livePreviewOf(req, target)?.url;
+	if (typeof url !== "function") return url;
+	const { localization } = req.payload.config;
+	const entry = localization ? localization.locales.find((item) => item.code === locale) : void 0;
+	return await url({
+		...target.kind === "collection" ? { collectionConfig: target.config } : { globalConfig: target.config },
+		data: doc,
+		locale: entry ?? {
+			code: locale ?? "",
+			label: locale ?? ""
+		},
+		payload: req.payload,
+		req
+	});
+};
+/**
+* The admin panel URL of a written document, and its preview URL where the
+* entity configures one. Both sit at the origin of `serverURL` when set, else
+* of the MCP request. A preview that fails is left out: the write has landed.
+*/ const documentLinks = async (req, args) => {
+	const { target, doc, locale } = args;
+	const { config } = req.payload;
+	const origin = config.serverURL || new URL(req.url ?? "").origin;
+	const path = target.kind === "collection" ? `/collections/${target.slug}/${String(doc["id"])}` : `/globals/${target.slug}`;
+	const adminUrl = formatAdminURL({
+		adminRoute: config.routes.admin,
+		path,
+		serverURL: origin
+	});
+	const preview = await previewOf(req, args).catch(() => void 0);
+	return {
+		adminUrl: locale ? `${adminUrl}?locale=${encodeURIComponent(locale)}` : adminUrl,
+		...preview ? { previewUrl: new URL(preview, origin).toString() } : {}
+	};
+};
+//#endregion
+export { documentLinks };

package/dist/tools/patch-document.mjs

@@ -7,6 +7,7 @@ import { collectPublishBlockers } from "../write/publish-blockers.mjs";
 import { assertAcceptsFile, fileShape, fileSlugs, fileWriteRefusal, uploadHandoff, uploadedFile } from "../upload/file.mjs";
 import { entityShape, idShape, liveWriteSentence, localeOf, localeShape } from "./shared.mjs";
 import { identityOf, readDraft, resolveDocument, staleReadResult } from "./document.mjs";
+import { documentLinks } from "./links.mjs";
 import { withTransaction } from "../write/transaction.mjs";
 import { applyPatchOperations, isElementPointer } from "../write/patch.mjs";
 import { buildWriteData } from "../write/write-data.mjs";
@@ -22,7 +23,7 @@ Read the document with getDocument right before patching. Append to a list with
 
 In a rich text field a pointer continues into the rich text state: "/content/root/children/2" is a node, "/content/root/children/2/tag" one of its properties and "/content/root/children/3/fields/tone" a field of a block node. getDocument "outline" lists each node's pointer and "version". Build nodes from describeSchema "nodeProperties". Check a position before writing to it, e.g. {"op":"test","path":"/content/root/children/2/type","value":"heading"}.
 
-The response carries "updatedAt" and, if any, "publishBlockers": what must be fixed before publishing. "publishBlockersUnavailable" means that check failed. The write stands either way. "notApplied" lists pointers whose value did not change or cannot be read back, for example where field access denies the update.`;
+The response carries "updatedAt" and, if any, "publishBlockers": what must be fixed before publishing. "publishBlockersUnavailable" means that check failed. The write stands either way. "notApplied" lists pointers whose value did not change or cannot be read back, for example where field access denies the update. The response links the document with "adminUrl" and "previewUrl".`;
 const POINTER = z.string().regex(JSON_POINTER_PATTERN);
 const PATCHES_LIMIT = 500;
 /**
@@ -130,6 +131,11 @@ const notAppliedPointers = (patches, intended, saved) => patches.flatMap((operat
 				...identityOf(target, saved["id"]),
 				status: saved["_status"],
 				updatedAt: saved["updatedAt"],
+				...await documentLinks(scope.req, {
+					target,
+					doc: saved,
+					locale
+				}),
 				...validation.blockers.length > 0 ? { publishBlockers: validation.blockers } : {},
 				...validation.unavailable ? { publishBlockersUnavailable: true } : {},
 				...notApplied.length > 0 ? { notApplied } : {}

package/dist/tools/publish-document.mjs

@@ -2,6 +2,7 @@ import { defineMcpxTool } from "../define-tool.mjs";
 import { jsonResult } from "../result.mjs";
 import { entityShape, idShape, localeOf, localeShape } from "./shared.mjs";
 import { collectLocaleBlockers, identityOf, readDraft, resolveDocument, staleReadResult } from "./document.mjs";
+import { documentLinks } from "./links.mjs";
 import { withPublishIntent } from "../write/publish-intent.mjs";
 import { withTransaction } from "../write/transaction.mjs";
 import { z } from "zod";
@@ -10,7 +11,7 @@ import { z } from "zod";
 * with drafts and the key has both the `write` and `publish` checkboxes.
 */ const publishDocument = defineMcpxTool({
 	name: "publishDocument",
-	description: `Makes the current draft of one document or global public, in every locale or only in "locale". A scoped publish keeps the other locales of localized fields as last published, and a never-published document goes live in full. A draft with publish blockers is refused, so call validateDocument first. Payload checks only the published locale, so "otherLocaleBlockers" lists what other locales still lack. There is no unpublish.`,
+	description: `Makes the current draft of one document or global public, in every locale or only in "locale". A scoped publish keeps the other locales of localized fields as last published, and a never-published document goes live in full. A draft with publish blockers is refused, so call validateDocument first. Payload checks only the published locale, so "otherLocaleBlockers" lists what other locales still lack. There is no unpublish. The response links the document with "adminUrl" and "previewUrl".`,
 	annotations: {
 		destructiveHint: true,
 		openWorldHint: false
@@ -63,6 +64,11 @@ import { z } from "zod";
 				...identityOf(target, saved["id"]),
 				status: saved["_status"],
 				updatedAt: saved["updatedAt"],
+				...await documentLinks(scope.req, {
+					target,
+					doc: saved,
+					locale
+				}),
 				...others.blockers.length > 0 ? { otherLocaleBlockers: others.blockers } : {},
 				...others.unavailable ? { otherLocaleBlockersUnavailable: true } : {}
 			});

package/dist/types.d.mts

@@ -34,8 +34,9 @@ export interface McpxCollectionOptions {
    */
   read?: boolean;
   /**
-   * Expose `patchDocument`, `validateDocument` and `createDocument`. An upload
-   * collection is created in only where MCP accepts its files. Without drafts
+   * 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;

package/dist/write/draft-guard.mjs

@@ -1,4 +1,4 @@
-import { hasPublishIntent, hasTrashIntent, takePublishIntent, takeTrashIntent, withTrashIntent } from "./publish-intent.mjs";
+import { hasPublishIntent, hasTrashIntent, takeDuplicateIntent, takePublishIntent, takeTrashIntent, withTrashIntent } from "./publish-intent.mjs";
 import { isMcpxRequest } from "../request.mjs";
 import { APIError } from "payload";
 import { hasDraftsEnabled } from "payload/shared";
@@ -30,6 +30,11 @@ const scrubWriteArgs = (args, intent) => {
 const forceDraftWrite = (hookArgs) => {
 	const { args, operation, req } = hookArgs;
 	if (!isMcpxRequest(req) || operation !== "create" && operation !== "update") return args;
+	if (operation === "create" && takeDuplicateIntent(args.data)) {
+		const next = scrubWriteArgs(args, void 0);
+		next["duplicateFromID"] = args.duplicateFromID;
+		return next;
+	}
 	const intent = operation !== "update" ? void 0 : hasPublishIntent(args.data) ? "publish" : hasTrashIntent(args.data) ? "trash" : void 0;
 	return scrubWriteArgs(args, intent);
 };

package/dist/write/publish-intent.mjs

@@ -3,6 +3,7 @@ import { randomUUID } from "node:crypto";
 //#region src/write/publish-intent.ts
 const PUBLISH_INTENT = "__mcpxPublishIntent";
 const TRASH_INTENT = "__mcpxTrashIntent";
+const DUPLICATE_INTENT = "__mcpxDuplicateIntent";
 const TOKEN = randomUUID();
 const take = (data, key) => {
 	if (!isPlainObject(data) || data[key] !== TOKEN) return false;
@@ -25,5 +26,12 @@ const hasTrashIntent = (data) => isPlainObject(data) && data[TRASH_INTENT] === T
 /**
 * The counterpart of {@link takePublishIntent}.
 */ const takeTrashIntent = (data) => take(data, TRASH_INTENT);
+const withDuplicateIntent = (data) => ({
+	...data,
+	[DUPLICATE_INTENT]: TOKEN
+});
+/**
+* Removes the marker, so it never reaches the operation.
+*/ const takeDuplicateIntent = (data) => take(data, DUPLICATE_INTENT);
 //#endregion
-export { hasPublishIntent, hasTrashIntent, takePublishIntent, takeTrashIntent, withPublishIntent, withTrashIntent };
+export { hasPublishIntent, hasTrashIntent, takeDuplicateIntent, takePublishIntent, takeTrashIntent, withDuplicateIntent, withPublishIntent, withTrashIntent };

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "@abinnovision/payloadcms-mcpx",
-  "version": "2.0.0-beta.15",
+  "version": "2.0.0-beta.18",
   "description": "Payload CMS plugin exposing a fixed, schema-aware MCP tool surface with draft-only writes and per-API-key capabilities.",
   "keywords": [
     "payload",
@@ -57,7 +57,7 @@
   },
   "prettier": "@abinnovision/prettier-config",
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.30.1",
+    "@modelcontextprotocol/sdk": "^1.31.0",
     "rfc6902": "^5.3.0",
     "zod": "^4.6.5"
   },
@@ -69,20 +69,20 @@
     "@payloadcms/db-sqlite": "3.90.2",
     "@payloadcms/richtext-lexical": "3.90.2",
     "@payloadcms/ui": "3.90.2",
-    "@swc/core": "^1.16.2",
-    "@types/node": "^26.5.1",
+    "@swc/core": "^1.16.12",
+    "@types/node": "^26.6.3",
     "@types/react": "^19.3.0",
-    "@vitest/coverage-v8": "^5.0.0",
-    "eslint": "^10.10.0",
+    "@vitest/coverage-v8": "^5.0.2",
+    "eslint": "^10.11.0",
     "payload": "3.90.2",
-    "prettier": "^3.9.5",
+    "prettier": "^3.9.9",
     "publint": "^0.3.24",
     "react": "^19.3.0",
     "react-dom": "^19.3.0",
     "tsdown": "^0.23.0",
     "typescript": "^6.0.3",
-    "unplugin-swc": "^1.6.0",
-    "vitest": "^5.0.0"
+    "unplugin-swc": "^2.0.0",
+    "vitest": "^5.0.2"
   },
   "peerDependencies": {
     "@payloadcms/ui": ">=3.88.0 <4",