@abinnovision/payloadcms-mcpx 1.0.0-beta.8 → 1.0.0-beta.9

package/README.md

@@ -27,6 +27,9 @@ yarn add @abinnovision/payloadcms-mcpx
 ```
 
 - Peer dependency: `payload >=3.88.0 <4`.
+- `@payloadcms/ui` and `react` are optional peers, needed only by the admin
+  setup guide. A headless install can leave them out and set
+  `apiKeys.setupGuide: false`.
 - The package is published as ESM only, matching Payload itself.
 
 ## Usage
@@ -85,6 +88,22 @@ all keys) or add fields.
 
 ## Connecting a client
 
+Saved keys carry a **Connect a client** tab in the admin holding these same
+instructions with their own URL and key filled in, each block behind a copy
+button. The tab only exists once the key does, so the create form stays free of
+it. Turn it off with `apiKeys.setupGuide: false`, which also drops the tabs and
+restores the flat form.
+
+The tab renders an admin component, so it has to be in the import map:
+
+```bash
+payload generate:importmap
+```
+
+Without that entry Payload logs a missing-component error and renders nothing
+else; the rest of the plugin is unaffected. The URL comes from `serverURL` when
+the config sets one and from the browser's origin otherwise.
+
 The endpoint speaks streamable HTTP with `Authorization: Bearer <key>`:
 
 ```bash
@@ -296,6 +315,7 @@ Builtin tools reject them instead.
 | `globals.<slug>.allowLiveWrites`     | `false`                        | Permit writes to a global without drafts (they land live).                                                         |
 | `userCollection`                     | `config.admin.user` or `users` | Auth collection the keys act as.                                                                                   |
 | `apiKeys.slug`                       | `mcpx-api-keys`                | Slug of the generated key collection.                                                                              |
+| `apiKeys.setupGuide`                 | `true`                         | Add a "Connect a client" tab to saved keys. Needs the import map.                                                  |
 | `apiKeys.overrideCollection`         | none                           | Final override applied to the generated collection.                                                                |
 | `endpoint.path`                      | `/mcpx`                        | Endpoint path below the API route.                                                                                 |
 | `limits.maxLimit`                    | `25`                           | Upper bound for `findDocuments.limit`.                                                                             |

package/dist/api-keys/collection.mjs

@@ -1,4 +1,4 @@
-import { createCapabilityFields, createKeyFields } from "./fields.mjs";
+import { createCapabilityFields, createKeyFields, withSetupGuideTab } from "./fields.mjs";
 import { generateApiKey, hashApiKey } from "./key.mjs";
 //#region src/api-keys/collection.ts
 /**
@@ -36,7 +36,7 @@ import { generateApiKey, hashApiKey } from "./key.mjs";
 			delete: ownKeysOnly
 		},
 		hooks: { beforeChange: [keyBeforeChange] },
-		fields: [
+		fields: withSetupGuideTab([
 			{
 				name: "user",
 				type: "relationship",
@@ -51,7 +51,7 @@ import { generateApiKey, hashApiKey } from "./key.mjs";
 			},
 			...createKeyFields(),
 			...createCapabilityFields(options)
-		]
+		], options)
 	};
 };
 //#endregion

package/dist/api-keys/fields.mjs

@@ -15,6 +15,7 @@ const checkbox = (name, description) => ({
 	defaultValue: false,
 	admin: { description }
 });
+const SETUP_GUIDE_FIELD = "setupGuide";
 /**
 * Fields every key carries. Key generation and the HMAC index live in the
 * collection-level `beforeChange` hook (see `collection.ts`), because sibling
@@ -56,6 +57,39 @@ const checkbox = (name, description) => ({
 	}
 ];
 /**
+* Wraps the key fields and the setup guide in unnamed tabs, so the wide
+* snippets get the full form width without pushing the key itself out of view.
+* Unnamed on purpose: named tabs would nest the data and move `capabilities`
+* off the document root, which capability resolution reads.
+*
+* The guide tab is conditioned on the update operation. On create there is no
+* key to hand out, and a tab leading to an empty panel is worse than no tab.
+*/ const withSetupGuideTab = (keyFields, options) => {
+	if (!options.setupGuide) return keyFields;
+	return [{
+		type: "tabs",
+		tabs: [{
+			label: "Key",
+			fields: keyFields
+		}, {
+			label: "Connect a client",
+			admin: { condition: (_data, _siblingData, { operation }) => operation === "update" },
+			fields: [{
+				name: SETUP_GUIDE_FIELD,
+				type: "ui",
+				admin: {
+					disableListColumn: true,
+					components: { Field: {
+						path: "@abinnovision/payloadcms-mcpx/client",
+						exportName: "McpxSetupGuide",
+						clientProps: { endpointPath: options.endpointPath }
+					} }
+				}
+			}]
+		}]
+	}];
+};
+/**
 * One checkbox per exposed operation, grouped per collection, per global and
 * per custom tool. Only operations the plugin config exposes get a checkbox, so
 * a key can never enable more than the config allows. Everything defaults to
@@ -100,4 +134,4 @@ const checkbox = (name, description) => ({
 	}];
 };
 //#endregion
-export { createCapabilityFields, createKeyFields };
+export { SETUP_GUIDE_FIELD, createCapabilityFields, createKeyFields, withSetupGuideTab };

package/dist/api-keys/setup-guide.mjs

@@ -0,0 +1,54 @@
+//#region src/api-keys/setup-guide.ts
+const KEY_PLACEHOLDER = "<your-key>";
+/**
+* Server name for the client config. MCP clients key their config by this, so
+* it has to survive labels with spaces or punctuation.
+*/ const toServerName = (label) => {
+	const slug = (label ?? "").toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
+	return slug === "" ? "payload" : slug;
+};
+/**
+* The connection instructions for one key, split into independently copyable
+* blocks. Kept a pure builder so the admin component holds only rendering and
+* the snippets stay unit-testable.
+*/ const buildSetupGuide = (input) => {
+	const key = typeof input.apiKey === "string" ? input.apiKey : KEY_PLACEHOLDER;
+	const name = toServerName(input.label);
+	const url = input.endpointUrl;
+	return [
+		{
+			id: "endpoint",
+			title: "Endpoint",
+			description: "Streamable HTTP. Point any MCP client at this URL.",
+			snippet: url
+		},
+		{
+			id: "header",
+			title: "Authorization header",
+			description: "The only accepted credential; cookies and JWTs are ignored.",
+			snippet: `Authorization: Bearer ${key}`
+		},
+		{
+			id: "claude-code",
+			title: "Claude Code",
+			snippet: [`claude mcp add --transport http ${name} ${url} \\`, `  --header "Authorization: Bearer ${key}"`].join("\n")
+		},
+		{
+			id: "claude-desktop",
+			title: "Claude Desktop",
+			description: "Has no direct header support, so it goes through mcp-remote.",
+			snippet: JSON.stringify({ mcpServers: { [name]: {
+				command: "npx",
+				args: [
+					"-y",
+					"mcp-remote",
+					url,
+					"--header",
+					`Authorization: Bearer ${key}`
+				]
+			} } }, null, 2)
+		}
+	];
+};
+//#endregion
+export { KEY_PLACEHOLDER, buildSetupGuide, toServerName };

package/dist/client/index.d.mts

@@ -0,0 +1,2 @@
+import { McpxSetupGuide, McpxSetupGuideProps } from "./setup-guide.mjs";
+export { McpxSetupGuide, type McpxSetupGuideProps };

package/dist/client/index.mjs

@@ -0,0 +1,2 @@
+import { McpxSetupGuide } from "./setup-guide.mjs";
+export { McpxSetupGuide };

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

@@ -0,0 +1,14 @@
+import React from "react";
+//#region src/client/setup-guide.d.ts
+interface McpxSetupGuideProps {
+  /** Endpoint path below the API route, from the plugin options. */
+  endpointPath: string;
+}
+/**
+ * Per-key connection instructions on the API key edit view. Renders nothing
+ * until the document is saved, because before that there is no key to hand to
+ * a client.
+ */
+declare const McpxSetupGuide: React.FC<McpxSetupGuideProps>;
+//#endregion
+export { McpxSetupGuide, type McpxSetupGuideProps };

package/dist/client/setup-guide.mjs

@@ -0,0 +1,87 @@
+"use client";
+import { buildSetupGuide } from "../api-keys/setup-guide.mjs";
+import { jsx, jsxs } from "react/jsx-runtime";
+import { CopyToClipboard, useConfig, useDocumentInfo, useFormFields } from "@payloadcms/ui";
+import { useEffect, useState } from "react";
+//#region src/client/setup-guide.tsx
+const asString = (value) => typeof value === "string" ? value : void 0;
+/**
+* Reads `serverURL` when the config sets one and falls back to the browser's
+* origin. The fallback has to wait for mount: this component is server-rendered
+* first, where `window` does not exist.
+*/ const useOrigin = (serverUrl) => {
+	const [origin, setOrigin] = useState(serverUrl);
+	useEffect(() => {
+		if (serverUrl === "") setOrigin(window.location.origin);
+	}, [serverUrl]);
+	return origin;
+};
+/**
+* Payload's own theme variables, so the panel follows the admin's light and
+* dark themes without shipping a stylesheet consumers would have to transpile.
+*/ const styles = {
+	lead: { marginBottom: "calc(var(--base) * 0.75)" },
+	section: { marginBottom: "calc(var(--base) * 0.75)" },
+	sectionHeader: {
+		display: "flex",
+		alignItems: "center",
+		gap: "calc(var(--base) * 0.25)"
+	},
+	description: {
+		margin: "calc(var(--base) * 0.15) 0",
+		color: "var(--theme-elevation-500)"
+	},
+	snippet: {
+		margin: 0,
+		padding: "calc(var(--base) * 0.4)",
+		background: "var(--theme-elevation-50)",
+		border: "1px solid var(--theme-elevation-150)",
+		borderRadius: "3px",
+		fontFamily: "var(--font-mono)",
+		overflowX: "auto",
+		whiteSpace: "pre-wrap",
+		wordBreak: "break-all"
+	}
+};
+/**
+* Per-key connection instructions on the API key edit view. Renders nothing
+* until the document is saved, because before that there is no key to hand to
+* a client.
+*/ const McpxSetupGuide = ({ endpointPath }) => {
+	const { id } = useDocumentInfo();
+	const { config } = useConfig();
+	const apiKey = useFormFields(([fields]) => fields["apiKey"]?.value);
+	const label = useFormFields(([fields]) => fields["label"]?.value);
+	const origin = useOrigin(config.serverURL);
+	if (id === void 0) return null;
+	const sections = buildSetupGuide({
+		endpointUrl: `${origin.replace(/\/+$/, "")}${config.routes.api}${endpointPath}`,
+		apiKey: asString(apiKey),
+		label: asString(label)
+	});
+	return /*#__PURE__*/ jsxs("div", {
+		className: "field-type",
+		children: [/*#__PURE__*/ jsx("p", {
+			style: styles.lead,
+			children: "Every snippet below contains this key in full. Treat it like a password."
+		}), sections.map((section) => /*#__PURE__*/ jsxs("section", {
+			style: styles.section,
+			children: [
+				/*#__PURE__*/ jsxs("div", {
+					style: styles.sectionHeader,
+					children: [/*#__PURE__*/ jsx("strong", { children: section.title }), /*#__PURE__*/ jsx(CopyToClipboard, { value: section.snippet })]
+				}),
+				section.description ? /*#__PURE__*/ jsx("p", {
+					style: styles.description,
+					children: section.description
+				}) : null,
+				/*#__PURE__*/ jsx("pre", {
+					style: styles.snippet,
+					children: section.snippet
+				})
+			]
+		}, section.id))]
+	});
+};
+//#endregion
+export { McpxSetupGuide };

package/dist/options.mjs

@@ -132,6 +132,7 @@ const normalizeLimits = (limits) => {
 		userCollection,
 		apiKeysSlug,
 		endpointPath: options.endpoint?.path ?? DEFAULT_ENDPOINT_PATH,
+		setupGuide: options.apiKeys?.setupGuide ?? true,
 		limits: normalizeLimits(options.limits),
 		tools,
 		auth: options.auth,

package/dist/types.d.mts

@@ -90,6 +90,11 @@ type McpxPluginOptions = {
   apiKeys?: {
     /** Slug of the generated API key collection. Default `mcpx-api-keys`. */
     slug?: string;
+    /**
+     * Add a "Connect a client" tab to saved keys, holding ready-to-paste MCP
+     * client config. Default `true`. The snippets contain the key in full.
+     */
+    setupGuide?: boolean;
     /** Final override applied to the generated collection. */
     overrideCollection?: (collection: CollectionConfig) => CollectionConfig;
   };

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "@abinnovision/payloadcms-mcpx",
-  "version": "1.0.0-beta.8",
+  "version": "1.0.0-beta.9",
   "description": "Payload CMS plugin exposing a fixed, schema-aware MCP tool surface with draft-only writes and per-API-key capabilities.",
   "keywords": [
     "payload",
@@ -26,6 +26,10 @@
     ".": {
       "types": "./dist/index.d.mts",
       "default": "./dist/index.mjs"
+    },
+    "./client": {
+      "types": "./dist/client/index.d.mts",
+      "default": "./dist/client/index.mjs"
     }
   },
   "files": [
@@ -35,17 +39,17 @@
   ],
   "scripts": {
     "build": "tsdown",
-    "format:check": "prettier --check 'src/**/*.ts' 'test/**/*.ts' '*.{json{,5},md,y{,a}ml}'",
-    "format:fix": "prettier --write 'src/**/*.ts' 'test/**/*.ts' '*.{json{,5},md,y{,a}ml}'",
-    "lint:check": "eslint 'src/**/*.ts' 'test/**/*.ts'",
-    "lint:fix": "eslint 'src/**/*.ts' 'test/**/*.ts' --fix",
+    "format:check": "prettier --check 'src/**/*.{ts,tsx}' 'test/**/*.ts' '*.{json{,5},md,y{,a}ml}'",
+    "format:fix": "prettier --write 'src/**/*.{ts,tsx}' 'test/**/*.ts' '*.{json{,5},md,y{,a}ml}'",
+    "lint:check": "eslint 'src/**/*.{ts,tsx}' 'test/**/*.ts'",
+    "lint:fix": "eslint 'src/**/*.{ts,tsx}' 'test/**/*.ts' --fix",
     "test-integration": "vitest --run --config test/integration/vitest.config.mts",
     "test-unit": "vitest --run --coverage --config vitest.config.mts",
     "test-unit:watch": "vitest --config vitest.config.mts",
     "typecheck": "tsc --noEmit"
   },
   "lint-staged": {
-    "{src,test}/**/*.ts": [
+    "{src,test}/**/*.{ts,tsx}": [
       "eslint --fix",
       "prettier --write"
     ],
@@ -63,6 +67,7 @@
     "@arethetypeswrong/core": "^0.18.5",
     "@payloadcms/db-sqlite": "3.88.0",
     "@payloadcms/richtext-lexical": "3.88.0",
+    "@payloadcms/ui": "3.88.0",
     "@swc/core": "^1.16.1",
     "@types/node": "^26.2.0",
     "@types/react": "^19.2.18",
@@ -79,7 +84,17 @@
     "vitest": "^4.1.10"
   },
   "peerDependencies": {
-    "payload": ">=3.88.0 <4"
+    "@payloadcms/ui": ">=3.88.0 <4",
+    "payload": ">=3.88.0 <4",
+    "react": "^19"
+  },
+  "peerDependenciesMeta": {
+    "@payloadcms/ui": {
+      "optional": true
+    },
+    "react": {
+      "optional": true
+    }
   },
   "publishConfig": {
     "ghpr": true,