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

package/dist/api-keys/fields.mjs

@@ -1,4 +1,4 @@
-import { CAPABILITIES_FIELD } from "../capabilities.mjs";
+import { CAPABILITIES_FIELD, canCreate, canPublish, canWrite } from "../capabilities.mjs";
 //#region src/api-keys/fields.ts
 const encryptKey = ({ req, value }) => typeof value === "string" ? req.payload.encrypt(value) : value;
 const decryptKey = ({ req, value }) => {
@@ -15,7 +15,7 @@ const checkbox = (name, description) => ({
 	defaultValue: false,
 	admin: { description }
 });
-const SETUP_GUIDE_FIELD = "setupGuide";
+/** Name of the `ui` field the "Connect a client" tab renders. */ const SETUP_GUIDE_FIELD = "setupGuide";
 /**
 * Fields every key carries. Key generation and the HMAC index live in the
 * collection-level `beforeChange` hook (see `collection.ts`), because sibling
@@ -89,25 +89,42 @@ const SETUP_GUIDE_FIELD = "setupGuide";
 		}]
 	}];
 };
+const PUBLISH_DESCRIPTION = "Publish the current draft. Changes what the public sees.";
 /**
 * One checkbox per exposed operation, grouped per collection, per global and
 * per custom tool. Only operations the plugin config exposes get a checkbox, so
 * a key can never enable more than the config allows. Everything defaults to
 * off, which is why a key issued before a capability existed stays closed to it.
+*
+* An entity without versions gets no `publish` checkbox even under
+* `write: "live"`: there is no draft to promote there, the write itself is the
+* live change, and a second checkbox would only make `write` a dead setting.
+*
+* An upload collection gets the same checkboxes as any other, only worded for
+* what `write` reaches there: a document's own fields, never `createDocument`,
+* because the file comes from the admin panel.
 */ const createCapabilityFields = (options) => {
 	const collectionGroups = options.collections.map((collection) => ({
 		name: collection.fieldName,
 		type: "group",
 		label: collection.slug,
-		fields: [...collection.read ? [checkbox("read", "Describe, find and read documents.")] : [], ...collection.write ? [checkbox("write", "Create, patch and validate drafts.")] : []]
+		fields: [
+			...collection.read ? [checkbox("read", "Describe, find and read documents.")] : [],
+			...canWrite(collection) ? [checkbox("write", canCreate(collection) ? "Create, patch and validate drafts." : "Patch and validate drafts. The file itself is uploaded in the admin panel.")] : [],
+			...canPublish(collection) ? [checkbox("publish", PUBLISH_DESCRIPTION)] : []
+		]
 	}));
 	const globalGroups = options.globals.map((global) => ({
 		name: global.fieldName,
 		type: "group",
 		label: global.slug,
-		fields: [...global.read ? [checkbox("read", "Describe and read this global.")] : [], ...global.write ? [checkbox("write", "Patch and validate this global's draft.")] : []]
+		fields: [
+			...global.read ? [checkbox("read", "Describe and read this global.")] : [],
+			...canWrite(global) ? [checkbox("write", "Patch and validate this global's draft.")] : [],
+			...canPublish(global) ? [checkbox("publish", PUBLISH_DESCRIPTION)] : []
+		]
 	}));
-	const toolCheckboxes = options.tools.map((tool) => checkbox(tool.name, tool.description));
+	const toolCheckboxes = options.tools.map((tool) => checkbox(tool.name, typeof tool.description === "string" ? tool.description : tool.name));
 	const groups = [
 		...collectionGroups.length > 0 ? [{
 			name: "collections",

package/dist/api-keys/setup-guide.mjs

@@ -1,5 +1,8 @@
 //#region src/api-keys/setup-guide.ts
-const KEY_PLACEHOLDER = "<your-key>";
+/**
+* Stands in for the key in the snippets whenever the real one is unavailable,
+* so the instructions still render and say what is missing.
+*/ const KEY_PLACEHOLDER = "<your-key>";
 /**
 * Server name for the client config. MCP clients key their config by this, so
 * it has to survive labels with spaces or punctuation.
@@ -8,9 +11,8 @@ const KEY_PLACEHOLDER = "<your-key>";
 	return slug === "" ? "payload" : slug;
 };
 /**
-* The connection instructions for one key, split into independently copyable
-* blocks. Kept a pure builder so the admin component holds only rendering and
-* the snippets stay unit-testable.
+* A pure builder, so the admin component holds only rendering and the snippets
+* stay unit-testable.
 */ const buildSetupGuide = (input) => {
 	const key = typeof input.apiKey === "string" ? input.apiKey : KEY_PLACEHOLDER;
 	const name = toServerName(input.label);

package/dist/auth/resolve.mjs

@@ -1,17 +1,15 @@
 import { hashApiKey } from "../api-keys/key.mjs";
 //#region src/auth/resolve.ts
 const BEARER = /^Bearer\s+(\S+)\s*$/i;
-/**
-* The bearer token of an `Authorization` header, or `null`.
-*/ const parseBearer = (headers) => {
-	const header = headers.get("authorization");
-	if (!header) return null;
-	return BEARER.exec(header.trim())?.[1] ?? null;
-};
 const relationId = (value) => {
 	if (typeof value === "string" || typeof value === "number") return value;
 	if (typeof value === "object" && value !== null && "id" in value) return value.id;
 };
+const parseBearer = (headers) => {
+	const header = headers.get("authorization");
+	if (!header) return null;
+	return BEARER.exec(header.trim())?.[1] ?? null;
+};
 /**
 * Resolves the bearer key of a request to the user it acts as.
 *

package/dist/capabilities.mjs

@@ -1,8 +1,23 @@
 //#region src/capabilities.ts
-/** Name of the capability group on the key document. */ const CAPABILITIES_FIELD = "capabilities";
+/** Group field holding the capability checkboxes on an API key document. */ const CAPABILITIES_FIELD = "capabilities";
+/** Whatever the write lands on; {@link isLiveWrite} tells the two apart. */ const canWrite = (entity) => entity.write !== false;
+/** The config lets MCP change live content and there is a draft to promote. */ const canPublish = (entity) => entity.write === "live" && entity.hasDrafts;
+/**
+* An upload document is a file, and no tool here carries one. Its own fields
+* stay patchable; the first version is made in the admin panel.
+*/ const canCreate = (entity) => canWrite(entity) && !entity.isUpload;
+/**
+* With no versions there is no draft to land on, so `write: "live"` permits the
+* write at all and every write is live.
+*/ const isLiveWrite = (entity) => entity.write === "live" && !entity.hasDrafts;
 const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
 const flag = (group, name) => isRecord(group) && group[name] === true;
 /**
+* Publishing is an extension of writing, never a capability of its own: a key
+* that may publish may also edit the draft it publishes. Both checkboxes are
+* therefore required, on top of the config exposing publishing at all.
+*/ const publishFlag = (entity, group) => canPublish(entity) && flag(group, "write") && flag(group, "publish");
+/**
 * Capabilities in force for a key: the plugin config decides what can exist,
 * the key's checkboxes decide what does. A missing checkbox is `false`, so keys
 * issued before a capability existed stay closed.
@@ -15,7 +30,8 @@ const flag = (group, name) => isRecord(group) && group[name] === true;
 		const group = isRecord(collectionsGroup) ? collectionsGroup[collection.fieldName] : void 0;
 		collections[collection.slug] = {
 			read: collection.read && flag(group, "read"),
-			write: collection.write && flag(group, "write")
+			write: canWrite(collection) && flag(group, "write"),
+			publish: publishFlag(collection, group)
 		};
 	}
 	const globals = {};
@@ -23,7 +39,8 @@ const flag = (group, name) => isRecord(group) && group[name] === true;
 		const group = isRecord(globalsGroup) ? globalsGroup[global.fieldName] : void 0;
 		globals[global.slug] = {
 			read: global.read && flag(group, "read"),
-			write: global.write && flag(group, "write")
+			write: canWrite(global) && flag(group, "write"),
+			publish: publishFlag(global, group)
 		};
 	}
 	const tools = {};
@@ -37,7 +54,9 @@ const flag = (group, name) => isRecord(group) && group[name] === true;
 const pick = (entries, operation) => Object.entries(entries).filter(([, value]) => value[operation]).map(([slug]) => slug);
 const readableSlugs = (capabilities) => pick(capabilities.collections, "read");
 const writableSlugs = (capabilities) => pick(capabilities.collections, "write");
+const publishableSlugs = (capabilities) => pick(capabilities.collections, "publish");
 const readableGlobalSlugs = (capabilities) => pick(capabilities.globals, "read");
 const writableGlobalSlugs = (capabilities) => pick(capabilities.globals, "write");
+const publishableGlobalSlugs = (capabilities) => pick(capabilities.globals, "publish");
 //#endregion
-export { CAPABILITIES_FIELD, readableGlobalSlugs, readableSlugs, resolveCapabilities, writableGlobalSlugs, writableSlugs };
+export { CAPABILITIES_FIELD, canCreate, canPublish, canWrite, isLiveWrite, publishableGlobalSlugs, publishableSlugs, readableGlobalSlugs, readableSlugs, resolveCapabilities, writableGlobalSlugs, writableSlugs };

package/dist/client/index.d.mts

@@ -1,2 +1,2 @@
-import { McpxSetupGuide, McpxSetupGuideProps } from "./setup-guide.mjs";
-export { McpxSetupGuide, type McpxSetupGuideProps };
+import { McpxSetupGuide } from "./setup-guide.mjs";
+export { McpxSetupGuide };

package/dist/client/setup-guide.d.mts

@@ -11,4 +11,4 @@ interface McpxSetupGuideProps {
  */
 declare const McpxSetupGuide: React.FC<McpxSetupGuideProps>;
 //#endregion
-export { McpxSetupGuide, type McpxSetupGuideProps };
+export { McpxSetupGuide };

package/dist/endpoint/{result.mjs → errors.mjs}

@@ -1,6 +1,8 @@
+import { errorResult } from "../result.mjs";
 import { pointerFromPayloadPath } from "../schema/walk.mjs";
+import "../schema/index.mjs";
 import { APIError, ValidationError } from "payload";
-//#region src/endpoint/result.ts
+//#region src/endpoint/errors.ts
 /**
 * A JSON-RPC error response for failures that happen before the MCP server
 * is involved (auth, method, body parsing).
@@ -20,27 +22,6 @@ import { APIError, ValidationError } from "payload";
 	});
 };
 /**
-* A successful tool result carrying `value` as JSON text.
-*/ const jsonResult = (value) => ({ content: [{
-	type: "text",
-	text: JSON.stringify(value)
-}] });
-/**
-* A failed tool result. `extras` travel alongside the message so the client
-* can act on them (problems, validation errors, the current `updatedAt`).
-*/ const errorResult = (message, extras = {}) => ({
-	content: [{
-		type: "text",
-		text: JSON.stringify({
-			error: message,
-			...extras
-		})
-	}],
-	isError: true
-});
-/**
-* Maps an exception thrown by a tool to a result the client can read.
-*
 * Payload's public errors keep their message and status; a `ValidationError`
 * also surfaces its per-field detail, with each field's path restated as a
 * JSON Pointer so it reads like every other path this plugin reports. Anything
@@ -62,4 +43,4 @@ import { APIError, ValidationError } from "payload";
 	return errorResult("Internal error");
 };
 //#endregion
-export { errorResult, jsonResult, jsonRpcError, toToolError };
+export { jsonRpcError, toToolError };

package/dist/endpoint/handler.mjs

@@ -1,6 +1,6 @@
-import { readableGlobalSlugs, readableSlugs, resolveCapabilities, writableGlobalSlugs, writableSlugs } from "../capabilities.mjs";
+import { publishableGlobalSlugs, publishableSlugs, readableGlobalSlugs, readableSlugs, resolveCapabilities, writableGlobalSlugs, writableSlugs } from "../capabilities.mjs";
+import { jsonRpcError } from "./errors.mjs";
 import { resolveApiKeyAuth } from "../auth/resolve.mjs";
-import { jsonRpcError } from "./result.mjs";
 import { createMcpServer } from "./server.mjs";
 import { WebStandardStreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/webStandardStreamableHttp.js";
 //#region src/endpoint/handler.ts
@@ -8,14 +8,20 @@ const buildScope = (req, options, capabilities) => {
 	const { localization } = req.payload.config;
 	return {
 		req,
-		options,
 		capabilities,
 		readable: readableSlugs(capabilities),
 		writable: writableSlugs(capabilities),
+		publishable: publishableSlugs(capabilities),
 		readableGlobals: readableGlobalSlugs(capabilities),
 		writableGlobals: writableGlobalSlugs(capabilities),
+		publishableGlobals: publishableGlobalSlugs(capabilities),
 		locales: localization ? localization.localeCodes : null,
-		defaultLocale: localization ? localization.defaultLocale : null
+		defaultLocale: localization ? localization.defaultLocale : null,
+		limits: options.limits,
+		exposure: {
+			collections: options.collections,
+			globals: options.globals
+		}
 	};
 };
 /**
@@ -68,7 +74,7 @@ const buildScope = (req, options, capabilities) => {
 		code: -32600,
 		message: "Invalid request: a JSON body is required."
 	});
-	const server = createMcpServer(buildScope(req, options, capabilities));
+	const server = createMcpServer(buildScope(req, options, capabilities), options);
 	const transport = new WebStandardStreamableHTTPServerTransport({ enableJsonResponse: true });
 	await server.connect(transport);
 	const headers = new Headers(req.headers);

package/dist/endpoint/index.mjs

@@ -0,0 +1,4 @@
+import { jsonRpcError, toToolError } from "./errors.mjs";
+import { createMcpServer, isToolEnabled, toolDescription, toolInputSchema } from "./server.mjs";
+import { createMcpxHandler, methodNotAllowed } from "./handler.mjs";
+export { createMcpServer, createMcpxHandler, isToolEnabled, jsonRpcError, methodNotAllowed, toToolError, toolDescription, toolInputSchema };

package/dist/endpoint/server.mjs

@@ -1,24 +1,23 @@
-import { toToolError } from "./result.mjs";
-import { BUILTIN_TOOLS } from "../tools/index.mjs";
+import { toToolError } from "./errors.mjs";
+import { draftSentence } from "../tools/shared.mjs";
+import { BUILTIN_TOOLS } from "../tools/builtin.mjs";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { z } from "zod";
 //#region src/endpoint/server.ts
+/** Strict, so an unknown argument is rejected by name rather than stripped. */ const toolInputSchema = (tool, scope) => z.strictObject(typeof tool.inputSchema === "function" ? tool.inputSchema(scope) : tool.inputSchema ?? {});
+/** May be built from the scope, to name the targets this key writes live. */ const toolDescription = (tool, scope) => typeof tool.description === "function" ? tool.description(scope) : tool.description;
+/** A tool that does not decide for itself is gated by its own checkbox. */ const isToolEnabled = (tool, scope) => tool.isEnabled ? tool.isEnabled(scope) : scope.capabilities.tools[tool.name] === true;
 /**
-* Builds a builtin tool's input schema as a strict object, so an unknown
-* argument is rejected with its name instead of being silently stripped and
-* the tool answering as if it had not been passed.
-*/ const builtinInputSchema = (tool, scope) => z.strictObject(tool.inputSchema(scope));
-/**
-* Builds the MCP server for one request. Tools are registered against the
-* key's capabilities, so `tools/list` shows exactly what the key may call and
-* every `collection` enum is limited to what it may touch.
-*/ const createMcpServer = (scope) => {
-	const { req, options, capabilities } = scope;
+* One server per request. Builtin and configured tools take the same route,
+* each registered against the key's capabilities, so `tools/list` shows exactly
+* what the key may call.
+*/ const createMcpServer = (scope, options) => {
+	const { req } = scope;
 	const { logger } = req.payload;
 	const server = new McpServer({
 		name: options.serverInfo.name,
 		version: options.serverInfo.version
-	}, { instructions: "Start with listCapabilities, then describeSchema for the collection or global you work on. Writes always land as drafts; a human publishes." });
+	}, { instructions: `Start with listCapabilities, then describeSchema for the collection or global you work on. ${draftSentence(scope)}` });
 	const guarded = (run) => async () => {
 		try {
 			return await run();
@@ -26,22 +25,15 @@ import { z } from "zod";
 			return toToolError(error, logger);
 		}
 	};
-	for (const tool of BUILTIN_TOOLS) {
-		if (!tool.isEnabled(scope)) continue;
-		server.registerTool(tool.name, {
-			description: tool.description,
-			inputSchema: builtinInputSchema(tool, scope),
-			annotations: tool.annotations
-		}, (args) => guarded(() => tool.handler(args, scope))());
-	}
-	for (const tool of options.tools) {
-		if (capabilities.tools[tool.name] !== true) continue;
+	for (const tool of [...BUILTIN_TOOLS, ...options.tools]) {
+		if (!isToolEnabled(tool, scope)) continue;
 		server.registerTool(tool.name, {
-			description: tool.description,
-			inputSchema: tool.inputSchema ?? {},
+			description: toolDescription(tool, scope),
+			inputSchema: toolInputSchema(tool, scope),
 			...tool.annotations ? { annotations: tool.annotations } : {}
 		}, (args, extra) => guarded(() => tool.handler({
 			args,
+			scope,
 			req,
 			extra
 		}))());
@@ -49,4 +41,4 @@ import { z } from "zod";
 	return server;
 };
 //#endregion
-export { builtinInputSchema, createMcpServer };
+export { createMcpServer, isToolEnabled, toolDescription, toolInputSchema };

package/dist/i18n.mjs

@@ -1,11 +1,6 @@
 //#region src/i18n.ts
-/**
-* A locale-keyed record, once it is known to hold nothing but strings.
-*/ const stringRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value) && Object.values(value).every((entry) => typeof entry === "string") ? value : void 0;
-/**
-* Picks the entry a language addresses, treating an empty value as absent so
-* the chain continues rather than yielding a useless string.
-*/ const pick = (record, language) => {
+const stringRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value) && Object.values(value).every((entry) => typeof entry === "string") ? value : void 0;
+/** Treats an empty value as absent, so the fallback chain continues. */ const pick = (record, language) => {
 	for (const code of Array.isArray(language) ? language : [language]) {
 		const entry = record[code];
 		if (entry !== void 0 && entry.trim() !== "") return entry;
@@ -25,14 +20,8 @@
 	if (!record) return;
 	return pick(record, language.language) ?? pick(record, language.fallbackLanguage) ?? Object.values(record).find((entry) => entry.trim() !== "");
 };
-/**
-* Binds {@link translateStatic} to a request's language, so a walk that
-* resolves many descriptions carries no request of its own.
-*/ const translatorFor = (i18n) => (value) => translateStatic(value, i18n);
-/**
-* Translator for callers with no request in hand. Both language keys miss, so
-* the chain degrades to the record's first entry.
-*/ const translateAny = translatorFor({
+/** Bound to one request's language, so a walk carries no request of its own. */ const translatorFor = (i18n) => (value) => translateStatic(value, i18n);
+/** For callers with no request: both keys miss, so the first entry wins. */ const translateAny = translatorFor({
 	fallbackLanguage: "",
 	language: ""
 });

package/dist/index.d.mts

@@ -1,5 +1,5 @@
-import { McpxAuthResult, McpxCollectionCapabilities, McpxCollectionOptions, McpxGlobalOptions, McpxPluginOptions, McpxRequestContext, McpxResolvedCapabilities, McpxTool, McpxToolExtra, defineMcpxTool } from "./types.mjs";
+import { McpxAnyTool, McpxAuthResult, McpxCollectionCapabilities, McpxCollectionOptions, McpxExposedEntity, McpxGlobalOptions, McpxPluginOptions, McpxRequestContext, McpxResolvedCapabilities, McpxTool, McpxToolExtra, McpxToolScope, McpxWriteMode, PublishBlocker, defineMcpxTool } from "./types.mjs";
 import { mcpxPlugin } from "./plugin.mjs";
-import { isMcpxRequest } from "./write/draft-guard.mjs";
-import { PublishBlocker } from "./write/publish-blockers.mjs";
-export { type McpxAuthResult, type McpxCollectionCapabilities, type McpxCollectionOptions, type McpxGlobalOptions, type McpxPluginOptions, type McpxRequestContext, type McpxResolvedCapabilities, type McpxTool, type McpxToolExtra, type PublishBlocker, defineMcpxTool, isMcpxRequest, mcpxPlugin };
+import { isMcpxRequest } from "./request.mjs";
+import { errorResult, jsonResult } from "./result.mjs";
+export { McpxAnyTool, McpxAuthResult, McpxCollectionCapabilities, McpxCollectionOptions, McpxExposedEntity, McpxGlobalOptions, McpxPluginOptions, McpxRequestContext, McpxResolvedCapabilities, McpxTool, McpxToolExtra, McpxToolScope, McpxWriteMode, PublishBlocker, defineMcpxTool, errorResult, isMcpxRequest, jsonResult, mcpxPlugin };

package/dist/index.mjs

@@ -1,4 +1,5 @@
-import { isMcpxRequest } from "./write/draft-guard.mjs";
-import { mcpxPlugin } from "./plugin.mjs";
+import { errorResult, jsonResult } from "./result.mjs";
 import { defineMcpxTool } from "./types.mjs";
-export { defineMcpxTool, isMcpxRequest, mcpxPlugin };
+import { isMcpxRequest } from "./request.mjs";
+import { mcpxPlugin } from "./plugin.mjs";
+export { defineMcpxTool, errorResult, isMcpxRequest, jsonResult, mcpxPlugin };

package/dist/options.mjs

@@ -1,7 +1,7 @@
 import { BUILTIN_TOOL_NAMES } from "./tools/names.mjs";
 import "./version.mjs";
 import { InvalidConfiguration } from "payload";
-import { hasDraftsEnabled } from "payload/shared";
+import { hasDraftsEnabled, hasLocalizeStatusEnabled } from "payload/shared";
 //#region src/options.ts
 const DEFAULT_API_KEYS_SLUG = "mcpx-api-keys";
 const DEFAULT_ENDPOINT_PATH = "/mcpx";
@@ -11,29 +11,36 @@ const TOOL_NAME_PATTERN = /^[a-zA-Z][a-zA-Z0-9]*$/;
 const fail = (message) => {
 	throw new InvalidConfiguration(`[payloadcms-mcpx] ${message}`);
 };
+/** The same transform the stock MCP plugin uses to derive field names. */ const toCamelCase = (value) => value.replace(/[-_\s]+(.)?/g, (_, char) => char ? char.toUpperCase() : "").replace(/^(.)/, (_, char) => char.toLowerCase());
 /**
-* Lower camel case of a slug, the same transform the stock MCP plugin applies
-* to derive field names from collection slugs.
-*/ const toCamelCase = (value) => value.replace(/[-_\s]+(.)?/g, (_, char) => char ? char.toUpperCase() : "").replace(/^(.)/, (_, char) => char.toLowerCase());
-/**
-* Refuses collections that must never be reachable through MCP, read included.
 * Auth collections carry credentials: `useAPIKey` stores a key that decrypts on
-* read, and email or lockout state is PII either way.
+* read, and email or lockout state is PII either way. Refused for read too.
 */ const assertExposable = (collection, apiKeysSlug) => {
 	const { slug } = collection;
 	if (slug === apiKeysSlug || slug.startsWith("payload-")) fail(`Collection "${slug}" cannot be exposed.`);
 	if (collection.auth) fail(`Auth collection "${slug}" cannot be exposed. Its documents carry credentials.`);
 };
+/** Checked at runtime too: for a JS caller a typo would silently mean "no write". */ const normalizeWriteMode = (kind, slug, value) => {
+	if (value === void 0 || value === false) return false;
+	if (value === "draft" || value === "live") return value;
+	return fail(`${kind} "${slug}" has write: ${JSON.stringify(value)}. Use false, "draft" or "live".`);
+};
+/**
+* `localizeStatus` makes `_status` a localized field, which flips Payload's
+* `publishAllLocales` default to false and turns `_status` into a locale-keyed
+* object. Publishing would then cover one locale while reporting success, and
+* the tool responses model `_status` as a string. Refused until both are
+* handled.
+*/ const assertPublishable = (kind, config) => {
+	if (hasLocalizeStatusEnabled(config)) fail(`${kind} "${config.slug}" has versions.drafts.localizeStatus enabled, which write: "live" does not support yet.`);
+};
 const assertWritable = (collection, options) => {
 	const { slug } = collection;
-	if (collection.upload) fail(`Upload collection "${slug}" cannot be exposed for write.`);
 	if (collection.timestamps === false) fail(`Collection "${slug}" has timestamps disabled, which write tools need for concurrency checks.`);
-	if (!options.hasDrafts && !options.allowLiveWrites) fail(`Collection "${slug}" has no drafts. Enable versions.drafts or set allowLiveWrites.`);
+	if (options.write === "draft" && !options.hasDrafts) fail(`Collection "${slug}" has no drafts. Enable versions.drafts or set write: "live".`);
+	if (options.write === "live") assertPublishable("Collection", collection);
 };
-/**
-* Refuses globals that must never be reachable. Globals cannot be auth or
-* upload entities, so only Payload's own reserved namespace is left to guard.
-*/ const assertGlobalExposable = (global) => {
+/** Globals cannot be auth or upload, so only the reserved namespace is left. */ const assertGlobalExposable = (global) => {
 	if (global.slug.startsWith("payload-")) fail(`Global "${global.slug}" cannot be exposed.`);
 };
 /**
@@ -41,7 +48,8 @@ const assertWritable = (collection, options) => {
 * `createdAt`/`updatedAt`, so the concurrency check the collection path guards
 * for is always available here. Drafts are the only requirement left.
 */ const assertGlobalWritable = (global, options) => {
-	if (!options.hasDrafts && !options.allowLiveWrites) fail(`Global "${global.slug}" has no drafts. Enable versions.drafts or set allowLiveWrites.`);
+	if (options.write === "draft" && !options.hasDrafts) fail(`Global "${global.slug}" has no drafts. Enable versions.drafts or set write: "live".`);
+	if (options.write === "live") assertPublishable("Global", global);
 };
 const normalizeCollections = (config, options, apiKeysSlug) => {
 	const collections = config.collections ?? [];
@@ -56,12 +64,12 @@ const normalizeCollections = (config, options, apiKeysSlug) => {
 		const normalized = {
 			slug,
 			read: settings.read ?? true,
-			write: settings.write ?? false,
-			allowLiveWrites: settings.allowLiveWrites ?? false,
+			write: normalizeWriteMode("Collection", slug, settings.write),
 			hasDrafts,
+			isUpload: Boolean(collection.upload),
 			fieldName: toCamelCase(slug)
 		};
-		if (normalized.write) assertWritable(collection, normalized);
+		if (normalized.write !== false) assertWritable(collection, normalized);
 		if (fieldNames.has(normalized.fieldName)) fail(`Collection "${slug}" maps to capability field "${normalized.fieldName}", which another exposed collection already uses.`);
 		fieldNames.add(normalized.fieldName);
 		return [normalized];
@@ -80,12 +88,12 @@ const normalizeGlobals = (config, options) => {
 		const normalized = {
 			slug,
 			read: settings.read ?? true,
-			write: settings.write ?? false,
-			allowLiveWrites: settings.allowLiveWrites ?? false,
+			write: normalizeWriteMode("Global", slug, settings.write),
 			hasDrafts,
+			isUpload: false,
 			fieldName: toCamelCase(slug)
 		};
-		if (normalized.write) assertGlobalWritable(global, normalized);
+		if (normalized.write !== false) assertGlobalWritable(global, normalized);
 		if (fieldNames.has(normalized.fieldName)) fail(`Global "${slug}" maps to capability field "${normalized.fieldName}", which another exposed global already uses.`);
 		fieldNames.add(normalized.fieldName);
 		return [normalized];
@@ -115,11 +123,7 @@ const normalizeLimits = (limits) => {
 		maxDepth
 	};
 };
-/**
-* Validates the plugin options against the incoming config and fills in
-* defaults. Every problem is an `InvalidConfiguration` so misconfiguration
-* fails at startup instead of at request time.
-*/ const normalizeOptions = (config, options) => {
+/** Every problem is an `InvalidConfiguration`, so it fails at startup. */ const normalizeOptions = (config, options) => {
 	const apiKeysSlug = options.apiKeys?.slug ?? DEFAULT_API_KEYS_SLUG;
 	const userCollection = options.userCollection ?? config.admin?.user ?? "users";
 	if ((config.collections ?? []).some((c) => c.slug === apiKeysSlug)) fail(`API key collection slug "${apiKeysSlug}" is already taken.`);
@@ -138,7 +142,7 @@ const normalizeLimits = (limits) => {
 		auth: options.auth,
 		serverInfo: {
 			name: options.serverInfo?.name ?? "payloadcms-mcpx",
-			version: options.serverInfo?.version ?? "0.0.0"
+			version: options.serverInfo?.version ?? "1.0.0"
 		}
 	};
 };

package/dist/plugin.mjs

@@ -1,5 +1,6 @@
 import { createApiKeysCollection } from "./api-keys/collection.mjs";
 import { createMcpxHandler, methodNotAllowed } from "./endpoint/handler.mjs";
+import "./endpoint/index.mjs";
 import { normalizeOptions } from "./options.mjs";
 import { installDraftGuards, installGlobalDraftGuards } from "./write/draft-guard.mjs";
 import { definePlugin } from "payload";

package/dist/{write/draft-guard.d.mts → request.d.mts}

@@ -1,5 +1,5 @@
-import { CollectionConfig, PayloadRequest } from "payload";
-//#region src/write/draft-guard.d.ts
+import { PayloadRequest } from "payload";
+//#region src/request.d.ts
 /**
  * Whether a request originated from the MCP endpoint. The endpoint stamps
  * `req.context.mcpx`, which travels into every local API call made with the

package/dist/request.mjs

@@ -0,0 +1,8 @@
+//#region src/request.ts
+/**
+* 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;
+//#endregion
+export { isMcpxRequest };

package/dist/result.d.mts

@@ -0,0 +1,11 @@
+import { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
+//#region src/result.d.ts
+/** `value` as JSON text. */
+declare const jsonResult: (value: unknown) => CallToolResult;
+/**
+ * `extras` travel alongside the message so the client can act on them:
+ * problems, validation errors, the current `updatedAt`.
+ */
+declare const errorResult: (message: string, extras?: Record<string, unknown>) => CallToolResult;
+//#endregion
+export { errorResult, jsonResult };

package/dist/result.mjs

@@ -0,0 +1,20 @@
+//#region src/result.ts
+/** `value` as JSON text. */ const jsonResult = (value) => ({ content: [{
+	type: "text",
+	text: JSON.stringify(value)
+}] });
+/**
+* `extras` travel alongside the message so the client can act on them:
+* problems, validation errors, the current `updatedAt`.
+*/ const errorResult = (message, extras = {}) => ({
+	content: [{
+		type: "text",
+		text: JSON.stringify({
+			error: message,
+			...extras
+		})
+	}],
+	isError: true
+});
+//#endregion
+export { errorResult, jsonResult };

package/dist/schema/describe.mjs

@@ -2,13 +2,8 @@ import { lexicalSubSchema, subSchemaNodeTypes } from "./lexical.mjs";
 import { translateAny } from "../i18n.mjs";
 import { blockOf, blockSlugsOf, describeFields, findBlocksField, findRichTextField, joinPath, splitPath, targetOf } from "./walk.mjs";
 //#region src/schema/describe.ts
-/**
-* The longest descriptor path that is a prefix of `remaining`. Blocks and rich
-* text fields are both leaves of the walk, so at most one can match.
-*/ const longestMatch = (descriptors, remaining) => descriptors.map((descriptor) => splitPath(descriptor.path)).filter((parts) => parts.every((part, offset) => part === remaining[offset])).sort((left, right) => right.length - left.length)[0];
-/**
-* Walks one step of a schema path through a blocks field.
-*/ const stepThroughBlocks = ({ config, fields, match, remaining }) => {
+/** Blocks and rich text are both leaves of the walk, so at most one matches. */ const longestMatch = (descriptors, remaining) => descriptors.map((descriptor) => splitPath(descriptor.path)).filter((parts) => parts.every((part, offset) => part === remaining[offset])).sort((left, right) => right.length - left.length)[0];
+const stepThroughBlocks = ({ config, fields, match, remaining }) => {
 	const field = findBlocksField(fields, match);
 	if (!field) throw new Error(`"${joinPath(match)}" could not be resolved.`);
 	const slug = remaining.at(match.length);
@@ -22,8 +17,6 @@ import { blockOf, blockSlugsOf, describeFields, findBlocksField, findRichTextFie
 	};
 };
 /**
-* Walks one step of a schema path into a Lexical node's own fields.
-*
 * A node that picks a block by slug takes one segment more, so `/content/block`
 * addresses the choice and `/content/block/callout` the definition. Everything
 * else, a link node being the usual case, resolves in a single segment.
@@ -52,8 +45,6 @@ import { blockOf, blockSlugsOf, describeFields, findBlocksField, findRichTextFie
 	};
 };
 /**
-* Walks a schema path to the field list it addresses.
-*
 * A schema path alternates a blocks field's own path with the slug of one of
 * the blocks it accepts, so `/layout/sections/sectionWrapper/modules/hero`
 * reaches `hero` as it exists under `pages` specifically. The slug sits where
@@ -114,11 +105,8 @@ import { blockOf, blockSlugsOf, describeFields, findBlocksField, findRichTextFie
 	}));
 };
 /**
-* Describes a collection or global root, one block reached through a schema
-* path, or the fields a Lexical node carries.
-*
 * Curried on the translator that resolves each `admin.description`, so a
-* request binds its language once and the walk itself stays request-free.
+* request binds its language once and the walk stays request-free.
 */ const nodeDescriber = (translate = translateAny) => (config, ref, schemaPath = "") => {
 	const { blockType, fields } = fieldsAtSchemaPath(config, targetOf(config, ref), schemaPath);
 	const descriptors = describeFields(fields, translate);

package/dist/schema/index.mjs

@@ -0,0 +1,8 @@
+import { REQUIRED_NODE_PROPERTIES, ROOT_PROPERTIES, allowedNodeTypes, constrainsFields, lexicalSubSchema, nodeOptions, nodeProblems, nodePropertiesFor, propertyProblem, rootProblems, subSchemaNodeTypes } from "./lexical.mjs";
+import { JSON_POINTER_PATTERN, RESERVED_FIELD_NAMES, blockOf, blockSlugsOf, describeAddressableFields, describeFields, findBlocksField, findRichTextField, isIndexSegment, isPlainObject, joinPath, pointerFromPayloadPath, splitPath, targetOf } from "./walk.mjs";
+import { nodeDescriber, reachableSchemaPaths } from "./describe.mjs";
+import { resolveLexicalPointer } from "./lexical-pointer.mjs";
+import { lexicalOutline } from "./outline.mjs";
+import { resolveDataPointer } from "./pointer.mjs";
+import { EMPTY_ROOT, validateWriteValue } from "./shape.mjs";
+export { EMPTY_ROOT, JSON_POINTER_PATTERN, REQUIRED_NODE_PROPERTIES, RESERVED_FIELD_NAMES, ROOT_PROPERTIES, allowedNodeTypes, blockOf, blockSlugsOf, constrainsFields, describeAddressableFields, describeFields, findBlocksField, findRichTextField, isIndexSegment, isPlainObject, joinPath, lexicalOutline, lexicalSubSchema, nodeDescriber, nodeOptions, nodeProblems, nodePropertiesFor, pointerFromPayloadPath, propertyProblem, reachableSchemaPaths, resolveDataPointer, resolveLexicalPointer, rootProblems, splitPath, subSchemaNodeTypes, targetOf, validateWriteValue };