@abinnovision/payloadcms-mcpx 1.0.0-beta.10 → 1.0.0-beta.11

package/README.md

@@ -297,9 +297,62 @@ const publishQueue = defineMcpxTool({
 
 Each custom tool gets its own checkbox on every API key, default off.
 
-Custom tool shapes are registered as given, and the MCP SDK wraps them in a
-non-strict object: unknown arguments are stripped before your handler runs.
-Builtin tools reject them instead.
+Custom tools take the same route as the builtins: one `McpxTool` shape, one
+registration loop. Anything a builtin does, a custom tool can do.
+
+`handler` receives `scope` alongside `args`, `req` and `extra`. The scope
+carries what the key may touch (`readable`, `writable`, `readableGlobals`,
+`writableGlobals`), the configured locales, the limits in force and the
+exposed collections and globals. `req` is shorthand for `scope.req`.
+
+`inputSchema` may be a function of that scope instead of a fixed shape, which
+is how a tool narrows an enum to what the key may read:
+
+```ts
+import { defineMcpxTool } from "@abinnovision/payloadcms-mcpx";
+import { z } from "zod";
+
+const whichCollection = defineMcpxTool({
+  name: "whichCollection",
+  description: "Echoes back one of the collections this key may read.",
+  isEnabled: (scope) =>
+    scope.capabilities.tools["whichCollection"] === true &&
+    scope.readable.length > 0,
+  inputSchema: (scope) => ({
+    collection: z.enum(scope.readable as [string, ...string[]]),
+  }),
+  handler: ({ args }) => ({
+    content: [{ type: "text", text: args.collection }],
+  }),
+});
+```
+
+`defineMcpxTool` defines every tool, builtin ones included, and infers the
+handler's arguments from the input schema either way: from a fixed shape, or
+from the object literal a per-request shape returns. Above, `args` is
+`{ collection: string }` without being told.
+
+Inference reaches as far as the shape's static type. A helper returning
+`z.ZodRawShape` erases that type and leaves `args` as
+`Record<string, unknown>`, so the builtins' shape helpers declare the superset
+they produce instead: which keys a helper emits depends on the key's scope,
+and the declared type states what a handler must cope with across every scope.
+Their arguments stay derived from their schema that way, and cannot drift from
+it. If your own helpers erase, state the arguments as a type argument:
+`defineMcpxTool<Args>({ ... })`.
+
+`isEnabled` decides whether the tool is registered for this key at all: a tool
+that is not enabled never appears in `tools/list`. It defaults to the tool's
+own checkbox, which is what the builtins replace to derive their availability
+from the key's collection and global capabilities. Defining it **replaces**
+the checkbox check, so restate `scope.capabilities.tools[name]` when you still
+want it, as above.
+
+Every input schema is registered strictly, custom tools included: an unknown
+argument is rejected by name rather than stripped before the handler runs.
+
+`jsonResult` and `errorResult` are exported so a custom tool can return
+results shaped like a builtin's.
 
 ## Options
 
@@ -320,7 +373,7 @@ Builtin tools reject them instead.
 | `endpoint.path`                      | `/mcpx`                        | Endpoint path below the API route.                                                                                 |
 | `limits.maxLimit`                    | `25`                           | Upper bound for `findDocuments.limit`.                                                                             |
 | `limits.maxDepth`                    | `1`                            | Upper bound for `depth` on reads.                                                                                  |
-| `tools`                              | `[]`                           | Custom tools.                                                                                                      |
+| `tools`                              | `[]`                           | Custom tools, defined the same way as the builtins.                                                                |
 | `auth.resolve`                       | none                           | Replace or wrap the default key resolution.                                                                        |
 | `serverInfo`                         | package name and version       | Reported to MCP clients.                                                                                           |
 

package/dist/endpoint/handler.mjs

@@ -1,6 +1,6 @@
+import { jsonRpcError } from "./result.mjs";
 import { readableGlobalSlugs, readableSlugs, resolveCapabilities, writableGlobalSlugs, writableSlugs } from "../capabilities.mjs";
 import { resolveApiKeyAuth } from "../auth/resolve.mjs";
-import { jsonRpcError } from "./result.mjs";
 import { createMcpServer } from "./server.mjs";
 import { WebStandardStreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/webStandardStreamableHttp.js";
 //#region src/endpoint/handler.ts
@@ -8,14 +8,18 @@ const buildScope = (req, options, capabilities) => {
 	const { localization } = req.payload.config;
 	return {
 		req,
-		options,
 		capabilities,
 		readable: readableSlugs(capabilities),
 		writable: writableSlugs(capabilities),
 		readableGlobals: readableGlobalSlugs(capabilities),
 		writableGlobals: writableGlobalSlugs(capabilities),
 		locales: localization ? localization.localeCodes : null,
-		defaultLocale: localization ? localization.defaultLocale : null
+		defaultLocale: localization ? localization.defaultLocale : null,
+		limits: options.limits,
+		exposure: {
+			collections: options.collections,
+			globals: options.globals
+		}
 	};
 };
 /**
@@ -68,7 +72,7 @@ const buildScope = (req, options, capabilities) => {
 		code: -32600,
 		message: "Invalid request: a JSON body is required."
 	});
-	const server = createMcpServer(buildScope(req, options, capabilities));
+	const server = createMcpServer(buildScope(req, options, capabilities), options);
 	const transport = new WebStandardStreamableHTTPServerTransport({ enableJsonResponse: true });
 	await server.connect(transport);
 	const headers = new Headers(req.headers);

package/dist/endpoint/result.d.mts

@@ -0,0 +1,14 @@
+import "payload";
+import { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
+//#region src/endpoint/result.d.ts
+/**
+ * A successful tool result carrying `value` as JSON text.
+ */
+declare const jsonResult: (value: unknown) => CallToolResult;
+/**
+ * A failed tool result. `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 };

package/dist/endpoint/server.mjs

@@ -4,16 +4,24 @@ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { z } from "zod";
 //#region src/endpoint/server.ts
 /**
-* Builds a builtin tool's input schema as a strict object, so an unknown
-* argument is rejected with its name instead of being silently stripped and
-* the tool answering as if it had not been passed.
-*/ const builtinInputSchema = (tool, scope) => z.strictObject(tool.inputSchema(scope));
+* Builds a tool's input schema as a strict object, so an unknown argument is
+* rejected with its name instead of being silently stripped and the tool
+* answering as if it had not been passed. A tool may build its shape from the
+* scope to narrow enums to what the key may touch.
+*/ const toolInputSchema = (tool, scope) => z.strictObject(typeof tool.inputSchema === "function" ? tool.inputSchema(scope) : tool.inputSchema ?? {});
 /**
-* Builds the MCP server for one request. Tools are registered against the
-* key's capabilities, so `tools/list` shows exactly what the key may call and
-* every `collection` enum is limited to what it may touch.
-*/ const createMcpServer = (scope) => {
-	const { req, options, capabilities } = scope;
+* Whether the key may call the tool. A tool that does not decide for itself is
+* gated by its own checkbox on the key, which is how the tools from
+* `options.tools` work; the builtins derive it from the key's collection and
+* global capabilities instead.
+*/ const isToolEnabled = (tool, scope) => tool.isEnabled ? tool.isEnabled(scope) : scope.capabilities.tools[tool.name] === true;
+/**
+* Builds the MCP server for one request. Builtin and configured tools take the
+* same route: each is registered against the key's capabilities, so
+* `tools/list` shows exactly what the key may call and every `collection` enum
+* is limited to what it may touch.
+*/ const createMcpServer = (scope, options) => {
+	const { req } = scope;
 	const { logger } = req.payload;
 	const server = new McpServer({
 		name: options.serverInfo.name,
@@ -26,22 +34,15 @@ import { z } from "zod";
 			return toToolError(error, logger);
 		}
 	};
-	for (const tool of BUILTIN_TOOLS) {
-		if (!tool.isEnabled(scope)) continue;
-		server.registerTool(tool.name, {
-			description: tool.description,
-			inputSchema: builtinInputSchema(tool, scope),
-			annotations: tool.annotations
-		}, (args) => guarded(() => tool.handler(args, scope))());
-	}
-	for (const tool of options.tools) {
-		if (capabilities.tools[tool.name] !== true) continue;
+	for (const tool of [...BUILTIN_TOOLS, ...options.tools]) {
+		if (!isToolEnabled(tool, scope)) continue;
 		server.registerTool(tool.name, {
 			description: tool.description,
-			inputSchema: tool.inputSchema ?? {},
+			inputSchema: toolInputSchema(tool, scope),
 			...tool.annotations ? { annotations: tool.annotations } : {}
 		}, (args, extra) => guarded(() => tool.handler({
 			args,
+			scope,
 			req,
 			extra
 		}))());
@@ -49,4 +50,4 @@ import { z } from "zod";
 	return server;
 };
 //#endregion
-export { builtinInputSchema, createMcpServer };
+export { createMcpServer, isToolEnabled, toolInputSchema };

package/dist/index.d.mts

@@ -1,5 +1,6 @@
-import { McpxAuthResult, McpxCollectionCapabilities, McpxCollectionOptions, McpxGlobalOptions, McpxPluginOptions, McpxRequestContext, McpxResolvedCapabilities, McpxTool, McpxToolExtra, defineMcpxTool } from "./types.mjs";
+import { errorResult, jsonResult } from "./endpoint/result.mjs";
+import { McpxAnyTool, McpxAuthResult, McpxCollectionCapabilities, McpxCollectionOptions, McpxExposedEntity, McpxGlobalOptions, McpxPluginOptions, McpxRequestContext, McpxResolvedCapabilities, McpxTool, McpxToolExtra, McpxToolScope, defineMcpxTool } from "./types.mjs";
 import { mcpxPlugin } from "./plugin.mjs";
 import { isMcpxRequest } from "./write/draft-guard.mjs";
 import { PublishBlocker } from "./write/publish-blockers.mjs";
-export { type McpxAuthResult, type McpxCollectionCapabilities, type McpxCollectionOptions, type McpxGlobalOptions, type McpxPluginOptions, type McpxRequestContext, type McpxResolvedCapabilities, type McpxTool, type McpxToolExtra, type PublishBlocker, defineMcpxTool, isMcpxRequest, mcpxPlugin };
+export { type McpxAnyTool, type McpxAuthResult, type McpxCollectionCapabilities, type McpxCollectionOptions, type McpxExposedEntity, type McpxGlobalOptions, type McpxPluginOptions, type McpxRequestContext, type McpxResolvedCapabilities, type McpxTool, type McpxToolExtra, type McpxToolScope, type PublishBlocker, defineMcpxTool, errorResult, isMcpxRequest, jsonResult, mcpxPlugin };

package/dist/index.mjs

@@ -1,4 +1,5 @@
+import { errorResult, jsonResult } from "./endpoint/result.mjs";
+import { defineMcpxTool } from "./types.mjs";
 import { isMcpxRequest } from "./write/draft-guard.mjs";
 import { mcpxPlugin } from "./plugin.mjs";
-import { defineMcpxTool } from "./types.mjs";
-export { defineMcpxTool, isMcpxRequest, mcpxPlugin };
+export { defineMcpxTool, errorResult, isMcpxRequest, jsonResult, mcpxPlugin };

package/dist/tools/create-document.mjs

@@ -2,11 +2,12 @@ import { errorResult, jsonResult } from "../endpoint/result.mjs";
 import { localeOf, localeShape, readTarget, slugEnum } from "./shared.mjs";
 import { resolveTarget } from "./target.mjs";
 import { validateWriteValue } from "../schema/shape.mjs";
+import { defineMcpxTool } from "../types.mjs";
 import { stripRowIds } from "../write/patch.mjs";
 import { collectPublishBlockers } from "../write/publish-blockers.mjs";
 import { z } from "zod";
 //#region src/tools/create-document.ts
-const createDocument = {
+const createDocument = defineMcpxTool({
 	name: "createDocument",
 	description: `Creates a new document as a draft from a minimal seed. Only the fields describeSchema lists may appear in "data"; unknown keys are refused with the valid siblings. The draft may be incomplete: the response lists "publishBlockers", which patchDocument can then work through. Use this when no document exists yet; prefer patching an existing draft otherwise.`,
 	annotations: {
@@ -24,7 +25,7 @@ const createDocument = {
 		}),
 		data: z.record(z.string(), z.unknown()).describe("Initial field values, as describeSchema lists them.")
 	}),
-	handler: async (args, scope) => {
+	handler: async ({ args, scope }) => {
 		const target = resolveTarget(scope, { collection: args.collection }, "write");
 		const { payload } = scope.req;
 		const locale = localeOf(scope, args.locale);
@@ -63,6 +64,6 @@ const createDocument = {
 			...publishBlockers.length > 0 ? { publishBlockers } : {}
 		});
 	}
-};
+});
 //#endregion
 export { createDocument };

package/dist/tools/describe-schema.mjs

@@ -2,10 +2,11 @@ import { translatorFor } from "../i18n.mjs";
 import { jsonResult } from "../endpoint/result.mjs";
 import { targetShape } from "./shared.mjs";
 import { refOf, resolveTarget } from "./target.mjs";
+import { defineMcpxTool } from "../types.mjs";
 import { nodeDescriber, reachableSchemaPaths } from "../schema/describe.mjs";
 import { z } from "zod";
 //#region src/tools/describe-schema.ts
-const describeSchema = {
+const describeSchema = defineMcpxTool({
 	name: "describeSchema",
 	description: `Describes the writable shape of a document, one node at a time.
 
@@ -31,7 +32,7 @@ Fields Payload maintains (id, _status, createdAt, updatedAt) are never listed an
 		paths: z.array(z.string()).optional().describe("Schema paths to describe, e.g. \"/layout/sections/sectionWrapper\". Omit for the collection root."),
 		expand: z.boolean().optional().describe("Return every node reachable from the root in one response. Ignores paths.")
 	}),
-	handler: (args, scope) => {
+	handler: ({ args, scope }) => {
 		const ref = refOf(resolveTarget(scope, args, "read"));
 		const { config } = scope.req.payload;
 		const describeNode = nodeDescriber(translatorFor(scope.req.i18n));
@@ -49,6 +50,6 @@ Fields Payload maintains (id, _status, createdAt, updatedAt) are never listed an
 		if (expanded?.truncated) nodes.push({ error: `Result truncated after ${String(400)} nodes. Request explicit paths instead.` });
 		return Promise.resolve(jsonResult(nodes));
 	}
-};
+});
 //#endregion
 export { describeSchema };

package/dist/tools/find-documents.mjs

@@ -1,9 +1,10 @@
 import { jsonResult } from "../endpoint/result.mjs";
 import { depthShape, localeOf, localeShape, slugEnum } from "./shared.mjs";
 import { resolveTarget } from "./target.mjs";
+import { defineMcpxTool } from "../types.mjs";
 import { z } from "zod";
 //#region src/tools/find-documents.ts
-const findDocuments = {
+const findDocuments = defineMcpxTool({
 	name: "findDocuments",
 	description: `Finds documents in a collection. "where" is a Payload query object, e.g. {"title":{"contains":"home"}} or {"and":[...]}; "select" picks fields, e.g. {"title":true}. Drafts are included by default so unpublished work is visible. Keep depth at 0 unless populated relationships are needed; ids are enough for writes.`,
 	annotations: {
@@ -15,7 +16,7 @@ const findDocuments = {
 		collection: slugEnum(scope.readable).describe("Collection to search."),
 		where: z.record(z.string(), z.unknown()).optional().describe("Payload where query."),
 		sort: z.string().optional().describe("Sort field, prefix with \"-\" for descending."),
-		limit: z.number().int().min(1).max(scope.options.limits.maxLimit).optional().describe(`Documents per page. Default 10, at most ${String(scope.options.limits.maxLimit)}.`),
+		limit: z.number().int().min(1).max(scope.limits.maxLimit).optional().describe(`Documents per page. Default 10, at most ${String(scope.limits.maxLimit)}.`),
 		page: z.number().int().min(1).optional().describe("Page number, from 1."),
 		...depthShape(scope),
 		select: z.record(z.string(), z.unknown()).optional().describe("Fields to return, e.g. {\"title\":true}."),
@@ -25,7 +26,7 @@ const findDocuments = {
 		}),
 		draft: z.boolean().optional().describe("Include the latest drafts. Default true.")
 	}),
-	handler: async (args, scope) => {
+	handler: async ({ args, scope }) => {
 		resolveTarget(scope, { collection: args.collection }, "read");
 		const locale = localeOf(scope, args.locale);
 		const result = await scope.req.payload.find({
@@ -50,6 +51,6 @@ const findDocuments = {
 			hasNextPage: result.hasNextPage
 		});
 	}
-};
+});
 //#endregion
 export { findDocuments };

package/dist/tools/get-document.mjs

@@ -2,10 +2,11 @@ import { JSON_POINTER_PATTERN } from "../schema/walk.mjs";
 import { errorResult, jsonResult } from "../endpoint/result.mjs";
 import { depthShape, idShape, localeOf, localeShape, targetShape } from "./shared.mjs";
 import { requireIdFor, resolveTarget } from "./target.mjs";
+import { defineMcpxTool } from "../types.mjs";
 import { z } from "zod";
 import { Pointer } from "rfc6902";
 //#region src/tools/get-document.ts
-const getDocument = {
+const getDocument = defineMcpxTool({
 	name: "getDocument",
 	description: `Reads one document, or one subtree of it when "path" is given as a JSON pointer such as "/layout/sections/2". Returns the latest draft by default. Read before patching: the response carries "updatedAt" for expectedUpdatedAt and the indices pointers need.
 
@@ -29,7 +30,7 @@ Pass exactly one of "collection" and "global". "id" is required with "collection
 		}),
 		draft: z.boolean().optional().describe("Return the latest draft. Default true.")
 	}),
-	handler: async (args, scope) => {
+	handler: async ({ args, scope }) => {
 		const target = resolveTarget(scope, args, "read");
 		const id = requireIdFor(target, args.id);
 		const locale = localeOf(scope, args.locale);
@@ -63,6 +64,6 @@ Pass exactly one of "collection" and "global". "id" is required with "collection
 			value
 		});
 	}
-};
+});
 //#endregion
 export { getDocument };

package/dist/tools/index.mjs

@@ -7,9 +7,12 @@ import { patchDocument } from "./patch-document.mjs";
 import { validateDocument } from "./validate-document.mjs";
 //#region src/tools/index.ts
 /**
-* The builtin tools in registration order. The surface is fixed: adding a
-* collection, block or field never changes it. Typed over `never` because
-* each tool validates its own arguments through its input schema.
+* The builtin tools in registration order. They are ordinary {@link McpxTool}s
+* that ship with the plugin and register through the same loop as the tools
+* from `options.tools`; only their `isEnabled` differs, deriving from the
+* key's collection and global capabilities rather than a checkbox of their
+* own. The surface is fixed: adding a collection, block or field never
+* changes it.
 */ const BUILTIN_TOOLS = [
 	listCapabilities,
 	describeSchema,

package/dist/tools/list-capabilities.mjs

@@ -1,9 +1,10 @@
 import { translatorFor } from "../i18n.mjs";
 import { jsonResult } from "../endpoint/result.mjs";
 import { translateLabel } from "./shared.mjs";
+import { defineMcpxTool } from "../types.mjs";
 import { hasDraftValidationEnabled } from "payload/shared";
 //#region src/tools/list-capabilities.ts
-const listCapabilities = {
+const listCapabilities = defineMcpxTool({
 	name: "listCapabilities",
 	description: `Lists what this key may do: the collections and globals it can read or write, their draft behaviour and id type, the configured locales, the limits in force and the custom tools available. Call it first to orient; nothing here changes with the content model.
 
@@ -14,10 +15,10 @@ A global is a singleton: it has no id, is not listed by findDocuments and cannot
 	},
 	isEnabled: () => true,
 	inputSchema: () => ({}),
-	handler: (_args, scope) => {
+	handler: ({ scope }) => {
 		const { payload } = scope.req;
 		const translate = translatorFor(scope.req.i18n);
-		const collections = scope.options.collections.flatMap((entry) => {
+		const collections = scope.exposure.collections.flatMap((entry) => {
 			const capability = scope.capabilities.collections[entry.slug];
 			const collection = payload.collections[entry.slug];
 			if (!capability || !collection || !(capability.read || capability.write)) return [];
@@ -37,7 +38,7 @@ A global is a singleton: it has no id, is not listed by findDocuments and cannot
 				idType: collection.customIDType ?? payload.db.defaultIDType
 			}];
 		});
-		const globals = scope.options.globals.flatMap((entry) => {
+		const globals = scope.exposure.globals.flatMap((entry) => {
 			const capability = scope.capabilities.globals[entry.slug];
 			const config = payload.globals.config.find((candidate) => candidate.slug === entry.slug);
 			if (!capability || !config || !(capability.read || capability.write)) return [];
@@ -59,10 +60,10 @@ A global is a singleton: it has no id, is not listed by findDocuments and cannot
 				codes: scope.locales,
 				default: scope.defaultLocale
 			} : null,
-			limits: scope.options.limits,
+			limits: scope.limits,
 			tools: Object.entries(scope.capabilities.tools).filter(([, enabled]) => enabled).map(([name]) => name)
 		}));
 	}
-};
+});
 //#endregion
 export { listCapabilities };

package/dist/tools/patch-document.mjs

@@ -1,6 +1,7 @@
 import { errorResult, jsonResult } from "../endpoint/result.mjs";
 import { idShape, localeOf, localeShape, readTarget, targetShape } from "./shared.mjs";
 import { refOf, requireIdFor, resolveTarget } from "./target.mjs";
+import { defineMcpxTool } from "../types.mjs";
 import { PATCH_OPERATION_SCHEMA, applyPatchToCopy, buildWriteData, findPatchProblems, isElementPointer } from "../write/patch.mjs";
 import { collectPublishBlockers } from "../write/publish-blockers.mjs";
 import { withTransaction } from "../write/transaction.mjs";
@@ -42,7 +43,7 @@ const isPlainObject = (value) => typeof value === "object" && value !== null &&
 	const actual = pointer.get(saved);
 	return survives(expected, actual) ? [] : [operation.path];
 });
-const patchDocument = {
+const patchDocument = defineMcpxTool({
 	name: "patchDocument",
 	description: DESCRIPTION,
 	annotations: {
@@ -65,11 +66,12 @@ const patchDocument = {
 		patches: z.array(PATCH_OPERATION_SCHEMA).min(1).describe("Operations, applied in order."),
 		expectedUpdatedAt: z.string().optional().describe("The updatedAt read before patching. The write is refused if the document has changed since.")
 	}),
-	handler: async (args, scope) => {
+	handler: async ({ args, scope }) => {
 		const target = resolveTarget(scope, args, "write");
 		const id = requireIdFor(target, args.id);
 		const { payload } = scope.req;
 		const locale = localeOf(scope, args.locale);
+		const patches = args.patches;
 		return await withTransaction(scope.req, async () => {
 			const doc = await readTarget(scope, {
 				target,
@@ -79,11 +81,11 @@ const patchDocument = {
 			if (args.expectedUpdatedAt !== void 0 && !sameInstant(doc["updatedAt"], args.expectedUpdatedAt)) return errorResult("The document changed since you read it. Read it again and re-apply the patch.", { updatedAt: doc["updatedAt"] });
 			const problems = findPatchProblems(payload.config, {
 				doc,
-				patches: args.patches,
+				patches,
 				ref: refOf(target)
 			});
 			if (problems.length > 0) return errorResult("No operation was applied.", { problems });
-			const applied = applyPatchToCopy(doc, args.patches);
+			const applied = applyPatchToCopy(doc, patches);
 			if ("problems" in applied) return errorResult("No operation was applied.", { problems: applied.problems });
 			const write = {
 				data: buildWriteData(payload.config, target.config, applied.next),
@@ -108,7 +110,7 @@ const patchDocument = {
 				locale,
 				privileged: true
 			});
-			const notApplied = notAppliedPointers(args.patches, applied.next, saved);
+			const notApplied = notAppliedPointers(patches, applied.next, saved);
 			const publishBlockers = await collectPublishBlockers(scope.req, {
 				doc: saved,
 				entity: target
@@ -122,6 +124,6 @@ const patchDocument = {
 			});
 		});
 	}
-};
+});
 //#endregion
 export { patchDocument };

package/dist/tools/shared.mjs

@@ -4,6 +4,11 @@ import { z } from "zod";
 //#region src/tools/shared.ts
 const slugEnum = (slugs) => z.enum(slugs);
 const idSchema = z.union([z.string(), z.number()]).describe("Document id.");
+/**
+* Widens one branch to the superset a handler sees. The widening itself is
+* unchecked — the runtime shape really does vary — so `Branch` checks what it
+* can around it.
+*/ const widen = (branch) => branch;
 const slugsFor = (scope, operation) => ({
 	collections: operation === "read" ? scope.readable : scope.writable,
 	globals: operation === "read" ? scope.readableGlobals : scope.writableGlobals
@@ -18,12 +23,12 @@ const slugsFor = (scope, operation) => ({
 * argument optional, and the handler enforces the exclusivity there.
 */ const targetShape = (scope, operation, descriptions) => {
 	const { collections, globals } = slugsFor(scope, operation);
-	if (globals.length === 0) return { collection: slugEnum(collections).describe(descriptions.collection) };
-	if (collections.length === 0) return { global: slugEnum(globals).describe(descriptions.global) };
-	return {
+	if (globals.length === 0) return widen({ collection: slugEnum(collections).describe(descriptions.collection) });
+	if (collections.length === 0) return widen({ global: slugEnum(globals).describe(descriptions.global) });
+	return widen({
 		collection: slugEnum(collections).optional().describe(descriptions.collection),
 		global: slugEnum(globals).optional().describe(descriptions.global)
-	};
+	});
 };
 /**
 * The `id` argument, which only a collection document has. Omitted when the key
@@ -31,18 +36,18 @@ const slugsFor = (scope, operation) => ({
 * in between, where `requireIdFor` enforces the dependency.
 */ const idShape = (scope, operation) => {
 	const { collections, globals } = slugsFor(scope, operation);
-	if (collections.length === 0) return {};
-	if (globals.length === 0) return { id: idSchema };
-	return { id: idSchema.optional().describe("Document id. Required with \"collection\"; must be omitted with \"global\".") };
+	if (collections.length === 0) return widen({});
+	if (globals.length === 0) return widen({ id: idSchema });
+	return widen({ id: idSchema.optional().describe("Document id. Required with \"collection\"; must be omitted with \"global\".") });
 };
 /**
 * The `locale` argument, present only when localization is configured.
 */ const localeShape = (scope, options) => {
-	if (!scope.locales) return {};
+	if (!scope.locales) return widen({});
 	const locale = z.enum(scope.locales);
-	return { locale: (options.required ? locale : locale.optional()).describe(options.description) };
+	return widen({ locale: (options.required ? locale : locale.optional()).describe(options.description) });
 };
-const depthShape = (scope) => ({ depth: z.number().int().min(0).max(scope.options.limits.maxDepth).optional().describe(`Relationship population depth. Default 0, at most ${String(scope.options.limits.maxDepth)}.`) });
+const depthShape = (scope) => ({ depth: z.number().int().min(0).max(scope.limits.maxDepth).optional().describe(`Relationship population depth. Default 0, at most ${String(scope.limits.maxDepth)}.`) });
 /**
 * The locale to operate on: the explicit argument, else the request's, else
 * the default. `undefined` when localization is off.

package/dist/tools/target.d.mts

@@ -1,3 +1,3 @@
-import "./types.mjs";
+import "../types.mjs";
 import "../schema/walk.mjs";
 import "payload";

package/dist/tools/validate-document.mjs

@@ -1,9 +1,10 @@
 import { jsonResult } from "../endpoint/result.mjs";
 import { idShape, localeOf, localeShape, readTarget, targetShape } from "./shared.mjs";
 import { requireIdFor, resolveTarget } from "./target.mjs";
+import { defineMcpxTool } from "../types.mjs";
 import { collectPublishBlockers } from "../write/publish-blockers.mjs";
 //#region src/tools/validate-document.ts
-const validateDocument = {
+const validateDocument = defineMcpxTool({
 	name: "validateDocument",
 	description: `Reports what still prevents a human from publishing the draft, without writing anything. The same list patchDocument returns after a write; use it to check work or to answer "is this ready".
 
@@ -24,7 +25,7 @@ Pass exactly one of "collection" and "global". "id" is required with "collection
 			description: "Locale to validate."
 		})
 	}),
-	handler: async (args, scope) => {
+	handler: async ({ args, scope }) => {
 		const target = resolveTarget(scope, args, "write");
 		const id = requireIdFor(target, args.id);
 		const locale = localeOf(scope, args.locale);
@@ -50,6 +51,6 @@ Pass exactly one of "collection" and "global". "id" is required with "collection
 			publishBlockers
 		});
 	}
-};
+});
 //#endregion
 export { validateDocument };

package/dist/types.d.mts

@@ -1,7 +1,7 @@
 import { CollectionConfig, CollectionSlug, GlobalSlug, PayloadRequest, TypedUser } from "payload";
 import { z } from "zod";
-import { RequestHandlerExtra } from "@modelcontextprotocol/sdk/shared/protocol.js";
 import { CallToolResult, ServerNotification, ServerRequest, ToolAnnotations } from "@modelcontextprotocol/sdk/types.js";
+import { RequestHandlerExtra } from "@modelcontextprotocol/sdk/shared/protocol.js";
 //#region src/types.d.ts
 declare module "payload" {
   interface RequestContext {
@@ -53,26 +53,110 @@ interface McpxGlobalOptions {
 }
 type McpxToolExtra = RequestHandlerExtra<ServerRequest, ServerNotification>;
 /**
- * A custom tool. It is gated by its own checkbox on every API key and runs
- * with `req.user` resolved from the key and `req.context.mcpx` set.
+ * A collection or global the plugin config exposes, before an API key's
+ * checkboxes narrow it further.
+ */
+interface McpxExposedEntity {
+  slug: string;
+  read: boolean;
+  write: boolean;
+  allowLiveWrites: boolean;
+  hasDrafts: boolean;
+  /** Name of the capability group on the key document. */
+  fieldName: string;
+}
+/**
+ * Everything a tool knows about the current request: the authenticated
+ * request, what this key may touch and the limits in force.
+ */
+interface McpxToolScope {
+  req: PayloadRequest;
+  capabilities: McpxResolvedCapabilities;
+  /** Collection slugs the key may read / write. */
+  readable: string[];
+  writable: string[];
+  /** Global slugs the key may read / write. */
+  readableGlobals: string[];
+  writableGlobals: string[];
+  /** Configured locale codes, or `null` when localization is off. */
+  locales: null | string[];
+  defaultLocale: null | string;
+  limits: {
+    maxLimit: number;
+    maxDepth: number;
+  };
+  /** What the plugin config exposes, before the key's checkboxes apply. */
+  exposure: {
+    collections: McpxExposedEntity[];
+    globals: McpxExposedEntity[];
+  };
+}
+/**
+ * A tool. The builtins and any tool passed through `options.tools` use this
+ * same shape and register through the same loop. Every tool runs with
+ * `req.user` resolved from the key and `req.context.mcpx` set.
+ *
+ * `Args` only needs stating when `inputSchema` is built per request, which
+ * leaves no static shape to infer from; a tool with a fixed shape gets its
+ * argument type from that shape.
  */
-interface McpxTool<Shape extends z.ZodRawShape = z.ZodRawShape> {
+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;
   description: string;
-  inputSchema?: Shape;
   annotations?: ToolAnnotations;
+  /**
+   * Whether this key may call the tool; a tool that is not enabled never
+   * appears in `tools/list`. Defaults to the tool's own checkbox on the API
+   * key, which the builtins replace to derive availability from the key's
+   * collection and global capabilities. Defining it replaces that checkbox
+   * check rather than adding to it.
+   */
+  isEnabled?: (scope: McpxToolScope) => boolean;
+  /**
+   * A fixed shape, or one built per request so enums can be narrowed to what
+   * the key may touch. Registered strictly either way: an unknown argument is
+   * rejected by name instead of being stripped and the tool answering as if
+   * it had not been passed.
+   */
+  inputSchema?: Shape | ((scope: McpxToolScope) => z.ZodRawShape);
   handler(ctx: {
-    args: z.infer<z.ZodObject<Shape>>;
+    args: Args;
+    scope: McpxToolScope;
+    /** Shorthand for `scope.req`. */
     req: PayloadRequest;
     extra: McpxToolExtra;
   }): CallToolResult | Promise<CallToolResult>;
 }
 /**
- * Identity helper that infers the argument type of a custom tool's handler
- * from its input schema.
+ * A tool with its argument type erased, which is how a registry holds tools of
+ * differing input shapes. Each tool validates its own arguments through its
+ * input schema.
+ */
+type McpxAnyTool = McpxTool<z.ZodRawShape, never>;
+/**
+ * Defines a tool with a fixed input shape. The handler's arguments are
+ * inferred from that shape.
+ */
+declare function defineMcpxTool<Shape extends z.ZodRawShape>(tool: McpxTool<Shape> & {
+  inputSchema?: Shape;
+}): McpxTool<Shape>;
+/**
+ * Defines a tool whose input shape is built per request and returned as an
+ * object literal. The handler's arguments are inferred from that literal, so
+ * a scope-narrowed enum still types as the value it produces.
+ */
+declare function defineMcpxTool<Shape extends z.ZodRawShape>(tool: McpxTool<Shape> & {
+  inputSchema: (scope: McpxToolScope) => Shape;
+}): McpxAnyTool;
+/**
+ * Defines a tool whose input shape is assembled from helpers that erase to
+ * `z.ZodRawShape`, as the builtins do. Nothing is left to infer from, so the
+ * handler's arguments are stated instead: `defineMcpxTool<Args>({ ... })`.
  */
-declare const defineMcpxTool: <Shape extends z.ZodRawShape>(tool: McpxTool<Shape>) => McpxTool<Shape>;
+declare function defineMcpxTool<Args>(tool: McpxTool<z.ZodRawShape, Args> & {
+  inputSchema: (scope: McpxToolScope) => z.ZodRawShape;
+}): McpxAnyTool;
 /**
  * Outcome of resolving an API key. `user` must carry `collection`.
  */
@@ -110,7 +194,7 @@ type McpxPluginOptions = {
     /** Upper bound for `depth` on reads. Default 1. */
     maxDepth?: number;
   };
-  tools?: McpxTool[];
+  tools?: McpxAnyTool[];
   auth?: {
     /** Replace or wrap the default key resolution. Return `null` for 401. */
     resolve?: (args: {
@@ -140,4 +224,4 @@ interface McpxRequestContext {
   capabilities: McpxResolvedCapabilities;
 }
 //#endregion
-export { McpxAuthResult, McpxCollectionCapabilities, McpxCollectionOptions, McpxGlobalOptions, McpxPluginOptions, McpxRequestContext, McpxResolvedCapabilities, McpxTool, McpxToolExtra, defineMcpxTool };
+export { McpxAnyTool, McpxAuthResult, McpxCollectionCapabilities, McpxCollectionOptions, McpxExposedEntity, McpxGlobalOptions, McpxPluginOptions, McpxRequestContext, McpxResolvedCapabilities, McpxTool, McpxToolExtra, McpxToolScope, defineMcpxTool };

package/dist/types.mjs

@@ -1,7 +1,6 @@
 //#region src/types.ts
-/**
-* Identity helper that infers the argument type of a custom tool's handler
-* from its input schema.
-*/ const defineMcpxTool = (tool) => tool;
+function defineMcpxTool(tool) {
+	return tool;
+}
 //#endregion
 export { defineMcpxTool };

package/package.json

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

package/dist/options.d.mts

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

package/dist/tools/types.d.mts

@@ -1,5 +0,0 @@
-import "../types.mjs";
-import "../options.mjs";
-import { PayloadRequest } from "payload";
-import { z } from "zod";
-import { CallToolResult, ToolAnnotations } from "@modelcontextprotocol/sdk/types.js";