@abinnovision/payloadcms-mcpx 2.0.0-beta.10 → 2.0.0-beta.12

package/README.md

@@ -103,6 +103,7 @@ Claude Desktop and the MCP Inspector are covered in
 | `tools`                      | `[]`                                      | Custom tools, see [`docs/custom-tools.md`](./docs/custom-tools.md). |
 | `auth.resolve`               | none                                      | Replace or wrap the key lookup.                                     |
 | `serverInfo`                 | `payloadcms-mcpx` and the package version | `{ name, version }` reported to clients.                            |
+| `diagnostics`                | `true`                                    | Expose the server version plus repository and issue links.          |
 
 The config only takes capabilities away: `true` exposes everything the entity supports, and a key's
 checkboxes decide what each key may do. `publish: false` keeps MCP writes as drafts. On an entity
@@ -121,8 +122,8 @@ every check.
 | `findDocuments`    | Queries a collection with a Payload `where`, `sort` and `select`.  | `read`             |
 | `getDocument`      | Reads a document, a subtree of it, an old version or a diff.       | `read`             |
 | `findVersions`     | Lists the version history of a document or global, without bodies. | `read`             |
-| `patchDocument`    | Applies JSON Patch operations to the current draft.                | `write`            |
-| `createDocument`   | Creates a draft from a seed. Not for upload collections.           | `write`            |
+| `patchDocument`    | Applies JSON Patch operations to the current draft, or a new file. | `write`            |
+| `createDocument`   | Creates a draft from a seed, with a file in an upload collection.  | `write`            |
 | `validateDocument` | Lists what blocks publishing, without saving.                      | `write`            |
 | `publishDocument`  | Publishes the current draft.                                       | `write`, `publish` |
 
@@ -163,6 +164,9 @@ To restrict that, use `apiKeys.overrideCollection` as shown in
   Blocker messages can name fields the user cannot read.
 - The request body is limited to 4 MB, a JSON-RPC batch to 10 messages, `patchDocument` to 500
   operations and `describeSchema` to 400 paths.
+- A file is sent in a second step, a `PUT`, and downloaded with a `GET`, each with a short-lived,
+  single-use grant. Only collections with `upload.mimeTypes` take files. Downloads go through the
+  collection's own file access. See [uploads](./docs/security.md#uploads).
 - Custom tools are trusted code and must apply access control themselves.
 
 Open limitations: a filter through a relation into a readable collection ignores that collection's

package/dist/api-keys/capability-matrix.mjs

@@ -1,4 +1,4 @@
-import { CAPABILITIES_FIELD, canCreate, canPublish, canWrite, isLiveWrite } from "../capabilities.mjs";
+import { CAPABILITIES_FIELD, canPublish, canWrite, isLiveWrite } from "../capabilities.mjs";
 //#region src/api-keys/capability-matrix.ts
 /**
 * The group's `admin.description`, rendered by the matrix in Payload's
@@ -25,12 +25,8 @@ import { CAPABILITIES_FIELD, canCreate, canPublish, canWrite, isLiveWrite } from
 		description: "Promote the current draft to what the public sees."
 	}
 ];
-const UPLOAD_HINT = "Files are uploaded in the admin panel.";
 const LIVE_HINT = "Writes go live immediately.";
-const hintFor = (entity) => {
-	const hints = [canWrite(entity) && !canCreate(entity) ? UPLOAD_HINT : void 0, isLiveWrite(entity) ? LIVE_HINT : void 0].filter((hint) => hint !== void 0);
-	return hints.length > 0 ? { hint: hints.join(" ") } : {};
-};
+const hintFor = (entity) => isLiveWrite(entity) ? { hint: LIVE_HINT } : {};
 const toRow = (entity) => ({
 	fieldName: entity.fieldName,
 	label: entity.slug,

package/dist/auth/resolve.mjs

@@ -22,6 +22,43 @@ const isId = (value) => typeof value === "string" || typeof value === "number";
 	return isId(auth["user"]["id"]) && auth["user"]["collection"] === options.userCollection && isId(auth["apiKeyId"]);
 };
 /**
+* The checks a key passes once it is looked up: enabled, not expired, and its
+* user exists, is verified and is not locked out. Yields the user it acts as,
+* or `null`.
+*/ const checkApiKey = async (req, options, keyDoc) => {
+	const userId = relationId(keyDoc?.user);
+	if (!keyDoc || keyDoc.enabled !== true || userId === void 0) return null;
+	if (toTime(keyDoc.expiresAt) <= Date.now()) return null;
+	const { payload } = req;
+	const userCollection = payload.collections[options.userCollection];
+	const lookup = {
+		collection: options.userCollection,
+		id: userId,
+		overrideAccess: true,
+		disableErrors: true
+	};
+	const [user, lock] = await Promise.all([payload.findByID({
+		...lookup,
+		depth: userCollection?.config.auth.depth ?? 0
+	}), payload.findByID({
+		...lookup,
+		depth: 0,
+		showHiddenFields: true,
+		select: { lockUntil: true }
+	})]);
+	const lockUntil = toTime(lock?.["lockUntil"]);
+	if (!user || user["_verified"] === false || lockUntil > Date.now()) return null;
+	return {
+		user: {
+			...user,
+			collection: options.userCollection,
+			_strategy: "mcpx-api-key"
+		},
+		apiKeyId: keyDoc.id,
+		capabilities: keyDoc.capabilities
+	};
+};
+/**
 * Resolves the bearer key of a request to the user it acts as.
 *
 * The key is looked up by its HMAC index, the same way Payload resolves its own
@@ -47,27 +84,8 @@ const isId = (value) => typeof value === "string" || typeof value === "number";
 		}
 	});
 	const keyDoc = docs[0];
-	const userId = relationId(keyDoc?.user);
-	if (!keyDoc || keyDoc.enabled !== true || userId === void 0) return null;
-	if (toTime(keyDoc.expiresAt) <= Date.now()) return null;
-	const userCollection = payload.collections[options.userCollection];
-	const lookup = {
-		collection: options.userCollection,
-		id: userId,
-		overrideAccess: true,
-		disableErrors: true
-	};
-	const [user, lock] = await Promise.all([payload.findByID({
-		...lookup,
-		depth: userCollection?.config.auth.depth ?? 0
-	}), payload.findByID({
-		...lookup,
-		depth: 0,
-		showHiddenFields: true,
-		select: { lockUntil: true }
-	})]);
-	const lockUntil = toTime(lock?.["lockUntil"]);
-	if (!user || user["_verified"] === false || lockUntil > Date.now()) return null;
+	const auth = await checkApiKey(req, options, keyDoc);
+	if (!auth || !keyDoc) return null;
 	const lastUsed = toTime(keyDoc.lastUsedAt);
 	if (Number.isNaN(lastUsed) || Date.now() - lastUsed > LAST_USED_INTERVAL_MS) try {
 		await payload.update({
@@ -84,15 +102,7 @@ const isId = (value) => typeof value === "string" || typeof value === "number";
 			msg: "Could not record the last use of an MCP API key"
 		});
 	}
-	return {
-		user: {
-			...user,
-			collection: options.userCollection,
-			_strategy: "mcpx-api-key"
-		},
-		apiKeyId: keyDoc.id,
-		capabilities: keyDoc.capabilities
-	};
+	return auth;
 };
 //#endregion
-export { isValidAuthResult, parseBearer, resolveApiKeyAuth };
+export { checkApiKey, isValidAuthResult, parseBearer, resolveApiKeyAuth };

package/dist/capabilities.mjs

@@ -10,9 +10,9 @@ import { isPlainObject } from "./guards.mjs";
 * The config lets MCP change live content and a draft exists 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;
+* Any writable collection. An upload collection also needs a file, which
+* depends on the request, so the tools check it per call.
+*/ const canCreate = (entity) => canWrite(entity);
 /**
 * Without drafts there is no draft stage, so every write is live.
 */ const isLiveWrite = (entity) => entity.write === "live" && !entity.hasDrafts;

package/dist/endpoint/handler.mjs

@@ -1,6 +1,7 @@
 import { resolveCapabilities, scopeSlugs } from "../capabilities.mjs";
 import { isValidAuthResult, resolveApiKeyAuth } from "../auth/resolve.mjs";
 import { jsonRpcError } from "./errors.mjs";
+import { uploadKvSlug } from "../upload/grant.mjs";
 import { createMcpServer } from "./server.mjs";
 import { WebStandardStreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/webStandardStreamableHttp.js";
 //#region src/endpoint/handler.ts
@@ -34,6 +35,11 @@ const readBody = async (req) => {
 			defaultLocale: localization.defaultLocale
 		} : null,
 		limits: options.limits,
+		uploads: options.auth?.resolve === void 0 && uploadKvSlug(req.payload.config) !== void 0,
+		diagnostics: options.diagnostics ? {
+			name: options.serverInfo.name,
+			version: options.serverInfo.version
+		} : null,
 		exposure: {
 			collections: options.collections,
 			globals: options.globals
@@ -41,6 +47,22 @@ const readBody = async (req) => {
 	};
 };
 /**
+* Makes `req` act as the key: sets `req.user`, replacing any user Payload
+* resolved from cookies, and the `req.context.mcpx` stamp the draft guard
+* reads. Returns the scope the tools see.
+*/ const authenticateAs = (req, options, auth) => {
+	const capabilities = resolveCapabilities(options, auth.capabilities);
+	req.user = auth.user;
+	req.context = {
+		...req.context,
+		mcpx: {
+			apiKeyId: auth.apiKeyId,
+			capabilities
+		}
+	};
+	return buildScope(req, options, capabilities);
+};
+/**
 * Answers GET and DELETE on the endpoint path. The server is stateless and
 * never streams, so only POST carries meaning.
 */ const methodNotAllowed = () => jsonRpcError({
@@ -69,15 +91,7 @@ const readBody = async (req) => {
 			headers: { "www-authenticate": "Bearer" }
 		});
 	}
-	const capabilities = resolveCapabilities(options, auth.capabilities);
-	req.user = auth.user;
-	req.context = {
-		...req.context,
-		mcpx: {
-			apiKeyId: auth.apiKeyId,
-			capabilities
-		}
-	};
+	const scope = authenticateAs(req, options, auth);
 	let parsedBody;
 	try {
 		const text = await readBody(req);
@@ -104,7 +118,7 @@ const readBody = async (req) => {
 		code: -32600,
 		message: `Invalid request: a batch may hold at most ${String(BATCH_MESSAGES_LIMIT)} messages.`
 	});
-	const server = createMcpServer(buildScope(req, options, capabilities), options);
+	const server = createMcpServer(scope, options);
 	const transport = new WebStandardStreamableHTTPServerTransport({ enableJsonResponse: true });
 	await server.connect(transport);
 	const headers = new Headers(req.headers);
@@ -119,4 +133,4 @@ const readBody = async (req) => {
 	}
 };
 //#endregion
-export { buildScope, createMcpxHandler, methodNotAllowed };
+export { authenticateAs, buildScope, createMcpxHandler, methodNotAllowed };

package/dist/endpoint/server.mjs

@@ -1,5 +1,7 @@
 import { toToolError } from "./errors.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";
@@ -11,6 +13,25 @@ const toolDescription = (tool, scope) => typeof tool.description === "function"
 /**
 * 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"],
@@ -24,10 +45,7 @@ const WORKFLOW = [
 		tools: ["findDocuments", "getDocument"],
 		does: "the content and its \"updatedAt\""
 	},
-	{
-		tools: ["patchDocument", "createDocument"],
-		does: "the write"
-	},
+	WRITE_STEP,
 	{
 		tools: ["validateDocument"],
 		does: "what blocks publishing"
@@ -37,6 +55,7 @@ const WORKFLOW = [
 		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.";
@@ -44,9 +63,12 @@ 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 steps = WORKFLOW.flatMap(({ tools, does }) => {
-		const present = tools.filter((name) => enabled.has(name));
-		return present.length === 0 ? [] : [`${present.join(" or ")}: ${does}.`];
+	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;
@@ -61,11 +83,11 @@ const DRAFTS_ONLY = "Every write is saved as a draft.";
 * 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
+		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;
@@ -74,18 +96,7 @@ const DRAFTS_ONLY = "Every write is saved as a draft.";
 			inputSchema: toolInputSchema(tool, scope),
 			...tool.annotations ? { annotations: tool.annotations } : {}
 		}, (args, extra) => {
-			const result = queue.then(async () => {
-				try {
-					return await tool.handler({
-						args,
-						scope,
-						req,
-						extra
-					});
-				} catch (error) {
-					return toToolError(error, logger);
-				}
-			});
+			const result = queue.then(async () => await runTool(tool, args, scope, req, extra));
 			queue = result.catch(() => void 0);
 			return result;
 		});
@@ -93,4 +104,4 @@ const DRAFTS_ONLY = "Every write is saved as a draft.";
 	return server;
 };
 //#endregion
-export { createMcpServer, isToolEnabled, 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/options.mjs

@@ -1,6 +1,6 @@
 import { isPlainObject } from "./guards.mjs";
-import { BUILTIN_TOOL_NAMES } from "./builtin-tool-names.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
@@ -151,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,12 +1,13 @@
 import { createApiKeysCollection } from "./api-keys/collection.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, adds the API key collection
+* and installs the draft guard on every collection and global.
 */ const mcpxPlugin = definePlugin({
 	slug: "@abinnovision/payloadcms-mcpx",
 	order: 100,
@@ -34,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/tools/create-document.mjs

@@ -2,10 +2,12 @@ import { defineMcpxTool } from "../define-tool.mjs";
 import { errorResult, jsonResult } from "../result.mjs";
 import { validateWriteValue } from "../schema/shape.mjs";
 import "../schema/index.mjs";
-import { liveWriteSentence, localeOf, localeShape, patchOnlySlugs, slugEnum, slugsFor } from "./shared.mjs";
 import { collectPublishBlockers } from "../write/publish-blockers.mjs";
+import { assertAcceptsFile, fileShape, fileWriteRefusal, uploadHandoff, uploadedFile } from "../upload/file.mjs";
+import { liveWriteSentence, localeOf, localeShape, patchOnlySlugs, slugEnum, slugsFor } from "./shared.mjs";
 import { readDraft, resolveEntity } from "./document.mjs";
 import { stripRowIds } from "../write/row-ids.mjs";
+import { APIError } from "payload";
 import { z } from "zod";
 //#region src/tools/create-document.ts
 const uploadSentence = (scope) => {
@@ -16,8 +18,9 @@ const DESCRIPTION = (scope) => `Creates a document in a collection. Use it only
 
 ${liveWriteSentence(scope, "create")}${uploadSentence(scope)}`;
 /**
-* Collection-only, because a global always exists. Upload collections are
-* excluded because a create there would need the file.
+* Collection-only, because a global always exists. A create in an upload
+* collection needs `file`: the call then returns an upload grant, and the PUT
+* to it runs the call again with the bytes.
 *
 * The seed is checked against the collection's fields first, so an unknown key
 * is refused along with its valid siblings. Row ids in the seed are stripped
@@ -40,13 +43,17 @@ ${liveWriteSentence(scope, "create")}${uploadSentence(scope)}`;
 			required: true,
 			description: "Locale of the localized fields in \"data\"."
 		}),
-		data: z.record(z.string(), z.unknown()).describe("Field values by name, e.g. {\"title\":\"Home\",\"slug\":\"home\"}.")
+		data: z.record(z.string(), z.unknown()).describe("Field values by name, e.g. {\"title\":\"Home\",\"slug\":\"home\"}."),
+		...fileShape(scope, (slugs) => `Required in ${slugs}. The call returns an "upload" for the bytes instead of writing.`)
 	}),
 	handler: async ({ args, scope }) => {
 		const target = resolveEntity(scope, { collection: args.collection }, "create");
 		if (target.kind === "global") throw new Error("createDocument resolved a global.");
 		const { payload } = scope.req;
 		const locale = localeOf(scope, args.locale);
+		const { file } = args;
+		if (file !== void 0) assertAcceptsFile(scope, target, file);
+		else if (scope.exposure.collections.some((entity) => entity.slug === target.slug && entity.isUpload)) throw new APIError(`"${target.slug}" stores files, so "file" is required.`, 400);
 		if (Object.hasOwn(args.data, "id")) return errorResult("Nothing was created.", { problems: ["/id: Payload assigns the id; it cannot be supplied."] });
 		const problems = validateWriteValue(payload.config, {
 			pointer: "",
@@ -56,6 +63,21 @@ ${liveWriteSentence(scope, "create")}${uploadSentence(scope)}`;
 			}
 		}, args.data);
 		if (problems.length > 0) return errorResult("Nothing was created.", { problems });
+		const bytes = uploadedFile(scope.req);
+		if (file !== void 0) {
+			const refusal = await fileWriteRefusal(scope, {
+				entity: target,
+				data: args.data
+			});
+			if (refusal) return refusal;
+			if (!bytes) return await uploadHandoff(scope, {
+				tool: "createDocument",
+				args: {
+					...args,
+					file
+				}
+			});
+		}
 		const created = await payload.create({
 			collection: args.collection,
 			data: stripRowIds(args.data),
@@ -63,7 +85,8 @@ ${liveWriteSentence(scope, "create")}${uploadSentence(scope)}`;
 			draft: true,
 			overrideAccess: false,
 			req: scope.req,
-			...locale === void 0 ? {} : { locale }
+			...locale === void 0 ? {} : { locale },
+			...bytes === void 0 ? {} : { file: bytes }
 		});
 		const saved = await readDraft(scope, {
 			target: {

package/dist/tools/document.mjs

@@ -1,6 +1,6 @@
 import { errorResult } from "../result.mjs";
-import { slugsFor } from "./shared.mjs";
 import { collectPublishBlockers } from "../write/publish-blockers.mjs";
+import { slugsFor } from "./shared.mjs";
 import { APIError, Forbidden, NotFound } from "payload";
 //#region src/tools/document.ts
 /**

package/dist/tools/get-document.mjs

@@ -6,6 +6,7 @@ import { SchemaError } from "../schema/errors.mjs";
 import { lexicalOutline } from "../schema/outline.mjs";
 import { resolveDataPointer } from "../schema/pointer.mjs";
 import "../schema/index.mjs";
+import { downloadHandoff, downloadSlugs } from "../upload/file.mjs";
 import { READ_LOCALE_DESCRIPTION, depthShape, entityShape, idSchema, idShape, localeOf, localeShape, slugsFor, widen } from "./shared.mjs";
 import { identityOf, resolveDocument } from "./document.mjs";
 import { diffDocuments, loadPublished, loadVersion, readLive } from "./versions.mjs";
@@ -46,6 +47,18 @@ const versionShape = (scope) => {
 		diffFrom: idSchema.optional().describe("Version id, or \"published\" for the newest version published in any locale. Returns {from, to, patch}, the JSON Patch from that version to what is read.")
 	});
 };
+const downloadShape = (scope) => {
+	const slugs = downloadSlugs(scope);
+	return widen(slugs.length === 0 ? {} : { download: z.literal(true).optional().describe(`Only for ${slugs.join(", ")}. Adds "download": GET its "url" with its "headers" once, within 5 minutes, for the file. Not with "path", "versionId" or "diffFrom".`) });
+};
+const assertDownloadArgs = (scope, target, args) => {
+	if (target.kind === "global" || !downloadSlugs(scope).includes(target.slug)) throw new APIError(`"${target.slug}" has no file to download.`, 400);
+	if (args.path !== void 0 || args.versionId !== void 0 || args.diffFrom !== void 0) throw new APIError("\"download\" cannot be combined with \"path\", \"versionId\" or \"diffFrom\".", 400);
+};
+const withDownload = async (scope, doc, target) => typeof doc["filename"] === "string" ? jsonResult({
+	...doc,
+	download: await downloadHandoff(scope, target)
+}) : errorResult("This document has no file to download.");
 /**
 * With `path` the handler returns the subtree plus the `id`, `_status` and
 * `updatedAt` a client needs to write back, so reading one branch still gives
@@ -69,11 +82,13 @@ const versionShape = (scope) => {
 		}),
 		draft: z.boolean().optional().describe("Default true. false reads the published version."),
 		outline: z.boolean().optional().describe("With \"path\" at a rich text field: list each node's pointer, type, \"version\" and text."),
-		...versionShape(scope)
+		...versionShape(scope),
+		...downloadShape(scope)
 	}),
 	handler: async ({ args, scope }) => {
 		const target = resolveDocument(scope, args, "read");
 		assertVersionArgs(scope, target, args);
+		if (args.download) assertDownloadArgs(scope, target, args);
 		const prototyped = args.path ? prototypeSegmentProblem(args.path) : void 0;
 		if (prototyped !== void 0) return errorResult(prototyped);
 		let pointer;
@@ -96,7 +111,12 @@ const versionShape = (scope) => {
 		}, doc);
 		if (pointer === void 0) {
 			if (args.outline) return errorResult(OUTLINE_ERROR);
-			return jsonResult(doc);
+			return args.download && args.id !== void 0 ? await withDownload(scope, doc, {
+				collection: target.slug,
+				id: args.id,
+				draft: args.draft ?? true,
+				locale: read.locale ?? null
+			}) : jsonResult(doc);
 		}
 		const path = pointer.toString();
 		const value = pointer.get(doc);

package/dist/tools/list-capabilities.mjs

@@ -1,10 +1,12 @@
 import { defineMcpxTool } from "../define-tool.mjs";
-import { canCreate } from "../capabilities.mjs";
 import { jsonResult } from "../result.mjs";
 import { translateStatic, translatorFor } from "../i18n.mjs";
+import { slugsFor } from "./shared.mjs";
+import { MCPX_ISSUES_URL, MCPX_REPOSITORY_URL } from "../version.mjs";
 import { hasDraftValidationEnabled } from "payload/shared";
 //#region src/tools/list-capabilities.ts
 const DESCRIPTION = `Lists what this key may do. Call it first. Returns each collection and global the key can read or write, with whether it can create, publish, has drafts and exposes versions to findVersions, and a collection's "idType". Also returns the locales, the "limits" on page size and depth, and the enabled custom tools.`;
+const DIAGNOSTICS = ` Its "server" block holds the server version with repository and issue links, for a bug report.`;
 const translateLabel = (scope, label, fallback) => {
 	const { i18n, t } = scope.req;
 	const resolved = typeof label === "function" ? label({
@@ -21,7 +23,7 @@ const translateLabel = (scope, label, fallback) => {
 * grows.
 */ const listCapabilities = defineMcpxTool({
 	name: "listCapabilities",
-	description: DESCRIPTION,
+	description: (scope) => scope.diagnostics ? `${DESCRIPTION}${DIAGNOSTICS}` : DESCRIPTION,
 	annotations: {
 		readOnlyHint: true,
 		openWorldHint: false
@@ -31,6 +33,7 @@ const translateLabel = (scope, label, fallback) => {
 	handler: ({ scope }) => {
 		const { payload } = scope.req;
 		const translate = translatorFor(scope.req.i18n);
+		const creatable = slugsFor(scope, "create").collections;
 		const collections = scope.exposure.collections.flatMap((entry) => {
 			const capability = scope.capabilities.collections[entry.slug];
 			const collection = payload.collections[entry.slug];
@@ -46,7 +49,7 @@ const translateLabel = (scope, label, fallback) => {
 				...description === void 0 ? {} : { description },
 				read: capability.read,
 				write: capability.write,
-				create: capability.write && canCreate(entry),
+				create: creatable.includes(entry.slug),
 				publish: capability.publish,
 				drafts: entry.hasDrafts,
 				versions: entry.hasVersions,
@@ -79,7 +82,13 @@ const translateLabel = (scope, label, fallback) => {
 				default: scope.localization.defaultLocale
 			} : null,
 			limits: scope.limits,
-			tools: Object.entries(scope.capabilities.tools).filter(([, enabled]) => enabled).map(([name]) => name)
+			tools: Object.entries(scope.capabilities.tools).filter(([, enabled]) => enabled).map(([name]) => name),
+			...scope.diagnostics ? { server: {
+				name: scope.diagnostics.name,
+				version: scope.diagnostics.version,
+				repository: MCPX_REPOSITORY_URL,
+				issues: MCPX_ISSUES_URL
+			} } : {}
 		});
 	}
 });

package/dist/tools/patch-document.mjs

@@ -3,13 +3,14 @@ import { isPlainObject } from "../guards.mjs";
 import { errorResult, jsonResult } from "../result.mjs";
 import { JSON_POINTER_PATTERN } from "../schema/path.mjs";
 import "../schema/index.mjs";
-import { entityShape, idShape, liveWriteSentence, localeOf, localeShape } from "./shared.mjs";
 import { collectPublishBlockers } from "../write/publish-blockers.mjs";
+import { assertAcceptsFile, fileShape, fileSlugs, fileWriteRefusal, uploadHandoff, uploadedFile } from "../upload/file.mjs";
+import { entityShape, idShape, liveWriteSentence, localeOf, localeShape } from "./shared.mjs";
 import { identityOf, readDraft, resolveDocument, staleReadResult } from "./document.mjs";
 import { applyPatchOperations, isElementPointer } from "../write/patch.mjs";
 import { withTransaction } from "../write/transaction.mjs";
 import { buildWriteData } from "../write/write-data.mjs";
-import { Forbidden, NotFound } from "payload";
+import { APIError, Forbidden, NotFound } from "payload";
 import { z } from "zod";
 import { Pointer } from "rfc6902";
 //#region src/tools/patch-document.ts
@@ -75,7 +76,8 @@ const notAppliedPointers = (patches, intended, saved) => patches.flatMap((operat
 * document before writing anything, runs the write in a transaction, then
 * re-reads the saved document to report which pointers survived and what still
 * blocks publishing. The draft guard, not this tool, decides where the write
-* lands.
+* lands. With `file`, the patches and the file land as one update, and the
+* transaction commits right after it because Payload has moved files by then.
 */ const patchDocument = defineMcpxTool({
 	name: "patchDocument",
 	description: DESCRIPTION,
@@ -93,27 +95,72 @@ const notAppliedPointers = (patches, intended, saved) => patches.flatMap((operat
 			required: true,
 			description: "Localized fields are written in this locale only."
 		}),
-		patches: z.array(PATCH_OPERATION_SCHEMA).min(1).max(PATCHES_LIMIT),
-		expectedUpdatedAt: z.string().optional().describe("\"updatedAt\" from your last read. Refused if the document changed since.")
+		patches: fileSlugs(scope).length === 0 ? z.array(PATCH_OPERATION_SCHEMA).min(1).max(PATCHES_LIMIT) : z.array(PATCH_OPERATION_SCHEMA).max(PATCHES_LIMIT).describe("May be empty when \"file\" is given."),
+		expectedUpdatedAt: z.string().optional().describe("\"updatedAt\" from your last read. Refused if the document changed since."),
+		...fileShape(scope, (slugs) => `Replaces the file of a document in ${slugs}. The call returns an "upload" for the bytes instead of writing.`)
 	}),
 	handler: async ({ args, scope }) => {
 		const target = resolveDocument(scope, args, "write");
 		const { payload } = scope.req;
 		const locale = localeOf(scope, args.locale);
 		const patches = args.patches;
-		return await withTransaction(scope.req, async () => {
+		const { file } = args;
+		const bytes = uploadedFile(scope.req);
+		if (file !== void 0) assertAcceptsFile(scope, target, file);
+		if (patches.length === 0 && file === void 0) throw new APIError("\"patches\" may be empty only when \"file\" is given.", 400);
+		const report = async (next) => {
+			const saved = await readDraft(scope, {
+				target,
+				locale,
+				privileged: true
+			});
+			const readable = await readDraft(scope, {
+				target,
+				locale
+			}).catch((error) => {
+				if (error instanceof NotFound || error instanceof Forbidden) return;
+				throw error;
+			});
+			const notApplied = readable ? notAppliedPointers(patches, next, readable) : [];
+			const validation = await collectPublishBlockers(scope.req, {
+				doc: saved,
+				entity: target
+			});
+			return jsonResult({
+				...identityOf(target, saved["id"]),
+				status: saved["_status"],
+				updatedAt: saved["updatedAt"],
+				...validation.blockers.length > 0 ? { publishBlockers: validation.blockers } : {},
+				...validation.unavailable ? { publishBlockersUnavailable: true } : {},
+				...notApplied.length > 0 ? { notApplied } : {}
+			});
+		};
+		const outcome = await withTransaction(scope.req, async () => {
 			const doc = await readDraft(scope, {
 				target,
 				locale
 			});
 			const stale = staleReadResult(doc, args.expectedUpdatedAt, "The document changed since you read it. Read it again and re-apply the patch.");
-			if (stale) return stale;
+			if (stale) return { done: stale };
 			const applied = applyPatchOperations(payload.config, {
 				doc,
 				patches,
 				ref: target
 			});
-			if ("problems" in applied) return errorResult("No operation was applied.", { problems: applied.problems });
+			if ("problems" in applied) return { done: errorResult("No operation was applied.", { problems: applied.problems }) };
+			if (file !== void 0 && target.kind === "collection") {
+				const refusal = await fileWriteRefusal(scope, {
+					entity: target,
+					id: target.id,
+					data: applied.next
+				});
+				if (refusal) return { done: refusal };
+				if (!bytes) return { handoff: {
+					...args,
+					file,
+					expectedUpdatedAt: doc["updatedAt"]
+				} };
+			}
 			const write = {
 				data: buildWriteData(payload.config, target.config, applied.next),
 				depth: 0,
@@ -125,39 +172,22 @@ const notAppliedPointers = (patches, intended, saved) => patches.flatMap((operat
 			if (target.kind === "collection") await payload.update({
 				...write,
 				collection: target.slug,
-				id: target.id
+				id: target.id,
+				...bytes === void 0 ? {} : { file: bytes }
 			});
 			else await payload.updateGlobal({
 				...write,
 				fallbackLocale: false,
 				slug: target.slug
 			});
-			const saved = await readDraft(scope, {
-				target,
-				locale,
-				privileged: true
-			});
-			const readable = await readDraft(scope, {
-				target,
-				locale
-			}).catch((error) => {
-				if (error instanceof NotFound || error instanceof Forbidden) return;
-				throw error;
-			});
-			const notApplied = readable ? notAppliedPointers(patches, applied.next, readable) : [];
-			const validation = await collectPublishBlockers(scope.req, {
-				doc: saved,
-				entity: target
-			});
-			return jsonResult({
-				...identityOf(target, saved["id"]),
-				status: saved["_status"],
-				updatedAt: saved["updatedAt"],
-				...validation.blockers.length > 0 ? { publishBlockers: validation.blockers } : {},
-				...validation.unavailable ? { publishBlockersUnavailable: true } : {},
-				...notApplied.length > 0 ? { notApplied } : {}
-			});
+			return bytes === void 0 ? { done: await report(applied.next) } : { written: applied.next };
+		});
+		if ("done" in outcome) return outcome.done;
+		if ("handoff" in outcome) return await uploadHandoff(scope, {
+			tool: "patchDocument",
+			args: outcome.handoff
 		});
+		return await report(outcome.written);
 	}
 });
 //#endregion

package/dist/tools/shared.mjs

@@ -1,4 +1,5 @@
 import { canCreate, isLiveWrite } from "../capabilities.mjs";
+import { acceptsFiles } from "../upload/file.mjs";
 import { z } from "zod";
 //#region src/tools/shared.ts
 /**
@@ -17,19 +18,19 @@ const slugsWhere = (scope, predicate, allowed) => {
 	return [...pick(scope.exposure.collections, allowed.collections), ...pick(scope.exposure.globals, allowed.globals)];
 };
 /**
-* Slugs this key may write but never create in, because their documents are
-* files. Collection-only, since nothing creates a global either way.
-*/ const patchOnlySlugs = (scope) => slugsWhere(scope, (entity) => !canCreate(entity), {
-	collections: scope.collections.writable,
-	globals: []
-});
+* Collections this key may write but not create in: upload collections whose
+* files MCP does not accept. Nothing creates a global either way.
+*/ const patchOnlySlugs = (scope) => {
+	const creatable = slugsFor(scope, "create").collections;
+	return scope.collections.writable.filter((slug) => !creatable.includes(slug));
+};
 const widen = (branch) => branch;
 /**
 * The one list the shape helpers and {@link resolveEntity} both read.
 */ const slugsFor = (scope, operation) => {
 	switch (operation) {
 		case "create": return {
-			collections: slugsWhere(scope, canCreate, {
+			collections: slugsWhere(scope, (entity) => canCreate(entity) && (!entity.isUpload || acceptsFiles(scope, entity.slug)), {
 				collections: scope.collections.writable,
 				globals: []
 			}),

package/dist/tools/validate-document.mjs

@@ -1,7 +1,7 @@
 import { defineMcpxTool } from "../define-tool.mjs";
 import { jsonResult } from "../result.mjs";
-import { entityShape, idShape, localeOf, localeShape } from "./shared.mjs";
 import { collectPublishBlockers } from "../write/publish-blockers.mjs";
+import { entityShape, idShape, localeOf, localeShape } from "./shared.mjs";
 import { collectLocaleBlockers, identityOf, readDraft, resolveDocument } from "./document.mjs";
 /**
 * Gated on write rather than read, because publish blockers only mean something

package/dist/types.d.mts

@@ -34,9 +34,9 @@ export interface McpxCollectionOptions {
    */
   read?: boolean;
   /**
-   * Expose `patchDocument`, `validateDocument` and, unless this is an upload
-   * collection, `createDocument`. Without drafts a write changes live
-   * content. Default `true`.
+   * Expose `patchDocument`, `validateDocument` and `createDocument`. An upload
+   * collection is created in only where MCP accepts its files. Without drafts
+   * a write changes live content. Default `true`.
    */
   write?: boolean;
   /**
@@ -66,7 +66,7 @@ export interface McpxExposedEntity {
    */
   hasVersions: boolean;
   /**
-   * An upload document is a file, and no tool here can supply one.
+   * An upload document is a file, which only an upload grant can supply.
    */
   isUpload: boolean;
   /**
@@ -101,6 +101,18 @@ export interface McpxToolScope {
     maxLimit: number;
     maxDepth: number;
   };
+  /**
+   * Whether files can be uploaded at all: the KV is database-backed and no
+   * custom `auth.resolve` is configured.
+   */
+  uploads: boolean;
+  /**
+   * `null` when `diagnostics` is off.
+   */
+  diagnostics: null | {
+    name: string;
+    version: string;
+  };
   exposure: {
     collections: McpxExposedEntity[];
     globals: McpxExposedEntity[];
@@ -224,6 +236,10 @@ export type McpxPluginOptions = {
     name?: string;
     version?: string;
   };
+  /**
+   * Expose the server version plus repository and issue links to clients. Default `true`.
+   */
+  diagnostics?: boolean;
 };
 /**
  * What a key may do with one entity. Globals reuse this shape.

package/dist/upload/file.mjs

@@ -0,0 +1,166 @@
+import { errorResult, jsonResult } from "../result.mjs";
+import { issueGrant, uploadKvSlug } from "./grant.mjs";
+import { collectPublishBlockers } from "../write/publish-blockers.mjs";
+import { APIError } from "payload";
+import { hasDraftValidationEnabled, hasDraftsEnabled, validateMimeType } from "payload/shared";
+import { z } from "zod";
+//#region src/upload/file.ts
+const MAX_BYTES = 26214400;
+const FILENAME = /^[^/\\\p{Cc}]+$/u;
+const MIME_TYPE = /^[\w.+-]+\/[\w.+-]+$/;
+const uploadedFiles = /* @__PURE__ */ new WeakMap();
+const fileSchema = (maxBytes) => z.strictObject({
+	filename: z.string().max(255).regex(FILENAME),
+	mimeType: z.string().max(255).regex(MIME_TYPE),
+	size: z.number().int().min(1).max(maxBytes)
+});
+/**
+* The largest file accepted: Payload's `upload.limits.fileSize` if set, and
+* never more than 25 MB, since the body is buffered.
+*/ const uploadMaxBytes = (config) => Math.min(config.upload.limits?.fileSize ?? MAX_BYTES, MAX_BYTES);
+const allowedMimeTypes = (scope, slug) => {
+	if (!scope.uploads || !scope.collections.writable.includes(slug)) return [];
+	const entity = scope.exposure.collections.find((candidate) => candidate.slug === slug);
+	const config = scope.req.payload.config.collections.find((candidate) => candidate.slug === slug);
+	return entity?.isUpload === true && Array.isArray(config?.upload.mimeTypes) ? config.upload.mimeTypes : [];
+};
+/**
+* Whether this key may send a file to `slug`: a writable upload collection
+* that sets `upload.mimeTypes`.
+*/ const acceptsFiles = (scope, slug) => allowedMimeTypes(scope, slug).length > 0;
+/**
+* The collections this key may send files to.
+*/ const fileSlugs = (scope) => scope.collections.writable.filter((slug) => acceptsFiles(scope, slug));
+/**
+* The `file` argument, present only when the key may send a file somewhere.
+*/ const fileShape = (scope, description) => {
+	const slugs = fileSlugs(scope);
+	return slugs.length === 0 ? {} : { file: fileSchema(uploadMaxBytes(scope.req.payload.config)).optional().describe(description(slugs.join(", "))) };
+};
+/**
+* Throws for a `file` sent to an entity that does not accept one, or declared
+* with a type outside its `upload.mimeTypes`. Payload stores the declared
+* type, so it is held to the same list as the content.
+*/ const assertAcceptsFile = (scope, target, file) => {
+	const mimeTypes = target.kind === "global" ? [] : allowedMimeTypes(scope, target.slug);
+	if (mimeTypes.length === 0) throw new APIError(`"${target.slug}" does not accept files through MCP: it is not an upload collection, or it sets no upload.mimeTypes.`, 400);
+	if (!validateMimeType(file.mimeType, mimeTypes)) throw new APIError(`"${target.slug}" accepts only ${mimeTypes.join(", ")}, not "${file.mimeType}".`, 400);
+};
+/**
+* Attaches the claimed bytes to the request the tool runs on.
+*/ const setUploadedFile = (req, file) => {
+	uploadedFiles.set(req, file);
+};
+/**
+* The bytes for this call, or `undefined` before they were sent.
+*/ const uploadedFile = (req) => uploadedFiles.get(req);
+const sharesPublishedFile = async (req, entity, id) => {
+	if (!hasDraftsEnabled(entity.config)) return false;
+	const read = {
+		collection: entity.slug,
+		id,
+		depth: 0,
+		overrideAccess: true,
+		disableErrors: true,
+		select: {
+			filename: true,
+			_status: true
+		},
+		req
+	};
+	const [latest, published] = await Promise.all([req.payload.findByID({
+		...read,
+		draft: true
+	}), req.payload.findByID({
+		...read,
+		draft: false
+	})]);
+	return latest?.["_status"] === "draft" && published?.["_status"] === "published" && latest["filename"] === published["filename"];
+};
+/**
+* Refuses a file write Payload would turn into data loss: a replace that
+* deletes the published file, or a write that fails validation after the old
+* file is gone. Payload validates only after it moves files, so the merged
+* data is validated here first wherever Payload will validate it.
+*/ const fileWriteRefusal = async (scope, target) => {
+	const { entity, id } = target;
+	if (id !== void 0 && await sharesPublishedFile(scope.req, entity, id)) return errorResult("The file was not replaced: the latest draft still uses the published file, which the replace would delete. Publish or discard the draft first.");
+	if (hasDraftsEnabled(entity.config) && !hasDraftValidationEnabled(entity.config)) return;
+	const { blockers } = await collectPublishBlockers(scope.req, {
+		doc: {
+			...target.data,
+			...id === void 0 ? {} : { id }
+		},
+		entity
+	});
+	return blockers.length === 0 ? void 0 : errorResult("Nothing was written: the document fails validation.", { validationErrors: blockers });
+};
+const handoffUrl = (req, path) => {
+	const request = new URL(req.url ?? "");
+	const url = new URL(req.payload.config.serverURL || request.origin);
+	url.pathname = `${request.pathname.replace(/\/+$/, "")}/${path}`;
+	return url.toString();
+};
+const grantContext = (req) => {
+	const slug = uploadKvSlug(req.payload.config);
+	const apiKeyId = req.context.mcpx?.apiKeyId;
+	if (slug === void 0 || apiKeyId === void 0) throw new Error("A handoff was offered without a database KV or key.");
+	return {
+		slug,
+		apiKeyId
+	};
+};
+/**
+* Stores the call as a grant and returns where to PUT its file. Nothing else
+* is written: the PUT runs the same call again with the bytes attached.
+*/ const uploadHandoff = async (scope, call) => {
+	const { req } = scope;
+	const { payload } = req;
+	const { slug, apiKeyId } = grantContext(req);
+	const url = handoffUrl(req, "upload");
+	const { grantId, exp } = await issueGrant(payload, slug, {
+		kind: "upload",
+		apiKeyId,
+		tool: call.tool,
+		args: call.args,
+		locale: req.locale ?? null,
+		fallbackLocale: req.fallbackLocale ?? null
+	});
+	return jsonResult({ upload: {
+		url,
+		method: "PUT",
+		headers: {
+			"content-type": call.args.file.mimeType,
+			"x-mcpx-grant": grantId
+		},
+		expiresAt: new Date(exp).toISOString(),
+		maxBytes: uploadMaxBytes(payload.config)
+	} });
+};
+/**
+* The upload collections whose files this key may download. A collection
+* with its own top-level `download` field is left out, since the handoff
+* would overwrite it in the result.
+*/ const downloadSlugs = (scope) => scope.uploads ? scope.collections.readable.filter((slug) => scope.exposure.collections.find((candidate) => candidate.slug === slug)?.isUpload === true && !scope.req.payload.collections[slug]?.config.flattenedFields.some((field) => field.name === "download")) : [];
+/**
+* Stores a grant for the file of a document just read and returns where to
+* GET it.
+*/ const downloadHandoff = async (scope, target) => {
+	const { req } = scope;
+	const { slug, apiKeyId } = grantContext(req);
+	const url = handoffUrl(req, "file");
+	const { grantId, exp } = await issueGrant(req.payload, slug, {
+		kind: "download",
+		apiKeyId,
+		...target,
+		fallbackLocale: req.fallbackLocale ?? null
+	});
+	return {
+		url,
+		method: "GET",
+		headers: { "x-mcpx-grant": grantId },
+		expiresAt: new Date(exp).toISOString()
+	};
+};
+//#endregion
+export { acceptsFiles, assertAcceptsFile, downloadHandoff, downloadSlugs, fileShape, fileSlugs, fileWriteRefusal, setUploadedFile, uploadHandoff, uploadMaxBytes, uploadedFile };

package/dist/upload/grant.mjs

@@ -0,0 +1,96 @@
+import { isPlainObject } from "../guards.mjs";
+import { hashApiKey } from "../api-keys/key.mjs";
+import { APIError, ValidationError } from "payload";
+import crypto from "node:crypto";
+//#region src/upload/grant.ts
+const GRANT_TTL_MS = 3e5;
+const GRANTS_PER_KEY = 10;
+const GRANT_ID = /^[\w-]{43}$/;
+const NO_REQ = {};
+const grantPrefix = (apiKeyId) => `mcpx-grant:${String(apiKeyId)}:`;
+const usedPrefix = (apiKeyId) => `mcpx-grant-used:${String(apiKeyId)}:`;
+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 uploadKvSlug = (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;
+};
+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;
+};
+/**
+* Stores a grant and returns its id, the only copy of which goes to the
+* client. The row key holds the HMAC of the id. Expired rows of the same key
+* are purged first, and a key may hold at most {@link GRANTS_PER_KEY} grants.
+*/ const issueGrant = async (payload, slug, grant) => {
+	const now = Date.now();
+	const prefixes = [grantPrefix(grant.apiKeyId), usedPrefix(grant.apiKeyId)];
+	const rows = (await findRows(payload, slug, prefixes)).filter((row) => prefixes.some((prefix) => row.key.startsWith(prefix)));
+	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(prefixes[0]) && expOf(row.data) > now).length >= GRANTS_PER_KEY) throw new APIError(`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.`, 429);
+	const grantId = crypto.randomBytes(32).toString("base64url");
+	const exp = now + GRANT_TTL_MS;
+	await payload.db.create({
+		collection: slug,
+		data: {
+			key: `${grantPrefix(grant.apiKeyId)}${hashApiKey(payload.secret, grantId)}`,
+			data: {
+				...grant,
+				exp
+			}
+		},
+		req: NO_REQ
+	});
+	return {
+		grantId,
+		exp
+	};
+};
+/**
+* Loads the grant for `grantId` and marks it used, or returns `undefined` for
+* a malformed, unknown, expired or used one. The marker is a unique-key
+* insert, so of two concurrent claims exactly one succeeds. A malformed id
+* is refused before any database read.
+*/ const claimGrant = async (payload, slug, grantId) => {
+	if (!GRANT_ID.test(grantId)) return;
+	const hash = hashApiKey(payload.secret, grantId);
+	const row = (await findRows(payload, slug, [hash])).find((candidate) => candidate.key.startsWith("mcpx-grant:") && candidate.key.endsWith(`:${hash}`));
+	const grant = row?.data;
+	if (!row || !isPlainObject(grant) || row.key !== `${grantPrefix(grant.apiKeyId)}${hash}` || expOf(grant) <= Date.now()) return;
+	try {
+		await payload.db.create({
+			collection: slug,
+			data: {
+				key: `${usedPrefix(grant.apiKeyId)}${hash}`,
+				data: { exp: grant.exp }
+			},
+			req: NO_REQ
+		});
+	} catch (error) {
+		if (error instanceof ValidationError) return;
+		throw error;
+	}
+	await payload.db.deleteOne({
+		collection: slug,
+		where: { key: { equals: row.key } },
+		req: NO_REQ
+	});
+	return grant;
+};
+//#endregion
+export { claimGrant, issueGrant, uploadKvSlug };

package/dist/version.mjs

@@ -2,5 +2,7 @@
 /**
 * Package version injected at build time; sources under Vitest report "dev".
 */ const MCPX_VERSION = "1.0.0";
+const MCPX_REPOSITORY_URL = "https://github.com/abinnovision/payloadcms-commons/tree/main/packages/mcpx";
+const MCPX_ISSUES_URL = "https://github.com/abinnovision/payloadcms-commons/issues";
 //#endregion
-export { MCPX_VERSION };
+export { MCPX_ISSUES_URL, MCPX_REPOSITORY_URL, MCPX_VERSION };

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "@abinnovision/payloadcms-mcpx",
-  "version": "2.0.0-beta.10",
+  "version": "2.0.0-beta.12",
   "description": "Payload CMS plugin exposing a fixed, schema-aware MCP tool surface with draft-only writes and per-API-key capabilities.",
   "keywords": [
     "payload",
@@ -57,7 +57,7 @@
   },
   "prettier": "@abinnovision/prettier-config",
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.30.0",
+    "@modelcontextprotocol/sdk": "^1.30.1",
     "rfc6902": "^5.3.0",
     "zod": "^4.6.5"
   },
@@ -66,15 +66,15 @@
     "@abinnovision/prettier-config": "^2.2.0",
     "@arethetypeswrong/core": "^0.18.5",
     "@internal/test-utils": "0.0.0",
-    "@payloadcms/db-sqlite": "3.89.0",
-    "@payloadcms/richtext-lexical": "3.89.0",
-    "@payloadcms/ui": "3.89.0",
+    "@payloadcms/db-sqlite": "3.90.2",
+    "@payloadcms/richtext-lexical": "3.90.2",
+    "@payloadcms/ui": "3.90.2",
     "@swc/core": "^1.16.2",
     "@types/node": "^26.5.1",
     "@types/react": "^19.3.0",
     "@vitest/coverage-v8": "^5.0.0",
     "eslint": "^10.10.0",
-    "payload": "3.89.0",
+    "payload": "3.90.2",
     "prettier": "^3.9.5",
     "publint": "^0.3.24",
     "react": "^19.3.0",