payload-mcp-toolkit 0.3.3 → 0.7.0

package/dist/tools/find-global.js

@@ -0,0 +1,122 @@
+import { z } from 'zod';
+import { errorMessage, jsonResponse, slugEnum, stampMcpContext, textResponse } from './_helpers';
+/**
+ * Read any global by slug. Mirrors `findDocument`'s slug-enum + draft +
+ * preview behaviour but acts on Payload's `findGlobal` Local API method —
+ * globals are singletons, so there's no `id`, `where`, or `limit`.
+ *
+ * Preview stamping uses each global's `admin.livePreview.url` (preferred)
+ * or `admin.preview` function, same fallback chain as collections.
+ */ export function createFindGlobalTool(globalSchemas, draftGlobals, globalsBySlug, previewSiteUrl, previewDisabled = false) {
+    const findableSlugs = [
+        ...globalSchemas.keys()
+    ];
+    const descriptionLines = findableSlugs.map((slug)=>`  - "${slug}"${draftGlobals.has(slug) ? ' (draft-enabled)' : ''}`);
+    return {
+        name: 'findGlobal',
+        routing: {
+            kind: 'global',
+            action: 'read'
+        },
+        description: 'Read a global (a singleton site-wide settings document) by slug. ' + 'Globals carry things like site name, footer config, navigation menus — there is no `id`, no list, no `where` filter. ' + 'Use `draft: true` to read the draft version of a draft-enabled global.\n\n' + 'Available globals:\n' + descriptionLines.join('\n'),
+        parameters: {
+            slug: slugEnum(findableSlugs, 'global').describe(`The global slug. One of: ${findableSlugs.join(', ')}`),
+            draft: z.boolean().optional().describe('When true, returns the draft version of a draft-enabled global. Default false (published).'),
+            depth: z.number().int().min(0).max(3).optional().describe('Relationship population depth. Default 1.'),
+            locale: z.string().optional().describe('Optional locale code (e.g. "en", "fr") for localized fields. Defaults to the request locale.')
+        },
+        handler: async (args, req, _extra)=>{
+            const { slug, draft, depth, locale } = args;
+            if (!globalSchemas.has(slug)) {
+                return textResponse(`Error: Unknown global "${slug}". Available: ${findableSlugs.join(', ')}`);
+            }
+            stampMcpContext(req);
+            const globalConfig = globalsBySlug.get(slug);
+            try {
+                const doc = await req.payload.findGlobal({
+                    slug: slug,
+                    depth: depth ?? 1,
+                    draft: draft ?? false,
+                    ...locale ? {
+                        locale: locale
+                    } : {},
+                    req,
+                    overrideAccess: false,
+                    user: req.user
+                });
+                const base = jsonResponse(doc);
+                if (previewDisabled || !globalConfig) return base;
+                const isDraft = doc?._status === 'draft';
+                if (!isDraft) return base;
+                const previewUrl = await resolveGlobalPreviewUrl(globalConfig, doc, req, previewSiteUrl);
+                const hint = previewUrl ? `\n📋 This global is in draft status. Preview it here: ${previewUrl}` : '\n📋 This global is in draft status. Use the admin panel to preview it.';
+                return {
+                    content: [
+                        ...base.content,
+                        {
+                            type: 'text',
+                            text: hint
+                        }
+                    ]
+                };
+            } catch (err) {
+                return textResponse(`Error reading global "${slug}": ${errorMessage(err)}`);
+            }
+        }
+    };
+}
+/**
+ * Resolve a preview URL from a global's `admin.livePreview.url` / `admin.preview`
+ * config. Same fallback chain as `resolvePreviewUrl` for collections, but
+ * passes `globalConfig` (not `collectionConfig`) to the user callback.
+ */ async function resolveGlobalPreviewUrl(global, doc, req, siteUrl) {
+    const admin = global.admin ?? {};
+    const locale = req.locale ?? 'en';
+    let raw;
+    const livePreviewUrl = admin.livePreview?.url;
+    if (typeof livePreviewUrl === 'function') {
+        try {
+            raw = await livePreviewUrl({
+                data: doc,
+                locale: {
+                    code: locale,
+                    label: locale
+                },
+                req,
+                payload: req.payload,
+                globalConfig: global
+            });
+        } catch (err) {
+            req.payload.logger?.warn?.({
+                err,
+                slug: global.slug
+            }, `[payload-mcp-toolkit] admin.livePreview.url threw for global "${global.slug}"`);
+            raw = null;
+        }
+    } else if (typeof livePreviewUrl === 'string') {
+        raw = livePreviewUrl;
+    }
+    if (!raw && typeof admin.preview === 'function') {
+        try {
+            raw = await admin.preview(doc, {
+                locale,
+                req,
+                token: null
+            });
+        } catch (err) {
+            req.payload.logger?.warn?.({
+                err,
+                slug: global.slug
+            }, `[payload-mcp-toolkit] admin.preview threw for global "${global.slug}"`);
+            raw = null;
+        }
+    }
+    if (!raw || typeof raw !== 'string') return null;
+    if (raw.startsWith('http://') || raw.startsWith('https://')) return raw;
+    if (!siteUrl) return null;
+    const base = siteUrl.endsWith('/') ? siteUrl.slice(0, -1) : siteUrl;
+    const path = raw.startsWith('/') ? raw : `/${raw}`;
+    return `${base}${path}`;
+}
+
+//# sourceMappingURL=find-global.js.map

package/dist/tools/find-global.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/tools/find-global.ts"],"sourcesContent":["import { z } from 'zod'\r\nimport type { GlobalConfig, PayloadRequest } from 'payload'\r\nimport type { GlobalSchema } from '../types'\r\nimport { errorMessage, jsonResponse, slugEnum, stampMcpContext, textResponse } from './_helpers'\r\n\r\ninterface FindGlobalArgs {\r\n  slug: string\r\n  draft?: boolean\r\n  depth?: number\r\n  locale?: string\r\n}\r\n\r\n/**\r\n * Read any global by slug. Mirrors `findDocument`'s slug-enum + draft +\r\n * preview behaviour but acts on Payload's `findGlobal` Local API method —\r\n * globals are singletons, so there's no `id`, `where`, or `limit`.\r\n *\r\n * Preview stamping uses each global's `admin.livePreview.url` (preferred)\r\n * or `admin.preview` function, same fallback chain as collections.\r\n */\r\nexport function createFindGlobalTool(\r\n  globalSchemas: Map<string, GlobalSchema>,\r\n  draftGlobals: Set<string>,\r\n  globalsBySlug: Map<string, GlobalConfig>,\r\n  previewSiteUrl: string | undefined,\r\n  previewDisabled = false,\r\n) {\r\n  const findableSlugs = [...globalSchemas.keys()]\r\n  const descriptionLines = findableSlugs.map(\r\n    (slug) => `  - \"${slug}\"${draftGlobals.has(slug) ? ' (draft-enabled)' : ''}`,\r\n  )\r\n\r\n  return {\r\n    name: 'findGlobal',\r\n    routing: { kind: 'global', action: 'read' } as const,\r\n    description:\r\n      'Read a global (a singleton site-wide settings document) by slug. ' +\r\n      'Globals carry things like site name, footer config, navigation menus — there is no `id`, no list, no `where` filter. ' +\r\n      'Use `draft: true` to read the draft version of a draft-enabled global.\\n\\n' +\r\n      'Available globals:\\n' +\r\n      descriptionLines.join('\\n'),\r\n    parameters: {\r\n      slug: slugEnum(findableSlugs, 'global').describe(\r\n        `The global slug. One of: ${findableSlugs.join(', ')}`,\r\n      ),\r\n      draft: z\r\n        .boolean()\r\n        .optional()\r\n        .describe(\r\n          'When true, returns the draft version of a draft-enabled global. Default false (published).',\r\n        ),\r\n      depth: z\r\n        .number()\r\n        .int()\r\n        .min(0)\r\n        .max(3)\r\n        .optional()\r\n        .describe('Relationship population depth. Default 1.'),\r\n      locale: z\r\n        .string()\r\n        .optional()\r\n        .describe(\r\n          'Optional locale code (e.g. \"en\", \"fr\") for localized fields. Defaults to the request locale.',\r\n        ),\r\n    },\r\n    handler: async (args: Record<string, unknown>, req: PayloadRequest, _extra: unknown) => {\r\n      const { slug, draft, depth, locale } = args as unknown as FindGlobalArgs\r\n\r\n      if (!globalSchemas.has(slug)) {\r\n        return textResponse(\r\n          `Error: Unknown global \"${slug}\". Available: ${findableSlugs.join(', ')}`,\r\n        )\r\n      }\r\n\r\n      stampMcpContext(req)\r\n      const globalConfig = globalsBySlug.get(slug)\r\n\r\n      try {\r\n        const doc = await req.payload.findGlobal({\r\n          slug: slug as never,\r\n          depth: depth ?? 1,\r\n          draft: draft ?? false,\r\n          ...(locale ? { locale: locale as never } : {}),\r\n          req,\r\n          overrideAccess: false,\r\n          user: req.user,\r\n        })\r\n\r\n        const base = jsonResponse(doc)\r\n        if (previewDisabled || !globalConfig) return base\r\n\r\n        const isDraft =\r\n          (doc as Record<string, unknown> | undefined)?._status === 'draft'\r\n        if (!isDraft) return base\r\n\r\n        const previewUrl = await resolveGlobalPreviewUrl(\r\n          globalConfig,\r\n          doc as Record<string, unknown>,\r\n          req,\r\n          previewSiteUrl,\r\n        )\r\n        const hint = previewUrl\r\n          ? `\\n📋 This global is in draft status. Preview it here: ${previewUrl}`\r\n          : '\\n📋 This global is in draft status. Use the admin panel to preview it.'\r\n        return { content: [...base.content, { type: 'text' as const, text: hint }] }\r\n      } catch (err) {\r\n        return textResponse(`Error reading global \"${slug}\": ${errorMessage(err)}`)\r\n      }\r\n    },\r\n  }\r\n}\r\n\r\n/**\r\n * Resolve a preview URL from a global's `admin.livePreview.url` / `admin.preview`\r\n * config. Same fallback chain as `resolvePreviewUrl` for collections, but\r\n * passes `globalConfig` (not `collectionConfig`) to the user callback.\r\n */\r\nasync function resolveGlobalPreviewUrl(\r\n  global: GlobalConfig,\r\n  doc: Record<string, unknown>,\r\n  req: PayloadRequest,\r\n  siteUrl: string | undefined,\r\n): Promise<string | null> {\r\n  const admin = (global.admin ?? {}) as Record<string, any>\r\n  const locale = (req as unknown as { locale?: string }).locale ?? 'en'\r\n\r\n  let raw: string | null | undefined\r\n\r\n  const livePreviewUrl = admin.livePreview?.url\r\n  if (typeof livePreviewUrl === 'function') {\r\n    try {\r\n      raw = await livePreviewUrl({\r\n        data: doc,\r\n        locale: { code: locale, label: locale },\r\n        req,\r\n        payload: req.payload,\r\n        globalConfig: global,\r\n      })\r\n    } catch (err) {\r\n      req.payload.logger?.warn?.(\r\n        { err, slug: global.slug },\r\n        `[payload-mcp-toolkit] admin.livePreview.url threw for global \"${global.slug}\"`,\r\n      )\r\n      raw = null\r\n    }\r\n  } else if (typeof livePreviewUrl === 'string') {\r\n    raw = livePreviewUrl\r\n  }\r\n\r\n  if (!raw && typeof admin.preview === 'function') {\r\n    try {\r\n      raw = await admin.preview(doc, { locale, req, token: null })\r\n    } catch (err) {\r\n      req.payload.logger?.warn?.(\r\n        { err, slug: global.slug },\r\n        `[payload-mcp-toolkit] admin.preview threw for global \"${global.slug}\"`,\r\n      )\r\n      raw = null\r\n    }\r\n  }\r\n\r\n  if (!raw || typeof raw !== 'string') return null\r\n  if (raw.startsWith('http://') || raw.startsWith('https://')) return raw\r\n  if (!siteUrl) return null\r\n\r\n  const base = siteUrl.endsWith('/') ? siteUrl.slice(0, -1) : siteUrl\r\n  const path = raw.startsWith('/') ? raw : `/${raw}`\r\n  return `${base}${path}`\r\n}\r\n"],"names":["z","errorMessage","jsonResponse","slugEnum","stampMcpContext","textResponse","createFindGlobalTool","globalSchemas","draftGlobals","globalsBySlug","previewSiteUrl","previewDisabled","findableSlugs","keys","descriptionLines","map","slug","has","name","routing","kind","action","description","join","parameters","describe","draft","boolean","optional","depth","number","int","min","max","locale","string","handler","args","req","_extra","globalConfig","get","doc","payload","findGlobal","overrideAccess","user","base","isDraft","_status","previewUrl","resolveGlobalPreviewUrl","hint","content","type","text","err","global","siteUrl","admin","raw","livePreviewUrl","livePreview","url","data","code","label","logger","warn","preview","token","startsWith","endsWith","slice","path"],"mappings":"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"}

package/dist/tools/global-versions.d.ts

@@ -0,0 +1,39 @@
+import { z } from 'zod';
+import type { PayloadRequest } from 'payload';
+/**
+ * List recent saved versions of a draft-enabled global. Returns null when no
+ * global has drafts enabled so the plugin entry can skip registration.
+ */
+export declare function createListGlobalVersionsTool(draftGlobals: Set<string>): {
+    name: string;
+    routing: {
+        readonly kind: "global";
+        readonly action: "read";
+    };
+    description: string;
+    parameters: {
+        slug: z.ZodEnum<[string, ...string[]]>;
+        limit: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+        locale: z.ZodOptional<z.ZodString>;
+    };
+    handler: (args: Record<string, unknown>, req: PayloadRequest, _extra: unknown) => Promise<import("./_helpers").McpTextResponse>;
+} | null;
+/**
+ * Restore a draft-enabled global to a previously saved version. Returns null
+ * when no global has drafts enabled.
+ */
+export declare function createRestoreGlobalVersionTool(draftGlobals: Set<string>): {
+    name: string;
+    routing: {
+        readonly kind: "global";
+        readonly action: "update";
+    };
+    description: string;
+    parameters: {
+        slug: z.ZodEnum<[string, ...string[]]>;
+        versionId: z.ZodString;
+        expectedUpdatedAt: z.ZodOptional<z.ZodString>;
+        locale: z.ZodOptional<z.ZodString>;
+    };
+    handler: (args: Record<string, unknown>, req: PayloadRequest, _extra: unknown) => Promise<import("./_helpers").McpTextResponse>;
+} | null;

package/dist/tools/global-versions.js

@@ -0,0 +1,132 @@
+import { z } from 'zod';
+import { errorMessage, jsonResponse, slugEnum, stampMcpContext, textResponse } from './_helpers';
+const DEFAULT_LIST_LIMIT = 10;
+/**
+ * List recent saved versions of a draft-enabled global. Returns null when no
+ * global has drafts enabled so the plugin entry can skip registration.
+ */ export function createListGlobalVersionsTool(draftGlobals) {
+    if (draftGlobals.size === 0) return null;
+    const slugs = [
+        ...draftGlobals
+    ];
+    return {
+        name: 'listGlobalVersions',
+        routing: {
+            kind: 'global',
+            action: 'read'
+        },
+        description: 'List recent saved versions of a draft-enabled global. ' + 'Use before restoreGlobalVersion to pick the right point in time. ' + `Draft-enabled globals: ${slugs.join(', ')}`,
+        parameters: {
+            slug: slugEnum(slugs, 'global').describe(`The global slug. One of: ${slugs.join(', ')}`),
+            limit: z.number().optional().default(DEFAULT_LIST_LIMIT).describe(`Maximum number of versions to return (default ${DEFAULT_LIST_LIMIT})`),
+            locale: z.string().optional().describe('Optional locale code (e.g. "en", "fr") to filter version snapshots to.')
+        },
+        handler: async (args, req, _extra)=>{
+            const { slug, limit = DEFAULT_LIST_LIMIT, locale } = args;
+            if (!draftGlobals.has(slug)) {
+                return textResponse(`Error: Global "${slug}" does not support versions. Draft-enabled globals: ${slugs.join(', ') || 'none'}`);
+            }
+            stampMcpContext(req);
+            try {
+                const result = await req.payload.findGlobalVersions({
+                    slug: slug,
+                    sort: '-updatedAt',
+                    limit,
+                    ...locale ? {
+                        locale: locale
+                    } : {},
+                    req,
+                    overrideAccess: false,
+                    user: req.user
+                });
+                const versions = result.docs.map((v)=>{
+                    const snapshot = v.version || {};
+                    return {
+                        id: v.id,
+                        updatedAt: v.updatedAt,
+                        createdAt: v.createdAt,
+                        status: snapshot._status ?? 'unknown',
+                        autosave: v.autosave === true
+                    };
+                });
+                return jsonResponse({
+                    slug,
+                    totalDocs: result.totalDocs,
+                    returned: versions.length,
+                    versions
+                });
+            } catch (err) {
+                return textResponse(`Error listing versions for global "${slug}": ${errorMessage(err)}`);
+            }
+        }
+    };
+}
+/**
+ * Restore a draft-enabled global to a previously saved version. Returns null
+ * when no global has drafts enabled.
+ */ export function createRestoreGlobalVersionTool(draftGlobals) {
+    if (draftGlobals.size === 0) return null;
+    const slugs = [
+        ...draftGlobals
+    ];
+    return {
+        name: 'restoreGlobalVersion',
+        routing: {
+            kind: 'global',
+            action: 'update'
+        },
+        description: 'Restore a global to a previously saved version. ' + 'Use listGlobalVersions first to find the version ID. ' + 'Restoring creates a new version on top, so the previous state is recoverable. ' + `Draft-enabled globals: ${slugs.join(', ')}`,
+        parameters: {
+            slug: slugEnum(slugs, 'global').describe(`The global slug. One of: ${slugs.join(', ')}`),
+            versionId: z.string().describe('The version ID returned by listGlobalVersions (NOT the global slug)'),
+            expectedUpdatedAt: z.string().optional().describe('Optional CAS guard. If set, the restore is rejected when the global\'s current updatedAt differs from this value — protects against clobbering concurrent edits. Pass the updatedAt returned by a prior findGlobal call.'),
+            locale: z.string().optional().describe('Optional locale code (e.g. "en", "fr") to scope the restore to a single locale.')
+        },
+        handler: async (args, req, _extra)=>{
+            const { slug, versionId, expectedUpdatedAt, locale } = args;
+            if (!draftGlobals.has(slug)) {
+                return textResponse(`Error: Global "${slug}" does not support versions. Draft-enabled globals: ${slugs.join(', ') || 'none'}`);
+            }
+            stampMcpContext(req);
+            if (expectedUpdatedAt !== undefined) {
+                try {
+                    const current = await req.payload.findGlobal({
+                        slug: slug,
+                        depth: 0,
+                        draft: true,
+                        ...locale ? {
+                            locale: locale
+                        } : {},
+                        req,
+                        overrideAccess: false,
+                        user: req.user
+                    });
+                    const currentUpdatedAt = current?.updatedAt;
+                    const currentStr = typeof currentUpdatedAt === 'string' ? currentUpdatedAt : currentUpdatedAt instanceof Date ? currentUpdatedAt.toISOString() : undefined;
+                    if (currentStr !== expectedUpdatedAt) {
+                        return textResponse(`Conflict: global "${slug}" was modified since expectedUpdatedAt (${expectedUpdatedAt}); current updatedAt is ${currentStr ?? 'unknown'}. Re-read the global and retry.`);
+                    }
+                } catch (err) {
+                    return textResponse(`Error checking expectedUpdatedAt on global "${slug}": ${errorMessage(err)}`);
+                }
+            }
+            try {
+                await req.payload.restoreGlobalVersion({
+                    slug: slug,
+                    id: versionId,
+                    ...locale ? {
+                        locale: locale
+                    } : {},
+                    req,
+                    overrideAccess: false,
+                    user: req.user
+                });
+                return textResponse(`Restored global "${slug}" from version ${versionId}. ` + `The global is now in draft status — use publishGlobalDraft to make the restored content live.`);
+            } catch (err) {
+                return textResponse(`Error restoring global "${slug}" from version ${versionId}: ${errorMessage(err)}`);
+            }
+        }
+    };
+}
+
+//# sourceMappingURL=global-versions.js.map

package/dist/tools/global-versions.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/tools/global-versions.ts"],"sourcesContent":["import { z } from 'zod'\r\nimport type { PayloadRequest } from 'payload'\r\nimport { errorMessage, jsonResponse, slugEnum, stampMcpContext, textResponse } from './_helpers'\r\n\r\nconst DEFAULT_LIST_LIMIT = 10\r\n\r\n/**\r\n * List recent saved versions of a draft-enabled global. Returns null when no\r\n * global has drafts enabled so the plugin entry can skip registration.\r\n */\r\nexport function createListGlobalVersionsTool(draftGlobals: Set<string>) {\r\n  if (draftGlobals.size === 0) return null\r\n\r\n  const slugs = [...draftGlobals]\r\n  return {\r\n    name: 'listGlobalVersions',\r\n    routing: { kind: 'global', action: 'read' } as const,\r\n    description:\r\n      'List recent saved versions of a draft-enabled global. ' +\r\n      'Use before restoreGlobalVersion to pick the right point in time. ' +\r\n      `Draft-enabled globals: ${slugs.join(', ')}`,\r\n    parameters: {\r\n      slug: slugEnum(slugs, 'global').describe(`The global slug. One of: ${slugs.join(', ')}`),\r\n      limit: z\r\n        .number()\r\n        .optional()\r\n        .default(DEFAULT_LIST_LIMIT)\r\n        .describe(`Maximum number of versions to return (default ${DEFAULT_LIST_LIMIT})`),\r\n      locale: z\r\n        .string()\r\n        .optional()\r\n        .describe('Optional locale code (e.g. \"en\", \"fr\") to filter version snapshots to.'),\r\n    },\r\n    handler: async (\r\n      args: Record<string, unknown>,\r\n      req: PayloadRequest,\r\n      _extra: unknown,\r\n    ) => {\r\n      const { slug, limit = DEFAULT_LIST_LIMIT, locale } = args as {\r\n        slug: string\r\n        limit?: number\r\n        locale?: string\r\n      }\r\n\r\n      if (!draftGlobals.has(slug)) {\r\n        return textResponse(\r\n          `Error: Global \"${slug}\" does not support versions. Draft-enabled globals: ${slugs.join(', ') || 'none'}`,\r\n        )\r\n      }\r\n\r\n      stampMcpContext(req)\r\n\r\n      try {\r\n        const result = await req.payload.findGlobalVersions({\r\n          slug: slug as never,\r\n          sort: '-updatedAt',\r\n          limit,\r\n          ...(locale ? { locale: locale as never } : {}),\r\n          req,\r\n          overrideAccess: false,\r\n          user: req.user,\r\n        })\r\n\r\n        const versions = result.docs.map((v: any) => {\r\n          const snapshot = v.version || {}\r\n          return {\r\n            id: v.id,\r\n            updatedAt: v.updatedAt,\r\n            createdAt: v.createdAt,\r\n            status: snapshot._status ?? 'unknown',\r\n            autosave: v.autosave === true,\r\n          }\r\n        })\r\n\r\n        return jsonResponse({\r\n          slug,\r\n          totalDocs: result.totalDocs,\r\n          returned: versions.length,\r\n          versions,\r\n        })\r\n      } catch (err) {\r\n        return textResponse(`Error listing versions for global \"${slug}\": ${errorMessage(err)}`)\r\n      }\r\n    },\r\n  }\r\n}\r\n\r\n/**\r\n * Restore a draft-enabled global to a previously saved version. Returns null\r\n * when no global has drafts enabled.\r\n */\r\nexport function createRestoreGlobalVersionTool(draftGlobals: Set<string>) {\r\n  if (draftGlobals.size === 0) return null\r\n\r\n  const slugs = [...draftGlobals]\r\n  return {\r\n    name: 'restoreGlobalVersion',\r\n    routing: { kind: 'global', action: 'update' } as const,\r\n    description:\r\n      'Restore a global to a previously saved version. ' +\r\n      'Use listGlobalVersions first to find the version ID. ' +\r\n      'Restoring creates a new version on top, so the previous state is recoverable. ' +\r\n      `Draft-enabled globals: ${slugs.join(', ')}`,\r\n    parameters: {\r\n      slug: slugEnum(slugs, 'global').describe(`The global slug. One of: ${slugs.join(', ')}`),\r\n      versionId: z\r\n        .string()\r\n        .describe('The version ID returned by listGlobalVersions (NOT the global slug)'),\r\n      expectedUpdatedAt: z\r\n        .string()\r\n        .optional()\r\n        .describe(\r\n          'Optional CAS guard. If set, the restore is rejected when the global\\'s current updatedAt differs from this value — protects against clobbering concurrent edits. Pass the updatedAt returned by a prior findGlobal call.',\r\n        ),\r\n      locale: z\r\n        .string()\r\n        .optional()\r\n        .describe('Optional locale code (e.g. \"en\", \"fr\") to scope the restore to a single locale.'),\r\n    },\r\n    handler: async (\r\n      args: Record<string, unknown>,\r\n      req: PayloadRequest,\r\n      _extra: unknown,\r\n    ) => {\r\n      const { slug, versionId, expectedUpdatedAt, locale } = args as {\r\n        slug: string\r\n        versionId: string\r\n        expectedUpdatedAt?: string\r\n        locale?: string\r\n      }\r\n\r\n      if (!draftGlobals.has(slug)) {\r\n        return textResponse(\r\n          `Error: Global \"${slug}\" does not support versions. Draft-enabled globals: ${slugs.join(', ') || 'none'}`,\r\n        )\r\n      }\r\n\r\n      stampMcpContext(req)\r\n\r\n      if (expectedUpdatedAt !== undefined) {\r\n        try {\r\n          const current = (await req.payload.findGlobal({\r\n            slug: slug as never,\r\n            depth: 0,\r\n            draft: true,\r\n            ...(locale ? { locale: locale as never } : {}),\r\n            req,\r\n            overrideAccess: false,\r\n            user: req.user,\r\n          })) as { updatedAt?: unknown } | undefined\r\n          const currentUpdatedAt = current?.updatedAt\r\n          const currentStr =\r\n            typeof currentUpdatedAt === 'string'\r\n              ? currentUpdatedAt\r\n              : currentUpdatedAt instanceof Date\r\n                ? currentUpdatedAt.toISOString()\r\n                : undefined\r\n          if (currentStr !== expectedUpdatedAt) {\r\n            return textResponse(\r\n              `Conflict: global \"${slug}\" was modified since expectedUpdatedAt (${expectedUpdatedAt}); current updatedAt is ${currentStr ?? 'unknown'}. Re-read the global and retry.`,\r\n            )\r\n          }\r\n        } catch (err) {\r\n          return textResponse(\r\n            `Error checking expectedUpdatedAt on global \"${slug}\": ${errorMessage(err)}`,\r\n          )\r\n        }\r\n      }\r\n\r\n      try {\r\n        await req.payload.restoreGlobalVersion({\r\n          slug: slug as never,\r\n          id: versionId,\r\n          ...(locale ? { locale: locale as never } : {}),\r\n          req,\r\n          overrideAccess: false,\r\n          user: req.user,\r\n        })\r\n        return textResponse(\r\n          `Restored global \"${slug}\" from version ${versionId}. ` +\r\n            `The global is now in draft status — use publishGlobalDraft to make the restored content live.`,\r\n        )\r\n      } catch (err) {\r\n        return textResponse(\r\n          `Error restoring global \"${slug}\" from version ${versionId}: ${errorMessage(err)}`,\r\n        )\r\n      }\r\n    },\r\n  }\r\n}\r\n"],"names":["z","errorMessage","jsonResponse","slugEnum","stampMcpContext","textResponse","DEFAULT_LIST_LIMIT","createListGlobalVersionsTool","draftGlobals","size","slugs","name","routing","kind","action","description","join","parameters","slug","describe","limit","number","optional","default","locale","string","handler","args","req","_extra","has","result","payload","findGlobalVersions","sort","overrideAccess","user","versions","docs","map","v","snapshot","version","id","updatedAt","createdAt","status","_status","autosave","totalDocs","returned","length","err","createRestoreGlobalVersionTool","versionId","expectedUpdatedAt","undefined","current","findGlobal","depth","draft","currentUpdatedAt","currentStr","Date","toISOString","restoreGlobalVersion"],"mappings":"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"}

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

@@ -0,0 +1,31 @@
+import { z } from 'zod';
+import type { PayloadRequest } from 'payload';
+import type { BlockCatalog, BlockNestingMap } from '../types';
+/**
+ * patchGlobalLayout — surgical wrapper that mutates a single blocks-typed
+ * field on a global without round-tripping the entire array through
+ * updateGlobal. Same operation grammar as patchLayout (append, prepend,
+ * insertAt, replaceAt, full); same recursive nesting validator against the
+ * unified BlockNestingMap.
+ *
+ * Returns null when no global has any blocks field — the plugin entry
+ * skips registration in that case, mirroring the schedulePublish pattern.
+ */
+export declare function createPatchGlobalLayoutTool(catalog: BlockCatalog, nesting: BlockNestingMap, draftGlobals: Set<string>): {
+    name: string;
+    routing: {
+        readonly kind: "global";
+        readonly action: "update";
+    };
+    description: string;
+    parameters: {
+        slug: z.ZodEnum<[string, ...string[]]>;
+        layoutField: z.ZodString;
+        blocks: z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnknown>, "many">;
+        operation: z.ZodEnum<["append", "prepend", "insertAt", "replaceAt", "full"]>;
+        insertIndex: z.ZodOptional<z.ZodNumber>;
+        expectedUpdatedAt: z.ZodOptional<z.ZodString>;
+        locale: z.ZodOptional<z.ZodString>;
+    };
+    handler: (args: Record<string, unknown>, req: PayloadRequest, _extra: unknown) => Promise<import("./_helpers").McpTextResponse>;
+} | null;

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

@@ -0,0 +1,127 @@
+import { z } from 'zod';
+import { DRAFT_NOTE, errorMessage, jsonResponse, slugEnum, stampMcpContext } from './_helpers';
+import { applyOperation, errorResponse, readPath, validateBlockList, writePath } from './_layout-helpers';
+/**
+ * patchGlobalLayout — surgical wrapper that mutates a single blocks-typed
+ * field on a global without round-tripping the entire array through
+ * updateGlobal. Same operation grammar as patchLayout (append, prepend,
+ * insertAt, replaceAt, full); same recursive nesting validator against the
+ * unified BlockNestingMap.
+ *
+ * Returns null when no global has any blocks field — the plugin entry
+ * skips registration in that case, mirroring the schedulePublish pattern.
+ */ export function createPatchGlobalLayoutTool(catalog, nesting, draftGlobals) {
+    const allBlockSlugs = new Set(catalog.blocks.map((b)=>b.slug));
+    const nestingByGlobalField = new Map();
+    const nestingByBlockField = new Map();
+    for (const edge of nesting){
+        const key = `${edge.owner}:${edge.fieldPath}`;
+        if (edge.ownerType === 'global') {
+            nestingByGlobalField.set(key, edge.acceptedBlockSlugs);
+        } else if (edge.ownerType === 'block') {
+            nestingByBlockField.set(key, edge.acceptedBlockSlugs);
+        }
+    }
+    // Conditional registration: no global has a blocks field → no tool.
+    if (nestingByGlobalField.size === 0) return null;
+    const patchableSlugs = [
+        ...new Set([
+            ...nestingByGlobalField.keys()
+        ].map((k)=>k.split(':')[0]))
+    ];
+    return {
+        name: 'patchGlobalLayout',
+        routing: {
+            kind: 'global',
+            action: 'update'
+        },
+        description: 'Surgically modify a blocks-typed field on a global (e.g. footer sections, header nav) without sending the whole array. Same operation grammar as patchLayout. Use the blockNesting resource to see which slugs each field accepts; global-owned edges have ownerType "global".',
+        parameters: {
+            slug: slugEnum(patchableSlugs, 'global').describe(`The global slug whose blocks-typed field will be patched. One of: ${patchableSlugs.join(', ')}`),
+            layoutField: z.string().describe('Name (or dotted path) of the blocks-typed field on the global to patch — e.g. "layout", "footer.sections".'),
+            blocks: z.array(z.record(z.string(), z.unknown())).describe('Blocks to compose. Each must have a `blockType` discriminator plus any block-specific fields. Nested blocks fields hold their own `blocks` arrays at any depth.'),
+            operation: z.enum([
+                'append',
+                'prepend',
+                'insertAt',
+                'replaceAt',
+                'full'
+            ]).describe('How to apply the blocks: append (end), prepend (start), insertAt (at index), replaceAt (overwrite N starting at index), full (replace entire array — use with care).'),
+            insertIndex: z.number().optional().describe('Index for insertAt/replaceAt operations'),
+            expectedUpdatedAt: z.string().optional().describe('Optional CAS guard. If set, the patch is rejected when the global\'s current updatedAt differs from this value — protects against lost writes when concurrent edits race. Pass the updatedAt returned by a prior findGlobal call.'),
+            locale: z.string().optional().describe('Optional locale code (e.g. "en", "fr") to scope the patch to a single locale on localized blocks fields.')
+        },
+        handler: async (args, req, _extra)=>{
+            const { slug, layoutField, blocks, operation, insertIndex, expectedUpdatedAt, locale } = args;
+            const rootKey = `${slug}:${layoutField}`;
+            const rootAllowed = nestingByGlobalField.get(rootKey);
+            if (!rootAllowed) {
+                return errorResponse(`Field "${layoutField}" on global "${slug}" is not a blocks-typed field, or no nesting map entry exists for it.`, {
+                    availableFields: [
+                        ...nestingByGlobalField.keys()
+                    ]
+                });
+            }
+            const errors = [];
+            validateBlockList(blocks, rootAllowed, layoutField, allBlockSlugs, nestingByBlockField, errors);
+            if (errors.length > 0) {
+                return errorResponse('Block validation failed.', {
+                    errors
+                });
+            }
+            stampMcpContext(req);
+            let existing;
+            try {
+                existing = await req.payload.findGlobal({
+                    slug: slug,
+                    depth: 0,
+                    draft: true,
+                    ...locale ? {
+                        locale: locale
+                    } : {},
+                    req,
+                    overrideAccess: false,
+                    user: req.user
+                });
+            } catch (error) {
+                return errorResponse(`Error fetching global "${slug}": ${errorMessage(error)}`);
+            }
+            if (expectedUpdatedAt !== undefined) {
+                const currentUpdatedAt = existing?.updatedAt;
+                const currentStr = typeof currentUpdatedAt === 'string' ? currentUpdatedAt : currentUpdatedAt instanceof Date ? currentUpdatedAt.toISOString() : undefined;
+                if (currentStr !== expectedUpdatedAt) {
+                    return errorResponse(`Conflict: global "${slug}" was modified since expectedUpdatedAt (${expectedUpdatedAt}); current updatedAt is ${currentStr ?? 'unknown'}. Re-read the global and retry.`, {
+                        currentUpdatedAt: currentStr
+                    });
+                }
+            }
+            const currentLayout = readPath(existing, layoutField);
+            const finalLayout = applyOperation(blocks, operation, insertIndex, currentLayout);
+            const isDraftGlobal = draftGlobals.has(slug);
+            try {
+                await req.payload.updateGlobal({
+                    slug: slug,
+                    data: writePath(existing ?? {}, layoutField, finalLayout),
+                    draft: isDraftGlobal,
+                    ...locale ? {
+                        locale: locale
+                    } : {},
+                    req,
+                    overrideAccess: false,
+                    user: req.user
+                });
+                const draftNote = isDraftGlobal ? DRAFT_NOTE : '';
+                return jsonResponse({
+                    success: true,
+                    message: `Patched ${layoutField} on global "${slug}". ` + `Operation: ${operation}. Block count: ${finalLayout.length}.` + draftNote,
+                    blockCount: finalLayout.length,
+                    operation
+                });
+            } catch (error) {
+                return errorResponse(`Error patching global "${slug}": ${errorMessage(error)}`);
+            }
+        }
+    };
+}
+
+//# sourceMappingURL=patch-global-layout.js.map

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

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/tools/patch-global-layout.ts"],"sourcesContent":["import { z } from 'zod'\r\nimport type { PayloadRequest } from 'payload'\r\nimport type { BlockCatalog, BlockNestingMap } from '../types'\r\nimport { DRAFT_NOTE, errorMessage, jsonResponse, slugEnum, stampMcpContext } from './_helpers'\r\nimport {\r\n  applyOperation,\r\n  errorResponse,\r\n  readPath,\r\n  validateBlockList,\r\n  writePath,\r\n} from './_layout-helpers'\r\n\r\n/**\r\n * patchGlobalLayout — surgical wrapper that mutates a single blocks-typed\r\n * field on a global without round-tripping the entire array through\r\n * updateGlobal. Same operation grammar as patchLayout (append, prepend,\r\n * insertAt, replaceAt, full); same recursive nesting validator against the\r\n * unified BlockNestingMap.\r\n *\r\n * Returns null when no global has any blocks field — the plugin entry\r\n * skips registration in that case, mirroring the schedulePublish pattern.\r\n */\r\nexport function createPatchGlobalLayoutTool(\r\n  catalog: BlockCatalog,\r\n  nesting: BlockNestingMap,\r\n  draftGlobals: Set<string>,\r\n) {\r\n  const allBlockSlugs = new Set(catalog.blocks.map((b) => b.slug))\r\n\r\n  const nestingByGlobalField = new Map<string, string[]>()\r\n  const nestingByBlockField = new Map<string, string[]>()\r\n  for (const edge of nesting) {\r\n    const key = `${edge.owner}:${edge.fieldPath}`\r\n    if (edge.ownerType === 'global') {\r\n      nestingByGlobalField.set(key, edge.acceptedBlockSlugs)\r\n    } else if (edge.ownerType === 'block') {\r\n      nestingByBlockField.set(key, edge.acceptedBlockSlugs)\r\n    }\r\n  }\r\n\r\n  // Conditional registration: no global has a blocks field → no tool.\r\n  if (nestingByGlobalField.size === 0) return null\r\n\r\n  const patchableSlugs = [...new Set([...nestingByGlobalField.keys()].map((k) => k.split(':')[0]))]\r\n\r\n  return {\r\n    name: 'patchGlobalLayout',\r\n    routing: { kind: 'global', action: 'update' } as const,\r\n    description:\r\n      'Surgically modify a blocks-typed field on a global (e.g. footer sections, header nav) without sending the whole array. Same operation grammar as patchLayout. Use the blockNesting resource to see which slugs each field accepts; global-owned edges have ownerType \"global\".',\r\n    parameters: {\r\n      slug: slugEnum(patchableSlugs, 'global').describe(\r\n        `The global slug whose blocks-typed field will be patched. One of: ${patchableSlugs.join(', ')}`,\r\n      ),\r\n      layoutField: z\r\n        .string()\r\n        .describe(\r\n          'Name (or dotted path) of the blocks-typed field on the global to patch — e.g. \"layout\", \"footer.sections\".',\r\n        ),\r\n      blocks: z\r\n        .array(z.record(z.string(), z.unknown()))\r\n        .describe(\r\n          'Blocks to compose. Each must have a `blockType` discriminator plus any block-specific fields. Nested blocks fields hold their own `blocks` arrays at any depth.',\r\n        ),\r\n      operation: z\r\n        .enum(['append', 'prepend', 'insertAt', 'replaceAt', 'full'])\r\n        .describe(\r\n          'How to apply the blocks: append (end), prepend (start), insertAt (at index), replaceAt (overwrite N starting at index), full (replace entire array — use with care).',\r\n        ),\r\n      insertIndex: z.number().optional().describe('Index for insertAt/replaceAt operations'),\r\n      expectedUpdatedAt: z\r\n        .string()\r\n        .optional()\r\n        .describe(\r\n          'Optional CAS guard. If set, the patch is rejected when the global\\'s current updatedAt differs from this value — protects against lost writes when concurrent edits race. Pass the updatedAt returned by a prior findGlobal call.',\r\n        ),\r\n      locale: z\r\n        .string()\r\n        .optional()\r\n        .describe(\r\n          'Optional locale code (e.g. \"en\", \"fr\") to scope the patch to a single locale on localized blocks fields.',\r\n        ),\r\n    },\r\n    handler: async (\r\n      args: Record<string, unknown>,\r\n      req: PayloadRequest,\r\n      _extra: unknown,\r\n    ) => {\r\n      const { slug, layoutField, blocks, operation, insertIndex, expectedUpdatedAt, locale } =\r\n        args as {\r\n          slug: string\r\n          layoutField: string\r\n          blocks: Array<Record<string, unknown>>\r\n          operation: 'append' | 'prepend' | 'insertAt' | 'replaceAt' | 'full'\r\n          insertIndex?: number\r\n          expectedUpdatedAt?: string\r\n          locale?: string\r\n        }\r\n\r\n      const rootKey = `${slug}:${layoutField}`\r\n      const rootAllowed = nestingByGlobalField.get(rootKey)\r\n      if (!rootAllowed) {\r\n        return errorResponse(\r\n          `Field \"${layoutField}\" on global \"${slug}\" is not a blocks-typed field, or no nesting map entry exists for it.`,\r\n          { availableFields: [...nestingByGlobalField.keys()] },\r\n        )\r\n      }\r\n\r\n      const errors: string[] = []\r\n      validateBlockList(blocks, rootAllowed, layoutField, allBlockSlugs, nestingByBlockField, errors)\r\n\r\n      if (errors.length > 0) {\r\n        return errorResponse('Block validation failed.', { errors })\r\n      }\r\n\r\n      stampMcpContext(req)\r\n\r\n      let existing: Record<string, unknown> | undefined\r\n      try {\r\n        existing = (await req.payload.findGlobal({\r\n          slug: slug as never,\r\n          depth: 0,\r\n          draft: true,\r\n          ...(locale ? { locale: locale as never } : {}),\r\n          req,\r\n          overrideAccess: false,\r\n          user: req.user,\r\n        })) as Record<string, unknown> | undefined\r\n      } catch (error) {\r\n        return errorResponse(`Error fetching global \"${slug}\": ${errorMessage(error)}`)\r\n      }\r\n\r\n      if (expectedUpdatedAt !== undefined) {\r\n        const currentUpdatedAt = (existing as { updatedAt?: unknown })?.updatedAt\r\n        const currentStr =\r\n          typeof currentUpdatedAt === 'string'\r\n            ? currentUpdatedAt\r\n            : currentUpdatedAt instanceof Date\r\n              ? currentUpdatedAt.toISOString()\r\n              : undefined\r\n        if (currentStr !== expectedUpdatedAt) {\r\n          return errorResponse(\r\n            `Conflict: global \"${slug}\" was modified since expectedUpdatedAt (${expectedUpdatedAt}); current updatedAt is ${currentStr ?? 'unknown'}. Re-read the global and retry.`,\r\n            { currentUpdatedAt: currentStr },\r\n          )\r\n        }\r\n      }\r\n\r\n      const currentLayout = readPath(existing, layoutField)\r\n      const finalLayout = applyOperation(blocks, operation, insertIndex, currentLayout)\r\n\r\n      const isDraftGlobal = draftGlobals.has(slug)\r\n\r\n      try {\r\n        await req.payload.updateGlobal({\r\n          slug: slug as never,\r\n          data: writePath(existing ?? {}, layoutField, finalLayout) as never,\r\n          draft: isDraftGlobal,\r\n          ...(locale ? { locale: locale as never } : {}),\r\n          req,\r\n          overrideAccess: false,\r\n          user: req.user,\r\n        })\r\n\r\n        const draftNote = isDraftGlobal ? DRAFT_NOTE : ''\r\n        return jsonResponse({\r\n          success: true,\r\n          message:\r\n            `Patched ${layoutField} on global \"${slug}\". ` +\r\n            `Operation: ${operation}. Block count: ${finalLayout.length}.` +\r\n            draftNote,\r\n          blockCount: finalLayout.length,\r\n          operation,\r\n        })\r\n      } catch (error) {\r\n        return errorResponse(`Error patching global \"${slug}\": ${errorMessage(error)}`)\r\n      }\r\n    },\r\n  }\r\n}\r\n\r\n"],"names":["z","DRAFT_NOTE","errorMessage","jsonResponse","slugEnum","stampMcpContext","applyOperation","errorResponse","readPath","validateBlockList","writePath","createPatchGlobalLayoutTool","catalog","nesting","draftGlobals","allBlockSlugs","Set","blocks","map","b","slug","nestingByGlobalField","Map","nestingByBlockField","edge","key","owner","fieldPath","ownerType","set","acceptedBlockSlugs","size","patchableSlugs","keys","k","split","name","routing","kind","action","description","parameters","describe","join","layoutField","string","array","record","unknown","operation","enum","insertIndex","number","optional","expectedUpdatedAt","locale","handler","args","req","_extra","rootKey","rootAllowed","get","availableFields","errors","length","existing","payload","findGlobal","depth","draft","overrideAccess","user","error","undefined","currentUpdatedAt","updatedAt","currentStr","Date","toISOString","currentLayout","finalLayout","isDraftGlobal","has","updateGlobal","data","draftNote","success","message","blockCount"],"mappings":"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"}

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

@@ -17,6 +17,10 @@ import type { BlockCatalog, BlockNestingMap } from '../types';
  */
 export declare function createPatchLayoutTool(catalog: BlockCatalog, nesting: BlockNestingMap, draftCollections: Set<string>): {
     name: string;
+    routing: {
+        readonly kind: "collection";
+        readonly action: "update";
+    };
     description: string;
     parameters: {
         collection: z.ZodString;
@@ -26,12 +30,5 @@ export declare function createPatchLayoutTool(catalog: BlockCatalog, nesting: Bl
         operation: z.ZodEnum<["append", "prepend", "insertAt", "replaceAt", "full"]>;
         insertIndex: z.ZodOptional<z.ZodNumber>;
     };
-    handler: (args: {
-        collection: string;
-        documentId: string;
-        layoutField?: string;
-        blocks: Array<Record<string, unknown>>;
-        operation: "append" | "prepend" | "insertAt" | "replaceAt" | "full";
-        insertIndex?: number;
-    }, req: PayloadRequest, _extra: unknown) => Promise<import("./_helpers").McpTextResponse>;
+    handler: (args: Record<string, unknown>, req: PayloadRequest, _extra: unknown) => Promise<import("./_helpers").McpTextResponse>;
 };