@abinnovision/payloadcms-mcpx 2.0.0 → 2.1.0-beta.2

package/README.md

@@ -30,7 +30,8 @@ leave them out. The package is ESM only, like Payload.
 
 ## Setup
 
-List the collections and globals the plugin may reach. Anything not listed is not exposed:
+List the collections and globals the plugin may reach. Anything not listed is not exposed, apart
+from Payload's folders, which are readable where an exposed collection uses them (see `folders`):
 
 ```ts
 // payload.config.ts
@@ -94,6 +95,7 @@ Claude Desktop and the MCP Inspector are covered in
 | `collections.<slug>.publish` | `true` with drafts                        | Expose `publishDocument`. Needs `versions.drafts` and `write`.                                                                                    |
 | `collections.<slug>.delete`  | `false`                                   | Expose `deleteDocument`. Needs `read`. Each delete is approved in the admin. `"unattended"` also offers trashing without approval; needs `trash`. |
 | `globals`                    | `{}`                                      | Globals to expose, with `read`, `write` and `publish`.                                                                                            |
+| `folders`                    | read-only where used                      | Payload's folders, where an exposed collection uses them. `{ write: true }` adds create and rename, never delete. `false` hides them.             |
 | `userCollection`             | `config.admin.user`, then `users`         | Auth collection whose users the keys act as.                                                                                                      |
 | `apiKeys.slug`               | `mcpx-api-keys`                           | Slug of the key collection.                                                                                                                       |
 | `apiKeys.setupGuide`         | `true`                                    | Add the "Connect a client" button to saved keys.                                                                                                  |
@@ -171,6 +173,8 @@ To restrict that, use `apiKeys.overrideCollection` as shown in
   the REST or GraphQL API.
 - A key acts as its user, and Payload access control applies to what its tools read and write.
 - Relations are populated only into collections the key can read.
+- Readable folders expose every folder name and the `folderType` options, which are the slugs of
+  the collections that use folders. They do not expose the documents in a folder.
 - The read tools leave out fields with `admin.hidden`. `findDocuments` refuses a `where` or `sort`
   that names one, or that goes through a relation into a collection the key cannot read.
 - After a write, the tools re-read the document with full access to report publish blockers.

package/dist/endpoint/confirmations.mjs

@@ -1,9 +1,9 @@
 import { isPlainObject } from "../guards.mjs";
-import { grantContext, grantKvSlug, rowHandle } from "../grants/grant.mjs";
+import { leaseContext, leaseHandle, leaseKvSlug } from "../leases/lease.mjs";
 import { respond } from "./http.mjs";
 import { CONFIRMATIONS_PATH, DECISIONS } from "../api-keys/confirmation-view.mjs";
 import { relationId } from "../auth/resolve.mjs";
-import { decideConfirmations, issueConfirmation, listConfirmations } from "../grants/confirmation.mjs";
+import { decideConfirmations, issueConfirmation, listConfirmations } from "../leases/confirmation.mjs";
 import { publicOrigin } from "../request.mjs";
 import { jsonResult } from "../result.mjs";
 import { BUILTIN_TOOLS } from "../tools/builtin.mjs";
@@ -25,7 +25,7 @@ const keyViewUrl = (req, options, apiKeyId) => {
 	confirmed: false,
 	request: async (args) => {
 		const { req } = scope;
-		const { slug, apiKeyId } = grantContext(req);
+		const { slug, apiKeyId } = leaseContext(req);
 		const view = keyViewUrl(req, options, apiKeyId);
 		const { id, exp } = await issueConfirmation(req.payload, slug, {
 			apiKeyId,
@@ -42,7 +42,7 @@ const keyViewUrl = (req, options, apiKeyId) => {
 	}
 });
 const authorize = async (req, options, keyId) => {
-	const slug = grantKvSlug(req.payload.config);
+	const slug = leaseKvSlug(req.payload.config);
 	if (slug === void 0) return respond(404, { error: "Confirmations are not available." });
 	if (req.user?.collection !== options.userCollection) return respond(401, { error: "Sign in as the user of this key." });
 	const key = typeof keyId === "string" || typeof keyId === "number" ? await req.payload.findByID({
@@ -88,7 +88,7 @@ const viewOf = async (req, entry, highlight) => {
 	if (allowed instanceof Response) return allowed;
 	const { payload } = req;
 	const highlighted = req.searchParams.get("confirmation");
-	const highlight = highlighted === null ? void 0 : rowHandle(payload, highlighted);
+	const highlight = highlighted === null ? void 0 : leaseHandle(payload, highlighted);
 	const entries = (await listConfirmations(payload, allowed.slug, allowed.apiKeyId)).filter((entry) => entry.confirmation.state === "pending");
 	const confirmations = [];
 	for (const entry of entries) confirmations.push(await viewOf(req, entry, highlight));

package/dist/endpoint/handler.mjs

@@ -1,5 +1,5 @@
 import { resolveCapabilities, scopeSlugs } from "../capabilities.mjs";
-import { grantsAvailable, readCapped } from "./http.mjs";
+import { leasesAvailable, readCapped } from "./http.mjs";
 import { isValidAuthResult, resolveApiKeyAuth } from "../auth/resolve.mjs";
 import { jsonRpcError } from "./errors.mjs";
 import { createMcpServer } from "./server.mjs";
@@ -22,7 +22,7 @@ const BATCH_MESSAGES_LIMIT = 10;
 			defaultLocale: localization.defaultLocale
 		} : null,
 		limits: options.limits,
-		uploads: grantsAvailable(req, options) !== void 0,
+		uploads: leasesAvailable(req, options) !== void 0,
 		diagnostics: options.diagnostics ? options.serverInfo : null,
 		exposure: {
 			collections: options.collections,

package/dist/endpoint/http.mjs

@@ -1,4 +1,4 @@
-import { grantKvSlug } from "../grants/grant.mjs";
+import { leaseKvSlug } from "../leases/lease.mjs";
 //#region src/endpoint/http.ts
 const respond = (status, body) => Response.json(body, { status });
 /**
@@ -19,9 +19,9 @@ const respond = (status, body) => Response.json(body, { status });
 	return Buffer.concat(chunks);
 };
 /**
-* The grant KV slug where uploads, downloads and confirmations are possible:
+* The lease KV slug where uploads, downloads and confirmations are possible:
 * the KV is database-backed and no custom `auth.resolve` is set, since the
-* grant endpoints cannot replay what such a resolver authenticated by.
-*/ const grantsAvailable = (req, options) => options.auth?.resolve === void 0 ? grantKvSlug(req.payload.config) : void 0;
+* lease endpoints cannot replay what such a resolver authenticated by.
+*/ const leasesAvailable = (req, options) => options.auth?.resolve === void 0 ? leaseKvSlug(req.payload.config) : void 0;
 //#endregion
-export { grantsAvailable, readCapped, respond };
+export { leasesAvailable, readCapped, respond };

package/dist/endpoint/upload.mjs

@@ -1,8 +1,8 @@
 import { isToolEnabled, toolInputSchema } from "../define-tool.mjs";
-import { claimGrant } from "../grants/grant.mjs";
-import { grantsAvailable, readCapped, respond } from "./http.mjs";
+import { leasesAvailable, readCapped, respond } from "./http.mjs";
 import { resolveApiKeyById } from "../auth/resolve.mjs";
 import { parseResult } from "../result.mjs";
+import { claimGrant } from "../leases/grant.mjs";
 import { downloadSlugs, setUploadedFile, uploadMaxBytes } from "../upload/file.mjs";
 import { BUILTIN_TOOLS } from "../tools/builtin.mjs";
 import { runTool } from "./server.mjs";
@@ -23,7 +23,7 @@ const NO_SESSION = {
 	sendRequest: () => Promise.reject(/* @__PURE__ */ new Error("No MCP session."))
 };
 const claimAs = async (req, options, kind) => {
-	const slug = grantsAvailable(req, options);
+	const slug = leasesAvailable(req, options);
 	const grantId = req.headers.get("x-mcpx-grant");
 	if (slug === void 0 || grantId === null) return;
 	const grant = await claimGrant(req.payload, slug, grantId);

package/dist/{grants → leases}/confirmation.mjs

@@ -1,8 +1,7 @@
-import { NO_REQ, ROW_ID, claimRow, expOf, issueRow, rowHandle, rowPrefixes, rowsWith } from "./grant.mjs";
-//#region src/grants/confirmation.ts
+import { LEASE_ID, NO_REQ, claimLease, issueLease, leaseHandle, leasePrefixes, leasesWith, unexpired } from "./lease.mjs";
+//#region src/leases/confirmation.ts
 const CONFIRMATION_TTL_MS = 9e5;
 const HANDLE = /^[\da-f]{64}$/;
-const asConfirmation = (row, now) => row && expOf(row.data) > now ? row.data : void 0;
 /**
 * Stores a pending call and returns its id. A key may hold at most
 * {@link CONFIRMATIONS_PER_KEY} calls.
@@ -11,8 +10,8 @@ const asConfirmation = (row, now) => row && expOf(row.data) > now ? row.data : v
 		...call,
 		state: "pending"
 	};
-	return await issueRow(payload, slug, {
-		...rowPrefixes("confirmation", call.apiKeyId),
+	return await issueLease(payload, slug, {
+		...leasePrefixes("confirmation", call.apiKeyId),
 		cap: 50,
 		capMessage: `This key already has ${String(50)} calls waiting for approval. Run or abandon them first; each expires 15 minutes after it was requested.`,
 		ttlMs: CONFIRMATION_TTL_MS,
@@ -23,22 +22,22 @@ const asConfirmation = (row, now) => row && expOf(row.data) > now ? row.data : v
 * The unexpired call of `apiKeyId` with `id`, without claiming it. A call of
 * another key is `undefined`, as is a malformed id, before any database read.
 */ const readConfirmation = async (payload, slug, apiKeyId, id) => {
-	if (!ROW_ID.test(id)) return;
-	const key = `${rowPrefixes("confirmation", apiKeyId).prefix}${rowHandle(payload, id)}`;
-	const rows = await rowsWith(payload, slug, [key]);
-	return asConfirmation(rows.find((row) => row.key === key), Date.now());
+	if (!LEASE_ID.test(id)) return;
+	const key = `${leasePrefixes("confirmation", apiKeyId).prefix}${leaseHandle(payload, id)}`;
+	const rows = await leasesWith(payload, slug, [key]);
+	return unexpired(rows.find((row) => row.key === key), Date.now());
 };
 /**
 * Marks the call used and removes it. Of two concurrent claims exactly one
 * returns `true`.
-*/ const claimConfirmation = async (payload, slug, apiKeyId, id, exp) => await claimRow(payload, slug, rowPrefixes("confirmation", apiKeyId), rowHandle(payload, id), exp);
+*/ const claimConfirmation = async (payload, slug, apiKeyId, id, exp) => await claimLease(payload, slug, leasePrefixes("confirmation", apiKeyId), leaseHandle(payload, id), exp);
 /**
 * Every unexpired call of `apiKeyId` with its handle, oldest first.
 */ const listConfirmations = async (payload, slug, apiKeyId) => {
-	const { prefix } = rowPrefixes("confirmation", apiKeyId);
+	const { prefix } = leasePrefixes("confirmation", apiKeyId);
 	const now = Date.now();
-	return (await rowsWith(payload, slug, [prefix])).flatMap((row) => {
-		const confirmation = asConfirmation(row, now);
+	return (await leasesWith(payload, slug, [prefix])).flatMap((row) => {
+		const confirmation = unexpired(row, now);
 		return confirmation ? [{
 			handle: row.key.slice(prefix.length),
 			confirmation
@@ -50,13 +49,13 @@ const asConfirmation = (row, now) => row && expOf(row.data) > now ? row.data : v
 * returns the handles it changed. A call that was decided, run or expired is
 * left alone and not returned.
 */ const decideConfirmations = async (payload, slug, apiKeyId, handles, state) => {
-	const { prefix } = rowPrefixes("confirmation", apiKeyId);
+	const { prefix } = leasePrefixes("confirmation", apiKeyId);
 	const keys = new Set(handles.filter((handle) => HANDLE.test(handle)).map((handle) => `${prefix}${handle}`));
 	if (keys.size === 0) return [];
 	const now = Date.now();
 	const decided = [];
-	for (const row of await rowsWith(payload, slug, [prefix])) {
-		const confirmation = asConfirmation(row, now);
+	for (const row of await leasesWith(payload, slug, [prefix])) {
+		const confirmation = unexpired(row, now);
 		if (!keys.has(row.key) || confirmation?.state !== "pending") continue;
 		const updated = await payload.db.updateMany({
 			collection: slug,

package/dist/leases/grant.mjs

@@ -0,0 +1,29 @@
+import { LEASE_ID, claimLease, issueLease, leaseHandle, leasePrefixes, leasesMatching, unexpired } from "./lease.mjs";
+//#region src/leases/grant.ts
+const GRANT_TTL_MS = 3e5;
+const GRANTS_PER_KEY = 10;
+/**
+* Stores a grant and returns its id. A key may hold at most
+* {@link GRANTS_PER_KEY} grants.
+*/ const issueGrant = async (payload, slug, grant) => await issueLease(payload, slug, {
+	...leasePrefixes("grant", grant.apiKeyId),
+	cap: GRANTS_PER_KEY,
+	capMessage: `This key already has ${String(GRANTS_PER_KEY)} uploads or downloads waiting. Use or abandon them first; each expires 5 minutes after it was issued.`,
+	ttlMs: GRANT_TTL_MS,
+	data: grant
+});
+/**
+* Loads the grant for `grantId` and marks it used, or returns `undefined` for
+* a malformed, unknown, expired or used one. A malformed id is refused before
+* any database read.
+*/ const claimGrant = async (payload, slug, grantId) => {
+	if (!LEASE_ID.test(grantId)) return;
+	const handle = leaseHandle(payload, grantId);
+	const row = (await leasesMatching(payload, slug, [handle])).find((candidate) => candidate.key.startsWith("mcpx-grant:") && candidate.key.endsWith(`:${handle}`));
+	const grant = unexpired(row, Date.now());
+	if (!row || !grant) return;
+	const prefixes = leasePrefixes("grant", grant.apiKeyId);
+	return row.key === `${prefixes.prefix}${handle}` && await claimLease(payload, slug, prefixes, handle, grant.exp) ? grant : void 0;
+};
+//#endregion
+export { claimGrant, issueGrant };

package/dist/{grants/grant.mjs → leases/lease.mjs}

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

package/dist/options.mjs

@@ -5,6 +5,7 @@ import { hasDraftsEnabled, hasLocalizeStatusEnabled } from "payload/shared";
 //#region src/options.ts
 const DEFAULT_API_KEYS_SLUG = "mcpx-api-keys";
 const DEFAULT_ENDPOINT_PATH = "/mcpx";
+const DEFAULT_FOLDERS_SLUG = "payload-folders";
 const DEFAULT_MAX_LIMIT = 25;
 const DEFAULT_MAX_DEPTH = 1;
 const TOOL_NAME_PATTERN = /^[a-zA-Z][a-zA-Z0-9]*$/;
@@ -83,12 +84,13 @@ const normalizeCapabilities = (kind, config, raw) => {
 	};
 };
 const bySlug = (configs) => new Map(configs.map((config) => [config.slug, config]));
-const normalizeEntities = (kind, configs, entries, apiKeysSlug) => {
+const foldersSlugOf = ({ folders }) => (folders === false ? void 0 : folders?.slug) ?? DEFAULT_FOLDERS_SLUG;
+const normalizeEntities = (kind, configs, entries, apiKeysSlug, foldersSlug) => {
 	const fieldNames = /* @__PURE__ */ new Set();
 	return Object.entries(entries).flatMap(([slug, raw]) => {
 		if (raw === void 0) return [];
 		const config = configs.get(slug);
-		if (!config) return fail(`Exposed ${kind.toLowerCase()} "${slug}" does not exist.`);
+		if (!config) return fail(slug === foldersSlug ? `Collection "${slug}" is Payload's folder collection. Use the folders option instead.` : slug.startsWith("payload-") ? `${kind} "${slug}" is internal to Payload and cannot be exposed.` : `Exposed ${kind.toLowerCase()} "${slug}" does not exist.`);
 		assertExposable(kind, config, apiKeysSlug);
 		const normalized = {
 			slug,
@@ -105,6 +107,40 @@ const normalizeEntities = (kind, configs, entries, apiKeysSlug) => {
 		return [normalized];
 	});
 };
+const normalizeFolders = (config, collections, raw, slug) => {
+	const usesFolders = (config.collections ?? []).some((collection) => Boolean(collection.folders) && collections.some((entity) => entity.slug === collection.slug));
+	if (raw === false) return [];
+	if (config.folders === false || !usesFolders) {
+		if (raw !== void 0) fail("folders is set, but no exposed collection uses folders. Remove the option.");
+		return [];
+	}
+	if (raw !== void 0 && !isPlainObject(raw)) fail(`folders has ${JSON.stringify(raw)}. Use false or { write }.`);
+	const settings = isPlainObject(raw) ? raw : {};
+	const unknownKey = Object.keys(settings).find((key) => key !== "write");
+	if (unknownKey !== void 0) fail(`folders has the unknown option "${unknownKey}". The only option is write.`);
+	const fieldName = toCamelCase(slug);
+	if (collections.some((entity) => entity.fieldName === fieldName)) fail(`folders maps to capability field "${fieldName}", which an exposed collection already uses.`);
+	const write = settings["write"] ?? false;
+	if (typeof write !== "boolean") fail(`folders.write has ${JSON.stringify(write)}. Use true or false.`);
+	return [{
+		slug,
+		...normalizeCapabilities("Collection", {
+			slug,
+			fields: []
+		}, { write }),
+		isUpload: false,
+		fieldName
+	}];
+};
+/**
+* Checks the sanitized folder collection against what {@link normalizeFolders}
+* assumed. `folders.collectionOverrides` can change it after this plugin ran.
+*/ const assertFolderCollection = (config, options) => {
+	const { folders } = config;
+	if (!folders || !options.collections.some((entity) => entity.slug === folders.slug)) return;
+	const collection = config.collections.find((candidate) => candidate.slug === folders.slug);
+	if (collection?.auth || collection?.upload || collection?.versions) fail(`Folder collection "${folders.slug}" has auth, upload or versions from folders.collectionOverrides, which mcpx does not support. Set folders: false.`);
+};
 const assertUserCollection = (collections, slug) => {
 	const collection = collections.get(slug);
 	if (!collection) fail(`User collection "${slug}" does not exist.`);
@@ -136,11 +172,13 @@ const normalizeLimits = (limits) => {
 	const apiKeysSlug = options.apiKeys?.slug ?? DEFAULT_API_KEYS_SLUG;
 	const userCollection = options.userCollection ?? config.admin?.user ?? "users";
 	const collectionConfigs = bySlug(config.collections ?? []);
+	const foldersSlug = foldersSlugOf(config);
 	if (collectionConfigs.has(apiKeysSlug)) fail(`API key collection slug "${apiKeysSlug}" is already taken.`);
 	assertUserCollection(collectionConfigs, userCollection);
 	const tools = options.tools ?? [];
 	assertTools(tools, reservedToolNames);
-	const collections = normalizeEntities("Collection", collectionConfigs, options.collections, apiKeysSlug);
+	const exposed = normalizeEntities("Collection", collectionConfigs, options.collections, apiKeysSlug, foldersSlug);
+	const collections = [...exposed, ...normalizeFolders(config, exposed, options.folders, foldersSlug)];
 	const confirmations = collections.some((entity) => entity.delete);
 	if (confirmations && options.auth?.resolve) fail("delete needs approval on the API key document, which a custom auth.resolve does not support. Remove delete: true or auth.resolve.");
 	return {
@@ -162,4 +200,4 @@ const normalizeLimits = (limits) => {
 	};
 };
 //#endregion
-export { normalizeOptions, toCamelCase };
+export { assertFolderCollection, normalizeOptions, toCamelCase };

package/dist/plugin.d.mts

@@ -3,7 +3,8 @@ import { McpxPluginOptions } from "./types.mjs";
 /**
  * Mounts the MCP, upload and download endpoints, and the confirmation
  * endpoints where a collection exposes `delete`. Adds the API key collection
- * and installs the draft guard on every collection and global.
+ * and installs the draft guard on every collection and global. Checks the
+ * folder collection once Payload has built it.
  */
 export declare const mcpxPlugin: (options: McpxPluginOptions) => import("payload").Plugin;
 //#endregion

package/dist/plugin.mjs

@@ -3,14 +3,15 @@ import { BUILTIN_TOOLS } from "./tools/builtin.mjs";
 import { confirmationEndpoints } from "./endpoint/confirmations.mjs";
 import { createMcpxHandler, methodNotAllowed } from "./endpoint/handler.mjs";
 import { createDownloadHandler, createUploadHandler } from "./endpoint/upload.mjs";
-import { normalizeOptions } from "./options.mjs";
+import { assertFolderCollection, normalizeOptions } from "./options.mjs";
 import { installDraftGuards, installGlobalDraftGuards } from "./write/draft-guard.mjs";
 import { definePlugin } from "payload";
 //#region src/plugin.ts
 /**
 * Mounts the MCP, upload and download endpoints, and the confirmation
 * endpoints where a collection exposes `delete`. Adds the API key collection
-* and installs the draft guard on every collection and global.
+* and installs the draft guard on every collection and global. Checks the
+* folder collection once Payload has built it.
 */ const mcpxPlugin = definePlugin({
 	slug: "@abinnovision/payloadcms-mcpx",
 	order: 100,
@@ -22,6 +23,10 @@ import { definePlugin } from "payload";
 			...config,
 			collections: installDraftGuards([...config.collections ?? [], apiKeysCollection]),
 			globals: installGlobalDraftGuards(config.globals ?? []),
+			onInit: async (payload) => {
+				assertFolderCollection(payload.config, normalized);
+				await config.onInit?.(payload);
+			},
 			endpoints: [
 				...config.endpoints ?? [],
 				{

package/dist/tools/run-confirmed.mjs

@@ -1,6 +1,6 @@
 import { defineMcpxTool, isToolEnabled, toolInputSchema } from "../define-tool.mjs";
-import { grantContext } from "../grants/grant.mjs";
-import { claimConfirmation, readConfirmation } from "../grants/confirmation.mjs";
+import { leaseContext } from "../leases/lease.mjs";
+import { claimConfirmation, readConfirmation } from "../leases/confirmation.mjs";
 import { jsonResult, parseResult } from "../result.mjs";
 import { withRequestLocale } from "./document.mjs";
 import { z } from "zod";
@@ -86,7 +86,7 @@ const claimApproved = async (req, slug, apiKeyId, id) => {
 	inputSchema: { ids: z.array(z.string().max(64)).min(1).max(50).describe("\"id\" of each \"confirmation\".") },
 	handler: async ({ args, scope, extra }) => {
 		const { req } = scope;
-		const { slug, apiKeyId } = grantContext(req);
+		const { slug, apiKeyId } = leaseContext(req);
 		const outcomes = [];
 		for (const id of args.ids) {
 			const confirmation = await claimApproved(req, slug, apiKeyId, id);

package/dist/types.d.mts

@@ -274,6 +274,15 @@ export type McpxPluginOptions = {
    * Allow-list of globals. `true` is shorthand for `{}`.
    */
   globals?: Partial<Record<GlobalSlug, McpxGlobalOptions | true>>;
+  /**
+   * Payload's folder collection, exposed read-only by default where an exposed
+   * collection has `folders: true`. `{ write: true }` also lets keys create and
+   * rename folders; folders are never deleted. `false` hides them. An object
+   * is refused where no exposed collection uses folders.
+   */
+  folders?: false | {
+    write?: boolean;
+  };
   /**
    * Collection the keys act as. Default `config.admin.user`, then `users`.
    */

package/dist/upload/file.mjs

@@ -1,6 +1,7 @@
-import { grantContext, issueGrant } from "../grants/grant.mjs";
+import { leaseContext } from "../leases/lease.mjs";
 import { publicOrigin } from "../request.mjs";
 import { errorResult, jsonResult } from "../result.mjs";
+import { issueGrant } from "../leases/grant.mjs";
 import { SchemaError } from "../schema/errors.mjs";
 import { resolveDataPointer } from "../schema/pointer.mjs";
 import "../schema/index.mjs";
@@ -126,7 +127,7 @@ const handoffUrl = (req, path) => {
 */ const uploadHandoff = async (scope, call) => {
 	const { req } = scope;
 	const { payload } = req;
-	const { slug, apiKeyId } = grantContext(req);
+	const { slug, apiKeyId } = leaseContext(req);
 	const url = handoffUrl(req, "upload");
 	const { id, exp } = await issueGrant(payload, slug, {
 		kind: "upload",
@@ -158,7 +159,7 @@ const handoffUrl = (req, path) => {
 * GET it.
 */ const downloadHandoff = async (scope, target) => {
 	const { req } = scope;
-	const { slug, apiKeyId } = grantContext(req);
+	const { slug, apiKeyId } = leaseContext(req);
 	const url = handoffUrl(req, "file");
 	const { id, exp } = await issueGrant(req.payload, slug, {
 		kind: "download",

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "@abinnovision/payloadcms-mcpx",
-  "version": "2.0.0",
+  "version": "2.1.0-beta.2",
   "description": "Payload CMS plugin exposing a fixed, schema-aware MCP tool surface with draft-only writes and per-API-key capabilities.",
   "keywords": [
     "payload",