payload-mcp-toolkit 0.3.0 → 0.3.1

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

@@ -2,17 +2,17 @@ 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.
+ * safeDelete 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.
+ * 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 can decide.
+ * 4. Otherwise, perform the delete.
  *
  * Excludes built-in Payload bookkeeping collections from the inbound search.
  */
@@ -28,10 +28,5 @@ export declare function createSafeDeleteTool(relationships: RelationshipEdge[]):
         collection: string;
         documentId: string;
         confirm?: boolean;
-    }, req: PayloadRequest, _extra: unknown) => Promise<{
-        content: {
-            type: "text";
-            text: string;
-        }[];
-    }>;
+    }, req: PayloadRequest, _extra: unknown) => Promise<import("./_helpers").McpTextResponse>;
 };

package/dist/tools/safe-delete.js

@@ -1,21 +1,22 @@
 import { z } from 'zod';
+import { errorMessage, jsonResponse, stampMcpContext, textResponse } from './_helpers';
 const SAMPLE_LIMIT = 5;
 /**
- * Creates the safeDelete MCP tool that wraps the official delete operation
- * with a relationship-graph pre-check.
+ * safeDelete 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.
+ * 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 can decide.
+ * 4. Otherwise, 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)]
+    // reverseIndex: target collection slug → edges that reference it
     const reverseIndex = new Map();
     for (const edge of relationships){
         const targets = Array.isArray(edge.toCollection) ? edge.toCollection : [
@@ -40,87 +41,69 @@ const SAMPLE_LIMIT = 5;
         },
         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) ?? [];
+            stampMcpContext(req);
+            const inboundEdges = (reverseIndex.get(collection) ?? []).filter((edge)=>!edge.fromCollection.startsWith('payload-'));
+            const settled = await Promise.allSettled(inboundEdges.map((edge)=>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
+                })));
             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`.
+            settled.forEach((outcome, i)=>{
+                const edge = inboundEdges[i];
+                if (outcome.status === 'rejected') {
+                    // Fail closed: an unverified edge means we don't know whether the
+                    // target is referenced. Refuse the delete unless the caller opts in.
                     failedEdges.push({
                         fromCollection: edge.fromCollection,
                         fieldName: edge.fieldName,
-                        error: error instanceof Error ? error.message : String(error)
+                        error: errorMessage(outcome.reason)
                     });
+                    return;
                 }
-            }
+                const result = outcome.value;
+                if (result.totalDocs > 0) {
+                    references.push({
+                        fromCollection: edge.fromCollection,
+                        fieldName: edge.fieldName,
+                        count: result.totalDocs,
+                        sampleIds: result.docs.map((d)=>d.id)
+                    });
+                }
+            });
             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
-                            })
-                        }
-                    ]
-                };
+                return jsonResponse({
+                    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
-                            })
-                        }
-                    ]
-                };
+                return jsonResponse({
+                    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({
@@ -130,29 +113,14 @@ const SAMPLE_LIMIT = 5;
                     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
-                            })
-                        }
-                    ]
-                };
+                return jsonResponse({
+                    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}`
-                        }
-                    ]
-                };
+                return textResponse(`Error deleting ${collection}#${documentId}: ${errorMessage(error)}`);
             }
         }
     };

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

@@ -1 +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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"}
+{"version":3,"sources":["../../src/tools/safe-delete.ts"],"sourcesContent":["import { z } from 'zod'\nimport type { PayloadRequest } from 'payload'\nimport type { RelationshipEdge } from '../types'\nimport { errorMessage, jsonResponse, stampMcpContext, textResponse } from './_helpers'\n\nconst SAMPLE_LIMIT = 5\n\ninterface InboundReference {\n  fromCollection: string\n  fieldName: string\n  count: number\n  sampleIds: (string | number)[]\n}\n\ninterface ReverseEdge {\n  fromCollection: string\n  fieldName: string\n  hasMany: boolean\n}\n\n/**\n * safeDelete wraps the official delete operation with a relationship-graph\n * 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\n *    counts and a small sample of inbound document IDs.\n * 3. If any inbound references exist and `confirm` is false, refuse and\n *    return the impact summary so the caller can decide.\n * 4. Otherwise, perform the delete.\n *\n * Excludes built-in Payload bookkeeping collections from the inbound search.\n */\nexport function createSafeDeleteTool(relationships: RelationshipEdge[]) {\n  // reverseIndex: target collection slug → edges that reference it\n  const reverseIndex = new Map<string, ReverseEdge[]>()\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      stampMcpContext(req)\n\n      const inboundEdges = (reverseIndex.get(collection) ?? []).filter(\n        (edge) => !edge.fromCollection.startsWith('payload-'),\n      )\n\n      const settled = await Promise.allSettled(\n        inboundEdges.map((edge) =>\n          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\n            // referencing the target is invisible to the safety check and\n            // the delete is allowed through — exactly the failure mode this\n            // tool is supposed to prevent.\n            draft: true,\n            req,\n            overrideAccess: false,\n            user: req.user,\n          }),\n        ),\n      )\n\n      const references: InboundReference[] = []\n      const failedEdges: { fromCollection: string; fieldName: string; error: string }[] = []\n\n      settled.forEach((outcome, i) => {\n        const edge = inboundEdges[i]\n        if (outcome.status === 'rejected') {\n          // Fail closed: an unverified edge means we don't know whether the\n          // target is referenced. Refuse the delete unless the caller opts in.\n          failedEdges.push({\n            fromCollection: edge.fromCollection,\n            fieldName: edge.fieldName,\n            error: errorMessage(outcome.reason),\n          })\n          return\n        }\n        const result = outcome.value\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      })\n\n      if (failedEdges.length > 0 && !confirm) {\n        return jsonResponse({\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      const totalReferences = references.reduce((sum, r) => sum + r.count, 0)\n\n      if (totalReferences > 0 && !confirm) {\n        return jsonResponse({\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      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 jsonResponse({\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      } catch (error) {\n        return textResponse(\n          `Error deleting ${collection}#${documentId}: ${errorMessage(error)}`,\n        )\n      }\n    },\n  }\n}\n"],"names":["z","errorMessage","jsonResponse","stampMcpContext","textResponse","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","inboundEdges","filter","startsWith","settled","Promise","allSettled","map","payload","find","where","equals","limit","select","id","draft","overrideAccess","user","references","failedEdges","forEach","outcome","i","status","error","reason","result","value","totalDocs","count","sampleIds","docs","d","length","success","refused","message","unverifiedEdges","totalReferences","reduce","sum","r","delete"],"mappings":"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"}

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

@@ -2,29 +2,24 @@ 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.
+ * schedulePublish 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:
+ * IMPORTANT: this tool ONLY sets `publishedAt` and keeps `_status: 'draft'`.
+ * It does not flip the status when the time arrives. The consumer's Payload
+ * config must own the actual flip via:
  *
- *   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.
+ *   1. A Payload Jobs Queue scheduled task that finds drafts whose
+ *      `publishedAt <= now` and updates `_status: 'published'`. This is the
+ *      canonical Payload-3 approach (https://payloadcms.com/docs/jobs-queue/scheduled-jobs).
+ *   2. An external cron / worker doing the same query + update.
+ *   3. A `beforeRead` hook 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.
+ * `publishedAt` date field.
  */
 export declare function createSchedulePublishTool(collectionSchemas: Map<string, CollectionSchema>, draftCollections: Set<string>): ReturnType<typeof buildTool> | null;
 declare function buildTool(schedulableSlugs: string[]): {
@@ -39,11 +34,6 @@ declare function buildTool(schedulableSlugs: string[]): {
         collection: string;
         documentId: string;
         publishAt: string;
-    }, req: PayloadRequest, _extra: unknown) => Promise<{
-        content: {
-            type: "text";
-            text: string;
-        }[];
-    }>;
+    }, req: PayloadRequest, _extra: unknown) => Promise<import("./_helpers").McpTextResponse>;
 };
 export {};

package/dist/tools/schedule-publish.js

@@ -1,28 +1,24 @@
 import { z } from 'zod';
+import { errorMessage, getDocDisplayName, stampMcpContext, textResponse } from './_helpers';
 /**
- * Creates the schedulePublish MCP tool that stamps a future publish time
- * on a draft document.
+ * schedulePublish 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:
+ * IMPORTANT: this tool ONLY sets `publishedAt` and keeps `_status: 'draft'`.
+ * It does not flip the status when the time arrives. The consumer's Payload
+ * config must own the actual flip via:
  *
- *   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.
+ *   1. A Payload Jobs Queue scheduled task that finds drafts whose
+ *      `publishedAt <= now` and updates `_status: 'published'`. This is the
+ *      canonical Payload-3 approach (https://payloadcms.com/docs/jobs-queue/scheduled-jobs).
+ *   2. An external cron / worker doing the same query + update.
+ *   3. A `beforeRead` hook 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.
+ * `publishedAt` date field.
  */ export function createSchedulePublishTool(collectionSchemas, draftCollections) {
     const schedulableSlugs = [];
     for (const slug of draftCollections){
@@ -46,40 +42,16 @@ function buildTool(schedulableSlugs) {
         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".'
-                        }
-                    ]
-                };
+                return textResponse(`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"`
-                        }
-                    ]
-                };
+                return textResponse(`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.`
-                        }
-                    ]
-                };
+                return textResponse(`Error: publishAt (${parsed.toISOString()}) is not in the future. ` + `Use the publishDraft tool to publish immediately instead.`);
             }
-            req.context = {
-                ...req.context,
-                source: 'mcp'
-            };
+            stampMcpContext(req);
             try {
                 const updated = await req.payload.update({
                     collection: collection,
@@ -93,25 +65,10 @@ function buildTool(schedulableSlugs) {
                     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.`
-                        }
-                    ]
-                };
+                const displayName = getDocDisplayName(updated, documentId);
+                return textResponse(`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}`
-                        }
-                    ]
-                };
+                return textResponse(`Error scheduling ${collection}#${documentId}: ${errorMessage(error)}`);
             }
         }
     };

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

@@ -1 +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":"AAAA,SAASA,CAAC,QAAQ,MAAK;AAIvB;;;;;;;;;;;;;;;;;;;;;;;;CAwBC,GACD,OAAO,SAASC,0BACdC,iBAAgD,EAChDC,gBAA6B;IAE7B,MAAMC,mBAA6B,EAAE;IACrC,KAAK,MAAMC,QAAQF,iBAAkB;QACnC,MAAMG,SAASJ,kBAAkBK,GAAG,CAACF;QACrC,IAAI,CAACC,QAAQ;QACb,MAAME,iBAAiBF,OAAOG,MAAM,CAACC,IAAI,CACvC,CAACC,IAAMA,EAAEC,IAAI,KAAK,iBAAiBD,EAAEE,IAAI,KAAK;QAEhD,IAAIL,gBAAgBJ,iBAAiBU,IAAI,CAACT;IAC5C;IAEA,IAAID,iBAAiBW,MAAM,KAAK,GAAG,OAAO;IAC1C,OAAOC,UAAUZ;AACnB;AAEA,SAASY,UAAUZ,gBAA0B;IAC3C,OAAO;QACLQ,MAAM;QACNK,aACE,0FACA,8FACA,yFACA,4EACA,CAAC,yEAAyE,EAAEb,iBAAiBc,IAAI,CAAC,MAAM,CAAC,CAAC;QAC5GC,YAAY;YACVC,YAAYpB,EACTqB,MAAM,GACNC,QAAQ,CAAC,CAAC,6BAA6B,EAAElB,iBAAiBc,IAAI,CAAC,OAAO;YACzEK,YAAYvB,EAAEqB,MAAM,GAAGC,QAAQ,CAAC;YAChCE,WAAWxB,EACRqB,MAAM,GACNC,QAAQ,CACP,4FACA;QAEN;QACAG,SAAS,OACPC,MACAC,KACAC;YAEA,MAAM,EAAER,UAAU,EAAEG,UAAU,EAAEC,SAAS,EAAE,GAAGE;YAE9C,IAAI,CAACtB,iBAAiByB,QAAQ,CAACT,aAAa;gBAC1C,OAAO;oBACLU,SAAS;wBACP;4BACEjB,MAAM;4BACNkB,MACE,CAAC,mBAAmB,EAAEX,WAAW,sBAAsB,CAAC,GACxD,CAAC,yBAAyB,EAAEhB,iBAAiBc,IAAI,CAAC,MAAM,EAAE,CAAC,GAC3D;wBACJ;qBACD;gBACH;YACF;YAEA,MAAMc,SAAS,IAAIC,KAAKT;YACxB,IAAIU,MAAMF,OAAOG,OAAO,KAAK;gBAC3B,OAAO;oBACLL,SAAS;wBACP;4BACEjB,MAAM;4BACNkB,MAAM,CAAC,QAAQ,EAAEP,UAAU,oEAAoE,CAAC;wBAClG;qBACD;gBACH;YACF;YAEA,IAAIQ,OAAOG,OAAO,MAAMF,KAAKG,GAAG,IAAI;gBAClC,OAAO;oBACLN,SAAS;wBACP;4BACEjB,MAAM;4BACNkB,MACE,CAAC,kBAAkB,EAAEC,OAAOK,WAAW,GAAG,wBAAwB,CAAC,GACnE,CAAC,yDAAyD,CAAC;wBAC/D;qBACD;gBACH;YACF;YAEAV,IAAIW,OAAO,GAAG;gBAAE,GAAGX,IAAIW,OAAO;gBAAEC,QAAQ;YAAM;YAE9C,IAAI;gBACF,MAAMC,UAAU,MAAMb,IAAIc,OAAO,CAACC,MAAM,CAAC;oBACvCtB,YAAYA;oBACZuB,IAAIpB;oBACJqB,MAAM;wBACJC,aAAab,OAAOK,WAAW;wBAC/BS,SAAS;oBACX;oBACAC,OAAO;oBACPpB;oBACAqB,gBAAgB;oBAChBC,MAAMtB,IAAIsB,IAAI;gBAChB;gBAEA,MAAMC,cACJ,AAACV,QAAgB5B,IAAI,IACrB,AAAC4B,QAAgBW,KAAK,IACtB,AAACX,QAAgBnC,IAAI,IACrBkB;gBAEF,OAAO;oBACLO,SAAS;wBACP;4BACEjB,MAAM;4BACNkB,MACE,CAAC,WAAW,EAAEmB,YAAY,GAAG,EAAE9B,WAAW,CAAC,EAAEG,WAAW,iBAAiB,EAAES,OAAOK,WAAW,GAAG,EAAE,CAAC,GACnG,CAAC,+FAA+F,CAAC,GACjG,CAAC,8FAA8F,CAAC,GAChG,CAAC,yFAAyF,CAAC;wBAC/F;qBACD;gBACH;YACF,EAAE,OAAOe,OAAO;gBACd,MAAMC,UAAUD,iBAAiBE,QAAQF,MAAMC,OAAO,GAAGE,OAAOH;gBAChE,OAAO;oBACLtB,SAAS;wBACP;4BACEjB,MAAM;4BACNkB,MAAM,CAAC,iBAAiB,EAAEX,WAAW,CAAC,EAAEG,WAAW,EAAE,EAAE8B,SAAS;wBAClE;qBACD;gBACH;YACF;QACF;IACF;AACF"}
+{"version":3,"sources":["../../src/tools/schedule-publish.ts"],"sourcesContent":["import { z } from 'zod'\nimport type { PayloadRequest } from 'payload'\nimport type { CollectionSchema } from '../types'\nimport {\n  errorMessage,\n  getDocDisplayName,\n  stampMcpContext,\n  textResponse,\n} from './_helpers'\n\n/**\n * schedulePublish stamps a future publish time on a draft document.\n *\n * IMPORTANT: this tool ONLY sets `publishedAt` and keeps `_status: 'draft'`.\n * It does not flip the status when the time arrives. The consumer's Payload\n * config must own the actual flip via:\n *\n *   1. A Payload Jobs Queue scheduled task that finds drafts whose\n *      `publishedAt <= now` and updates `_status: 'published'`. This is the\n *      canonical Payload-3 approach (https://payloadcms.com/docs/jobs-queue/scheduled-jobs).\n *   2. An external cron / worker doing the same query + update.\n *   3. A `beforeRead` hook 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` date field.\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 textResponse(\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      const parsed = new Date(publishAt)\n      if (isNaN(parsed.getTime())) {\n        return textResponse(\n          `Error: \"${publishAt}\" is not a valid ISO 8601 date-time. Example: \"2026-06-01T09:00:00Z\"`,\n        )\n      }\n\n      if (parsed.getTime() <= Date.now()) {\n        return textResponse(\n          `Error: publishAt (${parsed.toISOString()}) is not in the future. ` +\n            `Use the publishDraft tool to publish immediately instead.`,\n        )\n      }\n\n      stampMcpContext(req)\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 = getDocDisplayName(updated, documentId)\n        return textResponse(\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      } catch (error) {\n        return textResponse(\n          `Error scheduling ${collection}#${documentId}: ${errorMessage(error)}`,\n        )\n      }\n    },\n  }\n}\n"],"names":["z","errorMessage","getDocDisplayName","stampMcpContext","textResponse","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","parsed","Date","isNaN","getTime","now","toISOString","updated","payload","update","id","data","publishedAt","_status","draft","overrideAccess","user","displayName","error"],"mappings":"AAAA,SAASA,CAAC,QAAQ,MAAK;AAGvB,SACEC,YAAY,EACZC,iBAAiB,EACjBC,eAAe,EACfC,YAAY,QACP,aAAY;AAEnB;;;;;;;;;;;;;;;;;;;CAmBC,GACD,OAAO,SAASC,0BACdC,iBAAgD,EAChDC,gBAA6B;IAE7B,MAAMC,mBAA6B,EAAE;IACrC,KAAK,MAAMC,QAAQF,iBAAkB;QACnC,MAAMG,SAASJ,kBAAkBK,GAAG,CAACF;QACrC,IAAI,CAACC,QAAQ;QACb,MAAME,iBAAiBF,OAAOG,MAAM,CAACC,IAAI,CACvC,CAACC,IAAMA,EAAEC,IAAI,KAAK,iBAAiBD,EAAEE,IAAI,KAAK;QAEhD,IAAIL,gBAAgBJ,iBAAiBU,IAAI,CAACT;IAC5C;IAEA,IAAID,iBAAiBW,MAAM,KAAK,GAAG,OAAO;IAC1C,OAAOC,UAAUZ;AACnB;AAEA,SAASY,UAAUZ,gBAA0B;IAC3C,OAAO;QACLQ,MAAM;QACNK,aACE,0FACA,8FACA,yFACA,4EACA,CAAC,yEAAyE,EAAEb,iBAAiBc,IAAI,CAAC,MAAM,CAAC,CAAC;QAC5GC,YAAY;YACVC,YAAYxB,EACTyB,MAAM,GACNC,QAAQ,CAAC,CAAC,6BAA6B,EAAElB,iBAAiBc,IAAI,CAAC,OAAO;YACzEK,YAAY3B,EAAEyB,MAAM,GAAGC,QAAQ,CAAC;YAChCE,WAAW5B,EACRyB,MAAM,GACNC,QAAQ,CACP,4FACA;QAEN;QACAG,SAAS,OACPC,MACAC,KACAC;YAEA,MAAM,EAAER,UAAU,EAAEG,UAAU,EAAEC,SAAS,EAAE,GAAGE;YAE9C,IAAI,CAACtB,iBAAiByB,QAAQ,CAACT,aAAa;gBAC1C,OAAOpB,aACL,CAAC,mBAAmB,EAAEoB,WAAW,sBAAsB,CAAC,GACtD,CAAC,yBAAyB,EAAEhB,iBAAiBc,IAAI,CAAC,MAAM,EAAE,CAAC,GAC3D;YAEN;YAEA,MAAMY,SAAS,IAAIC,KAAKP;YACxB,IAAIQ,MAAMF,OAAOG,OAAO,KAAK;gBAC3B,OAAOjC,aACL,CAAC,QAAQ,EAAEwB,UAAU,oEAAoE,CAAC;YAE9F;YAEA,IAAIM,OAAOG,OAAO,MAAMF,KAAKG,GAAG,IAAI;gBAClC,OAAOlC,aACL,CAAC,kBAAkB,EAAE8B,OAAOK,WAAW,GAAG,wBAAwB,CAAC,GACjE,CAAC,yDAAyD,CAAC;YAEjE;YAEApC,gBAAgB4B;YAEhB,IAAI;gBACF,MAAMS,UAAU,MAAMT,IAAIU,OAAO,CAACC,MAAM,CAAC;oBACvClB,YAAYA;oBACZmB,IAAIhB;oBACJiB,MAAM;wBACJC,aAAaX,OAAOK,WAAW;wBAC/BO,SAAS;oBACX;oBACAC,OAAO;oBACPhB;oBACAiB,gBAAgB;oBAChBC,MAAMlB,IAAIkB,IAAI;gBAChB;gBAEA,MAAMC,cAAchD,kBAAkBsC,SAASb;gBAC/C,OAAOvB,aACL,CAAC,WAAW,EAAE8C,YAAY,GAAG,EAAE1B,WAAW,CAAC,EAAEG,WAAW,iBAAiB,EAAEO,OAAOK,WAAW,GAAG,EAAE,CAAC,GACjG,CAAC,+FAA+F,CAAC,GACjG,CAAC,8FAA8F,CAAC,GAChG,CAAC,yFAAyF,CAAC;YAEjG,EAAE,OAAOY,OAAO;gBACd,OAAO/C,aACL,CAAC,iBAAiB,EAAEoB,WAAW,CAAC,EAAEG,WAAW,EAAE,EAAE1B,aAAakD,QAAQ;YAE1E;QACF;IACF;AACF"}

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

@@ -34,10 +34,5 @@ export declare function createSearchContentTool(collectionSchemas: Map<string, C
         newerThanDays?: number;
         missingFields?: string[];
         limit?: number;
-    }, req: PayloadRequest, _extra: unknown) => Promise<{
-        content: {
-            type: "text";
-            text: string;
-        }[];
-    }>;
+    }, req: PayloadRequest, _extra: unknown) => Promise<import("./_helpers").McpTextResponse>;
 };