@payloadcms/plugin-mcp 3.70.0 → 3.71.0-internal.27e1e08

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/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({
@@ -147,6 +171,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.',

package/src/types.ts

@@ -1,4 +1,10 @@
-import type { CollectionConfig, CollectionSlug, PayloadRequest, TypedUser } from 'payload'
+import type {
+  CollectionConfig,
+  CollectionSlug,
+  GlobalSlug,
+  PayloadRequest,
+  TypedUser,
+} from 'payload'
 import type { z } from 'zod'
 
 import { type ResourceTemplate } from '@modelcontextprotocol/sdk/server/mcp.js'
@@ -115,6 +121,51 @@ export type PluginMCPServerConfig = {
       }
     }
   }
+  /**
+   * Set the globals that should be available as resources via MCP.
+   * Globals are singleton configuration objects (e.g., site settings, navigation).
+   * Note: Globals only support find and update operations.
+   */
+  globals?: Partial<
+    Record<
+      GlobalSlug,
+      {
+        /**
+         * Set the description of the global. This is used by MCP clients to determine when to use the global as a resource.
+         */
+        description?: string
+        /**
+         * Set the enabled capabilities of the global. Admins can then allow or disallow the use of the capability by MCP clients.
+         * Note: Globals only support find and update operations as they are singletons.
+         */
+        enabled:
+          | {
+              find?: boolean
+              update?: boolean
+            }
+          | boolean
+
+        /**
+         * Override the response generated by the MCP client. This allows you to modify the response that is sent to the MCP client. This is useful for adding additional data to the response, data normalization, or verifying data.
+         */
+        overrideResponse?: (
+          response: {
+            content: Array<{
+              text: string
+              type: string
+            }>
+          },
+          doc: Record<string, unknown>,
+          req: PayloadRequest,
+        ) => {
+          content: Array<{
+            text: string
+            type: string
+          }>
+        }
+      }
+    >
+  >
   /**
    * MCP Server options.
    */
@@ -349,6 +400,11 @@ export type MCPAccessSettings = {
     find?: boolean
     update?: boolean
   }
+  custom?: Record<string, boolean>
+  globals?: {
+    find?: boolean
+    update?: boolean
+  }
   jobs?: {
     create?: boolean
     run?: boolean
@@ -360,6 +416,8 @@ export type MCPAccessSettings = {
   user: TypedUser
 } & Record<string, unknown>
 
+export type EntityConfig = PluginMCPServerConfig['collections'] | PluginMCPServerConfig['globals']
+
 export type FieldDefinition = {
   description?: string
   name: string

package/src/utils/adminEntitySettings.ts

@@ -0,0 +1,40 @@
+/**
+ * Defines the default admin entity settings for Collections and Globals.
+ * This is used to create the MCP API key permission fields for the API Keys collection.
+ */
+export const adminEntitySettings = {
+  collection: [
+    {
+      name: 'find',
+      description: (slug: string) => `Allow clients to find ${slug}.`,
+      label: 'Find',
+    },
+    {
+      name: 'create',
+      description: (slug: string) => `Allow clients to create ${slug}.`,
+      label: 'Create',
+    },
+    {
+      name: 'update',
+      description: (slug: string) => `Allow clients to update ${slug}.`,
+      label: 'Update',
+    },
+    {
+      name: 'delete',
+      description: (slug: string) => `Allow clients to delete ${slug}.`,
+      label: 'Delete',
+    },
+  ],
+  global: [
+    {
+      name: 'find',
+      description: (slug: string) => `Allow clients to find ${slug} global.`,
+      label: 'Find',
+    },
+    {
+      name: 'update',
+      description: (slug: string) => `Allow clients to update ${slug} global.`,
+      label: 'Update',
+    },
+  ],
+}

package/src/utils/createApiKeyFields.ts

@@ -0,0 +1,72 @@
+import type { Field } from 'payload'
+
+import type { EntityConfig } from '../types.js'
+
+import { adminEntitySettings } from './adminEntitySettings.js'
+import { toCamelCase } from './camelCase.js'
+import { getEnabledSlugs } from './getEnabledSlugs.js'
+/**
+ * Creates MCP API key permission fields using collections or globals.
+ * Generates collapsible field groups with checkboxes for each enabled operation.
+ *
+ * @param config - The collections or globals configuration object
+ * @param configType - The type of configuration ('collection' or 'global')
+ * @returns Array of fields for the MCP API Keys collection
+ */
+export const createApiKeyFields = ({
+  config,
+  configType,
+}: {
+  config: EntityConfig | undefined
+  configType: 'collection' | 'global'
+}): Field[] => {
+  const operations = adminEntitySettings[configType]
+  const enabledSlugs = getEnabledSlugs(config, configType)
+
+  return enabledSlugs.map((slug) => {
+    const entityConfig = config?.[slug]
+
+    const enabledOperations = operations.filter((operation) => {
+      // If fully enabled, all operations are available
+      if (entityConfig?.enabled === true) {
+        return true
+      }
+
+      // If partially enabled, check if this specific operation is enabled
+      const enabled = entityConfig?.enabled
+      if (typeof enabled !== 'boolean' && enabled) {
+        const operationEnabled = enabled[operation.name as keyof typeof enabled]
+        return typeof operationEnabled === 'boolean' && operationEnabled === true
+      }
+
+      return false
+    })
+
+    // Generate checkbox fields for each enabled operation
+    const operationFields = enabledOperations.map((operation) => ({
+      name: operation.name,
+      type: 'checkbox' as const,
+      admin: {
+        description: operation.description(slug),
+      },
+      defaultValue: false,
+      label: operation.label,
+    }))
+
+    return {
+      type: 'collapsible' as const,
+      admin: {
+        position: 'sidebar' as const,
+      },
+      fields: [
+        {
+          name: toCamelCase(slug),
+          type: 'group' as const,
+          fields: operationFields,
+          label: configType,
+        },
+      ],
+      label: `${slug.charAt(0).toUpperCase() + toCamelCase(slug).slice(1)}`,
+    }
+  })
+}

package/src/utils/getEnabledSlugs.ts

@@ -0,0 +1,42 @@
+import type { EntityConfig } from '../types.js'
+
+import { adminEntitySettings } from './adminEntitySettings.js'
+
+/**
+ * Extracts enabled slugs from collections or globals configuration.
+ * A slug is considered enabled if:
+ * 1. enabled is set to true (fully enabled)
+ * 2. enabled is an object with at least one operation set to true
+ *
+ * @param config - The collections or globals configuration object
+ * @param configType - The type of configuration ('collection' or 'global')
+ * @returns Array of enabled slugs
+ */
+export const getEnabledSlugs = (
+  config: EntityConfig | undefined,
+  configType: 'collection' | 'global',
+): string[] => {
+  return Object.keys(config || {}).filter((slug) => {
+    const entityConfig = config?.[slug]
+    const operations = adminEntitySettings[configType]
+
+    // Check if fully enabled (boolean true)
+    const fullyEnabled =
+      typeof entityConfig?.enabled === 'boolean' && entityConfig?.enabled === true
+
+    if (fullyEnabled) {
+      return true
+    }
+
+    // Check if partially enabled (at least one operation is enabled)
+    const enabled = entityConfig?.enabled
+    if (typeof enabled !== 'boolean' && enabled) {
+      return operations.some((operation) => {
+        const operationEnabled = enabled[operation.name as keyof typeof enabled]
+        return typeof operationEnabled === 'boolean' && operationEnabled === true
+      })
+    }
+
+    return false
+  })
+}