payload-mcp-toolkit 0.2.0

package/dist/tools/patch-layout.js

@@ -0,0 +1,123 @@
+import { z } from 'zod';
+import { applyOperation, buildHint, composeSections, sectionSchema } from './compose-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.
+ *
+ * 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.
+ *
+ * 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);
+    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(', ')}.`,
+        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.'),
+            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).'),
+            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)
+                            })
+                        }
+                    ]
+                };
+            }
+            req.context = {
+                ...req.context,
+                source: 'mcp'
+            };
+            // Fetch current document so we can read the existing layout array
+            let existing;
+            try {
+                existing = await req.payload.findByID({
+                    collection: collection,
+                    id: documentId,
+                    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}`
+                        }
+                    ]
+                };
+            }
+            const currentLayout = Array.isArray(existing?.[layoutField]) ? existing[layoutField] : [];
+            const finalLayout = applyOperation(blocks, operation, insertIndex, currentLayout);
+            const isDraftCollection = draftCollections.has(collection);
+            try {
+                const updated = await req.payload.update({
+                    collection: collection,
+                    id: documentId,
+                    data: {
+                        [layoutField]: finalLayout
+                    },
+                    draft: isDraftCollection,
+                    req,
+                    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
+                            })
+                        }
+                    ]
+                };
+            } catch (error) {
+                const message = error instanceof Error ? error.message : String(error);
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: `Error patching ${collection}#${documentId}: ${message}`
+                        }
+                    ]
+                };
+            }
+        }
+    };
+}
+
+//# sourceMappingURL=patch-layout.js.map

package/dist/tools/patch-layout.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/tools/patch-layout.ts"],"sourcesContent":["import { z } from 'zod'\nimport type { PayloadRequest } from 'payload'\nimport type { BlockCatalog } from '../types'\nimport {\n  applyOperation,\n  buildHint,\n  composeSections,\n  sectionSchema,\n  type SectionInput,\n} from './compose-helpers'\n\n/**\n * Creates the patchLayout MCP tool — a surgical wrapper around composePageLayout\n * that mutates a single document's layout-style field directly, never round-tripping\n * the entire array through updateDocument.\n *\n * Why this exists: prompting an LLM to \"add a CTA at the bottom of the home page\"\n * via updateDocument forces it to send the entire layout array, which one bad token\n * can wipe out. patchLayout fetches the current layout itself, applies a scoped\n * operation, and writes back — the LLM only ever describes the delta.\n *\n * Defaults to layoutField \"layout\" but accepts any block-array field name.\n */\nexport function createPatchLayoutTool(\n  catalog: BlockCatalog,\n  draftCollections: Set<string>,\n) {\n  const sectionSlugs = catalog.sections.map((s) => s.slug)\n  const leafSlugs = catalog.leaves.map((l) => l.slug)\n\n  return {\n    name: 'patchLayout',\n    description:\n      'Surgically modify a document\\'s block-array field (e.g. \"layout\") without ' +\n      'sending the whole array. Pass only the sections to add or replace plus an operation ' +\n      '(append, prepend, insertAt, replaceAt). The current layout is fetched server-side ' +\n      'and the operation is applied atomically. Safer than updateDocument for incremental edits. ' +\n      `Available sections: ${sectionSlugs.join(', ')}. Available leaves: ${leafSlugs.join(', ')}.`,\n    parameters: {\n      collection: z.string().describe('The collection slug containing the document'),\n      documentId: z.string().describe('The ID of the document to patch'),\n      layoutField: z\n        .string()\n        .optional()\n        .default('layout')\n        .describe('Name of the block-array field to patch (default \"layout\")'),\n      sections: z\n        .array(sectionSchema)\n        .describe('Sections to compose. Same shape as composePageLayout.'),\n      operation: z\n        .enum(['append', 'prepend', 'insertAt', 'replaceAt', 'full'])\n        .describe(\n          'How to apply the sections: append (end), prepend (start), insertAt (at index), ' +\n          'replaceAt (overwrite N starting at index), full (replace entire array — use with care).',\n        ),\n      insertIndex: z\n        .number()\n        .optional()\n        .describe('Index for insertAt/replaceAt operations'),\n    },\n    handler: async (\n      args: {\n        collection: string\n        documentId: string\n        layoutField?: string\n        sections: SectionInput[]\n        operation: 'append' | 'prepend' | 'insertAt' | 'replaceAt' | 'full'\n        insertIndex?: number\n      },\n      req: PayloadRequest,\n      _extra: unknown,\n    ) => {\n      const {\n        collection,\n        documentId,\n        layoutField = 'layout',\n        sections,\n        operation,\n        insertIndex,\n      } = args\n\n      // Compose the new sections first — fail fast on validation errors before touching the doc\n      const { blocks, errors } = composeSections(sections, catalog)\n\n      if (errors.length > 0) {\n        return {\n          content: [\n            {\n              type: 'text' as const,\n              text: JSON.stringify({\n                success: false,\n                errors,\n                hint: buildHint(catalog),\n              }),\n            },\n          ],\n        }\n      }\n\n      req.context = { ...req.context, source: 'mcp' }\n\n      // Fetch current document so we can read the existing layout array\n      let existing: any\n      try {\n        existing = await req.payload.findByID({\n          collection: collection as any,\n          id: documentId,\n          draft: true,\n          req,\n          overrideAccess: false,\n          user: req.user,\n        })\n      } catch (error) {\n        const message = error instanceof Error ? error.message : String(error)\n        return {\n          content: [\n            {\n              type: 'text' as const,\n              text: `Error fetching ${collection}#${documentId}: ${message}`,\n            },\n          ],\n        }\n      }\n\n      const currentLayout = Array.isArray(existing?.[layoutField]) ? existing[layoutField] : []\n      const finalLayout = applyOperation(blocks, operation, insertIndex, currentLayout)\n\n      const isDraftCollection = draftCollections.has(collection)\n\n      try {\n        const updated = await req.payload.update({\n          collection: collection as any,\n          id: documentId,\n          data: { [layoutField]: finalLayout } as any,\n          draft: isDraftCollection,\n          req,\n          overrideAccess: false,\n          user: req.user,\n        })\n\n        const displayName =\n          (updated as any).name ||\n          (updated as any).title ||\n          (updated as any).slug ||\n          documentId\n\n        const draftNote = isDraftCollection\n          ? ' Document is in draft status — use publishDraft to make it live.'\n          : ''\n\n        return {\n          content: [\n            {\n              type: 'text' as const,\n              text: JSON.stringify({\n                success: true,\n                message:\n                  `Patched ${layoutField} on \"${displayName}\" (${collection}#${documentId}). ` +\n                  `Operation: ${operation}. Block count: ${finalLayout.length}.` +\n                  draftNote,\n                blockCount: finalLayout.length,\n                operation,\n              }),\n            },\n          ],\n        }\n      } catch (error) {\n        const message = error instanceof Error ? error.message : String(error)\n        return {\n          content: [\n            {\n              type: 'text' as const,\n              text: `Error patching ${collection}#${documentId}: ${message}`,\n            },\n          ],\n        }\n      }\n    },\n  }\n}\n"],"names":["z","applyOperation","buildHint","composeSections","sectionSchema","createPatchLayoutTool","catalog","draftCollections","sectionSlugs","sections","map","s","slug","leafSlugs","leaves","l","name","description","join","parameters","collection","string","describe","documentId","layoutField","optional","default","array","operation","enum","insertIndex","number","handler","args","req","_extra","blocks","errors","length","content","type","text","JSON","stringify","success","hint","context","source","existing","payload","findByID","id","draft","overrideAccess","user","error","message","Error","String","currentLayout","Array","isArray","finalLayout","isDraftCollection","has","updated","update","data","displayName","title","draftNote","blockCount"],"mappings":"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"}

package/dist/tools/publish-draft.d.ts

@@ -0,0 +1,24 @@
+import { z } from 'zod';
+import type { PayloadRequest } from 'payload';
+/**
+ * Creates the publishDraft MCP tool that transitions a document from draft to published status.
+ *
+ * @param draftCollections - Set of collection slugs that support drafts
+ */
+export declare function createPublishDraftTool(draftCollections: Set<string>): {
+    name: string;
+    description: string;
+    parameters: {
+        collection: z.ZodString;
+        documentId: z.ZodString;
+    };
+    handler: (args: {
+        collection: string;
+        documentId: string;
+    }, req: PayloadRequest, _extra: unknown) => Promise<{
+        content: {
+            type: "text";
+            text: string;
+        }[];
+    }>;
+};

package/dist/tools/publish-draft.js

@@ -0,0 +1,69 @@
+import { z } from 'zod';
+/**
+ * Creates the publishDraft MCP tool that transitions a document from draft to published status.
+ *
+ * @param draftCollections - Set of collection slugs that support drafts
+ */ export function createPublishDraftTool(draftCollections) {
+    return {
+        name: 'publishDraft',
+        description: 'Publish a draft document by transitioning its _status from "draft" to "published". ' + 'Only works on collections that support drafts. Use after creating or editing content ' + 'to make it live on the site.',
+        parameters: {
+            collection: z.string().describe(`The collection slug. Draft-enabled collections: ${[
+                ...draftCollections
+            ].join(', ') || 'none'}`),
+            documentId: z.string().describe('The ID of the document to publish')
+        },
+        handler: async (args, req, _extra)=>{
+            const { collection, documentId } = args;
+            if (!draftCollections.has(collection)) {
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: `Error: Collection "${collection}" does not support drafts. ` + `Draft-enabled collections: ${[
+                                ...draftCollections
+                            ].join(', ') || 'none'}`
+                        }
+                    ]
+                };
+            }
+            req.context = {
+                ...req.context,
+                source: 'mcp'
+            };
+            try {
+                const doc = await req.payload.update({
+                    collection: collection,
+                    id: documentId,
+                    data: {
+                        _status: 'published'
+                    },
+                    req,
+                    overrideAccess: false,
+                    user: req.user
+                });
+                const displayName = doc.name || doc.title || doc.slug || documentId;
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: `Successfully published "${displayName}" in ${collection} (ID: ${documentId}).`
+                        }
+                    ]
+                };
+            } catch (error) {
+                const message = error instanceof Error ? error.message : String(error);
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: `Error publishing document ${documentId} in ${collection}: ${message}`
+                        }
+                    ]
+                };
+            }
+        }
+    };
+}
+
+//# sourceMappingURL=publish-draft.js.map

package/dist/tools/publish-draft.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/tools/publish-draft.ts"],"sourcesContent":["import { z } from 'zod'\nimport type { PayloadRequest } from 'payload'\n\n/**\n * Creates the publishDraft MCP tool that transitions a document from draft to published status.\n *\n * @param draftCollections - Set of collection slugs that support drafts\n */\nexport function createPublishDraftTool(draftCollections: Set<string>) {\n  return {\n    name: 'publishDraft',\n    description:\n      'Publish a draft document by transitioning its _status from \"draft\" to \"published\". ' +\n      'Only works on collections that support drafts. Use after creating or editing content ' +\n      'to make it live on the site.',\n    parameters: {\n      collection: z\n        .string()\n        .describe(\n          `The collection slug. Draft-enabled collections: ${[...draftCollections].join(', ') || 'none'}`,\n        ),\n      documentId: z.string().describe('The ID of the document to publish'),\n    },\n    handler: async (\n      args: { collection: string; documentId: string },\n      req: PayloadRequest,\n      _extra: unknown,\n    ) => {\n      const { collection, documentId } = args\n\n      if (!draftCollections.has(collection)) {\n        return {\n          content: [\n            {\n              type: 'text' as const,\n              text: `Error: Collection \"${collection}\" does not support drafts. ` +\n                `Draft-enabled collections: ${[...draftCollections].join(', ') || 'none'}`,\n            },\n          ],\n        }\n      }\n\n      req.context = { ...req.context, source: 'mcp' }\n\n      try {\n        const doc = await req.payload.update({\n          collection: collection as any,\n          id: documentId,\n          data: { _status: 'published' } as any,\n          req,\n          overrideAccess: false,\n          user: req.user,\n        })\n\n        const displayName =\n          (doc as any).name ||\n          (doc as any).title ||\n          (doc as any).slug ||\n          documentId\n\n        return {\n          content: [\n            {\n              type: 'text' as const,\n              text: `Successfully published \"${displayName}\" in ${collection} (ID: ${documentId}).`,\n            },\n          ],\n        }\n      } catch (error) {\n        const message = error instanceof Error ? error.message : String(error)\n        return {\n          content: [\n            {\n              type: 'text' as const,\n              text: `Error publishing document ${documentId} in ${collection}: ${message}`,\n            },\n          ],\n        }\n      }\n    },\n  }\n}\n"],"names":["z","createPublishDraftTool","draftCollections","name","description","parameters","collection","string","describe","join","documentId","handler","args","req","_extra","has","content","type","text","context","source","doc","payload","update","id","data","_status","overrideAccess","user","displayName","title","slug","error","message","Error","String"],"mappings":"AAAA,SAASA,CAAC,QAAQ,MAAK;AAGvB;;;;CAIC,GACD,OAAO,SAASC,uBAAuBC,gBAA6B;IAClE,OAAO;QACLC,MAAM;QACNC,aACE,wFACA,0FACA;QACFC,YAAY;YACVC,YAAYN,EACTO,MAAM,GACNC,QAAQ,CACP,CAAC,gDAAgD,EAAE;mBAAIN;aAAiB,CAACO,IAAI,CAAC,SAAS,QAAQ;YAEnGC,YAAYV,EAAEO,MAAM,GAAGC,QAAQ,CAAC;QAClC;QACAG,SAAS,OACPC,MACAC,KACAC;YAEA,MAAM,EAAER,UAAU,EAAEI,UAAU,EAAE,GAAGE;YAEnC,IAAI,CAACV,iBAAiBa,GAAG,CAACT,aAAa;gBACrC,OAAO;oBACLU,SAAS;wBACP;4BACEC,MAAM;4BACNC,MAAM,CAAC,mBAAmB,EAAEZ,WAAW,2BAA2B,CAAC,GACjE,CAAC,2BAA2B,EAAE;mCAAIJ;6BAAiB,CAACO,IAAI,CAAC,SAAS,QAAQ;wBAC9E;qBACD;gBACH;YACF;YAEAI,IAAIM,OAAO,GAAG;gBAAE,GAAGN,IAAIM,OAAO;gBAAEC,QAAQ;YAAM;YAE9C,IAAI;gBACF,MAAMC,MAAM,MAAMR,IAAIS,OAAO,CAACC,MAAM,CAAC;oBACnCjB,YAAYA;oBACZkB,IAAId;oBACJe,MAAM;wBAAEC,SAAS;oBAAY;oBAC7Bb;oBACAc,gBAAgB;oBAChBC,MAAMf,IAAIe,IAAI;gBAChB;gBAEA,MAAMC,cACJ,AAACR,IAAYlB,IAAI,IACjB,AAACkB,IAAYS,KAAK,IAClB,AAACT,IAAYU,IAAI,IACjBrB;gBAEF,OAAO;oBACLM,SAAS;wBACP;4BACEC,MAAM;4BACNC,MAAM,CAAC,wBAAwB,EAAEW,YAAY,KAAK,EAAEvB,WAAW,MAAM,EAAEI,WAAW,EAAE,CAAC;wBACvF;qBACD;gBACH;YACF,EAAE,OAAOsB,OAAO;gBACd,MAAMC,UAAUD,iBAAiBE,QAAQF,MAAMC,OAAO,GAAGE,OAAOH;gBAChE,OAAO;oBACLhB,SAAS;wBACP;4BACEC,MAAM;4BACNC,MAAM,CAAC,0BAA0B,EAAER,WAAW,IAAI,EAAEJ,WAAW,EAAE,EAAE2B,SAAS;wBAC9E;qBACD;gBACH;YACF;QACF;IACF;AACF"}

package/dist/tools/resolve-reference.d.ts

@@ -0,0 +1,31 @@
+import { z } from 'zod';
+import type { PayloadRequest } from 'payload';
+/**
+ * Creates the resolveReference MCP tool that searches collections by
+ * natural language terms and returns ranked document ID candidates.
+ *
+ * @param searchableCollections - Map of collection slug → searchable field names
+ */
+export declare function createResolveReferenceTool(searchableCollections: Map<string, string[]>): {
+    name: string;
+    description: string;
+    parameters: z.ZodObject<{
+        query: z.ZodString;
+        collection: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        query: string;
+        collection?: string | undefined;
+    }, {
+        query: string;
+        collection?: string | undefined;
+    }>;
+    handler: (args: {
+        query: string;
+        collection?: string;
+    }, req: PayloadRequest) => Promise<{
+        content: {
+            type: "text";
+            text: string;
+        }[];
+    }>;
+};

package/dist/tools/resolve-reference.js

@@ -0,0 +1,169 @@
+import { z } from 'zod';
+/**
+ * Creates the resolveReference MCP tool that searches collections by
+ * natural language terms and returns ranked document ID candidates.
+ *
+ * @param searchableCollections - Map of collection slug → searchable field names
+ */ export function createResolveReferenceTool(searchableCollections) {
+    return {
+        name: 'resolveReference',
+        description: 'Search for documents across collections by name, title, or slug. ' + 'Returns ranked candidates with IDs for use in relationship fields. ' + 'Optionally filter to a specific collection.',
+        parameters: z.object({
+            query: z.string().describe('Search term to match against name, title, or slug fields'),
+            collection: z.string().optional().describe('Optional collection slug to restrict search to a single collection')
+        }),
+        handler: async (args, req)=>{
+            req.context = {
+                ...req.context,
+                source: 'mcp'
+            };
+            const { query, collection } = args;
+            const collectionsToSearch = collection ? new Map(searchableCollections.has(collection) ? [
+                [
+                    collection,
+                    searchableCollections.get(collection)
+                ]
+            ] : []) : searchableCollections;
+            if (collectionsToSearch.size === 0) {
+                const available = Array.from(searchableCollections.keys()).join(', ');
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: JSON.stringify({
+                                candidates: [],
+                                message: collection ? `Collection "${collection}" has no searchable fields or does not exist. Available searchable collections: ${available}` : 'No searchable collections found.'
+                            })
+                        }
+                    ]
+                };
+            }
+            const allCandidates = [];
+            for (const [slug, fields] of collectionsToSearch){
+                const orConditions = fields.map((field)=>({
+                        [field]: {
+                            like: query
+                        }
+                    }));
+                if (orConditions.length === 0) continue;
+                const selectFields = {};
+                for (const field of fields){
+                    selectFields[field] = true;
+                }
+                try {
+                    const result = await req.payload.find({
+                        collection: slug,
+                        where: {
+                            or: orConditions
+                        },
+                        limit: 5,
+                        select: selectFields,
+                        req,
+                        overrideAccess: false,
+                        user: req.user
+                    });
+                    for (const doc of result.docs){
+                        const candidates = rankDocument(doc, slug, fields, query);
+                        allCandidates.push(...candidates);
+                    }
+                } catch  {
+                    continue;
+                }
+            }
+            // Sort: exact-slug > exact > partial
+            allCandidates.sort((a, b)=>{
+                const order = {
+                    'exact-slug': 0,
+                    exact: 1,
+                    partial: 2
+                };
+                return order[a.matchType] - order[b.matchType];
+            });
+            const grouped = {};
+            for (const candidate of allCandidates){
+                const { collection: col, ...rest } = candidate;
+                if (!grouped[col]) grouped[col] = [];
+                grouped[col].push(rest);
+            }
+            if (allCandidates.length === 0) {
+                const searched = Array.from(collectionsToSearch.keys()).join(', ');
+                const available = Array.from(searchableCollections.keys()).join(', ');
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: JSON.stringify({
+                                candidates: {},
+                                message: `No results found for "${query}" in: ${searched}. Try a different spelling or search term. All searchable collections: ${available}`
+                            })
+                        }
+                    ]
+                };
+            }
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: JSON.stringify({
+                            candidates: grouped,
+                            total: allCandidates.length
+                        })
+                    }
+                ]
+            };
+        }
+    };
+}
+function rankDocument(doc, collection, fields, query) {
+    const queryLower = query.toLowerCase();
+    let bestMatch = null;
+    for (const field of fields){
+        const value = doc[field];
+        if (typeof value !== 'string') continue;
+        const valueLower = value.toLowerCase();
+        let matchType;
+        if (field === 'slug' && valueLower === queryLower) {
+            matchType = 'exact-slug';
+        } else if (valueLower === queryLower) {
+            matchType = 'exact';
+        } else {
+            matchType = 'partial';
+        }
+        if (!bestMatch || matchTypePriority(matchType) < matchTypePriority(bestMatch.matchType)) {
+            bestMatch = {
+                collection,
+                id: doc.id,
+                displayName: getDisplayName(doc, fields),
+                matchedField: field,
+                matchType
+            };
+        }
+    }
+    return bestMatch ? [
+        bestMatch
+    ] : [];
+}
+function matchTypePriority(type) {
+    switch(type){
+        case 'exact-slug':
+            return 0;
+        case 'exact':
+            return 1;
+        case 'partial':
+            return 2;
+    }
+}
+function getDisplayName(doc, fields) {
+    for (const preferred of [
+        'name',
+        'title',
+        'slug'
+    ]){
+        if (fields.includes(preferred) && typeof doc[preferred] === 'string') {
+            return doc[preferred];
+        }
+    }
+    return String(doc.id);
+}
+
+//# sourceMappingURL=resolve-reference.js.map

package/dist/tools/resolve-reference.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/tools/resolve-reference.ts"],"sourcesContent":["import { z } from 'zod'\nimport type { PayloadRequest } from 'payload'\n\ninterface MatchCandidate {\n  collection: string\n  id: string | number\n  displayName: string\n  matchedField: string\n  matchType: 'exact-slug' | 'exact' | 'partial'\n}\n\n/**\n * Creates the resolveReference MCP tool that searches collections by\n * natural language terms and returns ranked document ID candidates.\n *\n * @param searchableCollections - Map of collection slug → searchable field names\n */\nexport function createResolveReferenceTool(\n  searchableCollections: Map<string, string[]>,\n) {\n  return {\n    name: 'resolveReference',\n    description:\n      'Search for documents across collections by name, title, or slug. ' +\n      'Returns ranked candidates with IDs for use in relationship fields. ' +\n      'Optionally filter to a specific collection.',\n    parameters: z.object({\n      query: z.string().describe('Search term to match against name, title, or slug fields'),\n      collection: z\n        .string()\n        .optional()\n        .describe('Optional collection slug to restrict search to a single collection'),\n    }),\n    handler: async (args: { query: string; collection?: string }, req: PayloadRequest) => {\n      req.context = { ...req.context, source: 'mcp' }\n\n      const { query, collection } = args\n\n      const collectionsToSearch = collection\n        ? new Map(\n            searchableCollections.has(collection)\n              ? [[collection, searchableCollections.get(collection)!]]\n              : [],\n          )\n        : searchableCollections\n\n      if (collectionsToSearch.size === 0) {\n        const available = Array.from(searchableCollections.keys()).join(', ')\n        return {\n          content: [\n            {\n              type: 'text' as const,\n              text: JSON.stringify({\n                candidates: [],\n                message: collection\n                  ? `Collection \"${collection}\" has no searchable fields or does not exist. Available searchable collections: ${available}`\n                  : 'No searchable collections found.',\n              }),\n            },\n          ],\n        }\n      }\n\n      const allCandidates: MatchCandidate[] = []\n\n      for (const [slug, fields] of collectionsToSearch) {\n        const orConditions = fields.map((field) => ({\n          [field]: { like: query },\n        }))\n\n        if (orConditions.length === 0) continue\n\n        const selectFields: Record<string, true> = {}\n        for (const field of fields) {\n          selectFields[field] = true\n        }\n\n        try {\n          const result = await req.payload.find({\n            collection: slug as any,\n            where: { or: orConditions },\n            limit: 5,\n            select: selectFields,\n            req,\n            overrideAccess: false,\n            user: req.user,\n          })\n\n          for (const doc of result.docs) {\n            const candidates = rankDocument(doc, slug, fields, query)\n            allCandidates.push(...candidates)\n          }\n        } catch {\n          // Skip collections that fail (e.g. permission errors)\n          continue\n        }\n      }\n\n      // Sort: exact-slug > exact > partial\n      allCandidates.sort((a, b) => {\n        const order: Record<string, number> = {\n          'exact-slug': 0,\n          exact: 1,\n          partial: 2,\n        }\n        return order[a.matchType] - order[b.matchType]\n      })\n\n      const grouped: Record<string, Omit<MatchCandidate, 'collection'>[]> = {}\n      for (const candidate of allCandidates) {\n        const { collection: col, ...rest } = candidate\n        if (!grouped[col]) grouped[col] = []\n        grouped[col].push(rest)\n      }\n\n      if (allCandidates.length === 0) {\n        const searched = Array.from(collectionsToSearch.keys()).join(', ')\n        const available = Array.from(searchableCollections.keys()).join(', ')\n        return {\n          content: [\n            {\n              type: 'text' as const,\n              text: JSON.stringify({\n                candidates: {},\n                message: `No results found for \"${query}\" in: ${searched}. Try a different spelling or search term. All searchable collections: ${available}`,\n              }),\n            },\n          ],\n        }\n      }\n\n      return {\n        content: [\n          {\n            type: 'text' as const,\n            text: JSON.stringify({\n              candidates: grouped,\n              total: allCandidates.length,\n            }),\n          },\n        ],\n      }\n    },\n  }\n}\n\nfunction rankDocument(\n  doc: Record<string, any>,\n  collection: string,\n  fields: string[],\n  query: string,\n): MatchCandidate[] {\n  const queryLower = query.toLowerCase()\n  let bestMatch: MatchCandidate | null = null\n\n  for (const field of fields) {\n    const value = doc[field]\n    if (typeof value !== 'string') continue\n\n    const valueLower = value.toLowerCase()\n    let matchType: MatchCandidate['matchType']\n\n    if (field === 'slug' && valueLower === queryLower) {\n      matchType = 'exact-slug'\n    } else if (valueLower === queryLower) {\n      matchType = 'exact'\n    } else {\n      matchType = 'partial'\n    }\n\n    if (\n      !bestMatch ||\n      matchTypePriority(matchType) < matchTypePriority(bestMatch.matchType)\n    ) {\n      bestMatch = {\n        collection,\n        id: doc.id,\n        displayName: getDisplayName(doc, fields),\n        matchedField: field,\n        matchType,\n      }\n    }\n  }\n\n  return bestMatch ? [bestMatch] : []\n}\n\nfunction matchTypePriority(type: MatchCandidate['matchType']): number {\n  switch (type) {\n    case 'exact-slug':\n      return 0\n    case 'exact':\n      return 1\n    case 'partial':\n      return 2\n  }\n}\n\nfunction getDisplayName(doc: Record<string, any>, fields: string[]): string {\n  for (const preferred of ['name', 'title', 'slug']) {\n    if (fields.includes(preferred) && typeof doc[preferred] === 'string') {\n      return doc[preferred]\n    }\n  }\n  return String(doc.id)\n}\n"],"names":["z","createResolveReferenceTool","searchableCollections","name","description","parameters","object","query","string","describe","collection","optional","handler","args","req","context","source","collectionsToSearch","Map","has","get","size","available","Array","from","keys","join","content","type","text","JSON","stringify","candidates","message","allCandidates","slug","fields","orConditions","map","field","like","length","selectFields","result","payload","find","where","or","limit","select","overrideAccess","user","doc","docs","rankDocument","push","sort","a","b","order","exact","partial","matchType","grouped","candidate","col","rest","searched","total","queryLower","toLowerCase","bestMatch","value","valueLower","matchTypePriority","id","displayName","getDisplayName","matchedField","preferred","includes","String"],"mappings":"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"}

package/dist/tools/safe-delete.d.ts

@@ -0,0 +1,37 @@
+import { z } from 'zod';
+import type { PayloadRequest } from 'payload';
+import type { RelationshipEdge } from '../types';
+/**
+ * Creates the safeDelete MCP tool that wraps the official delete operation
+ * with a relationship-graph pre-check.
+ *
+ * Workflow:
+ * 1. Use the introspected relationshipGraph to find every (collection, field)
+ *    pair that points TO the target collection.
+ * 2. For each, query for documents that reference the target ID. Aggregate counts
+ *    and a small sample of inbound document IDs.
+ * 3. If any inbound references exist and `confirm` is false, refuse and return
+ *    the impact summary so the caller (or the LLM driving it) can decide.
+ * 4. If `confirm` is true OR there are no inbound references, perform the delete.
+ *
+ * Excludes built-in Payload bookkeeping collections from the inbound search.
+ */
+export declare function createSafeDeleteTool(relationships: RelationshipEdge[]): {
+    name: string;
+    description: string;
+    parameters: {
+        collection: z.ZodString;
+        documentId: z.ZodString;
+        confirm: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+    };
+    handler: (args: {
+        collection: string;
+        documentId: string;
+        confirm?: boolean;
+    }, req: PayloadRequest, _extra: unknown) => Promise<{
+        content: {
+            type: "text";
+            text: string;
+        }[];
+    }>;
+};