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

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

@@ -201,7 +201,7 @@ Upgrading from 1.x: [Upgrading to 2.0](./docs/integration.md#upgrading-to-20).
 - [`docs/concepts.md`](./docs/concepts.md): tool arguments, schema paths and pointers, patching,
   rich text, globals, uploads, drafts and publishing, versions and diffs.
 - [`docs/integration.md`](./docs/integration.md): the endpoint, startup validation, API keys in the
-  admin panel, and custom key resolution.
+  admin panel, custom key resolution, and the in-process client.
 - [`docs/custom-tools.md`](./docs/custom-tools.md): defining your own tools.
 - [`docs/security.md`](./docs/security.md): authentication, access, limits and known limitations.
 - [`docs/limitations.md`](./docs/limitations.md): what the plugin does not do.

package/dist/endpoint/handler.mjs

@@ -31,22 +31,24 @@ const BATCH_MESSAGES_LIMIT = 10;
 	};
 };
 /**
-* Makes `req` act as the key: sets `req.user`, replacing any user Payload
+* Makes `req` act as `user`: 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;
+*/ const actAs = (req, options, user, mcpx) => {
+	req.user = user;
 	req.context = {
 		...req.context,
-		mcpx: {
-			apiKeyId: auth.apiKeyId,
-			capabilities
-		}
+		mcpx
 	};
-	return buildScope(req, options, capabilities);
+	return buildScope(req, options, mcpx.capabilities);
 };
 /**
+* Makes `req` act as the key, with the capabilities its checkboxes resolve to.
+*/ const authenticateAs = (req, options, auth) => actAs(req, options, auth.user, {
+	apiKeyId: auth.apiKeyId,
+	capabilities: resolveCapabilities(options, auth.capabilities)
+});
+/**
 * Answers GET and DELETE on the endpoint path. The server is stateless and
 * never streams, so only POST carries meaning.
 */ const methodNotAllowed = () => jsonRpcError({
@@ -117,4 +119,4 @@ const BATCH_MESSAGES_LIMIT = 10;
 	}
 };
 //#endregion
-export { authenticateAs, buildScope, createMcpxHandler, methodNotAllowed };
+export { actAs, authenticateAs, buildScope, createMcpxHandler, methodNotAllowed };

package/dist/local.d.mts

@@ -0,0 +1,33 @@
+import { Payload, TypedUser } from "payload";
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+//#region src/local.d.ts
+/**
+ * What one entity grants, keyed by operation. Deleting is not offered here.
+ */
+export interface McpxLocalEntityCapabilities {
+  read?: boolean;
+  write?: boolean;
+  publish?: boolean;
+}
+/**
+ * What an in-process client may do, keyed by collection slug, global slug and
+ * tool name. The plugin config caps it the same way it caps an API key.
+ */
+export interface McpxLocalCapabilities {
+  collections?: Record<string, McpxLocalEntityCapabilities>;
+  globals?: Record<string, McpxLocalEntityCapabilities>;
+  tools?: Record<string, boolean>;
+}
+/**
+ * An MCP client connected in process to the tools of the plugin installed on
+ * `payload`, acting as `user` with `capabilities`. The caller vouches for
+ * `user`: no API key is checked, and Payload's access control runs as that
+ * user. Without a key there is nothing to approve or upload against, so
+ * deletes, uploads and confirmations are unavailable. `close` also closes the
+ * server.
+ */
+export declare const createMcpxClient: (payload: Payload, args: {
+  user: TypedUser;
+  capabilities: McpxLocalCapabilities;
+}) => Promise<Client>;
+//#endregion

package/dist/local.mjs

@@ -0,0 +1,51 @@
+import { ownValue } from "./guards.mjs";
+import { resolveCapabilities } from "./capabilities.mjs";
+import { relationId } from "./auth/resolve.mjs";
+import { MCPX_VERSION } from "./version.mjs";
+import { createMcpServer } from "./endpoint/server.mjs";
+import { actAs } from "./endpoint/handler.mjs";
+import { optionsOf } from "./plugin.mjs";
+import { createLocalReq } from "payload";
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { InMemoryTransport } from "@modelcontextprotocol/sdk/inMemory.js";
+//#region src/local.ts
+const storedGroup = (entities, granted) => Object.fromEntries(entities.map((entity) => {
+	const operations = ownValue(granted, entity.slug);
+	return [entity.fieldName, {
+		read: operations?.read,
+		write: operations?.write,
+		publish: operations?.publish
+	}];
+}));
+/**
+* An MCP client connected in process to the tools of the plugin installed on
+* `payload`, acting as `user` with `capabilities`. The caller vouches for
+* `user`: no API key is checked, and Payload's access control runs as that
+* user. Without a key there is nothing to approve or upload against, so
+* deletes, uploads and confirmations are unavailable. `close` also closes the
+* server.
+*/ const createMcpxClient = async (payload, args) => {
+	const options = optionsOf(payload);
+	const { user, capabilities } = args;
+	if (relationId(user) === void 0 || user.collection !== options.userCollection) throw new Error(`[payloadcms-mcpx] createMcpxClient needs a user of the "${options.userCollection}" collection with an id.`);
+	const req = await createLocalReq({ user }, payload);
+	const scope = actAs(req, options, user, { capabilities: resolveCapabilities(options, {
+		collections: storedGroup(options.collections, capabilities.collections),
+		globals: storedGroup(options.globals, capabilities.globals),
+		tools: capabilities.tools
+	}) });
+	const server = createMcpServer({
+		...scope,
+		uploads: false
+	}, options);
+	const client = new Client({
+		name: "mcpx-local",
+		version: MCPX_VERSION
+	});
+	const [clientTransport, serverTransport] = InMemoryTransport.createLinkedPair();
+	await server.connect(serverTransport);
+	await client.connect(clientTransport);
+	return client;
+};
+//#endregion
+export { createMcpxClient };

package/dist/options.mjs

@@ -194,7 +194,7 @@ 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
 	};

package/dist/plugin.d.mts

@@ -1,4 +1,6 @@
 import { McpxPluginOptions } from "./types.mjs";
+import "./options.mjs";
+import { Payload } from "payload";
 //#region src/plugin.d.ts
 /**
  * Mounts the MCP, upload and download endpoints, and the confirmation

package/dist/plugin.mjs

@@ -7,6 +7,15 @@ import { assertFolderCollection, normalizeOptions } from "./options.mjs";
 import { installDraftGuards, installGlobalDraftGuards } from "./write/draft-guard.mjs";
 import { definePlugin } from "payload";
 //#region src/plugin.ts
+const initialized = /* @__PURE__ */ new WeakMap();
+/**
+* The normalized options of the plugin installed on `payload`. Throws where
+* the plugin is not installed or Payload has not run `onInit`.
+*/ const optionsOf = (payload) => {
+	const options = initialized.get(payload.config);
+	if (options === void 0) throw new Error("[payloadcms-mcpx] The plugin is not installed on this Payload instance, or Payload has not been initialized.");
+	return options;
+};
 /**
 * Mounts the MCP, upload and download endpoints, and the confirmation
 * endpoints where a collection exposes `delete`. Adds the API key collection
@@ -25,6 +34,7 @@ import { definePlugin } from "payload";
 			globals: installGlobalDraftGuards(config.globals ?? []),
 			onInit: async (payload) => {
 				assertFolderCollection(payload.config, normalized);
+				initialized.set(payload.config, normalized);
 				await config.onInit?.(payload);
 			},
 			endpoints: [
@@ -60,4 +70,4 @@ import { definePlugin } from "payload";
 	}
 });
 //#endregion
-export { mcpxPlugin };
+export { mcpxPlugin, optionsOf };

package/dist/types.d.mts

@@ -372,7 +372,10 @@ export interface McpxResolvedCapabilities {
  * Stamped on `req.context.mcpx`; see {@link isMcpxRequest}.
  */
 export interface McpxRequestContext {
-  apiKeyId: DocumentId;
+  /**
+   * `undefined` for a client from `createMcpxClient`, which acts without a key.
+   */
+  apiKeyId?: DocumentId;
   capabilities: McpxResolvedCapabilities;
 }
 //#endregion

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.2",
+  "version": "2.2.0-beta.1",
   "description": "Payload CMS plugin exposing a fixed, schema-aware MCP tool surface with draft-only writes and per-API-key capabilities.",
   "keywords": [
     "payload",
@@ -30,6 +30,10 @@
     "./admin": {
       "types": "./dist/admin/index.d.mts",
       "default": "./dist/admin/index.mjs"
+    },
+    "./local": {
+      "types": "./dist/local.d.mts",
+      "default": "./dist/local.mjs"
     }
   },
   "files": [