@abinnovision/payloadcms-mcpx 2.1.0 → 2.2.0-beta.16

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/admin/capability-matrix.d.mts

@@ -32,4 +32,5 @@ interface McpxCapabilityMatrixProps {
  * unaffected.
  */
 export declare const McpxCapabilityMatrix: React.FC<McpxCapabilityMatrixProps>;
-//#endregion
+//#endregion
+export {};

package/dist/admin/confirmations.d.mts

@@ -12,4 +12,5 @@ interface McpxConfirmationsProps {
  * does not mark the key modified. Renders nothing while none is waiting.
  */
 export declare const McpxConfirmations: React.FC<McpxConfirmationsProps>;
-//#endregion
+//#endregion
+export {};

package/dist/admin/setup-guide.d.mts

@@ -12,4 +12,5 @@ interface McpxSetupGuideProps {
  * saved, because before that there is no key to hand to a client.
  */
 export declare const McpxSetupGuide: React.FC<McpxSetupGuideProps>;
-//#endregion
+//#endregion
+export {};

package/dist/api-keys/capability-matrix.d.mts

@@ -31,4 +31,5 @@ export interface CapabilityMatrix {
   globals: CapabilityRow[];
   tools: CapabilityTool[];
 }
-//#endregion
+//#endregion
+export {};

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/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,11 @@ 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
+//#endregion
+export {};

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "@abinnovision/payloadcms-mcpx",
-  "version": "2.1.0",
+  "version": "2.2.0-beta.16",
   "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": [
@@ -75,11 +79,11 @@
     "@vitest/coverage-v8": "^5.0.3",
     "eslint": "^10.12.0",
     "payload": "3.90.2",
-    "prettier": "^3.9.9",
+    "prettier": "^3.9.10",
     "publint": "^0.3.25",
     "react": "^19.3.0",
     "react-dom": "^19.3.0",
-    "tsdown": "^0.23.0",
+    "tsdown": "^0.23.1",
     "typescript": "^6.0.3",
     "unplugin-swc": "^2.0.0",
     "vitest": "^5.0.3"