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

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
 /**