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

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,7 +15,7 @@ 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)}`;
 /**
@@ -104,6 +105,11 @@ ${liveWriteSentence(scope, "create")}${uploadSentence(scope)}`;
 			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 } : {}
 		});

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/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.16",
   "description": "Payload CMS plugin exposing a fixed, schema-aware MCP tool surface with draft-only writes and per-API-key capabilities.",
   "keywords": [
     "payload",