payload-mcp-toolkit 0.2.0

package/dist/tools/safe-delete.js

@@ -0,0 +1,161 @@
+import { z } from 'zod';
+const SAMPLE_LIMIT = 5;
+/**
+ * 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 function createSafeDeleteTool(relationships) {
+    // Build a reverse index: target collection -> [(fromCollection, fieldName, hasMany)]
+    const reverseIndex = new Map();
+    for (const edge of relationships){
+        const targets = Array.isArray(edge.toCollection) ? edge.toCollection : [
+            edge.toCollection
+        ];
+        for (const target of targets){
+            if (!reverseIndex.has(target)) reverseIndex.set(target, []);
+            reverseIndex.get(target).push({
+                fromCollection: edge.fromCollection,
+                fieldName: edge.fieldName,
+                hasMany: edge.hasMany
+            });
+        }
+    }
+    return {
+        name: 'safeDelete',
+        description: 'Delete a document only after checking for inbound relationships. ' + 'If other documents reference the target, the delete is refused unless `confirm` is true. ' + 'Use this in preference to the raw delete tools when removing entities that other content might depend on ' + '(authors, categories, media, locations, etc.). Returns the impact summary either way.',
+        parameters: {
+            collection: z.string().describe('Slug of the collection containing the document to delete'),
+            documentId: z.string().describe('ID of the document to delete'),
+            confirm: z.boolean().optional().default(false).describe('If false (default), refuse to delete when inbound references exist and return the impact summary. ' + 'Pass true to delete anyway after reviewing the impact.')
+        },
+        handler: async (args, req, _extra)=>{
+            const { collection, documentId, confirm = false } = args;
+            req.context = {
+                ...req.context,
+                source: 'mcp'
+            };
+            // Find inbound references via the reverse index
+            const inboundEdges = reverseIndex.get(collection) ?? [];
+            const references = [];
+            const failedEdges = [];
+            for (const edge of inboundEdges){
+                // Skip Payload's internal bookkeeping collections — they don't represent meaningful editor concerns
+                if (edge.fromCollection.startsWith('payload-')) continue;
+                try {
+                    const result = await req.payload.find({
+                        collection: edge.fromCollection,
+                        where: {
+                            [edge.fieldName]: {
+                                equals: documentId
+                            }
+                        },
+                        limit: SAMPLE_LIMIT,
+                        select: {
+                            id: true
+                        },
+                        // CRITICAL: include drafts. Without this, a draft document referencing
+                        // the target is invisible to the safety check and the delete is allowed
+                        // through — exactly the failure mode this tool is supposed to prevent.
+                        draft: true,
+                        req,
+                        overrideAccess: false,
+                        user: req.user
+                    });
+                    if (result.totalDocs > 0) {
+                        references.push({
+                            fromCollection: edge.fromCollection,
+                            fieldName: edge.fieldName,
+                            count: result.totalDocs,
+                            sampleIds: result.docs.map((d)=>d.id)
+                        });
+                    }
+                } catch (error) {
+                    // Fail closed: an unverified edge means we don't actually know whether
+                    // the target is referenced. Record it and refuse the delete unless the
+                    // caller explicitly opts in via `confirm: true`.
+                    failedEdges.push({
+                        fromCollection: edge.fromCollection,
+                        fieldName: edge.fieldName,
+                        error: error instanceof Error ? error.message : String(error)
+                    });
+                }
+            }
+            if (failedEdges.length > 0 && !confirm) {
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: JSON.stringify({
+                                success: false,
+                                refused: true,
+                                message: `Refusing to delete ${collection}#${documentId}: could not verify ` + `${failedEdges.length} inbound reference path(s). Pass confirm=true to delete anyway.`,
+                                unverifiedEdges: failedEdges
+                            })
+                        }
+                    ]
+                };
+            }
+            const totalReferences = references.reduce((sum, r)=>sum + r.count, 0);
+            if (totalReferences > 0 && !confirm) {
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: JSON.stringify({
+                                success: false,
+                                refused: true,
+                                message: `Refusing to delete ${collection}#${documentId}: ${totalReferences} inbound reference(s) ` + `found across ${references.length} field path(s). Pass confirm=true to delete anyway.`,
+                                totalReferences,
+                                references
+                            })
+                        }
+                    ]
+                };
+            }
+            try {
+                await req.payload.delete({
+                    collection: collection,
+                    id: documentId,
+                    req,
+                    overrideAccess: false,
+                    user: req.user
+                });
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: JSON.stringify({
+                                success: true,
+                                message: totalReferences > 0 ? `Deleted ${collection}#${documentId} despite ${totalReferences} inbound reference(s) (confirm=true).` : `Deleted ${collection}#${documentId}. No inbound references were found.`,
+                                totalReferences,
+                                references
+                            })
+                        }
+                    ]
+                };
+            } catch (error) {
+                const message = error instanceof Error ? error.message : String(error);
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: `Error deleting ${collection}#${documentId}: ${message}`
+                        }
+                    ]
+                };
+            }
+        }
+    };
+}
+
+//# sourceMappingURL=safe-delete.js.map

package/dist/tools/safe-delete.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/tools/safe-delete.ts"],"sourcesContent":["import { z } from 'zod'\nimport type { PayloadRequest } from 'payload'\nimport type { RelationshipEdge } from '../types'\n\nconst SAMPLE_LIMIT = 5\n\ninterface InboundReference {\n  fromCollection: string\n  fieldName: string\n  count: number\n  sampleIds: (string | number)[]\n}\n\n/**\n * Creates the safeDelete MCP tool that wraps the official delete operation\n * with a relationship-graph pre-check.\n *\n * Workflow:\n * 1. Use the introspected relationshipGraph to find every (collection, field)\n *    pair that points TO the target collection.\n * 2. For each, query for documents that reference the target ID. Aggregate counts\n *    and a small sample of inbound document IDs.\n * 3. If any inbound references exist and `confirm` is false, refuse and return\n *    the impact summary so the caller (or the LLM driving it) can decide.\n * 4. If `confirm` is true OR there are no inbound references, perform the delete.\n *\n * Excludes built-in Payload bookkeeping collections from the inbound search.\n */\nexport function createSafeDeleteTool(relationships: RelationshipEdge[]) {\n  // Build a reverse index: target collection -> [(fromCollection, fieldName, hasMany)]\n  const reverseIndex = new Map<\n    string,\n    Array<{ fromCollection: string; fieldName: string; hasMany: boolean }>\n  >()\n\n  for (const edge of relationships) {\n    const targets = Array.isArray(edge.toCollection) ? edge.toCollection : [edge.toCollection]\n    for (const target of targets) {\n      if (!reverseIndex.has(target)) reverseIndex.set(target, [])\n      reverseIndex.get(target)!.push({\n        fromCollection: edge.fromCollection,\n        fieldName: edge.fieldName,\n        hasMany: edge.hasMany,\n      })\n    }\n  }\n\n  return {\n    name: 'safeDelete',\n    description:\n      'Delete a document only after checking for inbound relationships. ' +\n      'If other documents reference the target, the delete is refused unless `confirm` is true. ' +\n      'Use this in preference to the raw delete tools when removing entities that other content might depend on ' +\n      '(authors, categories, media, locations, etc.). Returns the impact summary either way.',\n    parameters: {\n      collection: z.string().describe('Slug of the collection containing the document to delete'),\n      documentId: z.string().describe('ID of the document to delete'),\n      confirm: z\n        .boolean()\n        .optional()\n        .default(false)\n        .describe(\n          'If false (default), refuse to delete when inbound references exist and return the impact summary. ' +\n          'Pass true to delete anyway after reviewing the impact.',\n        ),\n    },\n    handler: async (\n      args: { collection: string; documentId: string; confirm?: boolean },\n      req: PayloadRequest,\n      _extra: unknown,\n    ) => {\n      const { collection, documentId, confirm = false } = args\n\n      req.context = { ...req.context, source: 'mcp' }\n\n      // Find inbound references via the reverse index\n      const inboundEdges = reverseIndex.get(collection) ?? []\n      const references: InboundReference[] = []\n      const failedEdges: { fromCollection: string; fieldName: string; error: string }[] = []\n\n      for (const edge of inboundEdges) {\n        // Skip Payload's internal bookkeeping collections — they don't represent meaningful editor concerns\n        if (edge.fromCollection.startsWith('payload-')) continue\n\n        try {\n          const result = await req.payload.find({\n            collection: edge.fromCollection as any,\n            where: { [edge.fieldName]: { equals: documentId } } as any,\n            limit: SAMPLE_LIMIT,\n            select: { id: true } as any,\n            // CRITICAL: include drafts. Without this, a draft document referencing\n            // the target is invisible to the safety check and the delete is allowed\n            // through — exactly the failure mode this tool is supposed to prevent.\n            draft: true,\n            req,\n            overrideAccess: false,\n            user: req.user,\n          })\n\n          if (result.totalDocs > 0) {\n            references.push({\n              fromCollection: edge.fromCollection,\n              fieldName: edge.fieldName,\n              count: result.totalDocs,\n              sampleIds: result.docs.map((d: any) => d.id),\n            })\n          }\n        } catch (error) {\n          // Fail closed: an unverified edge means we don't actually know whether\n          // the target is referenced. Record it and refuse the delete unless the\n          // caller explicitly opts in via `confirm: true`.\n          failedEdges.push({\n            fromCollection: edge.fromCollection,\n            fieldName: edge.fieldName,\n            error: error instanceof Error ? error.message : String(error),\n          })\n        }\n      }\n\n      if (failedEdges.length > 0 && !confirm) {\n        return {\n          content: [\n            {\n              type: 'text' as const,\n              text: JSON.stringify({\n                success: false,\n                refused: true,\n                message:\n                  `Refusing to delete ${collection}#${documentId}: could not verify ` +\n                  `${failedEdges.length} inbound reference path(s). Pass confirm=true to delete anyway.`,\n                unverifiedEdges: failedEdges,\n              }),\n            },\n          ],\n        }\n      }\n\n      const totalReferences = references.reduce((sum, r) => sum + r.count, 0)\n\n      if (totalReferences > 0 && !confirm) {\n        return {\n          content: [\n            {\n              type: 'text' as const,\n              text: JSON.stringify({\n                success: false,\n                refused: true,\n                message:\n                  `Refusing to delete ${collection}#${documentId}: ${totalReferences} inbound reference(s) ` +\n                  `found across ${references.length} field path(s). Pass confirm=true to delete anyway.`,\n                totalReferences,\n                references,\n              }),\n            },\n          ],\n        }\n      }\n\n      try {\n        await req.payload.delete({\n          collection: collection as any,\n          id: documentId,\n          req,\n          overrideAccess: false,\n          user: req.user,\n        })\n\n        return {\n          content: [\n            {\n              type: 'text' as const,\n              text: JSON.stringify({\n                success: true,\n                message:\n                  totalReferences > 0\n                    ? `Deleted ${collection}#${documentId} despite ${totalReferences} inbound reference(s) (confirm=true).`\n                    : `Deleted ${collection}#${documentId}. No inbound references were found.`,\n                totalReferences,\n                references,\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 deleting ${collection}#${documentId}: ${message}`,\n            },\n          ],\n        }\n      }\n    },\n  }\n}\n"],"names":["z","SAMPLE_LIMIT","createSafeDeleteTool","relationships","reverseIndex","Map","edge","targets","Array","isArray","toCollection","target","has","set","get","push","fromCollection","fieldName","hasMany","name","description","parameters","collection","string","describe","documentId","confirm","boolean","optional","default","handler","args","req","_extra","context","source","inboundEdges","references","failedEdges","startsWith","result","payload","find","where","equals","limit","select","id","draft","overrideAccess","user","totalDocs","count","sampleIds","docs","map","d","error","Error","message","String","length","content","type","text","JSON","stringify","success","refused","unverifiedEdges","totalReferences","reduce","sum","r","delete"],"mappings":"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"}

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

@@ -0,0 +1,49 @@
+import { z } from 'zod';
+import type { PayloadRequest } from 'payload';
+import type { CollectionSchema } from '../types';
+/**
+ * Creates the schedulePublish MCP tool that stamps a future publish time
+ * on a draft document.
+ *
+ * IMPORTANT: This tool ONLY sets `publishedAt` to a future date and keeps
+ * `_status: 'draft'`. It does NOT itself flip the draft to published when
+ * the time arrives. The consumer's Payload config must own the actual flip,
+ * via one of:
+ *
+ *   1. A Payload Jobs Queue scheduled task that runs periodically and finds
+ *      drafts whose `publishedAt <= now`, then calls `payload.update` with
+ *      `_status: 'published'`. This is the canonical Payload-3 approach
+ *      (see https://payloadcms.com/docs/jobs-queue/scheduled-jobs).
+ *
+ *   2. An external cron / worker that does the same query + update.
+ *
+ *   3. A `beforeRead` hook on the collection that resolves status on the fly.
+ *
+ * Without one of those, scheduled drafts remain drafts forever — the tool
+ * tells the LLM exactly that in its response so the user doesn't get a
+ * silent surprise.
+ *
+ * Skip-detects: only registered for collections that have BOTH drafts AND a
+ * `publishedAt` field in their schema. Otherwise the tool is omitted entirely.
+ */
+export declare function createSchedulePublishTool(collectionSchemas: Map<string, CollectionSchema>, draftCollections: Set<string>): ReturnType<typeof buildTool> | null;
+declare function buildTool(schedulableSlugs: string[]): {
+    name: string;
+    description: string;
+    parameters: {
+        collection: z.ZodString;
+        documentId: z.ZodString;
+        publishAt: z.ZodString;
+    };
+    handler: (args: {
+        collection: string;
+        documentId: string;
+        publishAt: string;
+    }, req: PayloadRequest, _extra: unknown) => Promise<{
+        content: {
+            type: "text";
+            text: string;
+        }[];
+    }>;
+};
+export {};

package/dist/tools/schedule-publish.js

@@ -0,0 +1,120 @@
+import { z } from 'zod';
+/**
+ * Creates the schedulePublish MCP tool that stamps a future publish time
+ * on a draft document.
+ *
+ * IMPORTANT: This tool ONLY sets `publishedAt` to a future date and keeps
+ * `_status: 'draft'`. It does NOT itself flip the draft to published when
+ * the time arrives. The consumer's Payload config must own the actual flip,
+ * via one of:
+ *
+ *   1. A Payload Jobs Queue scheduled task that runs periodically and finds
+ *      drafts whose `publishedAt <= now`, then calls `payload.update` with
+ *      `_status: 'published'`. This is the canonical Payload-3 approach
+ *      (see https://payloadcms.com/docs/jobs-queue/scheduled-jobs).
+ *
+ *   2. An external cron / worker that does the same query + update.
+ *
+ *   3. A `beforeRead` hook on the collection that resolves status on the fly.
+ *
+ * Without one of those, scheduled drafts remain drafts forever — the tool
+ * tells the LLM exactly that in its response so the user doesn't get a
+ * silent surprise.
+ *
+ * Skip-detects: only registered for collections that have BOTH drafts AND a
+ * `publishedAt` field in their schema. Otherwise the tool is omitted entirely.
+ */ export function createSchedulePublishTool(collectionSchemas, draftCollections) {
+    const schedulableSlugs = [];
+    for (const slug of draftCollections){
+        const schema = collectionSchemas.get(slug);
+        if (!schema) continue;
+        const hasPublishedAt = schema.fields.some((f)=>f.name === 'publishedAt' && f.type === 'date');
+        if (hasPublishedAt) schedulableSlugs.push(slug);
+    }
+    if (schedulableSlugs.length === 0) return null;
+    return buildTool(schedulableSlugs);
+}
+function buildTool(schedulableSlugs) {
+    return {
+        name: 'schedulePublish',
+        description: 'Schedule a draft to be published at a future date by stamping its publishedAt field. ' + 'The document stays in draft status until your Payload jobs queue (or an external worker) ' + 'flips it. If your project does not have a scheduled job that publishes drafts whose ' + 'publishedAt has passed, the document will remain a draft indefinitely. ' + `Schedulable collections (have both drafts and a publishedAt date field): ${schedulableSlugs.join(', ')}.`,
+        parameters: {
+            collection: z.string().describe(`The collection slug. One of: ${schedulableSlugs.join(', ')}`),
+            documentId: z.string().describe('The ID of the draft document to schedule'),
+            publishAt: z.string().describe('ISO 8601 date-time when the document should be published, e.g. "2026-06-01T09:00:00Z". ' + 'Must be in the future.')
+        },
+        handler: async (args, req, _extra)=>{
+            const { collection, documentId, publishAt } = args;
+            if (!schedulableSlugs.includes(collection)) {
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: `Error: Collection "${collection}" is not schedulable. ` + `Schedulable collections: ${schedulableSlugs.join(', ')}. ` + 'A collection is schedulable when it has draft support AND a date field named "publishedAt".'
+                        }
+                    ]
+                };
+            }
+            const parsed = new Date(publishAt);
+            if (isNaN(parsed.getTime())) {
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: `Error: "${publishAt}" is not a valid ISO 8601 date-time. Example: "2026-06-01T09:00:00Z"`
+                        }
+                    ]
+                };
+            }
+            if (parsed.getTime() <= Date.now()) {
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: `Error: publishAt (${parsed.toISOString()}) is not in the future. ` + `Use the publishDraft tool to publish immediately instead.`
+                        }
+                    ]
+                };
+            }
+            req.context = {
+                ...req.context,
+                source: 'mcp'
+            };
+            try {
+                const updated = await req.payload.update({
+                    collection: collection,
+                    id: documentId,
+                    data: {
+                        publishedAt: parsed.toISOString(),
+                        _status: 'draft'
+                    },
+                    draft: true,
+                    req,
+                    overrideAccess: false,
+                    user: req.user
+                });
+                const displayName = updated.name || updated.title || updated.slug || documentId;
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: `Scheduled "${displayName}" (${collection}#${documentId}) for publish at ${parsed.toISOString()}. ` + `The document will remain a draft until a scheduled job (Payload jobs queue or external worker) ` + `flips its _status to "published". If your project has not configured such a job, the document ` + `will stay a draft indefinitely — see the Payload jobs queue docs for the canonical setup.`
+                        }
+                    ]
+                };
+            } catch (error) {
+                const message = error instanceof Error ? error.message : String(error);
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: `Error scheduling ${collection}#${documentId}: ${message}`
+                        }
+                    ]
+                };
+            }
+        }
+    };
+}
+
+//# sourceMappingURL=schedule-publish.js.map

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

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/tools/schedule-publish.ts"],"sourcesContent":["import { z } from 'zod'\nimport type { PayloadRequest } from 'payload'\nimport type { CollectionSchema } from '../types'\n\n/**\n * Creates the schedulePublish MCP tool that stamps a future publish time\n * on a draft document.\n *\n * IMPORTANT: This tool ONLY sets `publishedAt` to a future date and keeps\n * `_status: 'draft'`. It does NOT itself flip the draft to published when\n * the time arrives. The consumer's Payload config must own the actual flip,\n * via one of:\n *\n *   1. A Payload Jobs Queue scheduled task that runs periodically and finds\n *      drafts whose `publishedAt <= now`, then calls `payload.update` with\n *      `_status: 'published'`. This is the canonical Payload-3 approach\n *      (see https://payloadcms.com/docs/jobs-queue/scheduled-jobs).\n *\n *   2. An external cron / worker that does the same query + update.\n *\n *   3. A `beforeRead` hook on the collection that resolves status on the fly.\n *\n * Without one of those, scheduled drafts remain drafts forever — the tool\n * tells the LLM exactly that in its response so the user doesn't get a\n * silent surprise.\n *\n * Skip-detects: only registered for collections that have BOTH drafts AND a\n * `publishedAt` field in their schema. Otherwise the tool is omitted entirely.\n */\nexport function createSchedulePublishTool(\n  collectionSchemas: Map<string, CollectionSchema>,\n  draftCollections: Set<string>,\n): ReturnType<typeof buildTool> | null {\n  const schedulableSlugs: string[] = []\n  for (const slug of draftCollections) {\n    const schema = collectionSchemas.get(slug)\n    if (!schema) continue\n    const hasPublishedAt = schema.fields.some(\n      (f) => f.name === 'publishedAt' && f.type === 'date',\n    )\n    if (hasPublishedAt) schedulableSlugs.push(slug)\n  }\n\n  if (schedulableSlugs.length === 0) return null\n  return buildTool(schedulableSlugs)\n}\n\nfunction buildTool(schedulableSlugs: string[]) {\n  return {\n    name: 'schedulePublish',\n    description:\n      'Schedule a draft to be published at a future date by stamping its publishedAt field. ' +\n      'The document stays in draft status until your Payload jobs queue (or an external worker) ' +\n      'flips it. If your project does not have a scheduled job that publishes drafts whose ' +\n      'publishedAt has passed, the document will remain a draft indefinitely. ' +\n      `Schedulable collections (have both drafts and a publishedAt date field): ${schedulableSlugs.join(', ')}.`,\n    parameters: {\n      collection: z\n        .string()\n        .describe(`The collection slug. One of: ${schedulableSlugs.join(', ')}`),\n      documentId: z.string().describe('The ID of the draft document to schedule'),\n      publishAt: z\n        .string()\n        .describe(\n          'ISO 8601 date-time when the document should be published, e.g. \"2026-06-01T09:00:00Z\". ' +\n          'Must be in the future.',\n        ),\n    },\n    handler: async (\n      args: { collection: string; documentId: string; publishAt: string },\n      req: PayloadRequest,\n      _extra: unknown,\n    ) => {\n      const { collection, documentId, publishAt } = args\n\n      if (!schedulableSlugs.includes(collection)) {\n        return {\n          content: [\n            {\n              type: 'text' as const,\n              text:\n                `Error: Collection \"${collection}\" is not schedulable. ` +\n                `Schedulable collections: ${schedulableSlugs.join(', ')}. ` +\n                'A collection is schedulable when it has draft support AND a date field named \"publishedAt\".',\n            },\n          ],\n        }\n      }\n\n      const parsed = new Date(publishAt)\n      if (isNaN(parsed.getTime())) {\n        return {\n          content: [\n            {\n              type: 'text' as const,\n              text: `Error: \"${publishAt}\" is not a valid ISO 8601 date-time. Example: \"2026-06-01T09:00:00Z\"`,\n            },\n          ],\n        }\n      }\n\n      if (parsed.getTime() <= Date.now()) {\n        return {\n          content: [\n            {\n              type: 'text' as const,\n              text:\n                `Error: publishAt (${parsed.toISOString()}) is not in the future. ` +\n                `Use the publishDraft tool to publish immediately instead.`,\n            },\n          ],\n        }\n      }\n\n      req.context = { ...req.context, source: 'mcp' }\n\n      try {\n        const updated = await req.payload.update({\n          collection: collection as any,\n          id: documentId,\n          data: {\n            publishedAt: parsed.toISOString(),\n            _status: 'draft',\n          } as any,\n          draft: true,\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        return {\n          content: [\n            {\n              type: 'text' as const,\n              text:\n                `Scheduled \"${displayName}\" (${collection}#${documentId}) for publish at ${parsed.toISOString()}. ` +\n                `The document will remain a draft until a scheduled job (Payload jobs queue or external worker) ` +\n                `flips its _status to \"published\". If your project has not configured such a job, the document ` +\n                `will stay a draft indefinitely — see the Payload jobs queue docs for the canonical setup.`,\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 scheduling ${collection}#${documentId}: ${message}`,\n            },\n          ],\n        }\n      }\n    },\n  }\n}\n"],"names":["z","createSchedulePublishTool","collectionSchemas","draftCollections","schedulableSlugs","slug","schema","get","hasPublishedAt","fields","some","f","name","type","push","length","buildTool","description","join","parameters","collection","string","describe","documentId","publishAt","handler","args","req","_extra","includes","content","text","parsed","Date","isNaN","getTime","now","toISOString","context","source","updated","payload","update","id","data","publishedAt","_status","draft","overrideAccess","user","displayName","title","error","message","Error","String"],"mappings":"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"}

package/dist/tools/search-content.d.ts

@@ -0,0 +1,43 @@
+import { z } from 'zod';
+import type { PayloadRequest } from 'payload';
+import type { CollectionSchema } from '../types';
+/**
+ * Creates the searchContent MCP tool — natural-language filters across collections,
+ * built for editor triage tasks that the official find tools don't express well.
+ *
+ * Examples the LLM can drive:
+ *   - "all posts that are still drafts"
+ *   - "pages missing a meta description"
+ *   - "anything updated more than 30 days ago"
+ *   - "posts by jane in the last quarter"
+ *
+ * Returns compact hits per collection — id, displayName, _status, updatedAt, and
+ * (when missingFields was requested) which of those fields are blank on each doc.
+ */
+export declare function createSearchContentTool(collectionSchemas: Map<string, CollectionSchema>): {
+    name: string;
+    description: string;
+    parameters: {
+        collection: z.ZodOptional<z.ZodString>;
+        query: z.ZodOptional<z.ZodString>;
+        status: z.ZodOptional<z.ZodEnum<["draft", "published", "any"]>>;
+        olderThanDays: z.ZodOptional<z.ZodNumber>;
+        newerThanDays: z.ZodOptional<z.ZodNumber>;
+        missingFields: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        limit: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+    };
+    handler: (args: {
+        collection?: string;
+        query?: string;
+        status?: "draft" | "published" | "any";
+        olderThanDays?: number;
+        newerThanDays?: number;
+        missingFields?: string[];
+        limit?: number;
+    }, req: PayloadRequest, _extra: unknown) => Promise<{
+        content: {
+            type: "text";
+            text: string;
+        }[];
+    }>;
+};

package/dist/tools/search-content.js

@@ -0,0 +1,210 @@
+import { z } from 'zod';
+const DEFAULT_LIMIT = 20;
+const HARD_LIMIT = 100;
+/**
+ * Creates the searchContent MCP tool — natural-language filters across collections,
+ * built for editor triage tasks that the official find tools don't express well.
+ *
+ * Examples the LLM can drive:
+ *   - "all posts that are still drafts"
+ *   - "pages missing a meta description"
+ *   - "anything updated more than 30 days ago"
+ *   - "posts by jane in the last quarter"
+ *
+ * Returns compact hits per collection — id, displayName, _status, updatedAt, and
+ * (when missingFields was requested) which of those fields are blank on each doc.
+ */ export function createSearchContentTool(collectionSchemas) {
+    const allSlugs = [
+        ...collectionSchemas.keys()
+    ];
+    return {
+        name: 'searchContent',
+        description: 'Search and filter content across collections by status, age, missing fields, or free-text query. ' + 'Designed for editor triage — finding drafts, stale content, content with missing SEO fields, etc. ' + `Searchable collections: ${allSlugs.join(', ')}.`,
+        parameters: {
+            collection: z.string().optional().describe('Restrict search to a single collection slug. Omit to search all.'),
+            query: z.string().optional().describe('Free-text query matched against name/title/slug fields (case-insensitive).'),
+            status: z.enum([
+                'draft',
+                'published',
+                'any'
+            ]).optional().describe('Filter by draft status. "draft" or "published" only return matching docs; "any" or omitted returns all.'),
+            olderThanDays: z.number().optional().describe('Only docs whose updatedAt is older than this many days.'),
+            newerThanDays: z.number().optional().describe('Only docs whose updatedAt is newer than this many days.'),
+            missingFields: z.array(z.string()).optional().describe('Field names that should be empty/null. Useful for finding e.g. posts without a coverImage. ' + 'Each hit will include a missingFields array confirming which were actually blank.'),
+            limit: z.number().optional().default(DEFAULT_LIMIT).describe(`Maximum hits per collection (default ${DEFAULT_LIMIT}, max ${HARD_LIMIT}).`)
+        },
+        handler: async (args, req, _extra)=>{
+            const { collection, query, status, olderThanDays, newerThanDays, missingFields, limit = DEFAULT_LIMIT } = args;
+            req.context = {
+                ...req.context,
+                source: 'mcp'
+            };
+            const cappedLimit = Math.min(Math.max(1, limit), HARD_LIMIT);
+            // Determine target collections.
+            // When the user filters by a specific draft status, only consider collections
+            // that actually support drafts — other collections are not "draft" or
+            // "published" in any meaningful sense and shouldn't pollute the results.
+            const isDraftStatusFilter = status === 'draft' || status === 'published';
+            const initialTargets = collection ? collectionSchemas.has(collection) ? [
+                collection
+            ] : [] : allSlugs;
+            const targets = isDraftStatusFilter ? initialTargets.filter((slug)=>collectionSchemas.get(slug)?.hasDrafts) : initialTargets;
+            if (targets.length === 0) {
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: JSON.stringify({
+                                hits: {},
+                                message: collection ? `Unknown collection "${collection}". Available: ${allSlugs.join(', ')}` : 'No searchable collections found.'
+                            })
+                        }
+                    ]
+                };
+            }
+            const grouped = {};
+            const stats = {};
+            for (const slug of targets){
+                const schema = collectionSchemas.get(slug);
+                const where = buildWhereClause(schema, {
+                    query,
+                    status,
+                    olderThanDays,
+                    newerThanDays,
+                    missingFields
+                });
+                try {
+                    const result = await req.payload.find({
+                        collection: slug,
+                        where: where,
+                        limit: cappedLimit,
+                        sort: '-updatedAt',
+                        depth: 0,
+                        // Include drafts so status='draft' actually works and so missingFields
+                        // queries against draft-only collections aren't misleadingly empty.
+                        draft: schema.hasDrafts,
+                        req,
+                        overrideAccess: false,
+                        user: req.user
+                    });
+                    if (result.totalDocs > 0) {
+                        stats[slug] = {
+                            totalDocs: result.totalDocs,
+                            returned: result.docs.length
+                        };
+                        grouped[slug] = result.docs.map((doc)=>buildHit(doc, missingFields));
+                    }
+                } catch  {
+                    continue;
+                }
+            }
+            const totalHits = Object.values(grouped).reduce((sum, hits)=>sum + hits.length, 0);
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: JSON.stringify({
+                            totalHits,
+                            stats,
+                            hits: grouped
+                        })
+                    }
+                ]
+            };
+        }
+    };
+}
+function buildHit(doc, missingFields) {
+    const hit = {
+        id: doc.id,
+        displayName: doc.name || doc.title || doc.slug || String(doc.id),
+        status: doc._status,
+        updatedAt: doc.updatedAt
+    };
+    if (missingFields?.length) {
+        hit.missingFields = missingFields.filter((f)=>isFieldEmpty(getByPath(doc, f)));
+    }
+    return hit;
+}
+function getByPath(doc, path) {
+    // Walk dotted paths so `meta.description` reads doc.meta?.description rather
+    // than the literal key `"meta.description"`. Matches the `where` keys we emit.
+    let current = doc;
+    for (const segment of path.split('.')){
+        if (current === null || current === undefined) return undefined;
+        current = current[segment];
+    }
+    return current;
+}
+function isFieldEmpty(value) {
+    if (value === null || value === undefined) return true;
+    if (typeof value === 'string') return value.trim() === '';
+    if (Array.isArray(value)) return value.length === 0;
+    if (typeof value === 'object') return Object.keys(value).length === 0;
+    return false;
+}
+function buildWhereClause(schema, filters) {
+    const and = [];
+    // Free-text query against searchable fields
+    if (filters.query && schema.searchableFields.length > 0) {
+        const or = schema.searchableFields.map((field)=>({
+                [field]: {
+                    like: filters.query
+                }
+            }));
+        and.push({
+            or
+        });
+    }
+    // Status filter (only meaningful on draft-enabled collections)
+    if (filters.status && filters.status !== 'any' && schema.hasDrafts) {
+        and.push({
+            _status: {
+                equals: filters.status
+            }
+        });
+    }
+    // Age filters
+    if (filters.olderThanDays !== undefined) {
+        const cutoff = new Date(Date.now() - filters.olderThanDays * 24 * 60 * 60 * 1000);
+        and.push({
+            updatedAt: {
+                less_than: cutoff.toISOString()
+            }
+        });
+    }
+    if (filters.newerThanDays !== undefined) {
+        const cutoff = new Date(Date.now() - filters.newerThanDays * 24 * 60 * 60 * 1000);
+        and.push({
+            updatedAt: {
+                greater_than: cutoff.toISOString()
+            }
+        });
+    }
+    // Missing-field filter — express as "field is null OR field doesn't exist"
+    if (filters.missingFields?.length) {
+        for (const field of filters.missingFields){
+            and.push({
+                or: [
+                    {
+                        [field]: {
+                            exists: false
+                        }
+                    },
+                    {
+                        [field]: {
+                            equals: null
+                        }
+                    }
+                ]
+            });
+        }
+    }
+    if (and.length === 0) return {};
+    if (and.length === 1) return and[0];
+    return {
+        and
+    };
+}
+
+//# sourceMappingURL=search-content.js.map