@payloadcms/plugin-mcp 3.70.0 → 3.71.0-canary.3

package/src/collections/createApiKeysCollection.ts

@@ -3,119 +3,11 @@ import type { CollectionConfig } from 'payload'
 import type { PluginMCPServerConfig } from '../types.js'
 
 import { toCamelCase } from '../utils/camelCase.js'
-
-const addEnabledCollectionTools = (collections: PluginMCPServerConfig['collections']) => {
-  const enabledCollectionSlugs = Object.keys(collections || {}).filter((collection) => {
-    const fullyEnabled =
-      typeof collections?.[collection]?.enabled === 'boolean' && collections?.[collection]?.enabled
-
-    if (fullyEnabled) {
-      return true
-    }
-
-    const partiallyEnabled =
-      typeof collections?.[collection]?.enabled !== 'boolean' &&
-      ((typeof collections?.[collection]?.enabled?.find === 'boolean' &&
-        collections?.[collection]?.enabled?.find === true) ||
-        (typeof collections?.[collection]?.enabled?.create === 'boolean' &&
-          collections?.[collection]?.enabled?.create === true) ||
-        (typeof collections?.[collection]?.enabled?.update === 'boolean' &&
-          collections?.[collection]?.enabled?.update === true) ||
-        (typeof collections?.[collection]?.enabled?.delete === 'boolean' &&
-          collections?.[collection]?.enabled?.delete === true))
-
-    if (partiallyEnabled) {
-      return true
-    }
-  })
-  return enabledCollectionSlugs.map((enabledCollectionSlug) => ({
-    type: 'collapsible' as const,
-    admin: {
-      description: `Manage client access to ${enabledCollectionSlug}`,
-      position: 'sidebar' as const,
-    },
-    fields: [
-      {
-        name: `${toCamelCase(enabledCollectionSlug)}`,
-        type: 'group' as const,
-        fields: [
-          ...(collections?.[enabledCollectionSlug]?.enabled === true ||
-          (typeof collections?.[enabledCollectionSlug]?.enabled !== 'boolean' &&
-            typeof collections?.[enabledCollectionSlug]?.enabled?.find === 'boolean' &&
-            collections?.[enabledCollectionSlug]?.enabled?.find === true)
-            ? [
-                {
-                  name: `find`,
-                  type: 'checkbox' as const,
-                  admin: {
-                    description: `Allow clients to find ${enabledCollectionSlug}.`,
-                  },
-                  defaultValue: false,
-                  label: 'Find',
-                },
-              ]
-            : []),
-
-          ...(collections?.[enabledCollectionSlug]?.enabled === true ||
-          (typeof collections?.[enabledCollectionSlug]?.enabled !== 'boolean' &&
-            typeof collections?.[enabledCollectionSlug]?.enabled?.create === 'boolean' &&
-            collections?.[enabledCollectionSlug]?.enabled?.create === true)
-            ? [
-                {
-                  name: `create`,
-                  type: 'checkbox' as const,
-                  admin: {
-                    description: `Allow clients to create ${enabledCollectionSlug}.`,
-                  },
-                  defaultValue: false,
-                  label: 'Create',
-                },
-              ]
-            : []),
-
-          ...(collections?.[enabledCollectionSlug]?.enabled === true ||
-          (typeof collections?.[enabledCollectionSlug]?.enabled !== 'boolean' &&
-            typeof collections?.[enabledCollectionSlug]?.enabled?.update === 'boolean' &&
-            collections?.[enabledCollectionSlug]?.enabled?.update === true)
-            ? [
-                {
-                  name: `update`,
-                  type: 'checkbox' as const,
-                  admin: {
-                    description: `Allow clients to update ${enabledCollectionSlug}.`,
-                  },
-                  defaultValue: false,
-                  label: 'Update',
-                },
-              ]
-            : []),
-
-          ...(collections?.[enabledCollectionSlug]?.enabled === true ||
-          (typeof collections?.[enabledCollectionSlug]?.enabled !== 'boolean' &&
-            typeof collections?.[enabledCollectionSlug]?.enabled?.delete === 'boolean' &&
-            collections?.[enabledCollectionSlug]?.enabled?.delete === true)
-            ? [
-                {
-                  name: `delete`,
-                  type: 'checkbox' as const,
-                  admin: {
-                    description: `Allow clients to delete ${enabledCollectionSlug}.`,
-                  },
-                  defaultValue: false,
-                  label: 'Delete',
-                },
-              ]
-            : []),
-        ],
-        label: false as const,
-      },
-    ],
-    label: `${enabledCollectionSlug.charAt(0).toUpperCase() + toCamelCase(enabledCollectionSlug).slice(1)}`,
-  }))
-}
+import { createApiKeyFields } from '../utils/createApiKeyFields.js'
 
 export const createAPIKeysCollection = (
   collections: PluginMCPServerConfig['collections'],
+  globals: PluginMCPServerConfig['globals'],
   customTools: Array<{ description: string; name: string }> = [],
   experimentalTools: NonNullable<PluginMCPServerConfig['experimental']>['tools'] = {},
   pluginOptions: PluginMCPServerConfig,
@@ -204,7 +96,15 @@ export const createAPIKeysCollection = (
         },
       },
 
-      ...addEnabledCollectionTools(collections),
+      ...createApiKeyFields({
+        config: collections,
+        configType: 'collection',
+      }),
+
+      ...createApiKeyFields({
+        config: globals,
+        configType: 'global',
+      }),
 
       ...(customTools.length > 0
         ? [

package/src/endpoints/mcp.ts

@@ -44,6 +44,7 @@ export const initializeMCPHandler = (pluginOptions: PluginMCPServerConfig) => {
 
       const { docs } = await payload.find({
         collection: 'payload-mcp-api-keys',
+        depth: 1,
         limit: 1,
         pagination: false,
         where,

package/src/index.ts

@@ -27,6 +27,8 @@ export const mcpPlugin =
 
     // Collections
     const collections = pluginOptions.collections || {}
+    // Globals
+    const globals = pluginOptions.globals || {}
     // Extract custom tools for the global config
     const customTools =
       pluginOptions.mcp?.tools?.map((tool) => ({
@@ -46,11 +48,13 @@ export const mcpPlugin =
      * For example:
      *  - If a collection has all of its capabilities enabled, admins can allow or disallow the create, update, delete, and find capabilities on that collection.
      *  - If a collection only has the find capability enabled, admins can only allow or disallow the find capability on that collection.
+     *  - If a global has all of its capabilities enabled, admins can allow or disallow the find and update capabilities on that global.
      *  - If a custom tool has gone haywire, admins can disallow that tool.
      *
      */
     const apiKeyCollection = createAPIKeysCollection(
       collections,
+      globals,
       customTools,
       experimentalTools,
       pluginOptions,

package/src/mcp/getMcpHandler.ts

@@ -7,9 +7,12 @@ import { APIError, configToJSONSchema, type PayloadRequest, type TypedUser } fro
 import type { MCPAccessSettings, PluginMCPServerConfig } from '../types.js'
 
 import { toCamelCase } from '../utils/camelCase.js'
+import { getEnabledSlugs } from '../utils/getEnabledSlugs.js'
 import { registerTool } from './registerTool.js'
 
 // Tools
+import { findGlobalTool } from './tools/global/find.js'
+import { updateGlobalTool } from './tools/global/update.js'
 import { createResourceTool } from './tools/resource/create.js'
 import { deleteResourceTool } from './tools/resource/delete.js'
 import { findResourceTool } from './tools/resource/find.js'
@@ -81,6 +84,7 @@ export const getMCPHandler = (
   const experimentalTools: NonNullable<PluginMCPServerConfig['experimental']>['tools'] =
     pluginOptions?.experimental?.tools || {}
   const collectionsPluginConfig = pluginOptions.collections || {}
+  const globalsPluginConfig = pluginOptions.globals || {}
   const collectionsDirPath =
     experimentalTools && experimentalTools.collections?.collectionsDirPath
       ? experimentalTools.collections.collectionsDirPath
@@ -97,32 +101,8 @@ export const getMCPHandler = (
   try {
     return createMcpHandler(
       (server) => {
-        const enabledCollectionSlugs = Object.keys(collectionsPluginConfig || {}).filter(
-          (collection) => {
-            const fullyEnabled =
-              typeof collectionsPluginConfig?.[collection]?.enabled === 'boolean' &&
-              collectionsPluginConfig?.[collection]?.enabled
-
-            if (fullyEnabled) {
-              return true
-            }
-
-            const partiallyEnabled =
-              typeof collectionsPluginConfig?.[collection]?.enabled !== 'boolean' &&
-              ((typeof collectionsPluginConfig?.[collection]?.enabled?.find === 'boolean' &&
-                collectionsPluginConfig?.[collection]?.enabled?.find === true) ||
-                (typeof collectionsPluginConfig?.[collection]?.enabled?.create === 'boolean' &&
-                  collectionsPluginConfig?.[collection]?.enabled?.create === true) ||
-                (typeof collectionsPluginConfig?.[collection]?.enabled?.update === 'boolean' &&
-                  collectionsPluginConfig?.[collection]?.enabled?.update === true) ||
-                (typeof collectionsPluginConfig?.[collection]?.enabled?.delete === 'boolean' &&
-                  collectionsPluginConfig?.[collection]?.enabled?.delete === true))
-
-            if (partiallyEnabled) {
-              return true
-            }
-          },
-        )
+        // Get enabled collections
+        const enabledCollectionSlugs = getEnabledSlugs(collectionsPluginConfig, 'collection')
 
         // Collection Operation Tools
         enabledCollectionSlugs.forEach((enabledCollectionSlug) => {
@@ -215,6 +195,62 @@ export const getMCPHandler = (
           }
         })
 
+        // Global Operation Tools
+        const enabledGlobalSlugs = getEnabledSlugs(globalsPluginConfig, 'global')
+
+        enabledGlobalSlugs.forEach((enabledGlobalSlug) => {
+          try {
+            const schema = configSchema.definitions?.[enabledGlobalSlug] as JSONSchema4
+
+            const toolCapabilities = mcpAccessSettings?.[
+              `${toCamelCase(enabledGlobalSlug)}`
+            ] as Record<string, unknown>
+            const allowFind: boolean | undefined = toolCapabilities?.['find'] as boolean
+            const allowUpdate: boolean | undefined = toolCapabilities?.['update'] as boolean
+
+            if (allowFind) {
+              registerTool(
+                allowFind,
+                `Find ${enabledGlobalSlug}`,
+                () =>
+                  findGlobalTool(
+                    server,
+                    req,
+                    user,
+                    useVerboseLogs,
+                    enabledGlobalSlug,
+                    globalsPluginConfig,
+                  ),
+                payload,
+                useVerboseLogs,
+              )
+            }
+            if (allowUpdate) {
+              registerTool(
+                allowUpdate,
+                `Update ${enabledGlobalSlug}`,
+                () =>
+                  updateGlobalTool(
+                    server,
+                    req,
+                    user,
+                    useVerboseLogs,
+                    enabledGlobalSlug,
+                    globalsPluginConfig,
+                    schema,
+                  ),
+                payload,
+                useVerboseLogs,
+              )
+            }
+          } catch (error) {
+            throw new APIError(
+              `Error registering tools for global ${enabledGlobalSlug}: ${String(error)}`,
+              500,
+            )
+          }
+        })
+
         // Custom tools
         customMCPTools.forEach((tool) => {
           const camelCasedToolName = toCamelCase(tool.name)

package/src/mcp/tools/global/find.ts

@@ -0,0 +1,104 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
+import type { PayloadRequest, TypedUser } from 'payload'
+
+import type { PluginMCPServerConfig } from '../../../types.js'
+
+import { toCamelCase } from '../../../utils/camelCase.js'
+import { toolSchemas } from '../schemas.js'
+
+export const findGlobalTool = (
+  server: McpServer,
+  req: PayloadRequest,
+  user: TypedUser,
+  verboseLogs: boolean,
+  globalSlug: string,
+  globals: PluginMCPServerConfig['globals'],
+) => {
+  const tool = async (
+    depth: number = 0,
+    locale?: string,
+    fallbackLocale?: string,
+  ): Promise<{
+    content: Array<{
+      text: string
+      type: 'text'
+    }>
+  }> => {
+    const payload = req.payload
+
+    if (verboseLogs) {
+      payload.logger.info(
+        `[payload-mcp] Reading global: ${globalSlug}, depth: ${depth}${locale ? `, locale: ${locale}` : ''}`,
+      )
+    }
+
+    try {
+      const findOptions: Parameters<typeof payload.findGlobal>[0] = {
+        slug: globalSlug,
+        depth,
+        user,
+      }
+
+      // Add locale parameters if provided
+      if (locale) {
+        findOptions.locale = locale
+      }
+      if (fallbackLocale) {
+        findOptions.fallbackLocale = fallbackLocale
+      }
+
+      const result = await payload.findGlobal(findOptions)
+
+      if (verboseLogs) {
+        payload.logger.info(`[payload-mcp] Found global: ${globalSlug}`)
+      }
+
+      const response = {
+        content: [
+          {
+            type: 'text' as const,
+            text: `Global "${globalSlug}":
+\`\`\`json
+${JSON.stringify(result, null, 2)}
+\`\`\``,
+          },
+        ],
+      }
+
+      return (globals?.[globalSlug]?.overrideResponse?.(response, result, req) || response) as {
+        content: Array<{
+          text: string
+          type: 'text'
+        }>
+      }
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : 'Unknown error'
+      payload.logger.error(`[payload-mcp] Error reading global ${globalSlug}: ${errorMessage}`)
+      const response = {
+        content: [
+          {
+            type: 'text' as const,
+            text: `❌ **Error reading global "${globalSlug}":** ${errorMessage}`,
+          },
+        ],
+      }
+      return (globals?.[globalSlug]?.overrideResponse?.(response, {}, req) || response) as {
+        content: Array<{
+          text: string
+          type: 'text'
+        }>
+      }
+    }
+  }
+
+  if (globals?.[globalSlug]?.enabled) {
+    server.tool(
+      `find${globalSlug.charAt(0).toUpperCase() + toCamelCase(globalSlug).slice(1)}`,
+      `${toolSchemas.findGlobal.description.trim()}\n\n${globals?.[globalSlug]?.description || ''}`,
+      toolSchemas.findGlobal.parameters.shape,
+      async ({ depth, fallbackLocale, locale }) => {
+        return await tool(depth, locale, fallbackLocale)
+      },
+    )
+  }
+}

package/src/mcp/tools/global/update.ts

@@ -0,0 +1,168 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
+import type { JSONSchema4 } from 'json-schema'
+import type { PayloadRequest, TypedUser } from 'payload'
+
+import { z } from 'zod'
+
+import type { PluginMCPServerConfig } from '../../../types.js'
+
+import { toCamelCase } from '../../../utils/camelCase.js'
+import { convertCollectionSchemaToZod } from '../../../utils/convertCollectionSchemaToZod.js'
+import { toolSchemas } from '../schemas.js'
+
+export const updateGlobalTool = (
+  server: McpServer,
+  req: PayloadRequest,
+  user: TypedUser,
+  verboseLogs: boolean,
+  globalSlug: string,
+  globals: PluginMCPServerConfig['globals'],
+  schema: JSONSchema4,
+) => {
+  const tool = async (
+    data: string,
+    draft: boolean = false,
+    depth: number = 0,
+    locale?: string,
+    fallbackLocale?: string,
+  ): Promise<{
+    content: Array<{
+      text: string
+      type: 'text'
+    }>
+  }> => {
+    const payload = req.payload
+
+    if (verboseLogs) {
+      payload.logger.info(
+        `[payload-mcp] Updating global: ${globalSlug}, draft: ${draft}${locale ? `, locale: ${locale}` : ''}`,
+      )
+    }
+
+    try {
+      // Parse the data JSON
+      let parsedData: Record<string, unknown>
+      try {
+        parsedData = JSON.parse(data)
+        if (verboseLogs) {
+          payload.logger.info(
+            `[payload-mcp] Parsed data for ${globalSlug}: ${JSON.stringify(parsedData)}`,
+          )
+        }
+      } catch (_parseError) {
+        payload.logger.error(`[payload-mcp] Invalid JSON data provided: ${data}`)
+        const response = {
+          content: [{ type: 'text' as const, text: 'Error: Invalid JSON data provided' }],
+        }
+        return (globals?.[globalSlug]?.overrideResponse?.(response, {}, req) || response) as {
+          content: Array<{
+            text: string
+            type: 'text'
+          }>
+        }
+      }
+
+      const updateOptions: Parameters<typeof payload.updateGlobal>[0] = {
+        slug: globalSlug,
+        data: parsedData,
+        depth,
+        draft,
+        user,
+      }
+
+      // Add locale parameters if provided
+      if (locale) {
+        updateOptions.locale = locale
+      }
+      if (fallbackLocale) {
+        updateOptions.fallbackLocale = fallbackLocale
+      }
+
+      const result = await payload.updateGlobal(updateOptions)
+
+      if (verboseLogs) {
+        payload.logger.info(`[payload-mcp] Successfully updated global: ${globalSlug}`)
+      }
+
+      const response = {
+        content: [
+          {
+            type: 'text' as const,
+            text: `Global "${globalSlug}" updated successfully!
+\`\`\`json
+${JSON.stringify(result, null, 2)}
+\`\`\``,
+          },
+        ],
+      }
+
+      return (globals?.[globalSlug]?.overrideResponse?.(response, result, req) || response) as {
+        content: Array<{
+          text: string
+          type: 'text'
+        }>
+      }
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : 'Unknown error'
+      payload.logger.error(`[payload-mcp] Error updating global ${globalSlug}: ${errorMessage}`)
+
+      const response = {
+        content: [
+          {
+            type: 'text' as const,
+            text: `Error updating global "${globalSlug}": ${errorMessage}`,
+          },
+        ],
+      }
+
+      return (globals?.[globalSlug]?.overrideResponse?.(response, {}, req) || response) as {
+        content: Array<{
+          text: string
+          type: 'text'
+        }>
+      }
+    }
+  }
+
+  if (globals?.[globalSlug]?.enabled) {
+    const convertedFields = convertCollectionSchemaToZod(schema)
+
+    // Make all fields optional for partial updates (PATCH-style)
+    const optionalFields = Object.fromEntries(
+      Object.entries(convertedFields.shape).map(([key, value]) => [key, (value as any).optional()]),
+    )
+
+    const updateGlobalSchema = z.object({
+      ...optionalFields,
+      depth: z.number().optional().describe('Optional: Depth of relationships to populate'),
+      draft: z.boolean().optional().describe('Optional: Whether to save as draft (default: false)'),
+      fallbackLocale: z
+        .string()
+        .optional()
+        .describe('Optional: fallback locale code to use when requested locale is not available'),
+      locale: z
+        .string()
+        .optional()
+        .describe(
+          'Optional: locale code to update data in (e.g., "en", "es"). Use "all" to update all locales for localized fields',
+        ),
+    })
+
+    server.tool(
+      `update${globalSlug.charAt(0).toUpperCase() + toCamelCase(globalSlug).slice(1)}`,
+      `${toolSchemas.updateGlobal.description.trim()}\n\n${globals?.[globalSlug]?.description || ''}`,
+      updateGlobalSchema.shape,
+      async (params: Record<string, unknown>) => {
+        const { depth, draft, fallbackLocale, locale, ...rest } = params
+        const data = JSON.stringify(rest)
+        return await tool(
+          data,
+          draft as boolean,
+          depth as number,
+          locale as string,
+          fallbackLocale as string,
+        )
+      },
+    )
+  }
+}

package/src/mcp/tools/resource/find.ts

@@ -22,6 +22,7 @@ export const findResourceTool = (
     where?: string,
     locale?: string,
     fallbackLocale?: string,
+    draft?: boolean,
   ): Promise<{
     content: Array<{
       text: string
@@ -71,6 +72,7 @@ export const findResourceTool = (
             user,
             ...(locale && { locale }),
             ...(fallbackLocale && { fallbackLocale }),
+            ...(draft !== undefined && { draft }),
           })
 
           if (verboseLogs) {
@@ -126,6 +128,7 @@ ${JSON.stringify(doc, null, 2)}`,
         user,
         ...(locale && { locale }),
         ...(fallbackLocale && { fallbackLocale }),
+        ...(draft !== undefined && { draft }),
       }
 
       if (sort) {
@@ -196,8 +199,8 @@ Page: ${result.page} of ${result.totalPages}
       `find${collectionSlug.charAt(0).toUpperCase() + toCamelCase(collectionSlug).slice(1)}`,
       `${collections?.[collectionSlug]?.description || toolSchemas.findResources.description.trim()}`,
       toolSchemas.findResources.parameters.shape,
-      async ({ id, fallbackLocale, limit, locale, page, sort, where }) => {
-        return await tool(id, limit, page, sort, where, locale, fallbackLocale)
+      async ({ id, draft, fallbackLocale, limit, locale, page, sort, where }) => {
+        return await tool(id, limit, page, sort, where, locale, fallbackLocale, draft)
       },
     )
   }

package/src/mcp/tools/schemas.ts

@@ -1,6 +1,30 @@
 import { z } from 'zod'
 
 export const toolSchemas = {
+  findGlobal: {
+    description: 'Find a Payload global singleton configuration.',
+    parameters: z.object({
+      depth: z
+        .number()
+        .int()
+        .min(0)
+        .max(10)
+        .optional()
+        .default(0)
+        .describe('Depth of population for relationships'),
+      fallbackLocale: z
+        .string()
+        .optional()
+        .describe('Optional: fallback locale code to use when requested locale is not available'),
+      locale: z
+        .string()
+        .optional()
+        .describe(
+          'Optional: locale code to retrieve data in (e.g., "en", "es"). Use "all" to retrieve all locales for localized fields',
+        ),
+    }),
+  },
+
   findResources: {
     description: 'Find documents in a collection by ID or where clause using Find or FindByID.',
     parameters: z.object({
@@ -10,6 +34,12 @@ export const toolSchemas = {
         .describe(
           'Optional: specific document ID to retrieve. If not provided, returns all documents',
         ),
+      draft: z
+        .boolean()
+        .optional()
+        .describe(
+          'Optional: Whether the document should be queried from the versions table/collection or not.',
+        ),
       fallbackLocale: z
         .string()
         .optional()
@@ -147,6 +177,32 @@ export const toolSchemas = {
     }),
   },
 
+  updateGlobal: {
+    description: 'Update a Payload global singleton configuration.',
+    parameters: z.object({
+      data: z.string().describe('JSON string containing the data to update'),
+      depth: z
+        .number()
+        .int()
+        .min(0)
+        .max(10)
+        .optional()
+        .default(0)
+        .describe('Depth of population for relationships'),
+      draft: z.boolean().optional().default(false).describe('Whether to update as a draft'),
+      fallbackLocale: z
+        .string()
+        .optional()
+        .describe('Optional: fallback locale code to use when requested locale is not available'),
+      locale: z
+        .string()
+        .optional()
+        .describe(
+          'Optional: locale code to update data in (e.g., "en", "es"). Use "all" to update all locales for localized fields',
+        ),
+    }),
+  },
+
   // Experimental Below This Line
   createCollection: {
     description: 'Creates a new collection with specified fields and configuration.',