@payloadcms/plugin-mcp 0.0.1-alpha.0

package/src/collections/createApiKeysCollection.ts

@@ -0,0 +1,393 @@
+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: {
+      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: `${enabledCollectionSlug.charAt(0).toUpperCase() + toCamelCase(enabledCollectionSlug).slice(1)}`,
+  }))
+}
+
+export const createAPIKeysCollection = (
+  collections: PluginMCPServerConfig['collections'],
+  customTools: Array<{ description: string; name: string }> = [],
+  experimentalTools: NonNullable<PluginMCPServerConfig['experimental']>['tools'] = {},
+): CollectionConfig => {
+  const customToolsFields = customTools.map((tool) => {
+    const camelCasedName = toCamelCase(tool.name)
+    return {
+      name: camelCasedName,
+      type: 'checkbox' as const,
+      admin: {
+        description: tool.description,
+      },
+      defaultValue: true,
+      label: camelCasedName,
+    }
+  })
+
+  return {
+    slug: 'payload-mcp-api-keys',
+    admin: {
+      group: 'MCP',
+      useAsTitle: 'label',
+    },
+    auth: {
+      disableLocalStrategy: true,
+      useAPIKey: true,
+    },
+    fields: [
+      {
+        name: 'user',
+        type: 'relationship',
+        admin: {
+          description: 'The user that the API key is associated with.',
+        },
+        relationTo: 'users',
+        required: true,
+      },
+      {
+        name: 'label',
+        type: 'text',
+        admin: {
+          description: 'A useful label for the API key.',
+        },
+      },
+      {
+        name: 'description',
+        type: 'text',
+        admin: {
+          description: 'The purpose of the API key.',
+        },
+      },
+
+      ...addEnabledCollectionTools(collections),
+
+      ...(customTools.length > 0
+        ? [
+            {
+              type: 'collapsible' as const,
+              admin: {
+                position: 'sidebar' as const,
+              },
+              fields: [
+                {
+                  name: 'custom',
+                  type: 'group' as const,
+                  fields: customToolsFields,
+                },
+              ],
+              label: 'Custom Tools',
+            },
+          ]
+        : []),
+
+      // Experimental Tools
+      ...(process.env.NODE_ENV === 'development' &&
+      (experimentalTools?.collections?.enabled ||
+        experimentalTools?.jobs?.enabled ||
+        experimentalTools?.config?.enabled ||
+        experimentalTools?.auth?.enabled)
+        ? [
+            {
+              type: 'collapsible' as const,
+              admin: {
+                position: 'sidebar' as const,
+              },
+              fields: [
+                ...(experimentalTools?.collections?.enabled
+                  ? [
+                      {
+                        name: 'collections',
+                        type: 'group' as const,
+                        fields: [
+                          {
+                            name: 'find',
+                            type: 'checkbox' as const,
+                            admin: {
+                              description:
+                                'Allow LLMs to find and list Payload collections with optional content and document counts.',
+                            },
+                            defaultValue: false,
+                          },
+                          {
+                            name: 'create',
+                            type: 'checkbox' as const,
+                            admin: {
+                              description:
+                                'Allow LLMs to create new Payload collections with specified fields and configuration.',
+                            },
+                            defaultValue: false,
+                          },
+                          {
+                            name: 'update',
+                            type: 'checkbox' as const,
+                            admin: {
+                              description:
+                                'Allow LLMs to update existing Payload collections with new fields, modifications, or configuration changes.',
+                            },
+                            defaultValue: false,
+                          },
+                          {
+                            name: 'delete',
+                            type: 'checkbox' as const,
+                            admin: {
+                              description:
+                                'Allow LLMs to delete Payload collections and optionally update the configuration.',
+                            },
+                            defaultValue: false,
+                          },
+                        ],
+                      },
+                    ]
+                  : []),
+                ...(experimentalTools?.jobs?.enabled
+                  ? [
+                      {
+                        name: 'jobs',
+                        type: 'group' as const,
+                        fields: [
+                          {
+                            name: 'create',
+                            type: 'checkbox' as const,
+                            admin: {
+                              description:
+                                'Allow LLMs to create new Payload jobs (tasks and workflows) with custom schemas and configuration.',
+                            },
+                            defaultValue: false,
+                          },
+                          {
+                            name: 'run',
+                            type: 'checkbox' as const,
+                            admin: {
+                              description:
+                                'Allow LLMs to execute Payload jobs with custom input data and queue options.',
+                            },
+                            defaultValue: false,
+                          },
+                          {
+                            name: 'update',
+                            type: 'checkbox' as const,
+                            admin: {
+                              description:
+                                'Allow LLMs to update existing Payload jobs with new schemas, configuration, or handler code.',
+                            },
+                            defaultValue: false,
+                          },
+                        ],
+                      },
+                    ]
+                  : []),
+                ...(experimentalTools?.config?.enabled
+                  ? [
+                      {
+                        name: 'config',
+                        type: 'group' as const,
+                        fields: [
+                          {
+                            name: 'find',
+                            type: 'checkbox' as const,
+                            admin: {
+                              description:
+                                'Allow LLMs to read and display a Payload configuration file.',
+                            },
+                            defaultValue: false,
+                          },
+                          {
+                            name: 'update',
+                            type: 'checkbox' as const,
+                            admin: {
+                              description:
+                                'Allow LLMs to update a Payload configuration file with various modifications.',
+                            },
+                            defaultValue: false,
+                          },
+                        ],
+                      },
+                    ]
+                  : []),
+                ...(experimentalTools?.auth?.enabled
+                  ? [
+                      {
+                        name: 'auth',
+                        type: 'group' as const,
+                        fields: [
+                          {
+                            name: 'auth',
+                            type: 'checkbox' as const,
+                            admin: {
+                              description:
+                                'Allow LLMs to check authentication status for a user by setting custom headers. (e.g. {"Authorization": "Bearer <token>"})',
+                            },
+                            defaultValue: false,
+                            label: 'Check Auth Status',
+                          },
+                          {
+                            name: 'login',
+                            type: 'checkbox' as const,
+                            admin: {
+                              description:
+                                'Allow LLMs to authenticate a user with email and password.',
+                            },
+                            defaultValue: false,
+                            label: 'User Login',
+                          },
+                          {
+                            name: 'verify',
+                            type: 'checkbox' as const,
+                            admin: {
+                              description:
+                                'Allow LLMs to verify a user email with a verification token.',
+                            },
+                            defaultValue: false,
+                            label: 'Email Verification',
+                          },
+                          {
+                            name: 'resetPassword',
+                            type: 'checkbox' as const,
+                            admin: {
+                              description:
+                                'Allow LLMs to reset a user password with a reset token.',
+                            },
+                            defaultValue: false,
+                            label: 'Reset Password',
+                          },
+                          {
+                            name: 'forgotPassword',
+                            type: 'checkbox' as const,
+                            admin: {
+                              description: 'Allow LLMs to send a password reset email to a user.',
+                            },
+                            defaultValue: false,
+                            label: 'Forgot Password',
+                          },
+                          {
+                            name: 'unlock',
+                            type: 'checkbox' as const,
+                            admin: {
+                              description:
+                                'Allow LLMs to unlock a user account that has been locked due to failed login attempts.',
+                            },
+                            defaultValue: false,
+                            label: 'Unlock Account',
+                          },
+                        ],
+                      },
+                    ]
+                  : []),
+              ],
+              label: 'Experimental Tools',
+            },
+          ]
+        : []),
+    ],
+    labels: {
+      plural: 'API Keys',
+      singular: 'API Key',
+    },
+  }
+}

package/src/endpoints/mcp.ts

@@ -0,0 +1,60 @@
+import crypto from 'crypto'
+import { APIError, type PayloadHandler, type Where } from 'payload'
+
+import type { PluginMCPServerConfig, ToolSettings } from '../types.js'
+
+import { createRequestFromPayloadRequest } from '../mcp/createRequest.js'
+import { getMCPHandler } from '../mcp/getMcpHandler.js'
+
+export const initializeMCPHandler = (pluginOptions: PluginMCPServerConfig) => {
+  const mcpHandler: PayloadHandler = async (req) => {
+    const { payload } = req
+    const MCPOptions = pluginOptions.mcp || {}
+    const MCPHandlerOptions = MCPOptions.handlerOptions || {}
+    const useVerboseLogs = MCPHandlerOptions.verboseLogs ?? false
+
+    const apiKey = req.headers.get('Authorization')?.startsWith('Bearer ')
+      ? req.headers.get('Authorization')?.replace('Bearer ', '').trim()
+      : null
+
+    if (apiKey === null) {
+      throw new APIError('API Key is required', 401)
+    }
+
+    const sha256APIKeyIndex = crypto
+      .createHmac('sha256', payload.secret)
+      .update(apiKey || '')
+      .digest('hex')
+
+    const apiKeyConstraints = [
+      {
+        apiKeyIndex: {
+          equals: sha256APIKeyIndex,
+        },
+      },
+    ]
+    const where: Where = {
+      or: apiKeyConstraints,
+    }
+
+    const { docs } = await payload.find({
+      collection: 'payload-mcp-api-keys',
+      where,
+    })
+
+    if (docs.length === 0) {
+      throw new APIError('API Key is invalid', 401)
+    }
+
+    const toolSettings = docs[0] as ToolSettings
+
+    if (useVerboseLogs) {
+      payload.logger.info('[payload-mcp] API Key is valid')
+    }
+
+    const handler = getMCPHandler(pluginOptions, toolSettings, req)
+    const request = createRequestFromPayloadRequest(req)
+    return await handler(request)
+  }
+  return mcpHandler
+}

package/src/index.ts

@@ -0,0 +1,86 @@
+import type { Config } from 'payload'
+
+import type { PluginMCPServerConfig } from './types.js'
+
+import { createAPIKeysCollection } from './collections/createApiKeysCollection.js'
+import { initializeMCPHandler } from './endpoints/mcp.js'
+
+/**
+ * The MCP Plugin for Payload. This plugin allows you to add MCP capabilities to your Payload project.
+ *
+ * @param pluginOptions - The options for the MCP plugin.
+ * @experimental This plugin is experimental and may change in the future.
+ */
+export const mcpPlugin =
+  (pluginOptions: PluginMCPServerConfig) =>
+  (config: Config): Config => {
+    if (!config.collections) {
+      config.collections = []
+    }
+
+    // Collections
+    const collections = pluginOptions.collections || {}
+    // Extract custom tools for the global config
+    const customTools =
+      pluginOptions.mcp?.tools?.map((tool) => ({
+        name: tool.name,
+        description: tool.description,
+      })) || []
+
+    const experimentalTools = pluginOptions?.experimental?.tools || {}
+
+    /**
+     * API Keys
+     * --------
+     * High resolution control over MCP capabilities is crucial when using Payload with LLMs.
+     *
+     * This API Keys collection has ways for admins to create API keys and allow or disallow the MCP capabilities.
+     * This is useful when Admins want to allow or disallow the use of the MCP capabilities in real time.
+     * 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 custom tool has gone haywire, admins can disallow that tool.
+     *
+     */
+    const apiKeyCollection = createAPIKeysCollection(collections, customTools, experimentalTools)
+    if (pluginOptions.overrideApiKeyCollection) {
+      config.collections.push(pluginOptions.overrideApiKeyCollection(apiKeyCollection))
+    } else {
+      config.collections.push(apiKeyCollection)
+    }
+
+    /**
+     * If the plugin is disabled, we still want to keep added collections/fields so the database schema is consistent which is important for migrations.
+     * If your plugin heavily modifies the database schema, you may want to remove this property.
+     */
+    if (pluginOptions.disabled) {
+      return config
+    }
+
+    if (!config.endpoints) {
+      config.endpoints = []
+    }
+
+    /**
+     * This is the primary MCP Server Endpoint.
+     * Payload will automatically add the /api prefix to the path, so the full path is `/api/mcp`
+     * NOTE: This is only transport method until we add full support for SSE which will be another endpoint at `/api/sse`
+     */
+    config.endpoints.push({
+      handler: initializeMCPHandler(pluginOptions),
+      method: 'post',
+      path: '/mcp',
+    })
+
+    /**
+     * The GET response is always: {"jsonrpc":"2.0","error":{"code":-32000,"message":"Method not allowed."},"id":null} -- even with an API key
+     * This is expected behavior and MCP clients should always use the POST endpoint.
+     */
+    config.endpoints.push({
+      handler: initializeMCPHandler(pluginOptions),
+      method: 'get',
+      path: '/mcp',
+    })
+
+    return config
+  }

package/src/mcp/createRequest.ts

@@ -0,0 +1,13 @@
+import { APIError, type PayloadRequest } from 'payload'
+
+export const createRequestFromPayloadRequest = (req: PayloadRequest) => {
+  if (!req.url) {
+    throw new APIError('Request URL is required', 500)
+  }
+  return new Request(req.url, {
+    body: req.body,
+    duplex: 'half',
+    headers: req.headers,
+    method: req.method,
+  } as { duplex: 'half' } & RequestInit)
+}