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

package/README.md

@@ -13,8 +13,9 @@ resolved server-side against the real config and the real document, so unknown
 fields, misplaced blocks and unusable rich text nodes or node fields are refused with the
 valid alternatives listed, never silently dropped.
 
-Writes are RFC 6902 patches that always land as drafts; publishing stays a
-human action in the admin panel. Every write returns the publish
+Writes are RFC 6902 patches that land as drafts, with `allowLiveWrites` as the
+one documented exception; publishing stays a human action in the admin panel.
+Every write returns the publish
 blockers: the validation failures that still prevent a human from publishing
 the draft. Capabilities are declared twice: the plugin config decides what
 can exist, a checkbox on each API key decides what does, and a missing checkbox
@@ -153,7 +154,7 @@ only the slugs the key may touch.
 | `getDocument`      | Read one document or a subtree of it.                       | `collection` + `id` \| `global`, `path?` (JSON pointer), `depth?`, `locale?`, `draft?`       |
 | `patchDocument`    | Apply RFC 6902 operations to the current draft.             | `collection` + `id` \| `global`, `locale`, `patches`, `expectedUpdatedAt?`                   |
 | `createDocument`   | Create a draft from a minimal seed.                         | `collection`, `locale`, `data`                                                               |
-| `validateDocument` | Publish blockers without writing.                           | `collection` + `id` \| `global`, `locale`                                                    |
+| `validateDocument` | Publish blockers without saving anything.                   | `collection` + `id` \| `global`, `locale`                                                    |
 
 Rules the tools enforce and explain in their own descriptions:
 
@@ -266,6 +267,12 @@ Collections with `versions.drafts.validate: true` refuse invalid drafts
 outright; those failures come back as `validationErrors`. Both carry pointers,
 restated from the dotted paths Payload reports internally.
 
+`publishBlockersUnavailable` marks a check that could not complete, which is
+not the same answer as a document with nothing wrong with it. `validateDocument`
+runs the same traversal without saving anything, so it is not free of side
+effects: field `beforeValidate` and `beforeChange` hooks run, and it carries no
+`readOnlyHint` for that reason.
+
 Writes also report `notApplied`: pointers whose value Payload kept unchanged,
 which happens when field-level access denies the update.
 
@@ -297,9 +304,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,10 +380,15 @@ 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.                                                                                           |
 
+`allowLiveWrites` is the only way an MCP write reaches live content. Where it is
+set, the server instructions and the `patchDocument` and `createDocument`
+descriptions name those slugs for the key in question, so a client is never told
+its writes are drafts while they are not.
+
 Misconfiguration (unknown slugs, write on a collection without drafts, upload
 collections exposed for write, tool name collisions) fails at startup with
 `InvalidConfiguration`. Auth collections cannot be exposed at all, read

package/dist/api-keys/fields.mjs

@@ -107,7 +107,7 @@ const SETUP_GUIDE_FIELD = "setupGuide";
 		label: global.slug,
 		fields: [...global.read ? [checkbox("read", "Describe and read this global.")] : [], ...global.write ? [checkbox("write", "Patch and validate this global's draft.")] : []]
 	}));
-	const toolCheckboxes = options.tools.map((tool) => checkbox(tool.name, tool.description));
+	const toolCheckboxes = options.tools.map((tool) => checkbox(tool.name, typeof tool.description === "string" ? tool.description : tool.name));
 	const groups = [
 		...collectionGroups.length > 0 ? [{
 			name: "collections",

package/dist/endpoint/{result.mjs → errors.mjs}

@@ -1,6 +1,8 @@
+import { errorResult } from "../result.mjs";
 import { pointerFromPayloadPath } from "../schema/walk.mjs";
+import "../schema/index.mjs";
 import { APIError, ValidationError } from "payload";
-//#region src/endpoint/result.ts
+//#region src/endpoint/errors.ts
 /**
 * A JSON-RPC error response for failures that happen before the MCP server
 * is involved (auth, method, body parsing).
@@ -20,25 +22,6 @@ import { APIError, ValidationError } from "payload";
 	});
 };
 /**
-* A successful tool result carrying `value` as JSON text.
-*/ const jsonResult = (value) => ({ content: [{
-	type: "text",
-	text: JSON.stringify(value)
-}] });
-/**
-* A failed tool result. `extras` travel alongside the message so the client
-* can act on them (problems, validation errors, the current `updatedAt`).
-*/ const errorResult = (message, extras = {}) => ({
-	content: [{
-		type: "text",
-		text: JSON.stringify({
-			error: message,
-			...extras
-		})
-	}],
-	isError: true
-});
-/**
 * Maps an exception thrown by a tool to a result the client can read.
 *
 * Payload's public errors keep their message and status; a `ValidationError`
@@ -62,4 +45,4 @@ import { APIError, ValidationError } from "payload";
 	return errorResult("Internal error");
 };
 //#endregion
-export { errorResult, jsonResult, jsonRpcError, toToolError };
+export { jsonRpcError, toToolError };

package/dist/endpoint/handler.mjs

@@ -1,6 +1,6 @@
 import { readableGlobalSlugs, readableSlugs, resolveCapabilities, writableGlobalSlugs, writableSlugs } from "../capabilities.mjs";
+import { jsonRpcError } from "./errors.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/index.mjs

@@ -0,0 +1,4 @@
+import { jsonRpcError, toToolError } from "./errors.mjs";
+import { createMcpServer, isToolEnabled, toolDescription, toolInputSchema } from "./server.mjs";
+import { createMcpxHandler, methodNotAllowed } from "./handler.mjs";
+export { createMcpServer, createMcpxHandler, isToolEnabled, jsonRpcError, methodNotAllowed, toToolError, toolDescription, toolInputSchema };

package/dist/endpoint/server.mjs

@@ -1,24 +1,37 @@
-import { toToolError } from "./result.mjs";
-import { BUILTIN_TOOLS } from "../tools/index.mjs";
+import { toToolError } from "./errors.mjs";
+import { draftSentence } from "../tools/shared.mjs";
+import { BUILTIN_TOOLS } from "../tools/builtin.mjs";
 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;
+* A tool's description, which may be built from the scope so it can name the
+* targets this key writes live.
+*/ const toolDescription = (tool, scope) => typeof tool.description === "function" ? tool.description(scope) : tool.description;
+/**
+* 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,
 		version: options.serverInfo.version
-	}, { instructions: "Start with listCapabilities, then describeSchema for the collection or global you work on. Writes always land as drafts; a human publishes." });
+	}, { instructions: `Start with listCapabilities, then describeSchema for the collection or global you work on. ${draftSentence(scope)}` });
 	const guarded = (run) => async () => {
 		try {
 			return await run();
@@ -26,22 +39,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 ?? {},
+			description: toolDescription(tool, scope),
+			inputSchema: toolInputSchema(tool, scope),
 			...tool.annotations ? { annotations: tool.annotations } : {}
 		}, (args, extra) => guarded(() => tool.handler({
 			args,
+			scope,
 			req,
 			extra
 		}))());
@@ -49,4 +55,4 @@ import { z } from "zod";
 	return server;
 };
 //#endregion
-export { builtinInputSchema, createMcpServer };
+export { createMcpServer, isToolEnabled, toolDescription, toolInputSchema };

package/dist/index.d.mts

@@ -1,5 +1,5 @@
-import { McpxAuthResult, McpxCollectionCapabilities, McpxCollectionOptions, McpxGlobalOptions, McpxPluginOptions, McpxRequestContext, McpxResolvedCapabilities, McpxTool, McpxToolExtra, defineMcpxTool } from "./types.mjs";
+import { McpxAnyTool, McpxAuthResult, McpxCollectionCapabilities, McpxCollectionOptions, McpxExposedEntity, McpxGlobalOptions, McpxPluginOptions, McpxRequestContext, McpxResolvedCapabilities, McpxTool, McpxToolExtra, McpxToolScope, PublishBlocker, 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 };
+import { isMcpxRequest } from "./request.mjs";
+import { errorResult, jsonResult } from "./result.mjs";
+export { McpxAnyTool, McpxAuthResult, McpxCollectionCapabilities, McpxCollectionOptions, McpxExposedEntity, McpxGlobalOptions, McpxPluginOptions, McpxRequestContext, McpxResolvedCapabilities, McpxTool, McpxToolExtra, McpxToolScope, PublishBlocker, defineMcpxTool, errorResult, isMcpxRequest, jsonResult, mcpxPlugin };

package/dist/index.mjs

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

package/dist/plugin.mjs

@@ -1,5 +1,6 @@
 import { createApiKeysCollection } from "./api-keys/collection.mjs";
 import { createMcpxHandler, methodNotAllowed } from "./endpoint/handler.mjs";
+import "./endpoint/index.mjs";
 import { normalizeOptions } from "./options.mjs";
 import { installDraftGuards, installGlobalDraftGuards } from "./write/draft-guard.mjs";
 import { definePlugin } from "payload";

package/dist/{write/draft-guard.d.mts → request.d.mts}

@@ -1,5 +1,5 @@
-import { CollectionConfig, PayloadRequest } from "payload";
-//#region src/write/draft-guard.d.ts
+import { PayloadRequest } from "payload";
+//#region src/request.d.ts
 /**
  * Whether a request originated from the MCP endpoint. The endpoint stamps
  * `req.context.mcpx`, which travels into every local API call made with the

package/dist/request.mjs

@@ -0,0 +1,8 @@
+//#region src/request.ts
+/**
+* Whether a request originated from the MCP endpoint. The endpoint stamps
+* `req.context.mcpx`, which travels into every local API call made with the
+* same `req`, including those made by custom tools.
+*/ const isMcpxRequest = (req) => req.context.mcpx !== void 0;
+//#endregion
+export { isMcpxRequest };

package/dist/result.d.mts

@@ -0,0 +1,13 @@
+import { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
+//#region src/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/result.mjs

@@ -0,0 +1,22 @@
+//#region src/result.ts
+/**
+* A successful tool result carrying `value` as JSON text.
+*/ const jsonResult = (value) => ({ content: [{
+	type: "text",
+	text: JSON.stringify(value)
+}] });
+/**
+* A failed tool result. `extras` travel alongside the message so the client
+* can act on them (problems, validation errors, the current `updatedAt`).
+*/ const errorResult = (message, extras = {}) => ({
+	content: [{
+		type: "text",
+		text: JSON.stringify({
+			error: message,
+			...extras
+		})
+	}],
+	isError: true
+});
+//#endregion
+export { errorResult, jsonResult };

package/dist/schema/index.mjs

@@ -0,0 +1,6 @@
+import { allowedNodeTypes, lexicalSubSchema, nodeOptions, subSchemaNodeTypes } from "./lexical.mjs";
+import { JSON_POINTER_PATTERN, RESERVED_FIELD_NAMES, blockOf, blockSlugsOf, describeAddressableFields, describeFields, findBlocksField, findRichTextField, joinPath, pointerFromPayloadPath, splitPath, targetOf } from "./walk.mjs";
+import { nodeDescriber, reachableSchemaPaths } from "./describe.mjs";
+import { resolveDataPointer } from "./pointer.mjs";
+import { validateWriteValue } from "./shape.mjs";
+export { JSON_POINTER_PATTERN, RESERVED_FIELD_NAMES, allowedNodeTypes, blockOf, blockSlugsOf, describeAddressableFields, describeFields, findBlocksField, findRichTextField, joinPath, lexicalSubSchema, nodeDescriber, nodeOptions, pointerFromPayloadPath, reachableSchemaPaths, resolveDataPointer, splitPath, subSchemaNodeTypes, targetOf, validateWriteValue };

package/dist/schema/pointer.mjs

@@ -43,7 +43,7 @@ const partMatches = (part, segment) => segment !== void 0 && (part === "*" ? isI
 			if (isSubtreePrefix(descriptors, segments)) return {
 				...blockType === void 0 ? {} : { blockType },
 				fields,
-				prefix: segments
+				prefix: segments.map((segment) => isIndexSegment(segment) ? "*" : segment)
 			};
 			throw new Error(`"${joinPath(segments)}" is not a field here. Available: ${descriptors.map((descriptor) => descriptor.path).join(", ")}`);
 		}

package/dist/schema/walk.mjs

@@ -83,7 +83,7 @@ const withRows = (descriptor, field) => ({
 * Whether a descriptor stands for a construct that only holds other fields.
 *
 * These describe a position rather than a value, so everything that resolves a
-* path to something writable skips them; only {@link describeNode} reports
+* path to something writable skips them; only {@link nodeDescriber} reports
 * them, to carry what the container itself declares.
 */ const isContainer = (descriptor) => descriptor.type === "array" || descriptor.type === "group" || descriptor.type === "tab";
 /**
@@ -133,29 +133,25 @@ const withRows = (descriptor, field) => ({
 /**
 * The descriptors that address a value, which is what every walk resolving a
 * path against a document needs. A container describes a position rather than
-* a value, so only {@link describeNode} reports one.
+* a value, so only {@link nodeDescriber} reports one.
 */ const describeAddressableFields = (fields) => describeFields(fields).filter((descriptor) => !isContainer(descriptor));
 /**
-* Locates the blocks field that a resolved descriptor path refers to.
-*/ const findBlocksField = (fields, path) => {
+* Locates the field of `type` that a resolved descriptor path refers to.
+*/ const findFieldAt = (fields, path, type) => {
 	for (const field of fields) {
 		if (!("name" in field) || field.name !== path[0]) continue;
-		if (field.type === "blocks" && path.length === 1) return field;
-		if (field.type === "tab" || field.type === "group") return findBlocksField(field.flattenedFields, path.slice(1));
-		if (field.type === "array" && path[1] === "*") return findBlocksField(field.flattenedFields, path.slice(2));
+		if (field.type === type && path.length === 1) return field;
+		if (field.type === "tab" || field.type === "group") return findFieldAt(field.flattenedFields, path.slice(1), type);
+		if (field.type === "array" && path[1] === "*") return findFieldAt(field.flattenedFields, path.slice(2), type);
 	}
 };
 /**
+* Locates the blocks field that a resolved descriptor path refers to.
+*/ const findBlocksField = (fields, path) => findFieldAt(fields, path, "blocks");
+/**
 * Locates the rich text field that a resolved descriptor path refers to, so
 * its editor can be introspected for the fields its nodes carry.
-*/ const findRichTextField = (fields, path) => {
-	for (const field of fields) {
-		if (!("name" in field) || field.name !== path[0]) continue;
-		if (field.type === "richText" && path.length === 1) return field;
-		if (field.type === "tab" || field.type === "group") return findRichTextField(field.flattenedFields, path.slice(1));
-		if (field.type === "array" && path[1] === "*") return findRichTextField(field.flattenedFields, path.slice(2));
-	}
-};
+*/ const findRichTextField = (fields, path) => findFieldAt(fields, path, "richText");
 const targetOf = (config, ref) => {
 	const found = ref.kind === "collection" ? config.collections.find((candidate) => candidate.slug === ref.slug) : config.globals.find((candidate) => candidate.slug === ref.slug);
 	if (!found) throw new Error(`Unknown ${ref.kind} "${ref.slug}".`);

package/dist/tools/{index.mjs → builtin.mjs}

@@ -5,11 +5,14 @@ import { getDocument } from "./get-document.mjs";
 import { listCapabilities } from "./list-capabilities.mjs";
 import { patchDocument } from "./patch-document.mjs";
 import { validateDocument } from "./validate-document.mjs";
-//#region src/tools/index.ts
+//#region src/tools/builtin.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/create-document.mjs

@@ -1,14 +1,19 @@
-import { errorResult, jsonResult } from "../endpoint/result.mjs";
-import { localeOf, localeShape, readTarget, slugEnum } from "./shared.mjs";
-import { resolveTarget } from "./target.mjs";
+import { errorResult, jsonResult } from "../result.mjs";
 import { validateWriteValue } from "../schema/shape.mjs";
+import "../schema/index.mjs";
+import { draftSentence, localeOf, localeShape, readTarget, slugEnum } from "./shared.mjs";
+import { resolveTarget } from "./target.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 DESCRIPTION = (scope) => `Creates a new document from a minimal seed. Only the fields describeSchema lists may appear in "data"; unknown keys are refused with the valid siblings, and "id" is Payload's to assign. The document may be incomplete: the response lists "publishBlockers", which patchDocument can then work through, and "publishBlockersUnavailable" when that check itself failed. Use this when no document exists yet; prefer patching an existing draft otherwise.
+
+${draftSentence(scope)}`;
+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.`,
+	description: DESCRIPTION,
 	annotations: {
 		readOnlyHint: false,
 		destructiveHint: false,
@@ -24,22 +29,22 @@ 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);
-		const { id: _ignored, ...seed } = args.data;
+		if ("id" in args.data) return errorResult("Nothing was created.", { problems: ["/id: Payload assigns the id; it cannot be supplied."] });
 		const problems = validateWriteValue(payload.config, {
 			pointer: "",
 			resolution: {
 				fields: target.config.flattenedFields,
 				prefix: []
 			}
-		}, seed);
+		}, args.data);
 		if (problems.length > 0) return errorResult("Nothing was created.", { problems });
 		const created = await payload.create({
 			collection: args.collection,
-			data: stripRowIds(seed),
+			data: stripRowIds(args.data),
 			depth: 0,
 			draft: true,
 			overrideAccess: false,
@@ -52,7 +57,7 @@ const createDocument = {
 			locale,
 			privileged: true
 		});
-		const publishBlockers = await collectPublishBlockers(scope.req, {
+		const validation = await collectPublishBlockers(scope.req, {
 			doc: saved,
 			entity: target
 		});
@@ -60,9 +65,10 @@ const createDocument = {
 			id: saved["id"],
 			status: saved["_status"],
 			updatedAt: saved["updatedAt"],
-			...publishBlockers.length > 0 ? { publishBlockers } : {}
+			...validation.blockers.length > 0 ? { publishBlockers: validation.blockers } : {},
+			...validation.unavailable ? { publishBlockersUnavailable: true } : {}
 		});
 	}
-};
+});
 //#endregion
 export { createDocument };

package/dist/tools/describe-schema.mjs

@@ -1,11 +1,12 @@
+import { jsonResult } from "../result.mjs";
 import { translatorFor } from "../i18n.mjs";
-import { jsonResult } from "../endpoint/result.mjs";
+import { nodeDescriber, reachableSchemaPaths } from "../schema/describe.mjs";
+import "../schema/index.mjs";
 import { targetShape } from "./shared.mjs";
 import { refOf, resolveTarget } from "./target.mjs";
-import { nodeDescriber, reachableSchemaPaths } from "../schema/describe.mjs";
+import { defineMcpxTool } from "../types.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,9 @@
-import { jsonResult } from "../endpoint/result.mjs";
+import { jsonResult } from "../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 +15,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 +25,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 +50,6 @@ const findDocuments = {
 			hasNextPage: result.hasNextPage
 		});
 	}
-};
+});
 //#endregion
 export { findDocuments };