@abinnovision/payloadcms-mcpx 2.0.0-beta.8 → 2.0.0

package/dist/grants/grant.mjs

@@ -0,0 +1,137 @@
+import { isPlainObject } from "../guards.mjs";
+import { generateApiKey, hashApiKey } from "../api-keys/key.mjs";
+import { APIError, ValidationError } from "payload";
+//#region src/grants/grant.ts
+const GRANT_TTL_MS = 3e5;
+const GRANTS_PER_KEY = 10;
+const ROW_ID = /^[\w-]{43}$/;
+const NO_REQ = {};
+/**
+* The key prefixes of a kind of row: waiting rows and the markers of used
+* ones.
+*/ const rowPrefixes = (kind, apiKeyId) => ({
+	prefix: `mcpx-${kind}:${String(apiKeyId)}:`,
+	usedPrefix: `mcpx-${kind}-used:${String(apiKeyId)}:`
+});
+/**
+* What a row is addressed by: the HMAC of its id, which the row key ends in.
+*/ const rowHandle = (payload, id) => hashApiKey(payload.secret, id);
+const expOf = (data) => isPlainObject(data) && typeof data["exp"] === "number" ? data["exp"] : 0;
+/**
+* The KV collection slug, when Payload's database KV adapter backs it with a
+* unique `key`, which the single-use claim relies on. `undefined` otherwise.
+*/ const grantKvSlug = (config) => {
+	const kv = config.kv;
+	const key = kv?.kvCollection?.fields.find((field) => "name" in field && field.name === "key");
+	return key && "unique" in key && key.unique ? kv?.kvCollection?.slug : void 0;
+};
+/**
+* KV rows whose key contains one of `fragments`.
+*/ const findRows = async (payload, slug, fragments) => {
+	const { docs } = await payload.db.find({
+		collection: slug,
+		where: { or: fragments.map((fragment) => ({ key: { like: fragment } })) },
+		limit: 0,
+		pagination: false,
+		req: NO_REQ
+	});
+	return docs;
+};
+/**
+* KV rows whose key starts with one of `prefixes`. `like` matches a
+* substring, so the prefix is checked again here.
+*/ const rowsWith = async (payload, slug, prefixes) => (await findRows(payload, slug, prefixes)).filter((row) => prefixes.some((prefix) => row.key.startsWith(prefix)));
+/**
+* Stores `data` under `prefix` and the HMAC of a fresh id, and returns the id,
+* the only copy of which goes to the client. Expired rows under `prefix` and
+* `usedPrefix` are purged first, and at most `cap` unexpired rows may wait
+* under `prefix`; past that, `capMessage` is thrown with 429.
+*/ const issueRow = async (payload, slug, args) => {
+	const now = Date.now();
+	const rows = await rowsWith(payload, slug, [args.prefix, args.usedPrefix]);
+	const expired = rows.filter((row) => expOf(row.data) <= now);
+	if (expired.length > 0) await payload.db.deleteMany({
+		collection: slug,
+		where: { key: { in: expired.map((row) => row.key) } },
+		req: NO_REQ
+	});
+	if (rows.filter((row) => row.key.startsWith(args.prefix) && expOf(row.data) > now).length >= args.cap) throw new APIError(args.capMessage, 429);
+	const id = generateApiKey();
+	const exp = now + args.ttlMs;
+	await payload.db.create({
+		collection: slug,
+		data: {
+			key: `${args.prefix}${rowHandle(payload, id)}`,
+			data: {
+				...args.data,
+				exp
+			}
+		},
+		req: NO_REQ
+	});
+	return {
+		id,
+		exp
+	};
+};
+/**
+* Marks the row under `handle` used and removes it. The marker is a
+* unique-key insert, so of two concurrent claims exactly one returns `true`.
+*/ const claimRow = async (payload, slug, prefixes, handle, exp) => {
+	try {
+		await payload.db.create({
+			collection: slug,
+			data: {
+				key: `${prefixes.usedPrefix}${handle}`,
+				data: { exp }
+			},
+			req: NO_REQ
+		});
+	} catch (error) {
+		if (error instanceof ValidationError) return false;
+		throw error;
+	}
+	await payload.db.deleteOne({
+		collection: slug,
+		where: { key: { equals: `${prefixes.prefix}${handle}` } },
+		req: NO_REQ
+	});
+	return true;
+};
+/**
+* The KV slug and key id of the request, which a call that stores a grant or
+* a confirmation needs. Throws where the endpoint would not offer one.
+*/ const grantContext = (req) => {
+	const slug = grantKvSlug(req.payload.config);
+	const apiKeyId = req.context.mcpx?.apiKeyId;
+	if (slug === void 0 || apiKeyId === void 0) throw new Error("A grant or confirmation needs a database KV and a key.");
+	return {
+		slug,
+		apiKeyId
+	};
+};
+/**
+* Stores a grant and returns its id. A key may hold at most
+* {@link GRANTS_PER_KEY} grants.
+*/ const issueGrant = async (payload, slug, grant) => await issueRow(payload, slug, {
+	...rowPrefixes("grant", grant.apiKeyId),
+	cap: GRANTS_PER_KEY,
+	capMessage: `This key already has ${String(GRANTS_PER_KEY)} uploads or downloads waiting. Use or abandon them first; each expires 5 minutes after it was issued.`,
+	ttlMs: GRANT_TTL_MS,
+	data: grant
+});
+/**
+* Loads the grant for `grantId` and marks it used, or returns `undefined` for
+* a malformed, unknown, expired or used one. A malformed id is refused before
+* any database read.
+*/ const claimGrant = async (payload, slug, grantId) => {
+	if (!ROW_ID.test(grantId)) return;
+	const handle = rowHandle(payload, grantId);
+	const row = (await findRows(payload, slug, [handle])).find((candidate) => candidate.key.startsWith("mcpx-grant:") && candidate.key.endsWith(`:${handle}`));
+	const grant = row?.data;
+	if (!row || !isPlainObject(grant) || expOf(grant) <= Date.now()) return;
+	const prefixes = rowPrefixes("grant", grant.apiKeyId);
+	return row.key === `${prefixes.prefix}${handle}` && await claimRow(payload, slug, prefixes, handle, grant.exp) ? grant : void 0;
+};
+//#endregion
+export { NO_REQ, ROW_ID, claimGrant, claimRow, expOf, grantContext, grantKvSlug, issueGrant, issueRow, rowHandle, rowPrefixes, rowsWith };

package/dist/guards.mjs

@@ -1,5 +1,14 @@
 //#region src/guards.ts
 const isPlainObject = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
-/** An own property only, so a client-chosen key never reads the prototype. */ const ownValue = (record, key) => record !== void 0 && Object.hasOwn(record, key) ? record[key] : void 0;
+/**
+* A property of a plain object, `undefined` for any other value.
+*/ const propOf = (value, key) => isPlainObject(value) ? value[key] : void 0;
+/**
+* An own property only, so a client-chosen key never reads the prototype.
+*/ const ownValue = (record, key) => record !== void 0 && Object.hasOwn(record, key) ? record[key] : void 0;
+/**
+* The entries whose value is not `undefined`, for spreading optional arguments
+* into a call.
+*/ const definedProps = (props) => Object.fromEntries(Object.entries(props).filter(([, value]) => value !== void 0));
 //#endregion
-export { isPlainObject, ownValue };
+export { definedProps, isPlainObject, ownValue, propOf };

package/dist/i18n.mjs

@@ -21,7 +21,9 @@ const pick = (record, language) => {
 	return pick(record, language.language) ?? pick(record, language.fallbackLanguage) ?? Object.values(record).find((entry) => entry.trim() !== "");
 };
 const translatorFor = (i18n) => (value) => translateStatic(value, i18n);
-/** For callers with no request. Both languages miss, so the first entry wins. */ const translateAny = translatorFor({
+/**
+* For callers with no request. Both languages miss, so the first entry wins.
+*/ const translateAny = translatorFor({
 	fallbackLanguage: "",
 	language: ""
 });

package/dist/index.d.mts

@@ -1,8 +1,8 @@
 import { DocumentId } from "./entity.mjs";
-import { McpxAnyTool, McpxAuthResult, McpxCollectionCapabilities, McpxCollectionOptions, McpxExposedEntity, McpxGlobalOptions, McpxPluginOptions, McpxRequestContext, McpxResolvedCapabilities, McpxScopeSlugs, McpxTool, McpxToolExtra, McpxToolScope, McpxWriteMode } from "./types.mjs";
+import { McpxAnyTool, McpxAuthResult, McpxCollectionOptions, McpxEntityCapabilities, McpxExposedEntity, McpxGlobalOptions, McpxPluginOptions, McpxRequestContext, McpxResolvedCapabilities, McpxScopeSlugs, McpxTool, McpxToolExtra, McpxToolScope } from "./types.mjs";
 import { defineMcpxTool } from "./define-tool.mjs";
 import { mcpxPlugin } from "./plugin.mjs";
 import { isMcpxRequest } from "./request.mjs";
 import { errorResult, jsonResult } from "./result.mjs";
 import { mcpxReadRequest } from "./tools/read-request.mjs";
-export { type McpxAnyTool, type McpxAuthResult, type McpxCollectionCapabilities, type McpxCollectionOptions, type DocumentId as McpxDocumentId, type McpxExposedEntity, type McpxGlobalOptions, type McpxPluginOptions, type McpxRequestContext, type McpxResolvedCapabilities, type McpxScopeSlugs, type McpxTool, type McpxToolExtra, type McpxToolScope, type McpxWriteMode, defineMcpxTool, errorResult, isMcpxRequest, jsonResult, mcpxPlugin, mcpxReadRequest };
+export { type McpxAnyTool, type McpxAuthResult, type McpxCollectionOptions, type DocumentId as McpxDocumentId, type McpxEntityCapabilities, type McpxExposedEntity, type McpxGlobalOptions, type McpxPluginOptions, type McpxRequestContext, type McpxResolvedCapabilities, type McpxScopeSlugs, type McpxTool, type McpxToolExtra, type McpxToolScope, defineMcpxTool, errorResult, isMcpxRequest, jsonResult, mcpxPlugin, mcpxReadRequest };

package/dist/index.mjs

@@ -1,6 +1,6 @@
 import { defineMcpxTool } from "./define-tool.mjs";
+import { isMcpxRequest } from "./request.mjs";
 import { errorResult, jsonResult } from "./result.mjs";
 import { mcpxReadRequest } from "./tools/read-request.mjs";
-import { isMcpxRequest } from "./request.mjs";
 import { mcpxPlugin } from "./plugin.mjs";
 export { defineMcpxTool, errorResult, isMcpxRequest, jsonResult, mcpxPlugin, mcpxReadRequest };

package/dist/options.mjs

@@ -1,5 +1,4 @@
 import { isPlainObject } from "./guards.mjs";
-import { BUILTIN_TOOL_NAMES } from "./builtin-tool-names.mjs";
 import "./version.mjs";
 import { InvalidConfiguration } from "payload";
 import { hasDraftsEnabled, hasLocalizeStatusEnabled } from "payload/shared";
@@ -12,13 +11,21 @@ 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());
-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.`);
+/**
+* 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());
+const assertExposable = (kind, config, apiKeysSlug) => {
+	const { slug } = config;
+	if (slug.startsWith("payload-") || kind === "Collection" && slug === apiKeysSlug) fail(`${kind} "${slug}" cannot be exposed.`);
+	if ("auth" in config && config.auth) fail(`Auth collection "${slug}" cannot be exposed. Its documents carry credentials.`);
 };
 const OPTION_NAMES = [
+	"read",
+	"write",
+	"publish",
+	"delete"
+];
+const GLOBAL_OPTION_NAMES = [
 	"read",
 	"write",
 	"publish"
@@ -32,87 +39,82 @@ const readFlag = (kind, slug, name, value) => {
 	const moved = name === "write" && typeof value === "string" ? REMOVED_WRITE_MODES[value] : void 0;
 	return fail(`${kind} "${slug}" has ${name}: ${JSON.stringify(value)}. ${moved ?? "Use true or false."}`);
 };
-const assertWritable = (kind, config, write) => {
-	if (write === "live" && hasLocalizeStatusEnabled(config)) fail(`${kind} "${config.slug}" has versions.drafts.localizeStatus enabled, which live writes do not support yet. Set publish: false or write: false.`);
+const assertWritable = (kind, config, publish) => {
+	if (publish && hasLocalizeStatusEnabled(config)) fail(`${kind} "${config.slug}" has versions.drafts.localizeStatus enabled, which live writes do not support yet. Set publish: false or write: false.`);
+};
+const normalizeDelete = (kind, config, value) => {
+	if (value !== "unattended") return {
+		delete: readFlag(kind, config.slug, "delete", value) ?? false,
+		deleteUnattended: false
+	};
+	if (!("trash" in config) || !config.trash) fail(`${kind} "${config.slug}" has delete: "unattended" but no trash, so a delete without approval would be permanent. Enable trash or set delete: true.`);
+	return {
+		delete: true,
+		deleteUnattended: true
+	};
 };
 const normalizeCapabilities = (kind, config, raw) => {
 	const { slug } = config;
+	const names = kind === "Global" ? GLOBAL_OPTION_NAMES : OPTION_NAMES;
 	if (raw === false) fail(`${kind} "${slug}" is set to false. Remove the entry to hide the ${kind.toLowerCase()}.`);
-	if (raw !== true && !isPlainObject(raw)) fail(`${kind} "${slug}" has ${JSON.stringify(raw)}. Use true or an object of ${OPTION_NAMES.join(", ")}.`);
+	if (raw !== true && !isPlainObject(raw)) fail(`${kind} "${slug}" has ${JSON.stringify(raw)}. Use true or an object of ${names.join(", ")}.`);
 	const settings = isPlainObject(raw) ? raw : {};
-	const unknownKey = Object.keys(settings).find((key) => !OPTION_NAMES.includes(key));
-	if (unknownKey !== void 0) fail(`${kind} "${slug}" has the unknown option "${unknownKey}". The options are ${OPTION_NAMES.join(", ")}.`);
+	const unknownKey = Object.keys(settings).find((key) => !names.includes(key));
+	if (unknownKey !== void 0) fail(`${kind} "${slug}" has the unknown option "${unknownKey}". The options are ${names.join(", ")}.`);
 	const flag = (name) => readFlag(kind, slug, name, settings[name]);
 	const read = flag("read") ?? true;
-	const write = flag("write") ?? true;
+	const write = flag("write") ?? read;
 	const publish = flag("publish");
 	const hasDrafts = hasDraftsEnabled(config);
 	if (publish === false && write && !hasDrafts) fail(`${kind} "${slug}" has no drafts, so every write goes live. Set write: false or remove publish: false.`);
 	if (publish === true && !hasDrafts) fail(`${kind} "${slug}" has no drafts, so there is nothing to publish. Enable versions.drafts or remove publish: true.`);
+	if (!read && (flag("write") === true || publish === true)) fail(`${kind} "${slug}" has read: false but write or publish on. Writing and publishing need read.`);
 	if (publish === true && !write) fail(`${kind} "${slug}" has publish: true but write: false. Publishing follows write.`);
+	const deleting = normalizeDelete(kind, config, settings["delete"]);
+	if (!read && deleting.delete) fail(`${kind} "${slug}" has read: false but delete on. Deleting needs read.`);
 	return {
 		read,
-		write: write ? publish === false ? "draft" : "live" : false,
+		write,
+		publish: write && publish !== false && hasDrafts,
+		liveWrite: write && !hasDrafts,
 		hasDrafts,
-		hasVersions: read && Boolean(config.versions)
+		hasVersions: read && Boolean(config.versions),
+		...deleting
 	};
 };
-const assertGlobalExposable = (global) => {
-	if (global.slug.startsWith("payload-")) fail(`Global "${global.slug}" cannot be exposed.`);
-};
-const normalizeCollections = (config, options, apiKeysSlug) => {
-	const collections = config.collections ?? [];
+const bySlug = (configs) => new Map(configs.map((config) => [config.slug, config]));
+const normalizeEntities = (kind, configs, entries, apiKeysSlug) => {
 	const fieldNames = /* @__PURE__ */ new Set();
-	return Object.entries(options.collections).flatMap(([slug, raw]) => {
+	return Object.entries(entries).flatMap(([slug, raw]) => {
 		if (raw === void 0) return [];
-		const collection = collections.find((candidate) => candidate.slug === slug);
-		if (!collection) return fail(`Exposed collection "${slug}" does not exist.`);
-		assertExposable(collection, apiKeysSlug);
+		const config = configs.get(slug);
+		if (!config) return fail(`Exposed ${kind.toLowerCase()} "${slug}" does not exist.`);
+		assertExposable(kind, config, apiKeysSlug);
 		const normalized = {
 			slug,
-			...normalizeCapabilities("Collection", collection, raw),
-			isUpload: Boolean(collection.upload),
+			...normalizeCapabilities(kind, config, raw),
+			isUpload: "upload" in config && Boolean(config.upload),
 			fieldName: toCamelCase(slug)
 		};
-		if (normalized.write !== false) {
-			if (collection.timestamps === false) fail(`Collection "${slug}" has timestamps disabled, which write tools need for concurrency checks.`);
-			assertWritable("Collection", collection, normalized.write);
+		if (normalized.write) {
+			if ("timestamps" in config && config.timestamps === false) fail(`Collection "${slug}" has timestamps disabled, which write tools need for concurrency checks.`);
+			assertWritable(kind, config, normalized.publish);
 		}
-		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];
-	});
-};
-const normalizeGlobals = (config, options) => {
-	const globals = config.globals ?? [];
-	const fieldNames = /* @__PURE__ */ new Set();
-	return Object.entries(options.globals ?? {}).flatMap(([slug, raw]) => {
-		if (raw === void 0) return [];
-		const global = globals.find((candidate) => candidate.slug === slug);
-		if (!global) return fail(`Exposed global "${slug}" does not exist.`);
-		assertGlobalExposable(global);
-		const normalized = {
-			slug,
-			...normalizeCapabilities("Global", global, raw),
-			isUpload: false,
-			fieldName: toCamelCase(slug)
-		};
-		if (normalized.write !== false) assertWritable("Global", global, normalized.write);
-		if (fieldNames.has(normalized.fieldName)) fail(`Global "${slug}" maps to capability field "${normalized.fieldName}", which another exposed global already uses.`);
+		if (fieldNames.has(normalized.fieldName)) fail(`${kind} "${slug}" maps to capability field "${normalized.fieldName}", which another exposed ${kind.toLowerCase()} already uses.`);
 		fieldNames.add(normalized.fieldName);
 		return [normalized];
 	});
 };
-const assertUserCollection = (config, slug) => {
-	const collection = (config.collections ?? []).find((candidate) => candidate.slug === slug);
+const assertUserCollection = (collections, slug) => {
+	const collection = collections.get(slug);
 	if (!collection) fail(`User collection "${slug}" does not exist.`);
-	else if (!collection.auth) fail(`User collection "${slug}" is not an auth collection.`);
+	else if (!("auth" in collection && collection.auth)) fail(`User collection "${slug}" is not an auth collection.`);
 };
-const assertTools = (tools) => {
+const assertTools = (tools, reserved) => {
 	const names = /* @__PURE__ */ new Set();
 	for (const tool of tools) {
 		if (!TOOL_NAME_PATTERN.test(tool.name)) fail(`Tool name "${tool.name}" must match ${String(TOOL_NAME_PATTERN)}.`);
-		if (BUILTIN_TOOL_NAMES.includes(tool.name)) fail(`Tool name "${tool.name}" is reserved for a builtin tool.`);
+		if (reserved.includes(tool.name)) fail(`Tool name "${tool.name}" is reserved for a builtin tool.`);
 		if (names.has(tool.name)) fail(`Tool name "${tool.name}" is used twice.`);
 		names.add(tool.name);
 	}
@@ -127,27 +129,36 @@ const normalizeLimits = (limits) => {
 		maxDepth
 	};
 };
-/** Every problem is an `InvalidConfiguration`, so it fails at startup. */ const normalizeOptions = (config, options) => {
+/**
+* Every problem is an `InvalidConfiguration`, so it fails at startup.
+* `reservedToolNames` are the builtin tool names custom tools must not reuse.
+*/ const normalizeOptions = (config, options, reservedToolNames) => {
 	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.`);
-	assertUserCollection(config, userCollection);
+	const collectionConfigs = bySlug(config.collections ?? []);
+	if (collectionConfigs.has(apiKeysSlug)) fail(`API key collection slug "${apiKeysSlug}" is already taken.`);
+	assertUserCollection(collectionConfigs, userCollection);
 	const tools = options.tools ?? [];
-	assertTools(tools);
+	assertTools(tools, reservedToolNames);
+	const collections = normalizeEntities("Collection", collectionConfigs, options.collections, apiKeysSlug);
+	const confirmations = collections.some((entity) => entity.delete);
+	if (confirmations && options.auth?.resolve) fail("delete needs approval on the API key document, which a custom auth.resolve does not support. Remove delete: true or auth.resolve.");
 	return {
-		collections: normalizeCollections(config, options, apiKeysSlug),
-		globals: normalizeGlobals(config, options),
+		collections,
+		globals: normalizeEntities("Global", bySlug(config.globals ?? []), options.globals ?? {}, apiKeysSlug),
 		userCollection,
 		apiKeysSlug,
 		endpointPath: options.endpoint?.path ?? DEFAULT_ENDPOINT_PATH,
 		setupGuide: options.apiKeys?.setupGuide ?? true,
 		limits: normalizeLimits(options.limits),
 		tools,
+		confirmations,
 		auth: options.auth,
 		serverInfo: {
 			name: options.serverInfo?.name ?? "payloadcms-mcpx",
-			version: options.serverInfo?.version ?? "1.0.0"
-		}
+			version: options.serverInfo?.version ?? "2.0.0"
+		},
+		diagnostics: options.diagnostics ?? true
 	};
 };
 //#endregion

package/dist/plugin.d.mts

@@ -1,8 +1,9 @@
 import { McpxPluginOptions } from "./types.mjs";
 //#region src/plugin.d.ts
 /**
- * Mounts the MCP endpoint, adds the API key collection and installs the
- * draft guard on every collection and global.
+ * Mounts the MCP, upload and download endpoints, and the confirmation
+ * endpoints where a collection exposes `delete`. Adds the API key collection
+ * and installs the draft guard on every collection and global.
  */
 export declare const mcpxPlugin: (options: McpxPluginOptions) => import("payload").Plugin;
 //#endregion

package/dist/plugin.mjs

@@ -1,17 +1,21 @@
 import { createApiKeysCollection } from "./api-keys/collection.mjs";
+import { BUILTIN_TOOLS } from "./tools/builtin.mjs";
+import { confirmationEndpoints } from "./endpoint/confirmations.mjs";
 import { createMcpxHandler, methodNotAllowed } from "./endpoint/handler.mjs";
+import { createDownloadHandler, createUploadHandler } from "./endpoint/upload.mjs";
 import { normalizeOptions } from "./options.mjs";
 import { installDraftGuards, installGlobalDraftGuards } from "./write/draft-guard.mjs";
 import { definePlugin } from "payload";
 //#region src/plugin.ts
 /**
-* Mounts the MCP endpoint, adds the API key collection and installs the
-* draft guard on every collection and global.
+* Mounts the MCP, upload and download endpoints, and the confirmation
+* endpoints where a collection exposes `delete`. Adds the API key collection
+* and installs the draft guard on every collection and global.
 */ const mcpxPlugin = definePlugin({
 	slug: "@abinnovision/payloadcms-mcpx",
 	order: 100,
 	plugin: ({ config, plugins: _plugins, ...options }) => {
-		const normalized = normalizeOptions(config, options);
+		const normalized = normalizeOptions(config, options, BUILTIN_TOOLS.map((tool) => tool.name));
 		const apiKeys = createApiKeysCollection(normalized);
 		const apiKeysCollection = options.apiKeys?.overrideCollection?.(apiKeys) ?? apiKeys;
 		return {
@@ -34,7 +38,18 @@ import { definePlugin } from "payload";
 					path: normalized.endpointPath,
 					method: "delete",
 					handler: methodNotAllowed
-				}
+				},
+				{
+					path: `${normalized.endpointPath}/upload`,
+					method: "put",
+					handler: createUploadHandler(normalized)
+				},
+				{
+					path: `${normalized.endpointPath}/file`,
+					method: "get",
+					handler: createDownloadHandler(normalized)
+				},
+				...normalized.confirmations ? confirmationEndpoints(normalized) : []
 			]
 		};
 	}

package/dist/request.mjs

@@ -3,5 +3,9 @@
 * Whether `req` came through the MCP endpoint, which stamps `req.context.mcpx`.
 * The stamp follows `req` into every local API call, including custom tools.
 */ const isMcpxRequest = (req) => req.context.mcpx !== void 0;
+/**
+* The origin links to this server use: `serverURL` when set, else that of the
+* MCP request.
+*/ const publicOrigin = (req) => req.payload.config.serverURL || new URL(req.url ?? "").origin;
 //#endregion
-export { isMcpxRequest };
+export { isMcpxRequest, publicOrigin };

package/dist/result.mjs

@@ -1,4 +1,14 @@
 //#region src/result.ts
+/**
+* The JSON of a result's first text block. Other text comes back as `{ text }`.
+*/ const parseResult = (result) => {
+	const [first] = result.content;
+	try {
+		return first?.type === "text" ? JSON.parse(first.text) : {};
+	} catch {
+		return { text: first?.type === "text" ? first.text : void 0 };
+	}
+};
 const jsonResult = (value) => ({ content: [{
 	type: "text",
 	text: JSON.stringify(value)
@@ -17,4 +27,4 @@ const jsonResult = (value) => ({ content: [{
 	isError: true
 });
 //#endregion
-export { errorResult, jsonResult };
+export { errorResult, jsonResult, parseResult };

package/dist/schema/admin-hidden.mjs

@@ -1,5 +1,5 @@
 import { isPlainObject } from "../guards.mjs";
-import { RESERVED_FIELD_NAMES, ROW_KEYS, blockOf, blockSlugsOf, isAdminHidden, schemaOf } from "./walk.mjs";
+import { RESERVED_FIELD_NAMES, ROW_KEYS, adminFlag, blockForRow, blockOf, blockSlugsOf, schemaOf } from "./walk.mjs";
 //#region src/schema/admin-hidden.ts
 const UPLOAD_BASE_FIELDS = /* @__PURE__ */ new Set([
 	"filename",
@@ -22,7 +22,7 @@ const stripFields = (config, fields, doc, exempt = NONE) => {
 	const result = { ...doc };
 	for (const field of fields) {
 		if (!("name" in field) || exempt.has(field.name) || isPayloadKey(field.name) || !Object.hasOwn(result, field.name)) continue;
-		if (isAdminHidden(field)) Reflect.deleteProperty(result, field.name);
+		if (adminFlag(field, "hidden")) Reflect.deleteProperty(result, field.name);
 		else result[field.name] = stripValue(config, field, result[field.name]);
 	}
 	return result;
@@ -45,7 +45,7 @@ const stripValue = (config, field, value) => {
 		case "tab": return isPlainObject(value) ? stripFields(config, field.flattenedFields, value) : value;
 		case "array": return mapEach(value, (row) => isPlainObject(row) ? stripFields(config, field.flattenedFields, row) : row);
 		case "blocks": return mapEach(value, (row) => {
-			const block = isPlainObject(row) && typeof row["blockType"] === "string" ? blockOf(config, field, row["blockType"]) : void 0;
+			const block = blockForRow(config, field, row);
 			return block && isPlainObject(row) ? stripFields(config, block.flattenedFields, row) : row;
 		});
 		case "relationship":
@@ -76,7 +76,7 @@ const stripValue = (config, field, value) => {
 		const matches = fields.filter((field) => "name" in field && field.name === segment);
 		if (matches.length === 0) return locales.includes(segment) ? walk(fields, rest) : false;
 		return matches.some((field) => {
-			if (isAdminHidden(field)) return true;
+			if (adminFlag(field, "hidden")) return true;
 			if (field.type === "group" || field.type === "tab" || field.type === "array") return walk(field.flattenedFields, rest);
 			return field.type === "blocks" && blockSlugsOf(field).some((slug) => {
 				const block = blockOf(config, field, slug);

package/dist/schema/describe.mjs

@@ -1,25 +1,22 @@
+import { SchemaError } from "./errors.mjs";
 import { lexicalSubSchema, subSchemaNodeTypes } from "./lexical.mjs";
 import { joinPath, splitPath } from "./path.mjs";
 import { translateAny } from "../i18n.mjs";
-import { blockOf, blockSlugsOf, describeFields, findBlocksField, findRichTextField, schemaOf } from "./walk.mjs";
-import { SchemaError } from "./errors.mjs";
+import { blockSlugsOf, describeFields, findFieldAt, longestMatch, requireBlock, schemaOf } from "./walk.mjs";
 //#region src/schema/describe.ts
-const matchSchemaSegments = (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);
+	const field = findFieldAt(fields, match, "blocks");
 	if (!field) throw new Error(`"${joinPath(match)}" could not be resolved.`);
 	const slug = remaining.at(match.length);
 	if (slug === void 0) throw new SchemaError(`"${joinPath(match)}" is a blocks field; append one of: ${blockSlugsOf(field).join(", ")}`);
-	const block = blockOf(config, field, slug);
-	if (!block) throw new SchemaError(`"${slug}" is not allowed at "${joinPath(match)}". Allowed: ${blockSlugsOf(field).join(", ")}`);
 	return {
 		blockType: slug,
-		fields: block.flattenedFields,
+		fields: requireBlock(config, field, slug, joinPath(match)).flattenedFields,
 		rest: remaining.slice(match.length + 1)
 	};
 };
 const stepThroughLexical = ({ config, fields, match, remaining }) => {
-	const field = findRichTextField(fields, match);
+	const field = findFieldAt(fields, match, "richText");
 	if (!field) throw new Error(`"${joinPath(match)}" could not be resolved.`);
 	const available = subSchemaNodeTypes(field).join(", ") || "none";
 	const nodeType = remaining.at(match.length);
@@ -32,13 +29,10 @@ const stepThroughLexical = ({ config, fields, match, remaining }) => {
 		rest: remaining.slice(match.length + 1)
 	};
 	const slug = remaining.at(match.length + 1);
-	const slugs = blockSlugsOf(sub.blocksField).join(", ");
-	if (slug === void 0) throw new SchemaError(`"${reached}" selects a block; append one of: ${slugs}`);
-	const block = blockOf(config, sub.blocksField, slug);
-	if (!block) throw new SchemaError(`"${slug}" is not allowed at "${reached}". Allowed: ${slugs}`);
+	if (slug === void 0) throw new SchemaError(`"${reached}" selects a block; append one of: ${blockSlugsOf(sub.blocksField).join(", ")}`);
 	return {
 		blockType: slug,
-		fields: block.flattenedFields,
+		fields: requireBlock(config, sub.blocksField, slug, reached).flattenedFields,
 		rest: remaining.slice(match.length + 2)
 	};
 };
@@ -48,15 +42,15 @@ const fieldsAtSchemaPath = (config, target, schemaPath) => {
 	let remaining = splitPath(schemaPath);
 	while (remaining.length > 0) {
 		const descendable = describeFields(fields).filter((descriptor) => descriptor.type === "blocks" || descriptor.type === "richText");
-		const match = matchSchemaSegments(descendable, remaining);
-		if (!match) throw new SchemaError(`"${joinPath(remaining)}" does not address a blocks or rich text field. Available here: ${descendable.map((descriptor) => descriptor.path).join(", ") || "none"}`);
+		const found = longestMatch(descendable, remaining, (part, segment) => part === segment);
+		if (!found) throw new SchemaError(`"${joinPath(remaining)}" does not address a blocks or rich text field. Available here: ${descendable.map((descriptor) => descriptor.path).join(", ") || "none"}`);
 		const at = {
 			config,
 			fields,
-			match,
+			match: found.parts,
 			remaining
 		};
-		const step = findBlocksField(fields, match) === void 0 ? stepThroughLexical(at) : stepThroughBlocks(at);
+		const step = found.descriptor.type === "blocks" ? stepThroughBlocks(at) : stepThroughLexical(at);
 		blockType = step.blockType;
 		fields = step.fields;
 		remaining = step.rest;
@@ -69,7 +63,7 @@ const fieldsAtSchemaPath = (config, target, schemaPath) => {
 const branchesOf = (fields, descriptor, schemaPath) => {
 	const base = `${schemaPath}${descriptor.path}`;
 	if (descriptor.type === "richText") {
-		const field = findRichTextField(fields, splitPath(descriptor.path));
+		const field = findFieldAt(fields, splitPath(descriptor.path), "richText");
 		if (!field) return [];
 		return subSchemaNodeTypes(field).flatMap((nodeType) => {
 			const sub = lexicalSubSchema(field, nodeType);

package/dist/schema/index.mjs

@@ -1,11 +1,10 @@
-import { REQUIRED_NODE_PROPERTIES, ROOT_PROPERTIES, allowedNodeTypes, constrainsFields, lexicalSubSchema, nodeOptions, nodeProblems, nodePropertiesFor, propertyProblem, rootProblems, subSchemaNodeTypes } from "./lexical.mjs";
-import { JSON_POINTER_PATTERN, isIndexSegment, joinPath, pointerFromPayloadPath, prototypeSegmentProblem, splitPath } from "./path.mjs";
-import { RESERVED_FIELD_NAMES, ROW_KEYS, blockOf, blockSlugsOf, describeAddressableFields, describeFields, descriptorsUnder, findBlocksField, findRichTextField, isAdminHidden, schemaOf } from "./walk.mjs";
-import { addressesAdminHidden, stripAdminHidden } from "./admin-hidden.mjs";
 import { SchemaError } from "./errors.mjs";
+import { editorRoot, nodePropertiesFor } from "./lexical.mjs";
+import { JSON_POINTER_PATTERN, isIndexSegment, parentPointer, pointerFromPayloadPath, prototypeSegmentProblem, splitPath } from "./path.mjs";
+import { RESERVED_FIELD_NAMES, ROW_KEYS, blockForRow, classifyKey, descriptorsUnder, findFieldAt } from "./walk.mjs";
+import { addressesAdminHidden, stripAdminHidden } from "./admin-hidden.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, ROW_KEYS, SchemaError, addressesAdminHidden, allowedNodeTypes, blockOf, blockSlugsOf, constrainsFields, describeAddressableFields, describeFields, descriptorsUnder, findBlocksField, findRichTextField, isAdminHidden, isIndexSegment, joinPath, lexicalOutline, lexicalSubSchema, nodeDescriber, nodeOptions, nodeProblems, nodePropertiesFor, pointerFromPayloadPath, propertyProblem, prototypeSegmentProblem, reachableSchemaPaths, resolveDataPointer, resolveLexicalPointer, rootProblems, schemaOf, splitPath, stripAdminHidden, subSchemaNodeTypes, validateWriteValue };
+export { EMPTY_ROOT, JSON_POINTER_PATTERN, RESERVED_FIELD_NAMES, ROW_KEYS, SchemaError, addressesAdminHidden, blockForRow, classifyKey, descriptorsUnder, editorRoot, findFieldAt, isIndexSegment, lexicalOutline, nodeDescriber, nodePropertiesFor, parentPointer, pointerFromPayloadPath, prototypeSegmentProblem, reachableSchemaPaths, resolveDataPointer, splitPath, stripAdminHidden, validateWriteValue };