@payloadcms/plugin-mcp 4.0.0-internal.38b7f1d → 4.0.0-internal.4c792ad

package/src/index.ts

@@ -1,113 +1,55 @@
 import { definePlugin } from 'payload'
 
-import type { MCPAccessSettings, MCPPluginConfig } from './types.js'
+import type { AuthorizedMCP, MCPPluginConfig, SanitizedMCPPluginConfig } from './types.js'
 
-import { createAPIKeysCollection } from './collections/createApiKeysCollection.js'
-import { initializeMCPHandler } from './endpoints/mcp.js'
+import { mcpEndpoint } from './endpoint/index.js'
+import { sanitizeMCPConfig } from './mcp/sanitizeMCPConfig.js'
 
 declare module 'payload' {
   export interface PayloadRequest {
     payloadAPI: 'GraphQL' | 'local' | 'MCP' | 'REST'
   }
   interface RegisteredPlugins {
+    /** After the plugin's `plugin` callback runs, `options` holds the sanitized config. */
     '@payloadcms/plugin-mcp': MCPPluginConfig
   }
 }
 
-import { defaults } from './defaults.js'
+export type { AuthorizedMCP, MCPPluginConfig, SanitizedMCPPluginConfig }
 
-export type { MCPAccessSettings, MCPPluginConfig }
+export { defineCollectionTool, defineGlobalTool, definePrompt, defineTool } from './defineTool.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.
- */
 export const mcpPlugin = definePlugin<MCPPluginConfig>({
   slug: '@payloadcms/plugin-mcp',
   order: 10,
-  plugin: ({ config, plugins: _plugins, ...pluginOptions }) => {
-    if (!config.collections) {
-      config.collections = []
+  plugin: ({ config, plugins, ...rawConfig }) => {
+    const pluginConfig = sanitizeMCPConfig({ config, pluginConfig: rawConfig })
+
+    // Stash the sanitized config on plugin options so `getPluginConfig()` reads it.
+    const registered = plugins['@payloadcms/plugin-mcp']
+    if (registered) {
+      // @ts-expect-error
+      registered.sanitizedOptions = pluginConfig as unknown as typeof registered.options
     }
 
-    // Collections
-    const collections = pluginOptions.collections || {}
-    // Globals
-    const globals = pluginOptions.globals || {}
-    // Extract custom tools for the global config
-    const customTools =
-      pluginOptions.mcp?.tools?.map((tool) => ({
-        name: tool.name,
-        description: tool.description,
-      })) || []
-
-    // User Collection
-    pluginOptions.userCollection =
-      pluginOptions.userCollection ?? config?.admin?.user ?? defaults.userCollection
-
-    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 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,
-    )
-    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) {
+    if (pluginConfig.disabled) {
       return config
     }
 
-    if (!config.endpoints) {
-      config.endpoints = []
+    return {
+      ...config,
+      endpoints: [
+        ...(config.endpoints ?? []),
+        // Payload prefixes /api, so the full path is /api/mcp.
+        { handler: mcpEndpoint, method: 'post', path: '/mcp' },
+        // Streamable HTTP's optional server=>client GET stream. We don't offer
+        // one, so answer 405 per spec-— clients then skip it cleanly
+        {
+          handler: () => new Response(null, { headers: { Allow: 'POST' }, status: 405 }),
+          method: 'get',
+          path: '/mcp',
+        },
+      ],
     }
-
-    /**
-     * 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/buildMcpServer.ts

@@ -0,0 +1,264 @@
+import { McpServer, type ServerContext } from '@modelcontextprotocol/server'
+import { APIError, type PayloadRequest } from 'payload'
+import { z } from 'zod'
+
+import type {
+  AuthorizedMCP,
+  CollectionMCPItem,
+  GlobalMCPItem,
+  JsonSchemaType,
+  MCPResponseOverride,
+  MCPToolResponse,
+  SanitizedMCPPluginConfig,
+  ToolInputSchema,
+} from '../types.js'
+
+import { getLogger } from '../utils/getLogger.js'
+import { toStandardSchema } from '../utils/toStandardSchema.js'
+
+/**
+ * Transport-agnostic core: registers every authorized MCP item onto a fresh
+ * `McpServer` and returns it. The caller is responsible for picking a transport
+ * (`WebStandardStreamableHTTPServerTransport`, `StdioServerTransport`, …) and
+ * calling `server.connect(transport)`.
+ *
+ * `req` is the request context handlers see. For HTTP it's the live
+ * `PayloadRequest` derived from the incoming HTTP request; for stdio it's a
+ * synthesized one built via `createLocalReq`.
+ */
+export const buildMcpServer = ({
+  authorizedMCP,
+  pluginConfig,
+  req,
+}: {
+  authorizedMCP: AuthorizedMCP
+  pluginConfig: SanitizedMCPPluginConfig
+  req: PayloadRequest
+}): McpServer => {
+  const serverOptions = pluginConfig.mcp?.serverOptions || {}
+  const server = new McpServer(
+    { name: 'Payload MCP Server', version: '1.0.0', ...serverOptions.serverInfo },
+    serverOptions.options,
+  )
+
+  const logger = getLogger({ payload: req.payload })
+
+  /**
+   * Wrap a tool handler's response with the tool's `overrideResponse`, then
+   * strip the internal `doc` field so it doesn't leak onto the wire.
+   */
+  const finalizeToolResponse = (
+    response: MCPToolResponse,
+    overrideResponse?: MCPResponseOverride,
+  ): MCPToolResponse => {
+    const overridden = overrideResponse?.(response, response.doc ?? {}, req) ?? response
+    const { doc: _doc, ...rest } = overridden
+    return rest
+  }
+
+  /**
+   * Runs a collection/global tool call:
+   * - reads `collectionSlug` / `globalSlug` from the input
+   * - runs access control: errors if `authorizedMCP.items` has no entry for this tool + slug
+   * - runs the tool handler and finalizes its response
+   */
+  const callEntityTool = async ({
+    input,
+    item,
+    serverContext,
+  }: {
+    input: unknown
+    item: CollectionMCPItem | GlobalMCPItem
+    serverContext: ServerContext
+  }): Promise<MCPToolResponse> => {
+    const entity = item.type === 'collectionTool' ? 'collection' : 'global'
+    const slugKey = item.type === 'collectionTool' ? 'collectionSlug' : 'globalSlug'
+    const toolInput = (input ?? {}) as Record<string, unknown>
+    const slug = toolInput[slugKey] as string | undefined
+
+    if (!slug) {
+      return {
+        content: [
+          {
+            type: 'text',
+            text: `Error: "${item.mcpName}" requires ${slugKey}. Use getConfigInfo to inspect ${entity} slugs.`,
+          },
+        ],
+        isError: true,
+      }
+    }
+
+    const match = authorizedMCP.items.find(
+      (candidate): candidate is CollectionMCPItem | GlobalMCPItem =>
+        candidate.type === item.type &&
+        candidate.mcpName === item.mcpName &&
+        (candidate.type === 'collectionTool'
+          ? candidate.collectionSlug === slug
+          : candidate.type === 'globalTool' && candidate.globalSlug === slug),
+    )
+
+    if (!match) {
+      return {
+        content: [
+          {
+            type: 'text',
+            text: `Error: MCP access to "${item.mcpName}" is not enabled for ${entity} "${slug}"`,
+          },
+        ],
+        isError: true,
+      }
+    }
+
+    const handlerArgs = {
+      authorizedMCP,
+      input: toolInput,
+      req,
+      serverContext,
+    }
+    const response = await (match.type === 'collectionTool'
+      ? match.tool.handler({ ...handlerArgs, collectionSlug: slug })
+      : match.tool.handler({ ...handlerArgs, globalSlug: slug }))
+
+    return finalizeToolResponse(response, match.tool.overrideResponse)
+  }
+
+  try {
+    const registeredEntityTools = new Set<string>()
+
+    for (const item of authorizedMCP.items) {
+      switch (item.type) {
+        case 'collectionTool':
+        case 'globalTool': {
+          if (registeredEntityTools.has(item.mcpName)) {
+            break
+          }
+          registeredEntityTools.add(item.mcpName)
+
+          const inputSchema = withSlugInput({
+            name: item.type === 'collectionTool' ? 'collectionSlug' : 'globalSlug',
+            input: item.tool.input,
+          })
+
+          server.registerTool(
+            item.mcpName,
+            {
+              annotations: item.tool.annotations,
+              description: item.tool.description,
+              inputSchema: toStandardSchema(inputSchema),
+            },
+            async (input: unknown, ctx: ServerContext) =>
+              callEntityTool({ input, item, serverContext: ctx }),
+          )
+          logger.info(`✅ Tool: ${item.mcpName} Registered.`)
+          break
+        }
+        case 'prompt': {
+          const prompt = item.prompt
+          server.registerPrompt(
+            item.mcpName,
+            {
+              argsSchema: prompt.argsSchema ? toStandardSchema(prompt.argsSchema) : undefined,
+              description: prompt.description,
+              title: prompt.title,
+            },
+            async (input: unknown, ctx: ServerContext) =>
+              prompt.handler({
+                input: (input ?? {}) as Record<string, unknown>,
+                req,
+                serverContext: ctx,
+              }),
+          )
+          logger.info(`✅ Prompt: ${prompt.title} Registered.`)
+          break
+        }
+        case 'resource': {
+          const resource = item.resource
+          server.registerResource(
+            item.mcpName,
+            // @ts-expect-error - Overload type ambiguity (string OR ResourceTemplate is valid)
+            resource.uri,
+            {
+              description: resource.description,
+              mimeType: resource.mimeType,
+              title: resource.title,
+            },
+            // Static URIs call (uri, ctx); ResourceTemplates call (uri, params, ctx).
+            // The rest-params shape lets us collect either signature uniformly.
+            async (...sdkArgs: unknown[]) => {
+              const ctx = sdkArgs[sdkArgs.length - 1] as ServerContext
+              const uri = sdkArgs[0] as URL
+              const params = (sdkArgs.length > 2 ? sdkArgs[1] : {}) as Record<string, string>
+              return resource.handler({ params, req, serverContext: ctx, uri })
+            },
+          )
+          logger.info(`✅ Resource: ${resource.title} Registered.`)
+          break
+        }
+        case 'tool': {
+          const tool = item.tool
+          server.registerTool(
+            item.mcpName,
+            {
+              annotations: tool.annotations,
+              description: tool.description,
+              inputSchema: tool.input ? toStandardSchema(tool.input) : undefined,
+            },
+            async (input: unknown, ctx: ServerContext) =>
+              finalizeToolResponse(
+                await tool.handler({
+                  authorizedMCP,
+                  input: (input ?? {}) as Record<string, unknown>,
+                  req,
+                  serverContext: ctx,
+                }),
+                tool.overrideResponse,
+              ),
+          )
+          logger.info(`✅ Tool: ${item.mcpName} Registered.`)
+          break
+        }
+      }
+    }
+  } catch (error) {
+    throw new APIError(`Error initializing MCP handler: ${String(error)}`, 500)
+  }
+
+  return server
+}
+
+const withSlugInput = ({
+  name,
+  input,
+}: {
+  input?: ToolInputSchema
+  name: 'collectionSlug' | 'globalSlug'
+}): ToolInputSchema => {
+  const description = name === 'collectionSlug' ? 'The collection slug' : 'The global slug'
+  const slugSchema = z.string().describe(description)
+
+  if (!input) {
+    return z.object({ [name]: slugSchema })
+  }
+
+  if (input instanceof z.ZodObject) {
+    return input.extend({ [name]: slugSchema })
+  }
+
+  const schema = input as {
+    properties?: Record<string, JsonSchemaType>
+    required?: string[]
+  } & JsonSchemaType
+
+  return {
+    ...schema,
+    type: 'object',
+    properties: {
+      ...schema.properties,
+      [name]: {
+        type: 'string',
+        description,
+      },
+    },
+    required: Array.from(new Set([name, ...(schema.required ?? [])])),
+  }
+}

package/src/mcp/builtin/collections/authTools.ts

@@ -0,0 +1,269 @@
+import { z } from 'zod'
+
+import type { MCPToolResponse } from '../../../types.js'
+
+import { defineCollectionTool } from '../../../defineTool.js'
+import { getLogger } from '../../../utils/getLogger.js'
+
+/**
+ * Auth tools surfaced under `collections.<auth-collection>.tools`. Opt-in: they
+ * default off (an LLM with `login` access can probe passwords; not something
+ * to expose by default). Enable in plugin config via `tools: { login: true }`
+ * (or `{ description: '...' }`).
+ *
+ * `auth` (check current token) doesn't actually depend on the collection at
+ * runtime — `payload.auth({ headers })` is global — but it's grouped under the
+ * users collection so all auth-shaped tools live in one place.
+ */
+
+const emailSchema = z.string().email().describe('The user email address')
+
+const wrapError =
+  (name: string) =>
+  ({ collectionSlug, message }: { collectionSlug: string; message: string }): MCPToolResponse => {
+    return {
+      content: [
+        {
+          type: 'text',
+          text: `❌ **Error in ${name}** on ${collectionSlug}: ${message}`,
+        },
+      ],
+    }
+  }
+
+export const authCollectionTool = defineCollectionTool({
+  annotations: {
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: false,
+    readOnlyHint: true,
+    title: 'Check Auth Status',
+  },
+  description: 'Checks authentication status for the current user.',
+  input: z.object({
+    headers: z
+      .record(z.string(), z.string())
+      .describe('Optional custom headers to send with the authentication request')
+      .optional(),
+  }),
+}).handler(async ({ collectionSlug, input, req }) => {
+  const logger = getLogger({ payload: req.payload })
+  try {
+    let authHeaders = new Headers()
+    if (input.headers) {
+      authHeaders = new Headers(input.headers)
+    }
+    const result = await req.payload.auth({ headers: authHeaders })
+    return {
+      content: [
+        {
+          type: 'text',
+          text: `# Authentication Status\n\n\`\`\`json\n${JSON.stringify(result)}\n\`\`\``,
+        },
+      ],
+      doc: result as unknown as Record<string, unknown>,
+    }
+  } catch (error) {
+    const errorMessage = error instanceof Error ? error.message : 'Unknown error'
+    logger.error(`Error in auth tool on ${collectionSlug}: ${errorMessage}`)
+    return wrapError('auth')({ collectionSlug, message: errorMessage })
+  }
+})
+
+export const forgotPasswordCollectionTool = defineCollectionTool({
+  annotations: {
+    destructiveHint: false,
+    idempotentHint: false,
+    openWorldHint: true,
+    readOnlyHint: false,
+    title: 'Forgot Password',
+  },
+  description: 'Sends a password reset email to a user.',
+  input: z.object({
+    disableEmail: z
+      .boolean()
+      .describe('Whether to disable sending the email (for testing)')
+      .optional()
+      .default(false),
+    email: emailSchema,
+  }),
+}).handler(async ({ collectionSlug, input, req }) => {
+  const logger = getLogger({ payload: req.payload })
+  try {
+    const result = await req.payload.forgotPassword({
+      collection: collectionSlug,
+      data: { email: input.email },
+      disableEmail: input.disableEmail,
+    })
+    return {
+      content: [
+        {
+          type: 'text',
+          text: `# Forgot Password Email Sent\n\n**Collection:** ${collectionSlug}\n**Email:** ${input.email}\n\n\`\`\`json\n${JSON.stringify(result)}\n\`\`\``,
+        },
+      ],
+      doc: { result } as Record<string, unknown>,
+    }
+  } catch (error) {
+    const errorMessage = error instanceof Error ? error.message : 'Unknown error'
+    logger.error(`Error in forgotPassword tool on ${collectionSlug}: ${errorMessage}`)
+    return wrapError('forgotPassword')({ collectionSlug, message: errorMessage })
+  }
+})
+
+export const loginCollectionTool = defineCollectionTool({
+  annotations: {
+    destructiveHint: false,
+    idempotentHint: false,
+    openWorldHint: false,
+    readOnlyHint: false,
+    title: 'User Login',
+  },
+  description: 'Authenticates a user with email and password.',
+  input: z.object({
+    depth: z
+      .number()
+      .int()
+      .min(0)
+      .max(10)
+      .describe('Depth of population for relationships')
+      .optional()
+      .default(0),
+    email: emailSchema,
+    password: z.string().describe('The user password'),
+    showHiddenFields: z
+      .boolean()
+      .describe('Whether to show hidden fields in the response')
+      .optional()
+      .default(false),
+  }),
+}).handler(async ({ collectionSlug, input, req }) => {
+  const logger = getLogger({ payload: req.payload })
+  try {
+    const result = await req.payload.login({
+      collection: collectionSlug,
+      data: { email: input.email, password: input.password },
+      depth: input.depth,
+      showHiddenFields: input.showHiddenFields,
+    })
+    return {
+      content: [
+        {
+          type: 'text',
+          text: `# Login Successful\n\n**User:** ${input.email}\n**Collection:** ${collectionSlug}\n\n\`\`\`json\n${JSON.stringify(result)}\n\`\`\``,
+        },
+      ],
+      doc: result as unknown as Record<string, unknown>,
+    }
+  } catch (error) {
+    const errorMessage = error instanceof Error ? error.message : 'Unknown error'
+    logger.error(`Error in login tool on ${collectionSlug}: ${errorMessage}`)
+    return wrapError('login')({ collectionSlug, message: errorMessage })
+  }
+})
+
+export const resetPasswordCollectionTool = defineCollectionTool({
+  annotations: {
+    destructiveHint: false,
+    idempotentHint: false,
+    openWorldHint: false,
+    readOnlyHint: false,
+    title: 'Reset Password',
+  },
+  description: 'Resets a user password with a reset token.',
+  input: z.object({
+    password: z.string().describe('The new password for the user'),
+    token: z.string().describe('The password reset token sent to the user email'),
+  }),
+}).handler(async ({ collectionSlug, input, req }) => {
+  const logger = getLogger({ payload: req.payload })
+  try {
+    const result = await req.payload.resetPassword({
+      collection: collectionSlug,
+      data: { password: input.password, token: input.token },
+      overrideAccess: true,
+    })
+    return {
+      content: [
+        {
+          type: 'text',
+          text: `# Password Reset Successful\n\n**Collection:** ${collectionSlug}\n\n\`\`\`json\n${JSON.stringify(result)}\n\`\`\``,
+        },
+      ],
+      doc: result as unknown as Record<string, unknown>,
+    }
+  } catch (error) {
+    const errorMessage = error instanceof Error ? error.message : 'Unknown error'
+    logger.error(`Error in resetPassword tool on ${collectionSlug}: ${errorMessage}`)
+    return wrapError('resetPassword')({ collectionSlug, message: errorMessage })
+  }
+})
+
+export const unlockCollectionTool = defineCollectionTool({
+  annotations: {
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: false,
+    readOnlyHint: false,
+    title: 'Unlock Account',
+  },
+  description: 'Unlocks a user account that has been locked due to failed login attempts.',
+  input: z.object({ email: emailSchema }),
+}).handler(async ({ collectionSlug, input, req }) => {
+  const logger = getLogger({ payload: req.payload })
+  try {
+    const result = await req.payload.unlock({
+      collection: collectionSlug,
+      data: { email: input.email },
+      overrideAccess: true,
+    })
+    return {
+      content: [
+        {
+          type: 'text',
+          text: `# Account Unlocked\n\n**Collection:** ${collectionSlug}\n**Email:** ${input.email}\n**Result:** ${result ? 'Success' : 'Failed'}`,
+        },
+      ],
+      doc: { result } as Record<string, unknown>,
+    }
+  } catch (error) {
+    const errorMessage = error instanceof Error ? error.message : 'Unknown error'
+    logger.error(`Error in unlock tool on ${collectionSlug}: ${errorMessage}`)
+    return wrapError('unlock')({ collectionSlug, message: errorMessage })
+  }
+})
+
+export const verifyCollectionTool = defineCollectionTool({
+  annotations: {
+    destructiveHint: false,
+    idempotentHint: false,
+    openWorldHint: false,
+    readOnlyHint: false,
+    title: 'Email Verification',
+  },
+  description: 'Verifies a user email with a verification token.',
+  input: z.object({
+    token: z.string().describe('The verification token sent to the user email'),
+  }),
+}).handler(async ({ collectionSlug, input, req }) => {
+  const logger = getLogger({ payload: req.payload })
+  try {
+    const result = await req.payload.verifyEmail({
+      collection: collectionSlug,
+      token: input.token,
+    })
+    return {
+      content: [
+        {
+          type: 'text',
+          text: `# Email Verification Successful\n\n**Collection:** ${collectionSlug}\n**Result:** ${result ? 'Success' : 'Failed'}`,
+        },
+      ],
+      doc: { result } as Record<string, unknown>,
+    }
+  } catch (error) {
+    const errorMessage = error instanceof Error ? error.message : 'Unknown error'
+    logger.error(`Error in verify tool on ${collectionSlug}: ${errorMessage}`)
+    return wrapError('verify')({ collectionSlug, message: errorMessage })
+  }
+})