@payloadcms/plugin-mcp 3.70.0-canary.9 → 3.71.0-canary.2

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
+  })
+}