@abinnovision/payloadcms-mcpx 2.1.0-beta.1 → 2.1.0

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## [2.1.0](https://github.com/abinnovision/payloadcms-commons/compare/payloadcms-mcpx-v2.0.0...payloadcms-mcpx-v2.1.0) (2026-10-09)
+
+
+### Features
+
+* **mcpx:** expose payload folders read-only by default ([#129](https://github.com/abinnovision/payloadcms-commons/issues/129)) ([1b2dd55](https://github.com/abinnovision/payloadcms-commons/commit/1b2dd55305fb84991f9a585006a3a33687bb22a7))
+* **mcpx:** rename grants to leases and share the expiry check ([#127](https://github.com/abinnovision/payloadcms-commons/issues/127)) ([7170bd5](https://github.com/abinnovision/payloadcms-commons/commit/7170bd5d592226c6bb7f356fb17ec1b19a59e608))
+
 ## [2.0.0](https://github.com/abinnovision/payloadcms-commons/compare/payloadcms-mcpx-v1.0.0...payloadcms-mcpx-v2.0.0) (2026-10-08)
 
 

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/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 {
@@ -156,10 +194,10 @@ const normalizeLimits = (limits) => {
 		auth: options.auth,
 		serverInfo: {
 			name: options.serverInfo?.name ?? "payloadcms-mcpx",
-			version: options.serverInfo?.version ?? "2.0.0"
+			version: options.serverInfo?.version ?? "2.1.0"
 		},
 		diagnostics: options.diagnostics ?? true
 	};
 };
 //#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/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/version.mjs

@@ -1,7 +1,7 @@
 //#region src/version.ts
 /**
 * Package version injected at build time; sources under Vitest report "dev".
-*/ const MCPX_VERSION = "2.0.0";
+*/ const MCPX_VERSION = "2.1.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

package/package.json

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