payload-mcp-toolkit 0.2.0 → 0.3.1

package/dist/resources.js

@@ -1,65 +1,50 @@
-/**
- * Generate MCP resources that expose the block catalog,
- * collection schemas, and relationship graph as static JSON.
- */ export function generateResources(schemas, catalog, relationships) {
+/**
+ * Generate MCP resources that expose the introspected schema as static JSON.
+ *
+ * Four resources:
+ * - blocks://catalog — flat list of every block and its fields
+ * - blocks://nesting — per-blocks-field map of which slugs each field accepts
+ * - collections://schema — collection field metadata
+ * - collections://relationships — collection relationship graph
+ */ export function generateResources(schemas, catalog, nesting, relationships) {
     return [
-        buildBlockCatalogResource(catalog),
-        buildCollectionSchemaResource(schemas),
-        buildRelationshipGraphResource(relationships)
+        buildJsonResource({
+            name: 'blockCatalog',
+            title: 'Block Catalog',
+            description: 'Flat list of every block type and its fields. Pair with the blockNesting resource to know where each block can be placed.',
+            uri: 'blocks://catalog',
+            payload: catalog
+        }),
+        buildJsonResource({
+            name: 'blockNesting',
+            title: 'Block Nesting Map',
+            description: 'For every blocks-typed field in the schema (in collections and inside other blocks), lists the block slugs that field accepts. Use this to compose nested layouts at any depth.',
+            uri: 'blocks://nesting',
+            payload: nesting
+        }),
+        buildJsonResource({
+            name: 'collectionSchema',
+            title: 'Collection Schema',
+            description: 'JSON schema of all collections — fields, select options, and relationship targets.',
+            uri: 'collections://schema',
+            payload: Object.fromEntries(schemas)
+        }),
+        buildJsonResource({
+            name: 'relationshipGraph',
+            title: 'Relationship Graph',
+            description: 'JSON representation of the collection relationship graph — which collections link to which.',
+            uri: 'collections://relationships',
+            payload: relationships
+        })
     ];
 }
-// ─── Resource builders ────────────────────────────────────────────
-function buildBlockCatalogResource(catalog) {
-    const json = JSON.stringify(catalog, null, 2);
+function buildJsonResource(args) {
+    const json = JSON.stringify(args.payload, null, 2);
     return {
-        name: 'blockCatalog',
-        title: 'Block Catalog',
-        description: 'JSON catalog of all block types — section/leaf hierarchy, nesting rules, and required fields.',
-        uri: 'blocks://catalog',
-        mimeType: 'application/json',
-        handler (uri) {
-            return {
-                contents: [
-                    {
-                        uri: uri.href,
-                        text: json
-                    }
-                ]
-            };
-        }
-    };
-}
-function buildCollectionSchemaResource(schemas) {
-    const obj = {};
-    for (const [slug, schema] of schemas){
-        obj[slug] = schema;
-    }
-    const json = JSON.stringify(obj, null, 2);
-    return {
-        name: 'collectionSchema',
-        title: 'Collection Schema',
-        description: 'JSON schema of all collections — fields, select options, and relationship targets.',
-        uri: 'collections://schema',
-        mimeType: 'application/json',
-        handler (uri) {
-            return {
-                contents: [
-                    {
-                        uri: uri.href,
-                        text: json
-                    }
-                ]
-            };
-        }
-    };
-}
-function buildRelationshipGraphResource(relationships) {
-    const json = JSON.stringify(relationships, null, 2);
-    return {
-        name: 'relationshipGraph',
-        title: 'Relationship Graph',
-        description: 'JSON representation of the collection relationship graph — which collections link to which.',
-        uri: 'collections://relationships',
+        name: args.name,
+        title: args.title,
+        description: args.description,
+        uri: args.uri,
         mimeType: 'application/json',
         handler (uri) {
             return {

package/dist/resources.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/resources.ts"],"sourcesContent":["import type {\n  BlockCatalog,\n  CollectionSchema,\n  RelationshipEdge,\n} from './types'\n\n/**\n * Generate MCP resources that expose the block catalog,\n * collection schemas, and relationship graph as static JSON.\n */\nexport function generateResources(\n  schemas: Map<string, CollectionSchema>,\n  catalog: BlockCatalog,\n  relationships: RelationshipEdge[],\n) {\n  return [\n    buildBlockCatalogResource(catalog),\n    buildCollectionSchemaResource(schemas),\n    buildRelationshipGraphResource(relationships),\n  ]\n}\n\n// ─── Resource builders ────────────────────────────────────────────\n\nfunction buildBlockCatalogResource(catalog: BlockCatalog) {\n  const json = JSON.stringify(catalog, null, 2)\n\n  return {\n    name: 'blockCatalog',\n    title: 'Block Catalog',\n    description:\n      'JSON catalog of all block types — section/leaf hierarchy, nesting rules, and required fields.',\n    uri: 'blocks://catalog',\n    mimeType: 'application/json',\n    handler(uri: URL) {\n      return {\n        contents: [{ uri: uri.href, text: json }],\n      }\n    },\n  }\n}\n\nfunction buildCollectionSchemaResource(schemas: Map<string, CollectionSchema>) {\n  const obj: Record<string, CollectionSchema> = {}\n  for (const [slug, schema] of schemas) {\n    obj[slug] = schema\n  }\n  const json = JSON.stringify(obj, null, 2)\n\n  return {\n    name: 'collectionSchema',\n    title: 'Collection Schema',\n    description:\n      'JSON schema of all collections — fields, select options, and relationship targets.',\n    uri: 'collections://schema',\n    mimeType: 'application/json',\n    handler(uri: URL) {\n      return {\n        contents: [{ uri: uri.href, text: json }],\n      }\n    },\n  }\n}\n\nfunction buildRelationshipGraphResource(relationships: RelationshipEdge[]) {\n  const json = JSON.stringify(relationships, null, 2)\n\n  return {\n    name: 'relationshipGraph',\n    title: 'Relationship Graph',\n    description:\n      'JSON representation of the collection relationship graph — which collections link to which.',\n    uri: 'collections://relationships',\n    mimeType: 'application/json',\n    handler(uri: URL) {\n      return {\n        contents: [{ uri: uri.href, text: json }],\n      }\n    },\n  }\n}\n"],"names":["generateResources","schemas","catalog","relationships","buildBlockCatalogResource","buildCollectionSchemaResource","buildRelationshipGraphResource","json","JSON","stringify","name","title","description","uri","mimeType","handler","contents","href","text","obj","slug","schema"],"mappings":"AAMA;;;CAGC,GACD,OAAO,SAASA,kBACdC,OAAsC,EACtCC,OAAqB,EACrBC,aAAiC;IAEjC,OAAO;QACLC,0BAA0BF;QAC1BG,8BAA8BJ;QAC9BK,+BAA+BH;KAChC;AACH;AAEA,qEAAqE;AAErE,SAASC,0BAA0BF,OAAqB;IACtD,MAAMK,OAAOC,KAAKC,SAAS,CAACP,SAAS,MAAM;IAE3C,OAAO;QACLQ,MAAM;QACNC,OAAO;QACPC,aACE;QACFC,KAAK;QACLC,UAAU;QACVC,SAAQF,GAAQ;YACd,OAAO;gBACLG,UAAU;oBAAC;wBAAEH,KAAKA,IAAII,IAAI;wBAAEC,MAAMX;oBAAK;iBAAE;YAC3C;QACF;IACF;AACF;AAEA,SAASF,8BAA8BJ,OAAsC;IAC3E,MAAMkB,MAAwC,CAAC;IAC/C,KAAK,MAAM,CAACC,MAAMC,OAAO,IAAIpB,QAAS;QACpCkB,GAAG,CAACC,KAAK,GAAGC;IACd;IACA,MAAMd,OAAOC,KAAKC,SAAS,CAACU,KAAK,MAAM;IAEvC,OAAO;QACLT,MAAM;QACNC,OAAO;QACPC,aACE;QACFC,KAAK;QACLC,UAAU;QACVC,SAAQF,GAAQ;YACd,OAAO;gBACLG,UAAU;oBAAC;wBAAEH,KAAKA,IAAII,IAAI;wBAAEC,MAAMX;oBAAK;iBAAE;YAC3C;QACF;IACF;AACF;AAEA,SAASD,+BAA+BH,aAAiC;IACvE,MAAMI,OAAOC,KAAKC,SAAS,CAACN,eAAe,MAAM;IAEjD,OAAO;QACLO,MAAM;QACNC,OAAO;QACPC,aACE;QACFC,KAAK;QACLC,UAAU;QACVC,SAAQF,GAAQ;YACd,OAAO;gBACLG,UAAU;oBAAC;wBAAEH,KAAKA,IAAII,IAAI;wBAAEC,MAAMX;oBAAK;iBAAE;YAC3C;QACF;IACF;AACF"}
+{"version":3,"sources":["../src/resources.ts"],"sourcesContent":["import type {\r\n  BlockCatalog,\r\n  BlockNestingMap,\r\n  CollectionSchema,\r\n  RelationshipEdge,\r\n} from './types'\r\n\r\n/**\r\n * Generate MCP resources that expose the introspected schema as static JSON.\r\n *\r\n * Four resources:\r\n * - blocks://catalog — flat list of every block and its fields\r\n * - blocks://nesting — per-blocks-field map of which slugs each field accepts\r\n * - collections://schema — collection field metadata\r\n * - collections://relationships — collection relationship graph\r\n */\r\nexport function generateResources(\r\n  schemas: Map<string, CollectionSchema>,\r\n  catalog: BlockCatalog,\r\n  nesting: BlockNestingMap,\r\n  relationships: RelationshipEdge[],\r\n) {\r\n  return [\r\n    buildJsonResource({\r\n      name: 'blockCatalog',\r\n      title: 'Block Catalog',\r\n      description:\r\n        'Flat list of every block type and its fields. Pair with the blockNesting resource to know where each block can be placed.',\r\n      uri: 'blocks://catalog',\r\n      payload: catalog,\r\n    }),\r\n    buildJsonResource({\r\n      name: 'blockNesting',\r\n      title: 'Block Nesting Map',\r\n      description:\r\n        'For every blocks-typed field in the schema (in collections and inside other blocks), lists the block slugs that field accepts. Use this to compose nested layouts at any depth.',\r\n      uri: 'blocks://nesting',\r\n      payload: nesting,\r\n    }),\r\n    buildJsonResource({\r\n      name: 'collectionSchema',\r\n      title: 'Collection Schema',\r\n      description:\r\n        'JSON schema of all collections — fields, select options, and relationship targets.',\r\n      uri: 'collections://schema',\r\n      payload: Object.fromEntries(schemas),\r\n    }),\r\n    buildJsonResource({\r\n      name: 'relationshipGraph',\r\n      title: 'Relationship Graph',\r\n      description:\r\n        'JSON representation of the collection relationship graph — which collections link to which.',\r\n      uri: 'collections://relationships',\r\n      payload: relationships,\r\n    }),\r\n  ]\r\n}\r\n\r\nfunction buildJsonResource(args: {\r\n  name: string\r\n  title: string\r\n  description: string\r\n  uri: string\r\n  payload: unknown\r\n}) {\r\n  const json = JSON.stringify(args.payload, null, 2)\r\n  return {\r\n    name: args.name,\r\n    title: args.title,\r\n    description: args.description,\r\n    uri: args.uri,\r\n    mimeType: 'application/json',\r\n    handler(uri: URL) {\r\n      return {\r\n        contents: [{ uri: uri.href, text: json }],\r\n      }\r\n    },\r\n  }\r\n}\r\n\r\n"],"names":["generateResources","schemas","catalog","nesting","relationships","buildJsonResource","name","title","description","uri","payload","Object","fromEntries","args","json","JSON","stringify","mimeType","handler","contents","href","text"],"mappings":"AAOA;;;;;;;;CAQC,GACD,OAAO,SAASA,kBACdC,OAAsC,EACtCC,OAAqB,EACrBC,OAAwB,EACxBC,aAAiC;IAEjC,OAAO;QACLC,kBAAkB;YAChBC,MAAM;YACNC,OAAO;YACPC,aACE;YACFC,KAAK;YACLC,SAASR;QACX;QACAG,kBAAkB;YAChBC,MAAM;YACNC,OAAO;YACPC,aACE;YACFC,KAAK;YACLC,SAASP;QACX;QACAE,kBAAkB;YAChBC,MAAM;YACNC,OAAO;YACPC,aACE;YACFC,KAAK;YACLC,SAASC,OAAOC,WAAW,CAACX;QAC9B;QACAI,kBAAkB;YAChBC,MAAM;YACNC,OAAO;YACPC,aACE;YACFC,KAAK;YACLC,SAASN;QACX;KACD;AACH;AAEA,SAASC,kBAAkBQ,IAM1B;IACC,MAAMC,OAAOC,KAAKC,SAAS,CAACH,KAAKH,OAAO,EAAE,MAAM;IAChD,OAAO;QACLJ,MAAMO,KAAKP,IAAI;QACfC,OAAOM,KAAKN,KAAK;QACjBC,aAAaK,KAAKL,WAAW;QAC7BC,KAAKI,KAAKJ,GAAG;QACbQ,UAAU;QACVC,SAAQT,GAAQ;YACd,OAAO;gBACLU,UAAU;oBAAC;wBAAEV,KAAKA,IAAIW,IAAI;wBAAEC,MAAMP;oBAAK;iBAAE;YAC3C;QACF;IACF;AACF"}

package/dist/tools/_helpers.d.ts

@@ -0,0 +1,14 @@
+import type { PayloadRequest } from 'payload';
+export interface McpTextResponse {
+    content: Array<{
+        type: 'text';
+        text: string;
+    }>;
+}
+export declare const DRAFT_NOTE = " Document is in draft status \u2014 use publishDraft to make it live.";
+export declare function textResponse(text: string): McpTextResponse;
+export declare function jsonResponse(payload: unknown): McpTextResponse;
+export declare function errorMessage(error: unknown): string;
+export declare function stampMcpContext(req: PayloadRequest): void;
+export declare function getDocDisplayName(doc: unknown, fallback: string): string;
+export declare function requireDraftCollection(collection: string, draftCollections: Set<string>, noun?: string): McpTextResponse | null;

package/dist/tools/_helpers.js

@@ -0,0 +1,35 @@
+export const DRAFT_NOTE = ' Document is in draft status — use publishDraft to make it live.';
+export function textResponse(text) {
+    return {
+        content: [
+            {
+                type: 'text',
+                text
+            }
+        ]
+    };
+}
+export function jsonResponse(payload) {
+    return textResponse(JSON.stringify(payload));
+}
+export function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+export function stampMcpContext(req) {
+    req.context = {
+        ...req.context,
+        source: 'mcp'
+    };
+}
+export function getDocDisplayName(doc, fallback) {
+    const d = doc;
+    return typeof d?.name === 'string' && d.name || typeof d?.title === 'string' && d.title || typeof d?.slug === 'string' && d.slug || fallback;
+}
+export function requireDraftCollection(collection, draftCollections, noun = 'drafts') {
+    if (draftCollections.has(collection)) return null;
+    return textResponse(`Error: Collection "${collection}" does not support ${noun}. ` + `Draft-enabled collections: ${[
+        ...draftCollections
+    ].join(', ') || 'none'}`);
+}
+
+//# sourceMappingURL=_helpers.js.map

package/dist/tools/_helpers.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/tools/_helpers.ts"],"sourcesContent":["import type { PayloadRequest } from 'payload'\n\nexport interface McpTextResponse {\n  content: Array<{ type: 'text'; text: string }>\n}\n\nexport const DRAFT_NOTE = ' Document is in draft status — use publishDraft to make it live.'\n\nexport function textResponse(text: string): McpTextResponse {\n  return { content: [{ type: 'text', text }] }\n}\n\nexport function jsonResponse(payload: unknown): McpTextResponse {\n  return textResponse(JSON.stringify(payload))\n}\n\nexport function errorMessage(error: unknown): string {\n  return error instanceof Error ? error.message : String(error)\n}\n\nexport function stampMcpContext(req: PayloadRequest): void {\n  req.context = { ...req.context, source: 'mcp' }\n}\n\nexport function getDocDisplayName(doc: unknown, fallback: string): string {\n  const d = doc as Record<string, unknown> | null | undefined\n  return (\n    (typeof d?.name === 'string' && d.name) ||\n    (typeof d?.title === 'string' && d.title) ||\n    (typeof d?.slug === 'string' && d.slug) ||\n    fallback\n  )\n}\n\nexport function requireDraftCollection(\n  collection: string,\n  draftCollections: Set<string>,\n  noun = 'drafts',\n): McpTextResponse | null {\n  if (draftCollections.has(collection)) return null\n  return textResponse(\n    `Error: Collection \"${collection}\" does not support ${noun}. ` +\n      `Draft-enabled collections: ${[...draftCollections].join(', ') || 'none'}`,\n  )\n}\n"],"names":["DRAFT_NOTE","textResponse","text","content","type","jsonResponse","payload","JSON","stringify","errorMessage","error","Error","message","String","stampMcpContext","req","context","source","getDocDisplayName","doc","fallback","d","name","title","slug","requireDraftCollection","collection","draftCollections","noun","has","join"],"mappings":"AAMA,OAAO,MAAMA,aAAa,mEAAkE;AAE5F,OAAO,SAASC,aAAaC,IAAY;IACvC,OAAO;QAAEC,SAAS;YAAC;gBAAEC,MAAM;gBAAQF;YAAK;SAAE;IAAC;AAC7C;AAEA,OAAO,SAASG,aAAaC,OAAgB;IAC3C,OAAOL,aAAaM,KAAKC,SAAS,CAACF;AACrC;AAEA,OAAO,SAASG,aAAaC,KAAc;IACzC,OAAOA,iBAAiBC,QAAQD,MAAME,OAAO,GAAGC,OAAOH;AACzD;AAEA,OAAO,SAASI,gBAAgBC,GAAmB;IACjDA,IAAIC,OAAO,GAAG;QAAE,GAAGD,IAAIC,OAAO;QAAEC,QAAQ;IAAM;AAChD;AAEA,OAAO,SAASC,kBAAkBC,GAAY,EAAEC,QAAgB;IAC9D,MAAMC,IAAIF;IACV,OACE,AAAC,OAAOE,GAAGC,SAAS,YAAYD,EAAEC,IAAI,IACrC,OAAOD,GAAGE,UAAU,YAAYF,EAAEE,KAAK,IACvC,OAAOF,GAAGG,SAAS,YAAYH,EAAEG,IAAI,IACtCJ;AAEJ;AAEA,OAAO,SAASK,uBACdC,UAAkB,EAClBC,gBAA6B,EAC7BC,OAAO,QAAQ;IAEf,IAAID,iBAAiBE,GAAG,CAACH,aAAa,OAAO;IAC7C,OAAOzB,aACL,CAAC,mBAAmB,EAAEyB,WAAW,mBAAmB,EAAEE,KAAK,EAAE,CAAC,GAC5D,CAAC,2BAA2B,EAAE;WAAID;KAAiB,CAACG,IAAI,CAAC,SAAS,QAAQ;AAEhF"}

package/dist/tools/patch-layout.d.ts

@@ -1,93 +1,28 @@
 import { z } from 'zod';
 import type { PayloadRequest } from 'payload';
-import type { BlockCatalog } from '../types';
-import { type SectionInput } from './compose-helpers';
+import type { BlockCatalog, BlockNestingMap } from '../types';
 /**
- * Creates the patchLayout MCP tool — a surgical wrapper around composePageLayout
- * that mutates a single document's layout-style field directly, never round-tripping
- * the entire array through updateDocument.
+ * patchLayout — surgical wrapper that mutates a single document's blocks-typed
+ * field directly without round-tripping the entire array through updateDocument.
  *
- * Why this exists: prompting an LLM to "add a CTA at the bottom of the home page"
- * via updateDocument forces it to send the entire layout array, which one bad token
- * can wipe out. patchLayout fetches the current layout itself, applies a scoped
- * operation, and writes back — the LLM only ever describes the delta.
+ * Why this exists: prompting an LLM to "add a CTA at the bottom of the home
+ * page" via updateDocument forces it to send the whole layout array, which one
+ * bad token can wipe out. patchLayout fetches the current array itself,
+ * applies a scoped operation, and writes back — the LLM only describes the
+ * delta.
  *
- * Defaults to layoutField "layout" but accepts any block-array field name.
+ * Validation walks every block recursively against the introspected
+ * BlockNestingMap, so arbitrarily-nested layouts work as long as each
+ * `blocks`-typed field's content matches that field's allow list.
  */
-export declare function createPatchLayoutTool(catalog: BlockCatalog, draftCollections: Set<string>): {
+export declare function createPatchLayoutTool(catalog: BlockCatalog, nesting: BlockNestingMap, draftCollections: Set<string>): {
     name: string;
     description: string;
     parameters: {
         collection: z.ZodString;
         documentId: z.ZodString;
         layoutField: z.ZodDefault<z.ZodOptional<z.ZodString>>;
-        sections: z.ZodArray<z.ZodObject<{
-            sectionType: z.ZodString;
-            config: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
-            content: z.ZodOptional<z.ZodArray<z.ZodObject<{
-                blockType: z.ZodString;
-                fields: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
-            }, "strip", z.ZodTypeAny, {
-                blockType: string;
-                fields?: Record<string, unknown> | undefined;
-            }, {
-                blockType: string;
-                fields?: Record<string, unknown> | undefined;
-            }>, "many">>;
-            leftColumn: z.ZodOptional<z.ZodArray<z.ZodObject<{
-                blockType: z.ZodString;
-                fields: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
-            }, "strip", z.ZodTypeAny, {
-                blockType: string;
-                fields?: Record<string, unknown> | undefined;
-            }, {
-                blockType: string;
-                fields?: Record<string, unknown> | undefined;
-            }>, "many">>;
-            rightColumn: z.ZodOptional<z.ZodArray<z.ZodObject<{
-                blockType: z.ZodString;
-                fields: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
-            }, "strip", z.ZodTypeAny, {
-                blockType: string;
-                fields?: Record<string, unknown> | undefined;
-            }, {
-                blockType: string;
-                fields?: Record<string, unknown> | undefined;
-            }>, "many">>;
-            fields: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
-        }, "strip", z.ZodTypeAny, {
-            sectionType: string;
-            fields?: Record<string, unknown> | undefined;
-            config?: Record<string, unknown> | undefined;
-            content?: {
-                blockType: string;
-                fields?: Record<string, unknown> | undefined;
-            }[] | undefined;
-            leftColumn?: {
-                blockType: string;
-                fields?: Record<string, unknown> | undefined;
-            }[] | undefined;
-            rightColumn?: {
-                blockType: string;
-                fields?: Record<string, unknown> | undefined;
-            }[] | undefined;
-        }, {
-            sectionType: string;
-            fields?: Record<string, unknown> | undefined;
-            config?: Record<string, unknown> | undefined;
-            content?: {
-                blockType: string;
-                fields?: Record<string, unknown> | undefined;
-            }[] | undefined;
-            leftColumn?: {
-                blockType: string;
-                fields?: Record<string, unknown> | undefined;
-            }[] | undefined;
-            rightColumn?: {
-                blockType: string;
-                fields?: Record<string, unknown> | undefined;
-            }[] | undefined;
-        }>, "many">;
+        blocks: z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnknown>, "many">;
         operation: z.ZodEnum<["append", "prepend", "insertAt", "replaceAt", "full"]>;
         insertIndex: z.ZodOptional<z.ZodNumber>;
     };
@@ -95,13 +30,8 @@ export declare function createPatchLayoutTool(catalog: BlockCatalog, draftCollec
         collection: string;
         documentId: string;
         layoutField?: string;
-        sections: SectionInput[];
+        blocks: Array<Record<string, unknown>>;
         operation: "append" | "prepend" | "insertAt" | "replaceAt" | "full";
         insertIndex?: number;
-    }, req: PayloadRequest, _extra: unknown) => Promise<{
-        content: {
-            type: "text";
-            text: string;
-        }[];
-    }>;
+    }, req: PayloadRequest, _extra: unknown) => Promise<import("./_helpers").McpTextResponse>;
 };

package/dist/tools/patch-layout.js

@@ -1,79 +1,80 @@
 import { z } from 'zod';
-import { applyOperation, buildHint, composeSections, sectionSchema } from './compose-helpers';
+import { DRAFT_NOTE, errorMessage, getDocDisplayName, jsonResponse, stampMcpContext } from './_helpers';
 /**
- * Creates the patchLayout MCP tool — a surgical wrapper around composePageLayout
- * that mutates a single document's layout-style field directly, never round-tripping
- * the entire array through updateDocument.
+ * patchLayout — surgical wrapper that mutates a single document's blocks-typed
+ * field directly without round-tripping the entire array through updateDocument.
  *
- * Why this exists: prompting an LLM to "add a CTA at the bottom of the home page"
- * via updateDocument forces it to send the entire layout array, which one bad token
- * can wipe out. patchLayout fetches the current layout itself, applies a scoped
- * operation, and writes back — the LLM only ever describes the delta.
+ * Why this exists: prompting an LLM to "add a CTA at the bottom of the home
+ * page" via updateDocument forces it to send the whole layout array, which one
+ * bad token can wipe out. patchLayout fetches the current array itself,
+ * applies a scoped operation, and writes back — the LLM only describes the
+ * delta.
  *
- * Defaults to layoutField "layout" but accepts any block-array field name.
- */ export function createPatchLayoutTool(catalog, draftCollections) {
-    const sectionSlugs = catalog.sections.map((s)=>s.slug);
-    const leafSlugs = catalog.leaves.map((l)=>l.slug);
+ * Validation walks every block recursively against the introspected
+ * BlockNestingMap, so arbitrarily-nested layouts work as long as each
+ * `blocks`-typed field's content matches that field's allow list.
+ */ export function createPatchLayoutTool(catalog, nesting, draftCollections) {
+    const allBlockSlugs = new Set(catalog.blocks.map((b)=>b.slug));
+    // Lookups keyed by `<owner>:<fieldPath>` for O(1) access during recursive validation.
+    const nestingByCollectionField = new Map();
+    const nestingByBlockField = new Map();
+    for (const edge of nesting){
+        const key = `${edge.owner}:${edge.fieldPath}`;
+        if (edge.ownerType === 'collection') {
+            nestingByCollectionField.set(key, edge.acceptedBlockSlugs);
+        } else {
+            nestingByBlockField.set(key, edge.acceptedBlockSlugs);
+        }
+    }
     return {
         name: 'patchLayout',
-        description: 'Surgically modify a document\'s block-array field (e.g. "layout") without ' + 'sending the whole array. Pass only the sections to add or replace plus an operation ' + '(append, prepend, insertAt, replaceAt). The current layout is fetched server-side ' + 'and the operation is applied atomically. Safer than updateDocument for incremental edits. ' + `Available sections: ${sectionSlugs.join(', ')}. Available leaves: ${leafSlugs.join(', ')}.`,
+        description: 'Surgically modify a document\'s blocks-typed field (e.g. "layout") without sending the whole array. Pass the blocks to add/replace plus an operation (append, prepend, insertAt, replaceAt, full). The current array is fetched server-side and the operation is applied atomically. Each block must include a `blockType` plus its fields; nested `blocks`-typed fields can contain arbitrarily-deep block arrays as long as each level matches the schema. Use the `blockNesting` resource to see which slugs each field accepts.',
         parameters: {
             collection: z.string().describe('The collection slug containing the document'),
             documentId: z.string().describe('The ID of the document to patch'),
-            layoutField: z.string().optional().default('layout').describe('Name of the block-array field to patch (default "layout")'),
-            sections: z.array(sectionSchema).describe('Sections to compose. Same shape as composePageLayout.'),
+            layoutField: z.string().optional().default('layout').describe('Name of the blocks-typed field to patch (default "layout")'),
+            blocks: z.array(z.record(z.string(), z.unknown())).describe('Blocks to compose. Each must have a `blockType` discriminator plus any block-specific fields. Nested blocks fields hold their own `blocks` arrays at any depth.'),
             operation: z.enum([
                 'append',
                 'prepend',
                 'insertAt',
                 'replaceAt',
                 'full'
-            ]).describe('How to apply the sections: append (end), prepend (start), insertAt (at index), ' + 'replaceAt (overwrite N starting at index), full (replace entire array — use with care).'),
+            ]).describe('How to apply the blocks: append (end), prepend (start), insertAt (at index), replaceAt (overwrite N starting at index), full (replace entire array — use with care).'),
             insertIndex: z.number().optional().describe('Index for insertAt/replaceAt operations')
         },
         handler: async (args, req, _extra)=>{
-            const { collection, documentId, layoutField = 'layout', sections, operation, insertIndex } = args;
-            // Compose the new sections first — fail fast on validation errors before touching the doc
-            const { blocks, errors } = composeSections(sections, catalog);
-            if (errors.length > 0) {
-                return {
-                    content: [
-                        {
-                            type: 'text',
-                            text: JSON.stringify({
-                                success: false,
-                                errors,
-                                hint: buildHint(catalog)
-                            })
-                        }
+            const { collection, documentId, layoutField = 'layout', blocks, operation, insertIndex } = args;
+            const rootKey = `${collection}:${layoutField}`;
+            const rootAllowed = nestingByCollectionField.get(rootKey);
+            if (!rootAllowed) {
+                return errorResponse(`Field "${layoutField}" on collection "${collection}" is not a blocks-typed field, or no nesting map entry exists for it.`, {
+                    availableFields: [
+                        ...nestingByCollectionField.keys()
                     ]
-                };
+                });
+            }
+            const errors = [];
+            validateBlockList(blocks, rootAllowed, layoutField, allBlockSlugs, nestingByBlockField, errors);
+            if (errors.length > 0) {
+                return errorResponse('Block validation failed.', {
+                    errors
+                });
             }
-            req.context = {
-                ...req.context,
-                source: 'mcp'
-            };
-            // Fetch current document so we can read the existing layout array
+            stampMcpContext(req);
             let existing;
             try {
                 existing = await req.payload.findByID({
                     collection: collection,
                     id: documentId,
+                    depth: 0,
                     draft: true,
                     req,
                     overrideAccess: false,
                     user: req.user
                 });
             } catch (error) {
-                const message = error instanceof Error ? error.message : String(error);
-                return {
-                    content: [
-                        {
-                            type: 'text',
-                            text: `Error fetching ${collection}#${documentId}: ${message}`
-                        }
-                    ]
-                };
+                return errorResponse(`Error fetching ${collection}#${documentId}: ${errorMessage(error)}`);
             }
             const currentLayout = Array.isArray(existing?.[layoutField]) ? existing[layoutField] : [];
             const finalLayout = applyOperation(blocks, operation, insertIndex, currentLayout);
@@ -90,34 +91,106 @@ import { applyOperation, buildHint, composeSections, sectionSchema } from './com
                     overrideAccess: false,
                     user: req.user
                 });
-                const displayName = updated.name || updated.title || updated.slug || documentId;
-                const draftNote = isDraftCollection ? ' Document is in draft status — use publishDraft to make it live.' : '';
-                return {
-                    content: [
-                        {
-                            type: 'text',
-                            text: JSON.stringify({
-                                success: true,
-                                message: `Patched ${layoutField} on "${displayName}" (${collection}#${documentId}). ` + `Operation: ${operation}. Block count: ${finalLayout.length}.` + draftNote,
-                                blockCount: finalLayout.length,
-                                operation
-                            })
-                        }
-                    ]
-                };
+                const displayName = getDocDisplayName(updated, documentId);
+                const draftNote = isDraftCollection ? DRAFT_NOTE : '';
+                return jsonResponse({
+                    success: true,
+                    message: `Patched ${layoutField} on "${displayName}" (${collection}#${documentId}). ` + `Operation: ${operation}. Block count: ${finalLayout.length}.` + draftNote,
+                    blockCount: finalLayout.length,
+                    operation
+                });
             } catch (error) {
-                const message = error instanceof Error ? error.message : String(error);
-                return {
-                    content: [
-                        {
-                            type: 'text',
-                            text: `Error patching ${collection}#${documentId}: ${message}`
-                        }
-                    ]
-                };
+                return errorResponse(`Error patching ${collection}#${documentId}: ${errorMessage(error)}`);
             }
         }
     };
 }
+function errorResponse(message, extra) {
+    return jsonResponse({
+        success: false,
+        error: message,
+        ...extra ?? {}
+    });
+}
+/**
+ * Recursively validate a block array against an allow list, descending into
+ * each block's own `blocks`-typed fields when present.
+ */ function validateBlockList(blocks, allowedSlugs, pathLabel, allBlockSlugs, nestingByBlockField, errors) {
+    for(let i = 0; i < blocks.length; i++){
+        const block = blocks[i];
+        const here = `${pathLabel}[${i}]`;
+        if (!block || typeof block !== 'object') {
+            errors.push(`${here}: not an object`);
+            continue;
+        }
+        const slug = block.blockType;
+        if (typeof slug !== 'string' || !slug) {
+            errors.push(`${here}: missing string \`blockType\``);
+            continue;
+        }
+        if (!allBlockSlugs.has(slug)) {
+            errors.push(`${here}: unknown blockType "${slug}". Known: ${[
+                ...allBlockSlugs
+            ].join(', ')}`);
+            continue;
+        }
+        if (!allowedSlugs.includes(slug)) {
+            errors.push(`${here}: blockType "${slug}" not allowed here. Allowed at this position: ${allowedSlugs.join(', ') || '(none)'}`);
+            continue;
+        }
+        // Any value that is itself an array of objects with `blockType` is treated
+        // as a nested blocks field. The field name is cross-checked against the
+        // nesting map to find the next-level allow list.
+        for (const [fieldName, value] of Object.entries(block)){
+            if (!Array.isArray(value)) continue;
+            if (value.length === 0) continue;
+            if (!value.every((v)=>v && typeof v === 'object' && 'blockType' in v)) continue;
+            const nextKey = `${slug}:${fieldName}`;
+            const nextAllowed = nestingByBlockField.get(nextKey);
+            if (!nextAllowed) {
+                errors.push(`${here}.${fieldName}: block "${slug}" has no blocks field named "${fieldName}" in the schema`);
+                continue;
+            }
+            validateBlockList(value, nextAllowed, `${here}.${fieldName}`, allBlockSlugs, nestingByBlockField, errors);
+        }
+    }
+}
+/**
+ * Apply a list operation against an existing array of blocks.
+ * `full` always replaces; the rest preserve the existing array.
+ */ function applyOperation(newBlocks, operation, insertIndex, existingLayout) {
+    if (operation === 'full' || !existingLayout) {
+        return newBlocks;
+    }
+    const existing = [
+        ...existingLayout
+    ];
+    if (operation === 'append') return [
+        ...existing,
+        ...newBlocks
+    ];
+    if (operation === 'prepend') return [
+        ...newBlocks,
+        ...existing
+    ];
+    if (operation === 'insertAt') {
+        if (insertIndex === undefined || insertIndex < 0 || insertIndex > existing.length) {
+            return [
+                ...existing,
+                ...newBlocks
+            ];
+        }
+        existing.splice(insertIndex, 0, ...newBlocks);
+        return existing;
+    }
+    if (operation === 'replaceAt') {
+        if (insertIndex === undefined || insertIndex < 0 || insertIndex >= existing.length) {
+            return existing;
+        }
+        existing.splice(insertIndex, newBlocks.length, ...newBlocks);
+        return existing;
+    }
+    return newBlocks;
+}
 
 //# sourceMappingURL=patch-layout.js.map