@abinnovision/payloadcms-mcpx 1.0.0-beta.13 → 1.0.0-beta.14

package/dist/endpoint/server.mjs

@@ -4,27 +4,13 @@ import { BUILTIN_TOOLS } from "../tools/builtin.mjs";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { z } from "zod";
 //#region src/endpoint/server.ts
+/** Strict, so an unknown argument is rejected by name rather than stripped. */ const toolInputSchema = (tool, scope) => z.strictObject(typeof tool.inputSchema === "function" ? tool.inputSchema(scope) : tool.inputSchema ?? {});
+/** May be built from the scope, to name the targets this key writes live. */ const toolDescription = (tool, scope) => typeof tool.description === "function" ? tool.description(scope) : tool.description;
+/** A tool that does not decide for itself is gated by its own checkbox. */ const isToolEnabled = (tool, scope) => tool.isEnabled ? tool.isEnabled(scope) : scope.capabilities.tools[tool.name] === true;
 /**
-* 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 ?? {});
-/**
-* 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.
+* One server per request. Builtin and configured tools take the same route,
+* each registered against the key's capabilities, so `tools/list` shows exactly
+* what the key may call.
 */ const createMcpServer = (scope, options) => {
 	const { req } = scope;
 	const { logger } = req.payload;

package/dist/i18n.mjs

@@ -1,11 +1,6 @@
 //#region src/i18n.ts
-/**
-* A locale-keyed record, once it is known to hold nothing but strings.
-*/ const stringRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value) && Object.values(value).every((entry) => typeof entry === "string") ? value : void 0;
-/**
-* Picks the entry a language addresses, treating an empty value as absent so
-* the chain continues rather than yielding a useless string.
-*/ const pick = (record, language) => {
+const stringRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value) && Object.values(value).every((entry) => typeof entry === "string") ? value : void 0;
+/** Treats an empty value as absent, so the fallback chain continues. */ const pick = (record, language) => {
 	for (const code of Array.isArray(language) ? language : [language]) {
 		const entry = record[code];
 		if (entry !== void 0 && entry.trim() !== "") return entry;
@@ -25,14 +20,8 @@
 	if (!record) return;
 	return pick(record, language.language) ?? pick(record, language.fallbackLanguage) ?? Object.values(record).find((entry) => entry.trim() !== "");
 };
-/**
-* Binds {@link translateStatic} to a request's language, so a walk that
-* resolves many descriptions carries no request of its own.
-*/ const translatorFor = (i18n) => (value) => translateStatic(value, i18n);
-/**
-* Translator for callers with no request in hand. Both language keys miss, so
-* the chain degrades to the record's first entry.
-*/ const translateAny = translatorFor({
+/** Bound to one request's language, so a walk carries no request of its own. */ const translatorFor = (i18n) => (value) => translateStatic(value, i18n);
+/** For callers with no request: both keys miss, so the first entry wins. */ const translateAny = translatorFor({
 	fallbackLanguage: "",
 	language: ""
 });

package/dist/options.mjs

@@ -11,23 +11,16 @@ const TOOL_NAME_PATTERN = /^[a-zA-Z][a-zA-Z0-9]*$/;
 const fail = (message) => {
 	throw new InvalidConfiguration(`[payloadcms-mcpx] ${message}`);
 };
+/** The same transform the stock MCP plugin uses to derive field names. */ const toCamelCase = (value) => value.replace(/[-_\s]+(.)?/g, (_, char) => char ? char.toUpperCase() : "").replace(/^(.)/, (_, char) => char.toLowerCase());
 /**
-* Lower camel case of a slug, the same transform the stock MCP plugin applies
-* to derive field names from collection slugs.
-*/ const toCamelCase = (value) => value.replace(/[-_\s]+(.)?/g, (_, char) => char ? char.toUpperCase() : "").replace(/^(.)/, (_, char) => char.toLowerCase());
-/**
-* Refuses collections that must never be reachable through MCP, read included.
 * Auth collections carry credentials: `useAPIKey` stores a key that decrypts on
-* read, and email or lockout state is PII either way.
+* read, and email or lockout state is PII either way. Refused for read too.
 */ const assertExposable = (collection, apiKeysSlug) => {
 	const { slug } = collection;
 	if (slug === apiKeysSlug || slug.startsWith("payload-")) fail(`Collection "${slug}" cannot be exposed.`);
 	if (collection.auth) fail(`Auth collection "${slug}" cannot be exposed. Its documents carry credentials.`);
 };
-/**
-* The write mode, checked at runtime as well as in the type. JS callers get no
-* type checking, and a typo reading as "no write" would be a silent downgrade.
-*/ const normalizeWriteMode = (kind, slug, value) => {
+/** Checked at runtime too: for a JS caller a typo would silently mean "no write". */ const normalizeWriteMode = (kind, slug, value) => {
 	if (value === void 0 || value === false) return false;
 	if (value === "draft" || value === "live") return value;
 	return fail(`${kind} "${slug}" has write: ${JSON.stringify(value)}. Use false, "draft" or "live".`);
@@ -43,15 +36,11 @@ const fail = (message) => {
 };
 const assertWritable = (collection, options) => {
 	const { slug } = collection;
-	if (collection.upload) fail(`Upload collection "${slug}" cannot be exposed for write.`);
 	if (collection.timestamps === false) fail(`Collection "${slug}" has timestamps disabled, which write tools need for concurrency checks.`);
 	if (options.write === "draft" && !options.hasDrafts) fail(`Collection "${slug}" has no drafts. Enable versions.drafts or set write: "live".`);
 	if (options.write === "live") assertPublishable("Collection", collection);
 };
-/**
-* Refuses globals that must never be reachable. Globals cannot be auth or
-* upload entities, so only Payload's own reserved namespace is left to guard.
-*/ const assertGlobalExposable = (global) => {
+/** Globals cannot be auth or upload, so only the reserved namespace is left. */ const assertGlobalExposable = (global) => {
 	if (global.slug.startsWith("payload-")) fail(`Global "${global.slug}" cannot be exposed.`);
 };
 /**
@@ -77,6 +66,7 @@ const normalizeCollections = (config, options, apiKeysSlug) => {
 			read: settings.read ?? true,
 			write: normalizeWriteMode("Collection", slug, settings.write),
 			hasDrafts,
+			isUpload: Boolean(collection.upload),
 			fieldName: toCamelCase(slug)
 		};
 		if (normalized.write !== false) assertWritable(collection, normalized);
@@ -100,6 +90,7 @@ const normalizeGlobals = (config, options) => {
 			read: settings.read ?? true,
 			write: normalizeWriteMode("Global", slug, settings.write),
 			hasDrafts,
+			isUpload: false,
 			fieldName: toCamelCase(slug)
 		};
 		if (normalized.write !== false) assertGlobalWritable(global, normalized);
@@ -132,11 +123,7 @@ const normalizeLimits = (limits) => {
 		maxDepth
 	};
 };
-/**
-* Validates the plugin options against the incoming config and fills in
-* defaults. Every problem is an `InvalidConfiguration` so misconfiguration
-* fails at startup instead of at request time.
-*/ const normalizeOptions = (config, options) => {
+/** Every problem is an `InvalidConfiguration`, so it fails at startup. */ const normalizeOptions = (config, options) => {
 	const apiKeysSlug = options.apiKeys?.slug ?? DEFAULT_API_KEYS_SLUG;
 	const userCollection = options.userCollection ?? config.admin?.user ?? "users";
 	if ((config.collections ?? []).some((c) => c.slug === apiKeysSlug)) fail(`API key collection slug "${apiKeysSlug}" is already taken.`);

package/dist/result.d.mts

@@ -1,12 +1,10 @@
 import { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
 //#region src/result.d.ts
-/**
- * A successful tool result carrying `value` as JSON text.
- */
+/** `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`).
+ * `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

package/dist/result.mjs

@@ -1,13 +1,11 @@
 //#region src/result.ts
-/**
-* A successful tool result carrying `value` as JSON text.
-*/ const jsonResult = (value) => ({ content: [{
+/** `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`).
+* `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",

package/dist/schema/describe.mjs

@@ -2,13 +2,8 @@ import { lexicalSubSchema, subSchemaNodeTypes } from "./lexical.mjs";
 import { translateAny } from "../i18n.mjs";
 import { blockOf, blockSlugsOf, describeFields, findBlocksField, findRichTextField, joinPath, splitPath, targetOf } from "./walk.mjs";
 //#region src/schema/describe.ts
-/**
-* The longest descriptor path that is a prefix of `remaining`. Blocks and rich
-* text fields are both leaves of the walk, so at most one can match.
-*/ const longestMatch = (descriptors, remaining) => descriptors.map((descriptor) => splitPath(descriptor.path)).filter((parts) => parts.every((part, offset) => part === remaining[offset])).sort((left, right) => right.length - left.length)[0];
-/**
-* Walks one step of a schema path through a blocks field.
-*/ const stepThroughBlocks = ({ config, fields, match, remaining }) => {
+/** Blocks and rich text are both leaves of the walk, so at most one matches. */ const longestMatch = (descriptors, remaining) => descriptors.map((descriptor) => splitPath(descriptor.path)).filter((parts) => parts.every((part, offset) => part === remaining[offset])).sort((left, right) => right.length - left.length)[0];
+const stepThroughBlocks = ({ config, fields, match, remaining }) => {
 	const field = findBlocksField(fields, match);
 	if (!field) throw new Error(`"${joinPath(match)}" could not be resolved.`);
 	const slug = remaining.at(match.length);
@@ -22,8 +17,6 @@ import { blockOf, blockSlugsOf, describeFields, findBlocksField, findRichTextFie
 	};
 };
 /**
-* Walks one step of a schema path into a Lexical node's own fields.
-*
 * A node that picks a block by slug takes one segment more, so `/content/block`
 * addresses the choice and `/content/block/callout` the definition. Everything
 * else, a link node being the usual case, resolves in a single segment.
@@ -52,8 +45,6 @@ import { blockOf, blockSlugsOf, describeFields, findBlocksField, findRichTextFie
 	};
 };
 /**
-* Walks a schema path to the field list it addresses.
-*
 * A schema path alternates a blocks field's own path with the slug of one of
 * the blocks it accepts, so `/layout/sections/sectionWrapper/modules/hero`
 * reaches `hero` as it exists under `pages` specifically. The slug sits where
@@ -114,11 +105,8 @@ import { blockOf, blockSlugsOf, describeFields, findBlocksField, findRichTextFie
 	}));
 };
 /**
-* Describes a collection or global root, one block reached through a schema
-* path, or the fields a Lexical node carries.
-*
 * Curried on the translator that resolves each `admin.description`, so a
-* request binds its language once and the walk itself stays request-free.
+* request binds its language once and the walk stays request-free.
 */ const nodeDescriber = (translate = translateAny) => (config, ref, schemaPath = "") => {
 	const { blockType, fields } = fieldsAtSchemaPath(config, targetOf(config, ref), schemaPath);
 	const descriptors = describeFields(fields, translate);

package/dist/schema/lexical.mjs

@@ -1,8 +1,6 @@
 import { flattenAllFields } from "payload";
 //#region src/schema/lexical.ts
 /**
-* Node types Lexical registers itself.
-*
 * `editorConfig.features.nodes` lists only what a feature contributed, so a
 * field whose editor enables nothing but text formatting reports none at all.
 */ const LEXICAL_CORE_NODES = [
@@ -13,26 +11,17 @@ import { flattenAllFields } from "payload";
 	"tab"
 ];
 /**
-* Node types whose sub-fields exist but cannot be addressed by a schema path.
-*
-* Asked without a node, `upload` answers with every enabled collection's
-* upload fields concatenated, so the result describes no single position. It
-* would need addressing by `relationTo` to mean anything.
+* Sub-fields exist but cannot be addressed by a schema path. Asked without a
+* node, `upload` answers with every enabled collection's upload fields
+* concatenated, so the result describes no single position.
 */ const OPAQUE_NODE_TYPES = /* @__PURE__ */ new Set(["upload"]);
 /**
-* Sub-schemas per rich text field, keyed by node type. `null` records a node
-* type that was asked and has nothing to describe, so it is asked only once.
-*
-* Worth caching because the describe and validate paths resolve the same field
-* repeatedly, and because the block features build their answer from scratch on
-* every call. Keyed weakly on the sanitized field, which lives as long as the
-* config does.
+* `null` records a node type that was asked and has nothing to describe, so it
+* is asked only once. Worth caching because describe and validate resolve the
+* same field repeatedly and the block features rebuild their answer every call.
 */ const subSchemaCache = /* @__PURE__ */ new WeakMap();
 const featuresOf = (field) => field.editor?.editorConfig?.features;
-/**
-* Node types a rich text field accepts. Editors other than Lexical report
-* only the core nodes.
-*/ const allowedNodeTypes = (field) => {
+/** Editors other than Lexical report only the core nodes. */ const allowedNodeTypes = (field) => {
 	const registered = (featuresOf(field)?.nodes ?? []).flatMap((entry) => {
 		const type = entry.node?.getType?.();
 		return type ? [type] : [];
@@ -53,10 +42,7 @@ const resolveSubSchema = (field, nodeType) => {
 		kind: "fields"
 	};
 };
-/**
-* The sub-schema behind one node type of a rich text field, or `undefined`
-* when that node carries no addressable fields.
-*/ const lexicalSubSchema = (field, nodeType) => {
+const lexicalSubSchema = (field, nodeType) => {
 	let cached = subSchemaCache.get(field);
 	if (!cached) {
 		cached = /* @__PURE__ */ new Map();
@@ -65,13 +51,8 @@ const resolveSubSchema = (field, nodeType) => {
 	if (!cached.has(nodeType)) cached.set(nodeType, resolveSubSchema(field, nodeType));
 	return cached.get(nodeType) ?? void 0;
 };
+/** In the order their features registered them. */ const subSchemaNodeTypes = (field) => [...featuresOf(field)?.getSubFields?.keys() ?? []].filter((nodeType) => lexicalSubSchema(field, nodeType) !== void 0);
 /**
-* Node types of a rich text field that have a sub-schema, in the order their
-* features registered them.
-*/ const subSchemaNodeTypes = (field) => [...featuresOf(field)?.getSubFields?.keys() ?? []].filter((nodeType) => lexicalSubSchema(field, nodeType) !== void 0);
-/**
-* Node properties worth reporting and enforcing.
-*
 * Only properties a feature narrows and Lexical does not check on its own
 * belong here. Everything else a feature restricts is already visible: a
 * link's targets through its sub-schema, a block node's choices through the

package/dist/schema/pointer.mjs

@@ -9,10 +9,7 @@ const partMatches = (part, segment) => segment !== void 0 && (part === "*" ? isI
 	descriptor,
 	parts: splitPath(descriptor.path)
 })).filter(({ parts }) => parts.every((part, offset) => partMatches(part, segments[offset]))).sort((left, right) => right.consumed - left.consumed)[0];
-/**
-* Whether the segments stop part-way through some descriptor's path, which
-* means they address a subtree rather than a field.
-*/ const isSubtreePrefix = (descriptors, segments) => descriptors.some((descriptor) => {
+/** Stopping part-way through a descriptor's path means a subtree, not a field. */ const isSubtreePrefix = (descriptors, segments) => descriptors.some((descriptor) => {
 	const parts = splitPath(descriptor.path);
 	return parts.length > segments.length && segments.every((segment, offset) => {
 		const part = parts[offset];
@@ -20,15 +17,12 @@ const partMatches = (part, segment) => segment !== void 0 && (part === "*" ? isI
 	});
 });
 /**
-* Reads the value the given pointer segments address. Unlike a descriptor
-* path, the segments carry real indices, so intervening array fields are
-* descended through rather than skipped.
+* Unlike a descriptor path, the segments carry real indices, so intervening
+* array fields are descended through rather than skipped.
 */ const valueAtSegments = (data, segments) => segments.reduce((current, segment) => current === null || typeof current !== "object" ? void 0 : current[segment], data);
 /**
-* Resolves a JSON Pointer against the schema, using the stored document to
-* choose a branch at every blocks element.
-*
-* The document is required rather than optional: `/layout/sections/3/modules/1`
+* The stored document chooses the branch at every blocks element, and is
+* required rather than optional: `/layout/sections/3/modules/1`
 * can only be resolved by reading `blockType` off `sections[3]`, since a blocks
 * field admits many shapes at the same index.
 */ const resolveDataPointer = (config, target) => {

package/dist/schema/shape.mjs

@@ -1,20 +1,15 @@
 import { lexicalSubSchema } from "./lexical.mjs";
 import { blockOf, blockSlugsOf, describeAddressableFields, findBlocksField, findRichTextField, splitPath } from "./walk.mjs";
 //#region src/schema/shape.ts
-/**
-* Keys Payload manages on a row that a client may echo back harmlessly.
-*/ const TOLERATED_VALUE_KEYS = /* @__PURE__ */ new Set([
+const TOLERATED_VALUE_KEYS = /* @__PURE__ */ new Set([
 	"blockName",
 	"blockType",
 	"id"
 ]);
 const isPlainObject = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
 /**
-* Checks the fields a single Lexical node carries against the schema its
-* feature declares for that node type.
-*
-* A node with nothing to declare, and one whose sub-fields cannot be named at
-* a position, are both left alone.
+* A node with nothing to declare, and one whose sub-fields cannot be named at a
+* position, are both left alone.
 */ const checkNodeFields = (scope, field, node) => {
 	const sub = lexicalSubSchema(field, node.type);
 	if (!sub) return;
@@ -47,10 +42,7 @@ const isPlainObject = (value) => typeof value === "object" && value !== null &&
 	}, data);
 };
 /**
-* Checks an editor state against what the field's editor can actually
-* produce: every node type, and the fields each node carries.
-*
-* Payload does not: the Lexical validator runs node validations only for the
+* Payload does not check this: the Lexical validator runs node validations only for the
 * few node types that register one, so a `heading` inside a field whose
 * editor has no heading feature is stored without complaint and only fails
 * later, at render or when the document is reopened in the admin editor. A key
@@ -126,8 +118,7 @@ const checkLeafValue = (scope, descriptor, value) => {
 	});
 };
 /**
-* Walks an incoming value against the schema, reporting every shape problem
-* rather than the first.
+* Reports every shape problem rather than the first.
 *
 * Shape only: unknown field names, unknown block slugs, read-only fields, and
 * rich text nodes or node properties the field's editor cannot produce.

package/dist/schema/walk.mjs

@@ -2,50 +2,37 @@ import { allowedNodeTypes, nodeOptions } from "./lexical.mjs";
 import { translateAny } from "../i18n.mjs";
 import { fieldIsHiddenOrDisabled, fieldIsVirtual } from "payload/shared";
 //#region src/schema/walk.ts
-/**
-* Fields Payload maintains, which a client may neither address nor supply.
-*/ const RESERVED_FIELD_NAMES = /* @__PURE__ */ new Set([
+const RESERVED_FIELD_NAMES = /* @__PURE__ */ new Set([
 	"_status",
 	"createdAt",
 	"deletedAt",
 	"id",
 	"updatedAt"
 ]);
+const JSON_POINTER_PATTERN = /^(\/([^~/]|~[01])*)*$/;
+/** No segments is the root pointer, `""`. */ const joinPath = (parts) => parts.map((part) => `/${part.replace(/~/g, "~0").replace(/\//g, "~1")}`).join("");
+/** Unescapes `~1` and `~0`. The root pointer yields no segments. */ const splitPath = (path) => path.split("/").slice(1).map((segment) => segment.replace(/~1/g, "/").replace(/~0/g, "~"));
 /**
-* Shape a JSON Pointer must have to be parseable at all.
-*/ const JSON_POINTER_PATTERN = /^(\/([^~/]|~[01])*)*$/;
-/**
-* Joins segments into a JSON Pointer, so the segments `items`, `*`, `title`
-* read as one path to a subfield of every element of `items`. No segments is
-* the root pointer, `""`.
-*/ const joinPath = (parts) => parts.map((part) => `/${part.replace(/~/g, "~0").replace(/\//g, "~1")}`).join("");
-/**
-* Splits a JSON Pointer into its segments, unescaping `~1` and `~0`. The root
-* pointer yields no segments.
-*/ const splitPath = (path) => path.split("/").slice(1).map((segment) => segment.replace(/~1/g, "/").replace(/~0/g, "~"));
-/**
-* Restates a path Payload reports on a validation error (`layout.0.title`) as
-* a JSON Pointer, so everything this plugin hands back addresses documents the
-* same way. Payload's path already carries real indices, so it maps directly.
+* A path Payload reports on a validation error (`layout.0.title`) as a JSON
+* Pointer, so everything handed back addresses documents the same way. The
+* path already carries real indices, so it maps directly.
 */ const pointerFromPayloadPath = (path) => path ? joinPath(path.split(".")) : "";
+/** On a flattened field, whichever of `blockReferences` and `blocks` was declared. */ const blockSlugsOf = (field) => [...new Set((field.blockReferences ?? field.blocks).map((block) => typeof block === "string" ? block : block.slug))];
 /**
-* Blocks a blocks field accepts, by slug. On a flattened field, whichever of
-* `blockReferences` and `blocks` was declared carries the definitions.
-*/ const blockSlugsOf = (field) => [...new Set((field.blockReferences ?? field.blocks).map((block) => typeof block === "string" ? block : block.slug))];
-/**
-* Resolves one of a blocks field's slugs to its definition.
-*
-* A definition inlined on the field wins over the shared registry. A block's
-* own fields are identical wherever it appears, but the blocks its children
-* accept are not, so an inline definition has to be read at its position.
-* The registry (`config.blocks`) is the fallback for slugs referenced by name.
+* An inlined definition wins over the registry (`config.blocks`). A block's own
+* fields are identical wherever it appears, but the blocks its children accept
+* are not, so an inline definition has to be read at its position.
 */ const blockOf = (config, field, slug) => {
 	const declared = field.blockReferences ?? field.blocks;
 	const inline = declared.find((block) => typeof block !== "string" && block.slug === slug);
 	if (inline) return inline;
 	return declared.includes(slug) ? config.blocks?.find((block) => block.slug === slug) : void 0;
 };
-const isSkipped = (field) => !("name" in field) || field.type === "join" || RESERVED_FIELD_NAMES.has(field.name) || fieldIsVirtual(field) || fieldIsHiddenOrDisabled(field);
+/**
+* Payload's `fieldIsHiddenOrDisabled` reads `hidden` and `admin.disabled`, not
+* `admin.hidden`, which is what its own upload base fields carry.
+*/ const isAdminHidden = (field) => "admin" in field && field.admin.hidden === true;
+/** A field kept out of the admin panel is kept out of the MCP surface too. */ const isSkipped = (field) => !("name" in field) || field.type === "join" || RESERVED_FIELD_NAMES.has(field.name) || fieldIsVirtual(field) || isAdminHidden(field) || fieldIsHiddenOrDisabled(field);
 const isReadOnly = (field) => "admin" in field && field.admin.readOnly === true;
 const describeBase = (field, { path, readOnly, translate }) => {
 	const description = translate("admin" in field ? field.admin.description : void 0);
@@ -80,11 +67,9 @@ const withRows = (descriptor, field) => ({
 	...field.maxRows === void 0 ? {} : { maxRows: field.maxRows }
 });
 /**
-* 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 nodeDescriber} reports
-* them, to carry what the container itself declares.
+* A container describes a position rather than a value, so everything resolving
+* a path to something writable skips it. Only {@link nodeDescriber} reports one,
+* to carry what the container itself declares.
 */ const isContainer = (descriptor) => descriptor.type === "array" || descriptor.type === "group" || descriptor.type === "tab";
 /**
 * Whether a container declares anything a client could not infer from the
@@ -93,20 +78,16 @@ const withRows = (descriptor, field) => ({
 /**
 * Flattens a field list into descriptors addressed relative to the node.
 *
-* The input is Payload's own flattened shape, which has already merged every
-* construct that exists only in the admin UI (unnamed tabs, unnamed groups,
-* `row`, `collapsible`) and dropped `ui` fields. Named tabs, groups and
-* arrays contribute a path segment, and are described in their own right when
-* they declare something of their own: an array always, since its row counts
-* live nowhere else, a group or tab only when it carries a description or a
-* constraint. The walk stops at every blocks field and names the slugs instead
-* of descending, which keeps a node proportional to the number of blocks it
-* allows rather than to the size of their definitions.
+* The input is Payload's own flattened shape, so the admin-only constructs
+* (unnamed tabs and groups, `row`, `collapsible`, `ui`) are already gone. Named
+* tabs, groups and arrays contribute a path segment, and are described in their
+* own right when they declare something of their own: an array always, since
+* its row counts live nowhere else, a group or tab only when it carries a
+* description or a constraint. The walk stops at every blocks field and names
+* the slugs, which keeps a node proportional to the number of blocks it allows
+* rather than to the size of their definitions.
 *
-* `translate` resolves each `admin.description` to the request's language.
-* Callers that walk for paths alone leave it out and get the language-agnostic
-* default, so a missing argument costs language selection, never the
-* description itself.
+* Omitting `translate` costs language selection, never the description itself.
 */ const describeFields = (fields, translate = translateAny) => {
 	const walk = (current, prefix, parentReadOnly) => current.flatMap((field) => {
 		if (isSkipped(field)) return [];
@@ -135,9 +116,7 @@ const withRows = (descriptor, field) => ({
 * path against a document needs. A container describes a position rather than
 * a value, so only {@link nodeDescriber} reports one.
 */ const describeAddressableFields = (fields) => describeFields(fields).filter((descriptor) => !isContainer(descriptor));
-/**
-* Locates the field of `type` that a resolved descriptor path refers to.
-*/ const findFieldAt = (fields, path, type) => {
+const findFieldAt = (fields, path, type) => {
 	for (const field of fields) {
 		if (!("name" in field) || field.name !== path[0]) continue;
 		if (field.type === type && path.length === 1) return field;
@@ -145,14 +124,17 @@ const withRows = (descriptor, field) => ({
 		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");
+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) => findFieldAt(fields, path, "richText");
-const targetOf = (config, ref) => {
+/**
+* Looks up the sanitized config for a collection or global, as a
+* {@link SchemaTarget}. Throws on an unknown slug rather than returning
+* undefined, because a reference reaching here has already been checked against
+* the key's capabilities and a miss means the config changed underneath it.
+*/ 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}".`);
 	return found;

package/dist/tools/builtin.mjs

@@ -8,12 +8,10 @@ import { publishDocument } from "./publish-document.mjs";
 import { validateDocument } from "./validate-document.mjs";
 //#region src/tools/builtin.ts
 /**
-* 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.
+* The builtin tools, in registration order. Fixed: adding a collection, block
+* or field never changes the surface. They differ from a custom tool only in
+* `isEnabled`, which derives from the key's capabilities rather than a
+* checkbox of their own.
 */ const BUILTIN_TOOLS = [
 	listCapabilities,
 	describeSchema,

package/dist/tools/create-document.mjs

@@ -1,17 +1,30 @@
 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 { draftSentence, localeOf, localeShape, patchOnlySlugs, readTarget, slugEnum, slugsFor } 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
+/** Names the writable slugs this tool leaves out, so the gap reads as intent. */ const uploadSentence = (scope) => {
+	const slugs = patchOnlySlugs(scope);
+	return slugs.length === 0 ? "" : `\n\nLeft out of "collection" on purpose: ${slugs.join(", ")}. Those documents are files, and no tool here carries one. Upload the file in the admin panel, then edit its fields with patchDocument.`;
+};
 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({
+${draftSentence(scope)}${uploadSentence(scope)}`;
+/**
+* Collection-only, because a global always exists, and never reaches an upload
+* collection, because a create there would have to carry the file.
+*
+* The seed is checked against the collection's fields before the create, so an
+* unknown key is refused with its valid siblings rather than dropped. Row ids
+* in the seed are stripped and a top-level `id` is refused outright. The new
+* document is re-read privileged afterwards to collect publish blockers, which
+* is why an incomplete seed still succeeds and comes back with a checklist.
+*/ const createDocument = defineMcpxTool({
 	name: "createDocument",
 	description: DESCRIPTION,
 	annotations: {
@@ -20,9 +33,9 @@ const createDocument = defineMcpxTool({
 		idempotentHint: false,
 		openWorldHint: false
 	},
-	isEnabled: (scope) => scope.writable.length > 0,
+	isEnabled: (scope) => slugsFor(scope, "create").collections.length > 0,
 	inputSchema: (scope) => ({
-		collection: slugEnum(scope.writable).describe("Collection to create the document in."),
+		collection: slugEnum(slugsFor(scope, "create").collections).describe("Collection to create the document in."),
 		...localeShape(scope, {
 			required: true,
 			description: "Locale the localized fields of the seed belong to."
@@ -30,7 +43,7 @@ const createDocument = defineMcpxTool({
 		data: z.record(z.string(), z.unknown()).describe("Initial field values, as describeSchema lists them.")
 	}),
 	handler: async ({ args, scope }) => {
-		const target = resolveTarget(scope, { collection: args.collection }, "write");
+		const target = resolveTarget(scope, { collection: args.collection }, "create");
 		const { payload } = scope.req;
 		const locale = localeOf(scope, args.locale);
 		if ("id" in args.data) return errorResult("Nothing was created.", { problems: ["/id: Payload assigns the id; it cannot be supplied."] });

package/dist/tools/describe-schema.mjs

@@ -6,7 +6,13 @@ import { targetShape } from "./shared.mjs";
 import { refOf, resolveTarget } from "./target.mjs";
 import { defineMcpxTool } from "../types.mjs";
 import { z } from "zod";
-const describeSchema = defineMcpxTool({
+/**
+* Describes each requested path independently and returns a per
+* path error object instead of failing the call, so a client exploring several
+* branches at once keeps the nodes that did resolve. `expand` swaps the
+* requested paths for every node reachable from the root and appends a
+* truncation notice past {@link REACHABLE_PATHS_LIMIT}.
+*/ const describeSchema = defineMcpxTool({
 	name: "describeSchema",
 	description: `Describes the writable shape of a document, one node at a time.
 

package/dist/tools/find-documents.mjs

@@ -3,7 +3,14 @@ import { depthShape, localeOf, localeShape, slugEnum } from "./shared.mjs";
 import { resolveTarget } from "./target.mjs";
 import { defineMcpxTool } from "../types.mjs";
 import { z } from "zod";
-const findDocuments = defineMcpxTool({
+/**
+* Collection-only: a global is a singleton, so there is nothing to list.
+*
+* The query goes to Payload with `overrideAccess: false`, so the collection's
+* own access control decides what comes back. `limit` and `depth` are bounded
+* by the configured limits in the schema itself, which puts the ceiling in
+* front of the client rather than silently clamping behind it.
+*/ 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: {