@abinnovision/payloadcms-mcpx 1.1.0-beta.6 → 2.0.0-beta.12

package/dist/endpoint/server.mjs

@@ -1,44 +1,107 @@
 import { toToolError } from "./errors.mjs";
-import { draftSentence } from "../tools/shared.mjs";
+import { fileSlugs } from "../upload/file.mjs";
+import { liveWriteSlugs } from "../tools/shared.mjs";
+import { MCPX_REPOSITORY_URL } from "../version.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;
+/**
+* Strict, so an unknown argument is rejected by name instead of stripped.
+*/ const toolInputSchema = (tool, scope) => z.strictObject(typeof tool.inputSchema === "function" ? tool.inputSchema(scope) : tool.inputSchema ?? {});
+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;
+/**
+* Runs one tool call. Payload's public errors become error results; anything
+* else is logged and reported as an internal error.
+*/ const runTool = async (tool, args, scope, req, extra) => {
+	try {
+		return await tool.handler({
+			args,
+			scope,
+			req,
+			extra
+		});
+	} catch (error) {
+		return toToolError(error, req.payload.logger);
+	}
+};
+const WRITE_STEP = {
+	tools: ["patchDocument", "createDocument"],
+	does: "the write"
+};
+const WORKFLOW = [
+	{
+		tools: ["listCapabilities"],
+		does: "what this key may access"
+	},
+	{
+		tools: ["describeSchema"],
+		does: "the fields"
+	},
+	{
+		tools: ["findDocuments", "getDocument"],
+		does: "the content and its \"updatedAt\""
+	},
+	WRITE_STEP,
+	{
+		tools: ["validateDocument"],
+		does: "what blocks publishing"
+	},
+	{
+		tools: ["publishDocument"],
+		does: "make the draft public"
+	}
+];
+const UPLOAD_STEP = "A write that returns \"upload\": PUT the file bytes to its \"url\" with its \"headers\". The response is the result of the write.";
+const PATHS = `describeSchema takes and returns schema paths. Every other "path", and "from" in a patch operation, is a pointer into a document, with a 0-based index where a schema path has "*" for an array element or a block slug: "/layout/sections/sectionWrapper/identifier" is "/layout/sections/0/identifier". In rich text a pointer enters the rich text state: "/content/block/callout/tone" is "/content/root/children/3/fields/tone". getDocument "outline" gives the index.`;
+const DRAFTS = "Writes are saved as drafts, except in collections and globals without drafts, which patchDocument names: those go live immediately.";
+const DRAFTS_ONLY = "Every write is saved as a draft.";
+/**
+* The workflow for the tools this key has, and what its writes reach.
+*/ const serverInstructions = (scope) => {
+	const enabled = new Set(BUILTIN_TOOLS.filter((tool) => isToolEnabled(tool, scope)).map((tool) => tool.name));
+	const uploads = fileSlugs(scope).length > 0;
+	const steps = WORKFLOW.flatMap((step) => {
+		const present = step.tools.filter((name) => enabled.has(name));
+		if (present.length === 0) return [];
+		const line = `${present.join(" or ")}: ${step.does}.`;
+		return step === WRITE_STEP && uploads ? [line, UPLOAD_STEP] : [line];
+	}).map((step, index) => `${String(index + 1)}. ${step}`);
+	const publishing = enabled.has("publishDocument") ? "" : " This key cannot publish. A person publishes drafts in the admin panel.";
+	const drafts = liveWriteSlugs(scope, "write").length === 0 ? DRAFTS_ONLY : DRAFTS;
+	const writes = enabled.has("patchDocument") ? `\n\n${drafts}${publishing}` : "";
+	const paths = enabled.has("describeSchema") ? `\n\n${PATHS}` : "";
+	return `Call the tools in this order:\n${steps.join("\n")}${paths}${writes}`;
+};
 /**
 * 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.
+* what the key may call. The tool handlers of one JSON-RPC batch run one at a time,
+* so a failed call cannot roll back a write another call reported as done.
 */ const createMcpServer = (scope, options) => {
 	const { req } = scope;
-	const { logger } = req.payload;
+	let queue = Promise.resolve();
 	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. ${draftSentence(scope)}` });
-	const guarded = (run) => async () => {
-		try {
-			return await run();
-		} catch (error) {
-			return toToolError(error, logger);
-		}
-	};
+		version: options.serverInfo.version,
+		...options.diagnostics ? { websiteUrl: MCPX_REPOSITORY_URL } : {}
+	}, { instructions: serverInstructions(scope) });
 	for (const tool of [...BUILTIN_TOOLS, ...options.tools]) {
 		if (!isToolEnabled(tool, scope)) continue;
 		server.registerTool(tool.name, {
 			description: toolDescription(tool, scope),
 			inputSchema: toolInputSchema(tool, scope),
 			...tool.annotations ? { annotations: tool.annotations } : {}
-		}, (args, extra) => guarded(() => tool.handler({
-			args,
-			scope,
-			req,
-			extra
-		}))());
+		}, (args, extra) => {
+			const result = queue.then(async () => await runTool(tool, args, scope, req, extra));
+			queue = result.catch(() => void 0);
+			return result;
+		});
 	}
 	return server;
 };
 //#endregion
-export { createMcpServer, isToolEnabled, toolDescription, toolInputSchema };
+export { createMcpServer, isToolEnabled, runTool, toolInputSchema };

package/dist/endpoint/upload.mjs

@@ -0,0 +1,135 @@
+import { checkApiKey } from "../auth/resolve.mjs";
+import { claimGrant, uploadKvSlug } from "../upload/grant.mjs";
+import { downloadSlugs, setUploadedFile, uploadMaxBytes } from "../upload/file.mjs";
+import { BUILTIN_TOOLS } from "../tools/builtin.mjs";
+import { isToolEnabled, runTool, toolInputSchema } from "./server.mjs";
+import { authenticateAs } from "./handler.mjs";
+//#region src/endpoint/upload.ts
+const UPLOAD_TOOLS = /* @__PURE__ */ new Set(["createDocument", "patchDocument"]);
+const respond = (status, body) => Response.json(body, { status });
+const refused = () => respond(403, { error: "The request was refused: the grant is unknown, expired or used, or the key no longer allows it. Call the tool again for a new one." });
+const readExactly = async (req, size) => {
+	const declared = req.headers.get("content-length");
+	if (declared !== null && Number(declared) !== size) return null;
+	if (!req.body) return null;
+	const chunks = [];
+	let total = 0;
+	for await (const chunk of req.body) {
+		total += chunk.byteLength;
+		if (total > size) return null;
+		chunks.push(chunk);
+	}
+	return total === size ? Buffer.concat(chunks) : null;
+};
+const statusOf = (result, data) => {
+	if (result.isError !== true) return 200;
+	if ("updatedAt" in data || data["status"] === 423) return 409;
+	if (data["status"] === 401 || data["status"] === 403) return 403;
+	return data["error"] === "Internal error" ? 500 : 422;
+};
+const parseResult = (result) => {
+	const [first] = result.content;
+	return first?.type === "text" ? JSON.parse(first.text) : {};
+};
+const NO_SESSION = {
+	signal: new AbortController().signal,
+	requestId: "upload",
+	sendNotification: () => Promise.resolve(),
+	sendRequest: () => Promise.reject(/* @__PURE__ */ new Error("No MCP session."))
+};
+const reauthenticate = async (req, options, grant) => {
+	const keyDoc = await req.payload.findByID({
+		collection: options.apiKeysSlug,
+		id: grant.apiKeyId,
+		depth: 0,
+		overrideAccess: true,
+		disableErrors: true,
+		select: {
+			enabled: true,
+			user: true,
+			capabilities: true,
+			expiresAt: true
+		}
+	});
+	return await checkApiKey(req, options, keyDoc ?? void 0);
+};
+const claimAs = async (req, options, kind) => {
+	const slug = uploadKvSlug(req.payload.config);
+	const grantId = req.headers.get("x-mcpx-grant");
+	if (slug === void 0 || options.auth?.resolve || grantId === null) return;
+	const grant = await claimGrant(req.payload, slug, grantId);
+	if (grant?.kind !== kind) return;
+	const auth = await reauthenticate(req, options, grant);
+	if (!auth) return;
+	const scope = authenticateAs(req, options, auth);
+	req.query = {};
+	for (const name of [...req.searchParams.keys()]) req.searchParams.delete(name);
+	req.locale = grant.locale;
+	req.fallbackLocale = grant.fallbackLocale;
+	return {
+		grant,
+		scope
+	};
+};
+/**
+* Completes a call that returned an `upload`: claims the grant, acts as its
+* key again, then runs the same tool with the same arguments and the body as
+* the file. The response body is the tool's result. The grant header is never
+* logged.
+*/ const createUploadHandler = (options) => async (req) => {
+	const { payload } = req;
+	const claimed = await claimAs(req, options, "upload");
+	const file = claimed?.grant.args["file"];
+	if (!claimed || !UPLOAD_TOOLS.has(claimed.grant.tool) || !file) return refused();
+	const { grant, scope } = claimed;
+	const tool = BUILTIN_TOOLS.find((candidate) => candidate.name === grant.tool);
+	if (!tool || !isToolEnabled(tool, scope)) return refused();
+	const args = toolInputSchema(tool, scope).safeParse(grant.args);
+	if (!args.success) return refused();
+	if (file.size > uploadMaxBytes(payload.config)) return respond(413, { error: "The file is larger than allowed." });
+	const data = await readExactly(req, file.size);
+	if (data === null) return respond(400, { error: `The body must be exactly ${String(file.size)} bytes, the size the tool call declared.` });
+	setUploadedFile(req, {
+		data,
+		mimetype: file.mimeType,
+		name: file.filename,
+		size: data.length
+	});
+	const result = await runTool(tool, args.data, scope, req, NO_SESSION);
+	const body = parseResult(result);
+	return respond(statusOf(result, body), body);
+};
+/**
+* Serves the file of a `getDocument` call that returned a `download`: claims
+* the grant, acts as its key again, reloads the document as its user and
+* hands the request to the collection's own `/file/:filename` endpoint, so
+* Payload's file access, storage handlers and response headers apply.
+*/ const createDownloadHandler = (options) => async (req) => {
+	const claimed = await claimAs(req, options, "download");
+	if (!claimed || !downloadSlugs(claimed.scope).includes(claimed.grant.collection)) return refused();
+	const { collection, id, draft } = claimed.grant;
+	const doc = await req.payload.findByID({
+		collection,
+		id,
+		depth: 0,
+		draft,
+		overrideAccess: false,
+		disableErrors: true,
+		select: {
+			filename: true,
+			prefix: true
+		},
+		req
+	});
+	const { endpoints } = req.payload.collections[collection]?.config ?? {};
+	const endpoint = Array.isArray(endpoints) ? endpoints.find((candidate) => candidate.method === "get" && candidate.path === "/file/:filename") : void 0;
+	if (typeof doc?.filename !== "string" || !endpoint) return refused();
+	if (typeof doc.prefix === "string") req.searchParams.set("prefix", doc.prefix);
+	req.routeParams = {
+		collection,
+		filename: doc.filename
+	};
+	return await endpoint.handler(req);
+};
+//#endregion
+export { createDownloadHandler, createUploadHandler };

package/dist/entity.d.mts

@@ -0,0 +1,9 @@
+import "payload";
+//#region src/entity.d.ts
+/**
+ * The id type follows the database adapter and a collection's own `id` field,
+ * so one project can have both. Payload's `DefaultDocumentIDType` narrows to
+ * the project default, so it cannot be used here.
+ */
+export type DocumentId = number | string;
+//#endregion

package/dist/guards.mjs

@@ -0,0 +1,7 @@
+//#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;
+//#endregion
+export { isPlainObject, ownValue };

package/dist/i18n.mjs

@@ -1,27 +1,29 @@
 //#region src/i18n.ts
 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) => {
+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;
 	}
 };
 /**
-* Resolves a static label or `admin.description` to the one string a client
-* can use: the request's language, then the fallback language configured for
-* the deployment, then whichever entry the record declares first.
+* Resolves a static label or `admin.description` to one string: the request's
+* language, then the configured fallback language, then the first entry the
+* record declares.
 *
 * Anything that is not a string or a string-valued record is dropped. A
-* description written as a function or a React component is an admin-UI
-* construct that may reach client-only i18n, so it is never invoked here.
+* function or React component description may reach client-only i18n, so it is
+* never invoked.
 */ const translateStatic = (value, language) => {
 	if (typeof value === "string") return value.trim() === "" ? void 0 : value;
 	const record = stringRecord(value);
 	if (!record) return;
 	return pick(record, language.language) ?? pick(record, language.fallbackLanguage) ?? Object.values(record).find((entry) => entry.trim() !== "");
 };
-/** 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({
+const translatorFor = (i18n) => (value) => translateStatic(value, i18n);
+/**
+* For callers with no request. Both languages miss, so the first entry wins.
+*/ const translateAny = translatorFor({
 	fallbackLanguage: "",
 	language: ""
 });

package/dist/index.d.mts

@@ -1,5 +1,8 @@
-import { McpxAnyTool, McpxAuthResult, McpxCollectionCapabilities, McpxCollectionOptions, McpxExposedEntity, McpxGlobalOptions, McpxPluginOptions, McpxRequestContext, McpxResolvedCapabilities, McpxTool, McpxToolExtra, McpxToolScope, McpxWriteMode, PublishBlocker, defineMcpxTool } from "./types.mjs";
+import { DocumentId } from "./entity.mjs";
+import { McpxAnyTool, McpxAuthResult, McpxCollectionCapabilities, McpxCollectionOptions, McpxExposedEntity, McpxGlobalOptions, McpxPluginOptions, McpxRequestContext, McpxResolvedCapabilities, McpxScopeSlugs, McpxTool, McpxToolExtra, McpxToolScope, McpxWriteMode } 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";
-export { McpxAnyTool, McpxAuthResult, McpxCollectionCapabilities, McpxCollectionOptions, McpxExposedEntity, McpxGlobalOptions, McpxPluginOptions, McpxRequestContext, McpxResolvedCapabilities, McpxTool, McpxToolExtra, McpxToolScope, McpxWriteMode, PublishBlocker, defineMcpxTool, errorResult, isMcpxRequest, jsonResult, mcpxPlugin };
+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 };

package/dist/index.mjs

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

package/dist/options.mjs

@@ -1,5 +1,6 @@
-import { BUILTIN_TOOL_NAMES } from "./tools/names.mjs";
+import { isPlainObject } from "./guards.mjs";
 import "./version.mjs";
+import { BUILTIN_TOOL_NAMES } from "./builtin-tool-names.mjs";
 import { InvalidConfiguration } from "payload";
 import { hasDraftsEnabled, hasLocalizeStatusEnabled } from "payload/shared";
 //#region src/options.ts
@@ -11,45 +12,55 @@ 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());
 /**
-* Auth collections carry credentials: `useAPIKey` stores a key that decrypts on
-* read, and email or lockout state is PII either way. Refused for read too.
-*/ const assertExposable = (collection, apiKeysSlug) => {
+* 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.`);
 };
-/** 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".`);
+const OPTION_NAMES = [
+	"read",
+	"write",
+	"publish"
+];
+const REMOVED_WRITE_MODES = {
+	draft: "Use { publish: false } instead.",
+	live: "Writes are on by default, so remove it."
 };
-/**
-* `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 readFlag = (kind, slug, name, value) => {
+	if (value === void 0 || typeof value === "boolean") return 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 = (collection, options) => {
-	const { slug } = collection;
-	if (collection.timestamps === false) fail(`Collection "${slug}" has timestamps disabled, which write tools need for concurrency checks.`);
-	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);
+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.`);
 };
-/** 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.`);
+const normalizeCapabilities = (kind, config, raw) => {
+	const { slug } = config;
+	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(", ")}.`);
+	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 flag = (name) => readFlag(kind, slug, name, settings[name]);
+	const read = flag("read") ?? true;
+	const write = flag("write") ?? true;
+	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 (publish === true && !write) fail(`${kind} "${slug}" has publish: true but write: false. Publishing follows write.`);
+	return {
+		read,
+		write: write ? publish === false ? "draft" : "live" : false,
+		hasDrafts,
+		hasVersions: read && Boolean(config.versions)
+	};
 };
-/**
-* `GlobalConfig` has no `timestamps` option and `sanitizeGlobal` always appends
-* `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.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 assertGlobalExposable = (global) => {
+	if (global.slug.startsWith("payload-")) fail(`Global "${global.slug}" cannot be exposed.`);
 };
 const normalizeCollections = (config, options, apiKeysSlug) => {
 	const collections = config.collections ?? [];
@@ -59,18 +70,16 @@ const normalizeCollections = (config, options, apiKeysSlug) => {
 		const collection = collections.find((candidate) => candidate.slug === slug);
 		if (!collection) return fail(`Exposed collection "${slug}" does not exist.`);
 		assertExposable(collection, apiKeysSlug);
-		const settings = raw === true ? {} : raw;
-		const hasDrafts = hasDraftsEnabled(collection);
 		const normalized = {
 			slug,
-			read: settings.read ?? true,
-			write: normalizeWriteMode("Collection", slug, settings.write),
-			hasDrafts,
-			hasVersions: Boolean(collection.versions),
+			...normalizeCapabilities("Collection", collection, raw),
 			isUpload: Boolean(collection.upload),
 			fieldName: toCamelCase(slug)
 		};
-		if (normalized.write !== false) assertWritable(collection, normalized);
+		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 (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];
@@ -84,18 +93,13 @@ const normalizeGlobals = (config, options) => {
 		const global = globals.find((candidate) => candidate.slug === slug);
 		if (!global) return fail(`Exposed global "${slug}" does not exist.`);
 		assertGlobalExposable(global);
-		const settings = raw === true ? {} : raw;
-		const hasDrafts = hasDraftsEnabled(global);
 		const normalized = {
 			slug,
-			read: settings.read ?? true,
-			write: normalizeWriteMode("Global", slug, settings.write),
-			hasDrafts,
-			hasVersions: Boolean(global.versions),
+			...normalizeCapabilities("Global", global, raw),
 			isUpload: false,
 			fieldName: toCamelCase(slug)
 		};
-		if (normalized.write !== false) assertGlobalWritable(global, normalized);
+		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.`);
 		fieldNames.add(normalized.fieldName);
 		return [normalized];
@@ -125,7 +129,9 @@ 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.
+*/ 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.`);
@@ -145,7 +151,8 @@ const normalizeLimits = (limits) => {
 		serverInfo: {
 			name: options.serverInfo?.name ?? "payloadcms-mcpx",
 			version: options.serverInfo?.version ?? "1.0.0"
-		}
+		},
+		diagnostics: options.diagnostics ?? true
 	};
 };
 //#endregion

package/dist/plugin.d.mts

@@ -1,8 +1,8 @@
 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, 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,13 +1,13 @@
 import { createApiKeysCollection } from "./api-keys/collection.mjs";
 import { createMcpxHandler, methodNotAllowed } from "./endpoint/handler.mjs";
-import "./endpoint/index.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, adds the API key collection
+* and installs the draft guard on every collection and global.
 */ const mcpxPlugin = definePlugin({
 	slug: "@abinnovision/payloadcms-mcpx",
 	order: 100,
@@ -35,6 +35,16 @@ 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)
 				}
 			]
 		};

package/dist/request.d.mts

@@ -1,9 +1,8 @@
 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
- * same `req`, including those made by custom tools.
+ * Whether `req` came through the MCP endpoint, which stamps `req.context.mcpx`.
+ * The stamp follows `req` into every local API call, including custom tools.
  */
 export declare const isMcpxRequest: (req: PayloadRequest) => boolean;
 //#endregion

package/dist/request.mjs

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

package/dist/result.d.mts

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

package/dist/result.mjs

@@ -1,11 +1,11 @@
 //#region src/result.ts
-/** `value` as JSON text. */ const jsonResult = (value) => ({ content: [{
+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`.
+* `extras` carries data the client can act on, such as problems, validation
+* errors or the current `updatedAt`.
 */ const errorResult = (message, extras = {}) => ({
 	content: [{
 		type: "text",