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

package/dist/schema/shape.mjs

@@ -1,26 +1,27 @@
-import { lexicalSubSchema } from "./lexical.mjs";
-import { blockOf, blockSlugsOf, describeAddressableFields, findBlocksField, findRichTextField, splitPath } from "./walk.mjs";
+import { ROOT_PROPERTIES, constrainsFields, lexicalSubSchema, nodeProblems, propertyProblem, rootProblems } from "./lexical.mjs";
+import { blockOf, blockSlugsOf, describeAddressableFields, findBlocksField, findRichTextField, isPlainObject, 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.
+* Lexical refuses to hydrate a state whose root holds nothing: `isEmpty` is a
+* node map of one, and the editor throws on it rather than rendering nothing.
+* An empty field is stored as null instead, so this is only ever reached by
+* emptying one that was there.
+*/ const EMPTY_ROOT = "an editor state needs at least one node. Clear the field with null instead.";
+const quoted = (properties) => properties.map((property) => `"${property}"`).join(", ");
+/**
+* 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;
 	const data = node.fields;
 	if (!isPlainObject(data)) {
-		scope.problems.push(`${scope.pointer}: a "${node.type}" node carries a "fields" object.`);
+		if (!constrainsFields(node.type)) scope.problems.push(`${scope.pointer}: a "${node.type}" node carries a "fields" object.`);
 		return;
 	}
 	const nested = {
@@ -47,48 +48,126 @@ 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.
+* An absent property is already reported as missing. Anything else present is
+* checked, not just a string: Lexical stores a heading tag of 3 as readily as
+* one of "h3".
+*/ const checkNarrowedProperty = (scope, at, value) => {
+	if (value !== void 0 && !(typeof value === "string" && at.values.includes(value))) scope.problems.push(`${at.pointer}: ${JSON.stringify(value)} is not available for a "${at.type}" node in this field's editor. Allowed: ${at.values.join(", ")}`);
+};
+/**
+* One node, wherever it came from. `pointer` addresses the node itself, so a
+* node written at a position and a node written inside a whole editor state
+* are held to the same rules and report them the same way.
 *
-* Payload does not: 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
-* a node's fields do not declare is dropped just as silently. The same holds
-* one level down, for the node properties a feature narrows: an `h3` in an
-* editor restricted to `h4` is stored as readily as an `h4`.
-*/ const checkRichText = (scope, editor, value) => {
+* Payload does not check any of 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 a node's fields do not declare is dropped just as
+* silently. The same holds one level down, for the node properties a feature
+* narrows: an `h3` in an editor restricted to `h4` is stored as readily as an
+* `h4`, and a node written without the properties its class hydrates from is
+* stored and then throws when the editor opens it.
+*/ const checkNode = (scope, editor, node, pointer) => {
+	if (!isPlainObject(node) || typeof node["type"] !== "string") {
+		scope.problems.push(`${pointer}: every node needs a "type".`);
+		return;
+	}
+	const type = node["type"];
+	if (!editor.allowed.includes(type)) {
+		scope.problems.push(`${pointer}: "${type}" is not available in this field's editor. Allowed: ${editor.allowed.join(", ")}`);
+		return;
+	}
+	const problems = nodeProblems(node);
+	if (problems.missing.length > 0) scope.problems.push(`${pointer}: a "${type}" node is missing ${quoted(problems.missing)}. Write nodes as Lexical serializes them.`);
+	for (const problem of problems.rejected) scope.problems.push(`${pointer}/${problem.property}: a "${type}" node needs ${problem.needs} here.`);
+	for (const [property, values] of Object.entries(editor.nodeOptions?.[type] ?? {})) checkNarrowedProperty(scope, {
+		pointer: `${pointer}/${property}`,
+		type,
+		values
+	}, node[property]);
+	if (editor.field) checkNodeFields({
+		...scope,
+		pointer
+	}, editor.field, {
+		fields: node["fields"],
+		type
+	});
+	checkNodes(scope, editor, node["children"], `${pointer}/children`);
+};
+/** `pointer` addresses the list. A node holding none is left alone. */ const checkNodes = (scope, editor, nodes, pointer) => {
+	if (!Array.isArray(nodes)) return;
+	nodes.forEach((node, index) => {
+		checkNode(scope, editor, node, `${pointer}/${String(index)}`);
+	});
+};
+const checkRichText = (scope, editor, value) => {
 	if (!isPlainObject(value) || !isPlainObject(value["root"])) {
 		scope.problems.push(`${scope.pointer}: expected a Lexical editor state with a "root".`);
 		return;
 	}
-	const walk = (nodes, pointer) => {
-		if (!Array.isArray(nodes)) return;
-		nodes.forEach((node, index) => {
-			const at = `${pointer}/${String(index)}`;
-			if (!isPlainObject(node) || typeof node["type"] !== "string") {
-				scope.problems.push(`${at}: every node needs a "type".`);
-				return;
-			}
-			if (!editor.allowed.includes(node["type"])) {
-				scope.problems.push(`${at}: "${node["type"]}" is not available in this field's editor. Allowed: ${editor.allowed.join(", ")}`);
-				return;
-			}
-			for (const [property, values] of Object.entries(editor.nodeOptions?.[node["type"]] ?? {})) {
-				const value = node[property];
-				if (typeof value === "string" && !values.includes(value)) scope.problems.push(`${at}/${property}: "${value}" is not available for a "${node["type"]}" node in this field's editor. Allowed: ${values.join(", ")}`);
-			}
-			if (editor.field) checkNodeFields({
-				...scope,
-				pointer: at
-			}, editor.field, {
-				fields: node["fields"],
-				type: node["type"]
-			});
-			walk(node["children"], `${at}/children`);
-		});
+	const root = value["root"];
+	const { missing, rejected, unexpected } = rootProblems(root);
+	if (missing.length > 0) scope.problems.push(`${scope.pointer}/root: the root node is missing ${quoted(missing)}. Write nodes as Lexical serializes them.`);
+	for (const problem of rejected) scope.problems.push(`${scope.pointer}/root/${problem.property}: the root node needs ${problem.needs} here.`);
+	for (const property of unexpected) scope.problems.push(`${scope.pointer}/root/${property}: no such property on the root node. Available: ${Object.keys(ROOT_PROPERTIES).join(", ")}`);
+	if (Array.isArray(root["children"]) && root["children"].length === 0) scope.problems.push(`${scope.pointer}/root/children: ${EMPTY_ROOT}`);
+	checkNodes(scope, editor, root["children"], `${scope.pointer}/root/children`);
+};
+/**
+* `type` decides how every other property on a node is read, so replacing it
+* alone would leave a heading shaped like a text node. Everything else is held
+* to the constraint the node walk holds it to and nothing more, since a
+* feature may put any property on a node.
+*/ const checkNodeProperty = (scope, editor, position, value) => {
+	const { nodeType: type, property } = position;
+	if (property === "type") {
+		scope.problems.push(`${scope.pointer}: a node's "type" cannot be replaced on its own. Replace the whole node.`);
+		return;
+	}
+	if (position.isRoot && !(property in ROOT_PROPERTIES)) {
+		scope.problems.push(`${scope.pointer}: no such property on the root node. Available: ${Object.keys(ROOT_PROPERTIES).join(", ")}`);
+		return;
+	}
+	const problem = propertyProblem(type, property, value);
+	if (problem) scope.problems.push(`${scope.pointer}: a "${type}" node needs ${problem.needs} here.`);
+	const values = editor.nodeOptions?.[type]?.[property];
+	if (values) checkNarrowedProperty(scope, {
+		pointer: scope.pointer,
+		type,
+		values
+	}, value);
+};
+/**
+* A value written at a position inside an editor state rather than as the
+* whole state.
+*/ const checkLexicalWrite = (scope, position, value) => {
+	const editor = {
+		allowed: position.descriptor.nodes ?? [],
+		field: position.field,
+		nodeOptions: position.descriptor.nodeOptions
 	};
-	walk(value["root"]["children"], `${scope.pointer}/root/children`);
+	if (position.kind === "property") {
+		checkNodeProperty(scope, editor, position, value);
+		return;
+	}
+	if (position.kind === "nodes") {
+		if (!Array.isArray(value)) {
+			scope.problems.push(`${scope.pointer}: expected an array of nodes.`);
+			return;
+		}
+		if (position.isRoot && value.length === 0) {
+			scope.problems.push(`${scope.pointer}: ${EMPTY_ROOT}`);
+			return;
+		}
+		checkNodes(scope, editor, value, scope.pointer);
+		return;
+	}
+	if (position.isRoot) {
+		scope.problems.push(`${scope.pointer}: the root of an editor state cannot be replaced on its own. Write the whole field instead.`);
+		return;
+	}
+	checkNode(scope, editor, value, scope.pointer);
 };
 const checkLeafValue = (scope, descriptor, value) => {
 	if (descriptor.readOnly) {
@@ -126,8 +205,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.
@@ -197,6 +275,10 @@ const checkLeafValue = (scope, descriptor, value) => {
 		prefix: target.resolution.prefix,
 		problems
 	};
+	if (target.resolution.lexical) {
+		checkLexicalWrite(scope, target.resolution.lexical, value);
+		return problems;
+	}
 	if (target.resolution.descriptor) {
 		checkLeafValue(scope, target.resolution.descriptor, value);
 		return problems;
@@ -205,4 +287,4 @@ const checkLeafValue = (scope, descriptor, value) => {
 	return problems;
 };
 //#endregion
-export { validateWriteValue };
+export { EMPTY_ROOT, validateWriteValue };

package/dist/schema/walk.mjs

@@ -2,50 +2,39 @@ 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, "~"));
+/** `-` included, since RFC 6901 reads it as the position after the last. */ const isIndexSegment = (segment) => segment === "-" || /^\d+$/.test(segment);
+const isPlainObject = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
 /**
-* 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 +69,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 describeNode} 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 +80,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 [];
@@ -133,33 +116,30 @@ 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) => {
+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);
 	}
 };
+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 targetOf = (config, ref) => {
+*/ const findRichTextField = (fields, path) => findFieldAt(fields, path, "richText");
+/**
+* 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;
 };
 //#endregion
-export { JSON_POINTER_PATTERN, RESERVED_FIELD_NAMES, blockOf, blockSlugsOf, describeAddressableFields, describeFields, findBlocksField, findRichTextField, joinPath, pointerFromPayloadPath, splitPath, targetOf };
+export { JSON_POINTER_PATTERN, RESERVED_FIELD_NAMES, blockOf, blockSlugsOf, describeAddressableFields, describeFields, findBlocksField, findRichTextField, isIndexSegment, isPlainObject, joinPath, pointerFromPayloadPath, splitPath, targetOf };

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

@@ -4,12 +4,14 @@ import { findDocuments } from "./find-documents.mjs";
 import { getDocument } from "./get-document.mjs";
 import { listCapabilities } from "./list-capabilities.mjs";
 import { patchDocument } from "./patch-document.mjs";
+import { publishDocument } from "./publish-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. 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,
@@ -17,7 +19,8 @@ import { validateDocument } from "./validate-document.mjs";
 	getDocument,
 	patchDocument,
 	createDocument,
-	validateDocument
+	validateDocument,
+	publishDocument
 ];
 //#endregion
 export { BUILTIN_TOOLS };

package/dist/tools/create-document.mjs

@@ -1,45 +1,63 @@
-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, 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
-const createDocument = {
+/** 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)}${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: `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,
 		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."
 		}),
 		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");
+	handler: async ({ args, scope }) => {
+		const target = resolveTarget(scope, { collection: args.collection }, "create");
 		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 +70,7 @@ const createDocument = {
 			locale,
 			privileged: true
 		});
-		const publishBlockers = await collectPublishBlockers(scope.req, {
+		const validation = await collectPublishBlockers(scope.req, {
 			doc: saved,
 			entity: target
 		});
@@ -60,9 +78,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,19 @@
+import { jsonResult } from "../result.mjs";
+import { nodePropertiesFor } from "../schema/lexical.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 = {
+/**
+* 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.
 
@@ -15,7 +23,11 @@ Call it with no "paths" to get a collection's own fields. Every "blocks" field s
 
 A "richText" field stops there too. It lists the Lexical node types it accepts in "nodes", and "next" carries a path for every node type that holds fields of its own: "/content/link" for a link node, "/content/block/callout" and "/content/inlineBlock/badge" for the block nodes. Descend to get the real field list instead of guessing what a node carries. Upload nodes are not addressable, because their fields depend on the collection the node points at.
 
-Paths here use the same JSON Pointer syntax as getDocument and patchDocument, and are already resolved through anything that does not nest in the stored document. The difference is only what stands in an element position: a path names an array element "*" and a block by its slug, where a pointer into a document carries a 0-based index. So "/items/*/title" is written at "/items/0/title", and "/layout/sections/hero" at "/layout/sections/0".
+Write each Lexical node the way Lexical serializes it, with every property its type carries rather than a trimmed subset, and with the value Lexical would have written there. Those requirements are stated rather than left to be discovered: the response carries one final "nodeProperties" entry keyed by node type, naming each property and what belongs there in the same words a refused write uses, so a node can be built from this response alone. A field's own "nodes" says which of those types it accepts. The root takes exactly "children", "direction", "format", "indent", "type" and "version" and refuses anything else. The admin editor rehydrates nodes through their classes, so a list item whose "indent" is missing, null or a string is stored and then throws on open, and a heading whose "tag" is a number is stored untagged. A write naming a property means exactly that. A state whose root holds no children is refused however it is written, because Lexical reads it as empty and throws; clear a field with null instead.
+
+A rich text field's value is addressable too, so an edit does not have to rewrite the whole state: "/content/root/children/0" is the first top-level node, "/content/root/children/0/children/1" a node inside it, "/content/root/children/0/tag" one property of a node, and "/content/root/children/0/fields/url" a field of a node, described at the "next" path for that node type. Append a node with "/-". Which node sits at an index is only knowable from what is stored, so read it first: getDocument with "outline" answers with the pointer, type, "version" and a text excerpt for every node, which is far cheaper than reading the whole state.
+
+Paths here use the same JSON Pointer syntax as getDocument and patchDocument, and are already resolved through anything that does not nest in the stored document. The difference is only what stands in an element position: a path names an array element "*" and a block by its slug, where a pointer into a document carries a 0-based index. So "/items/*/title" is written at "/items/0/title", and "/layout/sections/hero" at "/layout/sections/0". Inside a rich text field that substitution does not apply: a path there names the node type, and a block node its slug, where a pointer enters the stored state at "root" and walks "children" by an index counted over every child at that level, not over the blocks among them, with the node's own fields under "fields". So "/content/block/practice-note/variant" is written at "/content/root/children/7/fields/variant".
 
 Fields Payload maintains (id, _status, createdAt, updatedAt) are never listed and cannot be written. Fields marked readOnly are listed but refused on write.`,
 	annotations: {
@@ -31,7 +43,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));
@@ -46,9 +58,11 @@ Fields Payload maintains (id, _status, createdAt, updatedAt) are never listed an
 				};
 			}
 		});
+		const nodeTypes = nodes.flatMap((node) => (node.fields ?? []).flatMap((field) => field.nodes ?? []));
+		if (nodeTypes.length > 0) nodes.push({ nodeProperties: nodePropertiesFor(nodeTypes) });
 		if (expanded?.truncated) nodes.push({ error: `Result truncated after ${String(400)} nodes. Request explicit paths instead.` });
 		return Promise.resolve(jsonResult(nodes));
 	}
-};
+});
 //#endregion
 export { describeSchema };