@abinnovision/payloadcms-mcpx 1.0.1-beta.1 → 1.1.0-beta.3

package/README.md

@@ -330,6 +330,25 @@ to anyone who may read the key document (own keys only, by default). Each key:
   is configured `write: "live"`, and it counts only alongside `write`, since
   publishing is an extension of writing.
 
+### The capabilities matrix
+
+The checkboxes render as one table per namespace: a row per collection, global
+or tool, a column per operation, and a bulk toggle in each column header that
+grants or clears the whole column at once. Clicking a row's name does the same
+for that entity.
+
+A cell the plugin config does not expose shows a dash instead of an empty box,
+so a `write: false` collection reads as a refusal by config rather than a
+capability someone forgot to tick. A column no row exposes is left out
+altogether. Ticking `publish` ticks `write` with it, and clearing `write` clears
+`publish`, because a publish without a write resolves to nothing.
+
+Each operation is explained on its column header rather than beside every
+checkbox, so the same sentence is never repeated down the table.
+
+The matrix renders an admin component, so it has to be in the import map; see
+[Admin components](#admin-components).
+
 Keys authenticate only the MCP endpoint. They are deliberately not a Payload
 auth strategy, so a key can never authenticate the REST or GraphQL API. The
 reverse also holds: an admin session or JWT is ignored by the MCP endpoint.
@@ -345,15 +364,22 @@ 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:
+The URL comes from `serverURL` when the config sets one and from the browser's
+origin otherwise.
+
+### Admin components
+
+The key form renders two components of its own, the capabilities matrix and the
+setup guide, so both have 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.
+Without those entries Payload logs a missing-component error and renders nothing
+in their place. For the setup guide that costs a tab; for the matrix it costs
+the whole capabilities editor, leaving no way to grant a key anything from the
+admin. The rest of the plugin is unaffected either way.
 
 ## Drafts and publishing
 

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

@@ -0,0 +1,32 @@
+import "../options.mjs";
+//#region src/api-keys/capability-matrix.d.ts
+/**
+ * One entity's row. The three booleans say what the plugin config exposes, not
+ * what the key has been granted: a `false` renders as a dash rather than an
+ * empty box, so absence reads as a refusal by config rather than a gap.
+ */
+export interface CapabilityRow {
+  fieldName: string;
+  /** The slug, which is what MCP clients send and what refusals name. */
+  label: string;
+  read: boolean;
+  write: boolean;
+  publish: boolean;
+  /** Said only where a row departs from what its column header promises. */
+  hint?: string;
+}
+export interface CapabilityTool {
+  name: string;
+  description: string;
+}
+/**
+ * Everything the admin component needs to draw the matrix, derived from the
+ * plugin options at config time. Crosses the server/client boundary as a client
+ * prop, so every leaf has to stay JSON-serializable.
+ */
+export interface CapabilityMatrix {
+  collections: CapabilityRow[];
+  globals: CapabilityRow[];
+  tools: CapabilityTool[];
+}
+//#endregion

package/dist/api-keys/capability-matrix.mjs

@@ -0,0 +1,128 @@
+import { CAPABILITIES_FIELD, canCreate, canPublish, canWrite } from "../capabilities.mjs";
+//#region src/api-keys/capability-matrix.ts
+/**
+* The group's `admin.description`, which the matrix renders in Payload's own
+* description slot under the heading. It is the one place the two markings in
+* the table are explained, so both belong in it.
+*/ const CAPABILITIES_DESCRIPTION = "What this key may do. An unticked box is a refusal, and a dash means the plugin config does not expose that operation at all.";
+/**
+* The three operations a collection or global can expose, described once. The
+* generated checkboxes and the matrix column headers both read these, so the
+* wording a key's owner sees cannot drift from what the field config carries.
+*/ const CAPABILITY_OPERATIONS = [
+	{
+		id: "read",
+		label: "Read",
+		description: "Describe, find and read."
+	},
+	{
+		id: "write",
+		label: "Write",
+		description: "Create, patch and validate drafts."
+	},
+	{
+		id: "publish",
+		label: "Publish",
+		description: "Promote the current draft to what the public sees."
+	}
+];
+const UPLOAD_HINT = "Files are uploaded in the admin panel.";
+const toRow = (entity) => ({
+	fieldName: entity.fieldName,
+	label: entity.slug,
+	read: entity.read,
+	write: canWrite(entity),
+	publish: canPublish(entity),
+	...canWrite(entity) && !canCreate(entity) ? { hint: UPLOAD_HINT } : {}
+});
+/**
+* The single description of what the config exposes. `createCapabilityFields`
+* generates its checkboxes from this, and the admin component draws from it, so
+* a cell can never appear without a field behind it.
+*/ const createCapabilityMatrix = (options) => ({
+	collections: options.collections.map(toRow),
+	globals: options.globals.map(toRow),
+	tools: options.tools.map((tool) => ({
+		name: tool.name,
+		description: typeof tool.description === "string" ? tool.description : tool.name
+	}))
+});
+const cellPath = (basePath, namespace, fieldName, operation) => `${basePath}.${namespace}.${fieldName}.${operation}`;
+const toolPath = (basePath, name) => `${basePath}.tools.${name}`;
+/** Every path the matrix can address, in a stable order. */ const capabilityPaths = (matrix, basePath = CAPABILITIES_FIELD) => [...["collections", "globals"].flatMap((namespace) => matrix[namespace].flatMap((row) => CAPABILITY_OPERATIONS.filter((operation) => row[operation.id]).map((operation) => cellPath(basePath, namespace, row.fieldName, operation.id)))), ...matrix.tools.map((tool) => toolPath(basePath, tool.name))];
+const stateOf = (paths, values) => {
+	if (paths.length === 0) return "off";
+	const granted = paths.filter((path) => values[path] === true).length;
+	if (granted === 0) return "off";
+	return granted === paths.length ? "on" : "mixed";
+};
+/**
+* Whether a column's bulk toggle reads as on, off or indeterminate. Non-exposed
+* cells are ignored: a column of two granted cells and one dash is fully on.
+*/ const columnState = (matrix, basePath, namespace, operation, values) => stateOf(matrix[namespace].filter((row) => row[operation]).map((row) => cellPath(basePath, namespace, row.fieldName, operation)), values);
+/**
+* Whether an entity's row toggle reads as on, off or indeterminate, over the
+* operations the config exposes for that row.
+*/ const rowState = (basePath, namespace, row, values) => stateOf(CAPABILITY_OPERATIONS.filter((operation) => row[operation.id]).map((operation) => cellPath(basePath, namespace, row.fieldName, operation.id)), values);
+const toolsState = (matrix, basePath, values) => stateOf(matrix.tools.map((tool) => toolPath(basePath, tool.name)), values);
+/**
+* Publishing is an extension of writing, and `publishFlag` in `capabilities.ts`
+* discards a publish without a write. Ticking publish therefore ticks write,
+* and clearing write clears publish, so the form cannot save a combination the
+* server ignores.
+*/ const reconcile = (next, touched) => {
+	if (touched.has("publish") && next.publish) return {
+		...next,
+		write: true
+	};
+	if (touched.has("write") && !next.write) return {
+		...next,
+		publish: false
+	};
+	return next;
+};
+const rowActions = (basePath, namespace, row, values, changes) => {
+	const current = {
+		read: values[cellPath(basePath, namespace, row.fieldName, "read")] === true,
+		write: values[cellPath(basePath, namespace, row.fieldName, "write")] === true,
+		publish: values[cellPath(basePath, namespace, row.fieldName, "publish")] === true
+	};
+	const touched = /* @__PURE__ */ new Set();
+	const next = { ...current };
+	for (const operation of CAPABILITY_OPERATIONS) {
+		const change = changes[operation.id];
+		if (change !== void 0 && row[operation.id]) {
+			next[operation.id] = change;
+			touched.add(operation.id);
+		}
+	}
+	const reconciled = reconcile(next, touched);
+	return CAPABILITY_OPERATIONS.filter((operation) => row[operation.id] && reconciled[operation.id] !== current[operation.id]).map((operation) => ({
+		type: "UPDATE",
+		path: cellPath(basePath, namespace, row.fieldName, operation.id),
+		value: reconciled[operation.id]
+	}));
+};
+/**
+* The form-state updates one click implies, as literal actions. Every toggle in
+* the matrix — cell, row, column or tool — comes through here, so the publish
+* rule holds for bulk grants as much as for a single box.
+*
+* Only cells whose value actually changes get an action, which keeps a bulk
+* toggle from marking the form modified when it changes nothing.
+*/ const buildToggleActions = (matrix, basePath, values, intent) => {
+	if (intent.kind === "tool" || intent.kind === "tools") return matrix.tools.filter((tool) => intent.kind === "tools" || tool.name === intent.name).filter((tool) => values[toolPath(basePath, tool.name)] === true !== intent.value).map((tool) => ({
+		type: "UPDATE",
+		path: toolPath(basePath, tool.name),
+		value: intent.value
+	}));
+	const rows = matrix[intent.namespace].filter((row) => intent.kind === "column" || row.fieldName === intent.fieldName);
+	const changes = intent.kind === "row" ? {
+		read: intent.value,
+		write: intent.value,
+		publish: intent.value
+	} : { [intent.operation]: intent.value };
+	return rows.flatMap((row) => rowActions(basePath, intent.namespace, row, values, changes));
+};
+//#endregion
+export { CAPABILITIES_DESCRIPTION, CAPABILITY_OPERATIONS, buildToggleActions, capabilityPaths, cellPath, columnState, createCapabilityMatrix, rowState, toolPath, toolsState };

package/dist/api-keys/fields.mjs

@@ -1,4 +1,5 @@
-import { CAPABILITIES_FIELD, canCreate, canPublish, canWrite } from "../capabilities.mjs";
+import { CAPABILITIES_FIELD } from "../capabilities.mjs";
+import { CAPABILITIES_DESCRIPTION, CAPABILITY_OPERATIONS, createCapabilityMatrix } from "./capability-matrix.mjs";
 //#region src/api-keys/fields.ts
 const encryptKey = ({ req, value }) => typeof value === "string" ? req.payload.encrypt(value) : value;
 const decryptKey = ({ req, value }) => {
@@ -89,10 +90,11 @@ const checkbox = (name, description) => ({
 		}]
 	}];
 };
-const PUBLISH_DESCRIPTION = "Publish the current draft. Changes what the public sees.";
 /**
 * One checkbox per exposed operation, grouped per collection, per global and
-* per custom tool. Only operations the plugin config exposes get a checkbox, so
+* per custom tool, generated from the same {@link createCapabilityMatrix}
+* descriptor the admin component draws, so a cell can never appear without a
+* field behind it. Only operations the plugin config exposes get a checkbox, so
 * a key can never enable more than the config allows. Everything defaults to
 * off, which is why a key issued before a capability existed stays closed to it.
 *
@@ -100,31 +102,21 @@ const PUBLISH_DESCRIPTION = "Publish the current draft. Changes what the public
 * `write: "live"`: there is no draft to promote there, the write itself is the
 * live change, and a second checkbox would only make `write` a dead setting.
 *
-* An upload collection gets the same checkboxes as any other, only worded for
-* what `write` reaches there: a document's own fields, never `createDocument`,
-* because the file comes from the admin panel.
+* The group renders as a matrix rather than as nested boxes; see
+* `src/client/capability-matrix.tsx`. The descriptions below therefore reach
+* the screen on the matrix column headers, and survive here for a consumer who
+* replaces the component through `apiKeys.overrideCollection`.
 */ const createCapabilityFields = (options) => {
-	const collectionGroups = options.collections.map((collection) => ({
-		name: collection.fieldName,
+	const matrix = createCapabilityMatrix(options);
+	const entityGroups = (rows) => rows.map((row) => ({
+		name: row.fieldName,
 		type: "group",
-		label: collection.slug,
-		fields: [
-			...collection.read ? [checkbox("read", "Describe, find and read documents.")] : [],
-			...canWrite(collection) ? [checkbox("write", canCreate(collection) ? "Create, patch and validate drafts." : "Patch and validate drafts. The file itself is uploaded in the admin panel.")] : [],
-			...canPublish(collection) ? [checkbox("publish", PUBLISH_DESCRIPTION)] : []
-		]
+		label: row.label,
+		fields: CAPABILITY_OPERATIONS.filter((operation) => row[operation.id]).map((operation) => checkbox(operation.id, operation.description))
 	}));
-	const globalGroups = options.globals.map((global) => ({
-		name: global.fieldName,
-		type: "group",
-		label: global.slug,
-		fields: [
-			...global.read ? [checkbox("read", "Describe and read this global.")] : [],
-			...canWrite(global) ? [checkbox("write", "Patch and validate this global's draft.")] : [],
-			...canPublish(global) ? [checkbox("publish", PUBLISH_DESCRIPTION)] : []
-		]
-	}));
-	const toolCheckboxes = options.tools.map((tool) => checkbox(tool.name, typeof tool.description === "string" ? tool.description : tool.name));
+	const collectionGroups = entityGroups(matrix.collections);
+	const globalGroups = entityGroups(matrix.globals);
+	const toolCheckboxes = matrix.tools.map((tool) => checkbox(tool.name, tool.description));
 	const groups = [
 		...collectionGroups.length > 0 ? [{
 			name: "collections",
@@ -146,7 +138,17 @@ const PUBLISH_DESCRIPTION = "Publish the current draft. Changes what the public
 	return [{
 		name: CAPABILITIES_FIELD,
 		type: "group",
-		admin: { description: "What this key may do. Unchecked means refused, whatever the plugin config allows." },
+		admin: {
+			description: CAPABILITIES_DESCRIPTION,
+			components: { Field: {
+				path: "@abinnovision/payloadcms-mcpx/client",
+				exportName: "McpxCapabilityMatrix",
+				clientProps: {
+					matrix,
+					withinTab: options.setupGuide
+				}
+			} }
+		},
 		fields: groups
 	}];
 };

package/dist/client/capability-matrix.d.mts

@@ -0,0 +1,26 @@
+import { CapabilityMatrix } from "../api-keys/capability-matrix.mjs";
+import React from "react";
+//#region src/client/capability-matrix.d.ts
+interface McpxCapabilityMatrixProps {
+  /** Built from the plugin options at config time. */
+  matrix: CapabilityMatrix;
+  /** The group's own config, supplied by Payload. Carries the description. */
+  field?: {
+    admin?: {
+      description?: unknown;
+    };
+  };
+  /** The `capabilities` group's own path, supplied by Payload. */
+  path?: string;
+  readOnly?: boolean;
+  /** Whether the key form is split into tabs, from the plugin options. */
+  withinTab?: boolean;
+}
+/**
+ * What an API key may do, as one table per namespace: a row per entity, a
+ * column per operation, and a bulk toggle in each column header. The nested
+ * checkbox fields this replaces still back every cell, so the stored document
+ * is unchanged; only the rendering is.
+ */
+export declare const McpxCapabilityMatrix: React.FC<McpxCapabilityMatrixProps>;
+//#endregion

package/dist/client/capability-matrix.mjs

@@ -0,0 +1,349 @@
+"use client";
+import { CAPABILITIES_FIELD } from "../capabilities.mjs";
+import { CAPABILITY_OPERATIONS, buildToggleActions, capabilityPaths, cellPath, columnState, rowState, toolPath, toolsState } from "../api-keys/capability-matrix.mjs";
+import { jsx, jsxs } from "react/jsx-runtime";
+import { CheckboxInput, FieldDescription, FieldLabel, useForm, useFormFields } from "@payloadcms/ui";
+import { useCallback, useMemo } from "react";
+//#region src/client/capability-matrix.tsx
+const NOT_EXPOSED = "The plugin config does not expose this.";
+const BASE_CLASS = "mcpx-capabilities";
+const SHEET = `
+.${BASE_CLASS} tbody tr:hover { background: var(--theme-elevation-50); }
+.${BASE_CLASS}__toggle:hover { text-decoration: underline; }
+.${BASE_CLASS} section:last-of-type { margin-bottom: 0; }
+`;
+const CELL_PADDING = "calc(var(--base) * 0.6)";
+const EDGE_PADDING = "calc(var(--base) * 0.8)";
+/**
+* Payload's own theme variables, so the matrix follows the admin's light and
+* dark themes without shipping a stylesheet consumers would have to transpile.
+* The header block borrows the admin table's treatment: muted, raised a step
+* off the page and closed with a rule.
+*
+* The only literal left is the small-caps section heading, which has no
+* counterpart in the admin to borrow from.
+*/ const styles = {
+	section: { marginBottom: "var(--base)" },
+	table: {
+		tableLayout: "fixed",
+		width: "auto",
+		borderCollapse: "separate",
+		borderSpacing: 0,
+		textAlign: "left"
+	},
+	head: { background: "var(--theme-elevation-50)" },
+	/** The section name, which heads the label column instead of a stray title. */ headTitle: {
+		padding: `${CELL_PADDING} ${CELL_PADDING} ${CELL_PADDING} ${EDGE_PADDING}`,
+		verticalAlign: "middle",
+		fontSize: "0.8em",
+		letterSpacing: "0.08em",
+		textTransform: "uppercase",
+		color: "var(--theme-elevation-400)",
+		fontWeight: "normal"
+	},
+	headOperation: {
+		padding: CELL_PADDING,
+		verticalAlign: "middle",
+		color: "var(--theme-elevation-400)",
+		fontWeight: "normal",
+		textAlign: "center",
+		whiteSpace: "nowrap"
+	},
+	headLabel: {
+		padding: `${CELL_PADDING} ${CELL_PADDING} ${CELL_PADDING} ${EDGE_PADDING}`,
+		verticalAlign: "middle",
+		color: "var(--theme-elevation-500)",
+		fontWeight: "normal"
+	},
+	/** Closes the header block, across every column rather than the first. */ rule: { borderBottom: "1px solid var(--theme-border-color)" },
+	topStart: { borderStartStartRadius: "var(--style-radius-s)" },
+	topEnd: { borderStartEndRadius: "var(--style-radius-s)" },
+	rowHeader: {
+		padding: `${CELL_PADDING} ${CELL_PADDING} ${CELL_PADDING} ${EDGE_PADDING}`,
+		verticalAlign: "middle",
+		fontWeight: "normal",
+		wordBreak: "break-word"
+	},
+	rowButton: {
+		padding: 0,
+		border: 0,
+		background: "none",
+		color: "inherit",
+		font: "inherit",
+		cursor: "pointer",
+		textAlign: "start",
+		textDecoration: "none"
+	},
+	hint: {
+		display: "block",
+		color: "var(--theme-elevation-400)"
+	},
+	cell: {
+		padding: CELL_PADDING,
+		verticalAlign: "middle",
+		textAlign: "center"
+	},
+	lastCell: { paddingInlineEnd: EDGE_PADDING },
+	dash: {
+		color: "var(--theme-elevation-400)",
+		cursor: "help"
+	}
+};
+/**
+* Payload's own checkbox, which carries the admin's styling and the partial
+* state the column and row toggles need. `name` is what it renders as the
+* input's `title`, so it doubles as the control's accessible name.
+*/ const Box = ({ label, onChange, readOnly, state }) => /*#__PURE__*/ jsx(CheckboxInput, {
+	checked: state === "on",
+	name: label,
+	onToggle: onChange,
+	partialChecked: state === "mixed",
+	readOnly
+});
+/** Both in `--base` multiples, so the columns keep Payload's rhythm. */ const LABEL_WIDTH = "calc(var(--base) * 9)";
+const OPERATION_WIDTH = "calc(var(--base) * 3.5)";
+/** Fixed widths, so every table lines its columns up with the ones above it. */ const Columns = ({ count }) => /*#__PURE__*/ jsxs("colgroup", { children: [/*#__PURE__*/ jsx("col", { style: { width: LABEL_WIDTH } }), Array.from({ length: count }, (_, index) => /*#__PURE__*/ jsx("col", { style: { width: OPERATION_WIDTH } }, index))] });
+/** The rightmost cell carries the table's outer padding, as Payload's does. */ const cellStyle = (isLast) => isLast ? {
+	...styles.cell,
+	...styles.lastCell
+} : styles.cell;
+const Dash = () => /*#__PURE__*/ jsx("span", {
+	"aria-label": NOT_EXPOSED,
+	style: styles.dash,
+	title: NOT_EXPOSED,
+	children: "—"
+});
+/**
+* What an API key may do, as one table per namespace: a row per entity, a
+* column per operation, and a bulk toggle in each column header. The nested
+* checkbox fields this replaces still back every cell, so the stored document
+* is unchanged; only the rendering is.
+*/ const McpxCapabilityMatrix = ({ field, matrix, path = CAPABILITIES_FIELD, readOnly = false, withinTab = false }) => {
+	const { dispatchFields, setModified } = useForm();
+	const paths = useMemo(() => capabilityPaths(matrix, path), [matrix, path]);
+	const encoded = useFormFields(([fields]) => paths.map((cell) => fields[cell]?.value === true ? "1" : "0").join(""));
+	const values = useMemo(() => Object.fromEntries(paths.map((cell, index) => [cell, encoded[index] === "1"])), [paths, encoded]);
+	const toggle = useCallback((intent) => {
+		const actions = buildToggleActions(matrix, path, values, intent);
+		if (actions.length === 0) return;
+		for (const action of actions) dispatchFields(action);
+		setModified(true);
+	}, [
+		matrix,
+		path,
+		values,
+		dispatchFields,
+		setModified
+	]);
+	const namespaces = [{
+		id: "collections",
+		title: "Collections"
+	}, {
+		id: "globals",
+		title: "Globals"
+	}].filter((namespace) => matrix[namespace.id].length > 0);
+	const toolState = toolsState(matrix, path, values);
+	return /*#__PURE__*/ jsxs("div", {
+		className: [
+			"field-type",
+			"group-field",
+			"group-field--top-level",
+			withinTab && "group-field--within-tab",
+			BASE_CLASS
+		].filter(Boolean).join(" "),
+		children: [/*#__PURE__*/ jsx("style", { children: SHEET }), /*#__PURE__*/ jsxs("div", {
+			className: "group-field__wrap",
+			children: [
+				/*#__PURE__*/ jsx("div", {
+					className: "group-field__header",
+					children: /*#__PURE__*/ jsxs("header", { children: [/*#__PURE__*/ jsx("h3", {
+						className: "group-field__title",
+						children: /*#__PURE__*/ jsx(FieldLabel, {
+							as: "span",
+							label: "Capabilities"
+						})
+					}), typeof field?.admin?.description === "string" ? /*#__PURE__*/ jsx(FieldDescription, {
+						description: field.admin.description,
+						path
+					}) : null] })
+				}),
+				namespaces.map((namespace) => {
+					const rows = matrix[namespace.id];
+					const columns = CAPABILITY_OPERATIONS.filter((operation) => rows.some((row) => row[operation.id]));
+					return /*#__PURE__*/ jsx("section", {
+						style: styles.section,
+						children: /*#__PURE__*/ jsxs("table", {
+							style: styles.table,
+							children: [
+								/*#__PURE__*/ jsx(Columns, { count: columns.length }),
+								/*#__PURE__*/ jsxs("thead", {
+									style: styles.head,
+									children: [/*#__PURE__*/ jsxs("tr", { children: [/*#__PURE__*/ jsx("th", {
+										scope: "col",
+										style: {
+											...styles.headTitle,
+											...styles.topStart
+										},
+										children: namespace.title
+									}), columns.map((operation, column) => /*#__PURE__*/ jsx("th", {
+										scope: "col",
+										style: column === columns.length - 1 ? {
+											...styles.headOperation,
+											...styles.topEnd
+										} : styles.headOperation,
+										title: operation.description,
+										children: operation.label
+									}, operation.id))] }), /*#__PURE__*/ jsxs("tr", { children: [/*#__PURE__*/ jsx("th", {
+										scope: "row",
+										style: {
+											...styles.headLabel,
+											...styles.rule
+										},
+										children: "All"
+									}), columns.map((operation, column) => {
+										const state = columnState(matrix, path, namespace.id, operation.id, values);
+										return /*#__PURE__*/ jsx("td", {
+											style: {
+												...cellStyle(column === columns.length - 1),
+												...styles.rule
+											},
+											children: /*#__PURE__*/ jsx(Box, {
+												label: `${operation.label} every ${namespace.title.toLowerCase()} entry`,
+												onChange: () => {
+													toggle({
+														kind: "column",
+														namespace: namespace.id,
+														operation: operation.id,
+														value: state !== "on"
+													});
+												},
+												readOnly,
+												state
+											})
+										}, operation.id);
+									})] })]
+								}),
+								/*#__PURE__*/ jsx("tbody", { children: rows.map((row) => {
+									const state = rowState(path, namespace.id, row, values);
+									return /*#__PURE__*/ jsxs("tr", { children: [/*#__PURE__*/ jsxs("th", {
+										scope: "row",
+										style: styles.rowHeader,
+										children: [/*#__PURE__*/ jsx("button", {
+											className: `${BASE_CLASS}__toggle`,
+											disabled: readOnly,
+											onClick: () => {
+												toggle({
+													kind: "row",
+													namespace: namespace.id,
+													fieldName: row.fieldName,
+													value: state !== "on"
+												});
+											},
+											style: styles.rowButton,
+											title: `Toggle every capability for ${row.label}`,
+											type: "button",
+											children: row.label
+										}), row.hint ? /*#__PURE__*/ jsx("span", {
+											style: styles.hint,
+											children: row.hint
+										}) : null]
+									}), columns.map((operation, column) => /*#__PURE__*/ jsx("td", {
+										style: cellStyle(column === columns.length - 1),
+										children: row[operation.id] ? /*#__PURE__*/ jsx(Box, {
+											label: `${operation.label} ${row.label}`,
+											onChange: () => {
+												toggle({
+													kind: "cell",
+													namespace: namespace.id,
+													fieldName: row.fieldName,
+													operation: operation.id,
+													value: values[cellPath(path, namespace.id, row.fieldName, operation.id)] !== true
+												});
+											},
+											readOnly,
+											state: values[cellPath(path, namespace.id, row.fieldName, operation.id)] === true ? "on" : "off"
+										}) : /*#__PURE__*/ jsx(Dash, {})
+									}, operation.id))] }, row.fieldName);
+								}) })
+							]
+						})
+					}, namespace.id);
+				}),
+				matrix.tools.length > 0 ? /*#__PURE__*/ jsx("section", {
+					style: styles.section,
+					children: /*#__PURE__*/ jsxs("table", {
+						style: styles.table,
+						children: [
+							/*#__PURE__*/ jsx(Columns, { count: 1 }),
+							/*#__PURE__*/ jsxs("thead", {
+								style: styles.head,
+								children: [/*#__PURE__*/ jsxs("tr", { children: [/*#__PURE__*/ jsx("th", {
+									scope: "col",
+									style: {
+										...styles.headTitle,
+										...styles.topStart
+									},
+									children: "Tools"
+								}), /*#__PURE__*/ jsx("th", {
+									scope: "col",
+									style: {
+										...styles.headOperation,
+										...styles.topEnd
+									},
+									children: "Enabled"
+								})] }), /*#__PURE__*/ jsxs("tr", { children: [/*#__PURE__*/ jsx("th", {
+									scope: "row",
+									style: {
+										...styles.headLabel,
+										...styles.rule
+									},
+									children: "All"
+								}), /*#__PURE__*/ jsx("td", {
+									style: {
+										...cellStyle(true),
+										...styles.rule
+									},
+									children: /*#__PURE__*/ jsx(Box, {
+										label: "Enable every tool",
+										onChange: () => {
+											toggle({
+												kind: "tools",
+												value: toolState !== "on"
+											});
+										},
+										readOnly,
+										state: toolState
+									})
+								})] })]
+							}),
+							/*#__PURE__*/ jsx("tbody", { children: matrix.tools.map((tool) => /*#__PURE__*/ jsxs("tr", { children: [/*#__PURE__*/ jsxs("th", {
+								scope: "row",
+								style: styles.rowHeader,
+								children: [tool.name, /*#__PURE__*/ jsx("span", {
+									style: styles.hint,
+									children: tool.description
+								})]
+							}), /*#__PURE__*/ jsx("td", {
+								style: cellStyle(true),
+								children: /*#__PURE__*/ jsx(Box, {
+									label: `Enable ${tool.name}`,
+									onChange: () => {
+										toggle({
+											kind: "tool",
+											name: tool.name,
+											value: values[toolPath(path, tool.name)] !== true
+										});
+									},
+									readOnly,
+									state: values[toolPath(path, tool.name)] === true ? "on" : "off"
+								})
+							})] }, tool.name)) })
+						]
+					})
+				}) : null
+			]
+		})]
+	});
+};
+//#endregion
+export { McpxCapabilityMatrix };

package/dist/client/index.d.mts

@@ -1,2 +1,3 @@
+import { McpxCapabilityMatrix } from "./capability-matrix.mjs";
 import { McpxSetupGuide } from "./setup-guide.mjs";
-export { McpxSetupGuide };
+export { McpxCapabilityMatrix, McpxSetupGuide };

package/dist/client/index.mjs

@@ -1,2 +1,3 @@
+import { McpxCapabilityMatrix } from "./capability-matrix.mjs";
 import { McpxSetupGuide } from "./setup-guide.mjs";
-export { McpxSetupGuide };
+export { McpxCapabilityMatrix, McpxSetupGuide };

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

@@ -9,6 +9,5 @@ interface McpxSetupGuideProps {
  * 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 };
+export declare const McpxSetupGuide: React.FC<McpxSetupGuideProps>;
+//#endregion

package/dist/options.d.mts

@@ -0,0 +1,2 @@
+import "./types.mjs";
+import "payload";

package/dist/plugin.d.mts

@@ -4,6 +4,5 @@ import { McpxPluginOptions } from "./types.mjs";
  * Mounts the MCP endpoint, adds the API key collection and installs the
  * draft guard on every collection and global.
  */
-declare const mcpxPlugin: (options: McpxPluginOptions) => import("payload").Plugin;
-//#endregion
-export { mcpxPlugin };
+export declare const mcpxPlugin: (options: McpxPluginOptions) => import("payload").Plugin;
+//#endregion

package/dist/request.d.mts

@@ -5,6 +5,5 @@ import { PayloadRequest } from "payload";
  * `req.context.mcpx`, which travels into every local API call made with the
  * same `req`, including those made by custom tools.
  */
-declare const isMcpxRequest: (req: PayloadRequest) => boolean;
-//#endregion
-export { isMcpxRequest };
+export declare const isMcpxRequest: (req: PayloadRequest) => boolean;
+//#endregion

package/dist/result.d.mts

@@ -1,11 +1,10 @@
 import { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
 //#region src/result.d.ts
 /** `value` as JSON text. */
-declare const jsonResult: (value: unknown) => CallToolResult;
+export declare const jsonResult: (value: unknown) => CallToolResult;
 /**
  * `extras` travel alongside the message so the client can act on them:
  * problems, validation errors, the current `updatedAt`.
  */
-declare const errorResult: (message: string, extras?: Record<string, unknown>) => CallToolResult;
-//#endregion
-export { errorResult, jsonResult };
+export declare const errorResult: (message: string, extras?: Record<string, unknown>) => CallToolResult;
+//#endregion

package/dist/types.d.mts

@@ -21,9 +21,9 @@ declare module "payload" {
  *   `publishDocument` is exposed; on one without, where there is no draft to
  *   land on, it means the write itself is permitted and lands live.
  */
-type McpxWriteMode = "draft" | "live" | false;
+export type McpxWriteMode = "draft" | "live" | false;
 /** A key can only enable what the config exposes here. */
-interface McpxCollectionOptions {
+export interface McpxCollectionOptions {
   /** Expose `describeSchema`, `findDocuments`, `getDocument`. Default `true`. */
   read?: boolean;
   /**
@@ -34,7 +34,7 @@ interface McpxCollectionOptions {
   write?: McpxWriteMode;
 }
 /** A singleton, so neither `findDocuments` nor `createDocument` reaches one. */
-interface McpxGlobalOptions {
+export interface McpxGlobalOptions {
   /** Expose `describeSchema` and `getDocument`. Default `true`. */
   read?: boolean;
   /**
@@ -43,9 +43,9 @@ interface McpxGlobalOptions {
    */
   write?: McpxWriteMode;
 }
-type McpxToolExtra = RequestHandlerExtra<ServerRequest, ServerNotification>;
+export type McpxToolExtra = RequestHandlerExtra<ServerRequest, ServerNotification>;
 /** What the config exposes, before an API key's checkboxes narrow it. */
-interface McpxExposedEntity {
+export interface McpxExposedEntity {
   slug: string;
   read: boolean;
   write: McpxWriteMode;
@@ -56,7 +56,7 @@ interface McpxExposedEntity {
   fieldName: string;
 }
 /** What a tool knows about the current request. */
-interface McpxToolScope {
+export interface McpxToolScope {
   req: PayloadRequest;
   capabilities: McpxResolvedCapabilities;
   readable: string[];
@@ -82,7 +82,7 @@ interface McpxToolScope {
  * `req.context.mcpx` set. `Args` only needs stating when `inputSchema` is built
  * per request, leaving no static shape to infer from.
  */
-interface McpxTool<Shape extends z.ZodRawShape = z.ZodRawShape, Args = z.infer<z.ZodObject<Shape>>> {
+export interface McpxTool<Shape extends z.ZodRawShape = z.ZodRawShape, Args = z.infer<z.ZodObject<Shape>>> {
   /** camelCase, unique, not one of the builtin tool names. */
   name: string;
   /** Built per request so it can state what this key's writes actually do. */
@@ -109,23 +109,23 @@ interface McpxTool<Shape extends z.ZodRawShape = z.ZodRawShape, Args = z.infer<z
   }): CallToolResult | Promise<CallToolResult>;
 }
 /** Argument type erased, so a registry can hold tools of differing shapes. */
-type McpxAnyTool = McpxTool<z.ZodRawShape, never>;
+export type McpxAnyTool = McpxTool<z.ZodRawShape, never>;
 /** Fixed shape; arguments inferred from it. */
-declare function defineMcpxTool<Shape extends z.ZodRawShape>(tool: McpxTool<Shape> & {
+export declare function defineMcpxTool<Shape extends z.ZodRawShape>(tool: McpxTool<Shape> & {
   inputSchema?: Shape;
 }): McpxTool<Shape>;
 /** Per-request shape returned as an object literal; arguments inferred from it. */
-declare function defineMcpxTool<Shape extends z.ZodRawShape>(tool: McpxTool<Shape> & {
+export declare function defineMcpxTool<Shape extends z.ZodRawShape>(tool: McpxTool<Shape> & {
   inputSchema: (scope: McpxToolScope) => Shape;
 }): McpxAnyTool;
 /**
  * Per-request shape built from helpers that erase to `z.ZodRawShape`, as the
  * builtins do. Nothing to infer from, so state the arguments instead.
  */
-declare function defineMcpxTool<Args>(tool: McpxTool<z.ZodRawShape, Args> & {
+export declare function defineMcpxTool<Args>(tool: McpxTool<z.ZodRawShape, Args> & {
   inputSchema: (scope: McpxToolScope) => z.ZodRawShape;
 }): McpxAnyTool;
-interface McpxAuthResult {
+export interface McpxAuthResult {
   /** Must carry `collection`. */
   user: TypedUser;
   apiKeyId: number | string;
@@ -138,7 +138,7 @@ interface McpxAuthResult {
  * A type alias rather than an interface: `definePlugin` constrains its options
  * to `Record<string, unknown>`, which interfaces do not satisfy.
  */
-type McpxPluginOptions = {
+export type McpxPluginOptions = {
   /** Allow-list of collections. `true` is shorthand for `{ read: true }`. */
   collections: Partial<Record<CollectionSlug, McpxCollectionOptions | true>>;
   /** Allow-list of globals. `true` is shorthand for `{ read: true }`. */
@@ -180,30 +180,29 @@ type McpxPluginOptions = {
   };
 };
 /** What a key may do with one entity. Globals reuse this shape. */
-interface McpxCollectionCapabilities {
+export interface McpxCollectionCapabilities {
   read: boolean;
   write: boolean;
   /** Only ever true where the config sets `write: "live"` and drafts exist. */
   publish: boolean;
 }
 /** In force for one request: plugin config AND key checkboxes. */
-interface McpxResolvedCapabilities {
+export interface McpxResolvedCapabilities {
   collections: Record<string, McpxCollectionCapabilities>;
   globals: Record<string, McpxCollectionCapabilities>;
   tools: Record<string, boolean>;
 }
 /** Stamped on `req.context.mcpx`; see {@link isMcpxRequest}. */
-interface McpxRequestContext {
+export interface McpxRequestContext {
   apiKeyId: number | string;
   capabilities: McpxResolvedCapabilities;
 }
 /** One reason a human could not publish the draft as it stands. */
-interface PublishBlocker {
+export interface PublishBlocker {
   /** Resolved field label path, e.g. "Layout > Block 2 (Hero) > Title". */
   field?: string;
   message: string;
   /** JSON Pointer to the offending value, e.g. "/layout/2/title". */
   path: string;
 }
-//#endregion
-export { McpxAnyTool, McpxAuthResult, McpxCollectionCapabilities, McpxCollectionOptions, McpxExposedEntity, McpxGlobalOptions, McpxPluginOptions, McpxRequestContext, McpxResolvedCapabilities, McpxTool, McpxToolExtra, McpxToolScope, McpxWriteMode, PublishBlocker, defineMcpxTool };
+//#endregion

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "@abinnovision/payloadcms-mcpx",
-  "version": "1.0.1-beta.1",
+  "version": "1.1.0-beta.3",
   "description": "Payload CMS plugin exposing a fixed, schema-aware MCP tool surface with draft-only writes and per-API-key capabilities.",
   "keywords": [
     "payload",
@@ -68,20 +68,20 @@
     "@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.3.0",
+    "@swc/core": "^1.16.2",
+    "@types/node": "^26.5.1",
     "@types/react": "^19.2.18",
-    "@vitest/coverage-v8": "^4.1.10",
-    "eslint": "^10.9.1",
+    "@vitest/coverage-v8": "^5.0.0",
+    "eslint": "^10.10.0",
     "payload": "3.88.0",
     "prettier": "^3.9.5",
     "publint": "^0.3.24",
     "react": "^19.2.8",
     "react-dom": "^19.2.8",
-    "tsdown": "^0.22.14",
+    "tsdown": "^0.23.0",
     "typescript": "^6.0.3",
-    "unplugin-swc": "^1.5.11",
-    "vitest": "^4.1.10"
+    "unplugin-swc": "^1.6.0",
+    "vitest": "^5.0.0"
   },
   "peerDependencies": {
     "@payloadcms/ui": ">=3.88.0 <4",