@payloadcms/plugin-mcp 4.0.0-internal.e16cf59 → 4.0.0-internal.fa345ef

package/src/mcp/buildMcpServer.ts

@@ -0,0 +1,284 @@
+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'
+
+/**
+ * Serving-entry-agnostic core: registers every authorized MCP item onto a fresh
+ * `McpServer` and returns it. The HTTP and stdio entry point callers provide fresh
+ * instances from this builder while they own the transport and protocol-era
+ * decision.
+ *
+ * `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 = async ({
+    input,
+    overrideResponse,
+    response,
+    toolName,
+  }: {
+    input: unknown
+    overrideResponse?: MCPResponseOverride
+    response: MCPToolResponse
+    toolName: string
+  }): Promise<MCPToolResponse> => {
+    let overridden = overrideResponse?.(response, response.doc ?? {}, req) ?? response
+    for (const hook of pluginConfig.hooks?.afterToolCall ?? []) {
+      overridden = await hook({ input, req, response: overridden, toolName })
+    }
+    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({
+      input: toolInput,
+      overrideResponse: match.tool.overrideResponse,
+      response,
+      toolName: match.mcpName,
+    })
+  }
+
+  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) => {
+              const toolInput = (input ?? {}) as Record<string, unknown>
+              const response = await tool.handler({
+                authorizedMCP,
+                input: toolInput,
+                req,
+                serverContext: ctx,
+              })
+              return finalizeToolResponse({
+                input: toolInput,
+                overrideResponse: tool.overrideResponse,
+                response,
+                toolName: item.mcpName,
+              })
+            },
+          )
+          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 })
+  }
+})

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

@@ -0,0 +1,74 @@
+import { z } from 'zod'
+
+import { defaultAccess } from '../../../defaultAccess.js'
+import { defineCollectionTool } from '../../../defineTool.js'
+import { getLogger } from '../../../utils/getLogger.js'
+import { localAPIDefaults } from '../../../utils/localAPIDefaults.js'
+import { whereSchema } from '../../../utils/whereSchema.js'
+
+const DEFAULT_DESCRIPTION =
+  'Count documents in any collection by passing the collection slug and optional where clause.'
+
+export const countDocumentsTool = defineCollectionTool({
+  access: (args) =>
+    defaultAccess(args) && Boolean(args.permissions?.collections?.[args.collectionSlug]?.read),
+  annotations: {
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: false,
+    readOnlyHint: true,
+    title: 'Count Documents',
+  },
+  description: DEFAULT_DESCRIPTION,
+  input: z.object({
+    locale: z.string().describe('Optional: locale code to count documents in').optional(),
+    trash: z
+      .boolean()
+      .describe('Optional: include soft-deleted documents when trash is enabled on the collection')
+      .optional(),
+    where: whereSchema
+      .describe(
+        'Optional: where clause for filtering. Use field names with Payload operators, and/or arrays for grouping. Example: {"title":{"contains":"test"}}',
+      )
+      .optional(),
+  }),
+}).handler(async ({ authorizedMCP, collectionSlug, input, req }) => {
+  const payload = req.payload
+  const logger = getLogger({ payload })
+  const { locale, trash, where } = input
+
+  logger.info(`Counting documents in collection: ${collectionSlug}`)
+
+  try {
+    const result = await payload.count({
+      collection: collectionSlug,
+      req,
+      ...localAPIDefaults(authorizedMCP),
+      ...(locale ? { locale } : {}),
+      ...(trash !== undefined ? { trash } : {}),
+      ...(where ? { where } : {}),
+    })
+
+    return {
+      content: [
+        {
+          type: 'text',
+          text: `Collection "${collectionSlug}" contains ${result.totalDocs} matching documents.\n\`\`\`json\n${JSON.stringify(result)}\n\`\`\``,
+        },
+      ],
+      doc: result,
+    }
+  } catch (error) {
+    const errorMessage = error instanceof Error ? error.message : 'Unknown error'
+    logger.error(`Error counting documents in ${collectionSlug}: ${errorMessage}`)
+    return {
+      content: [
+        {
+          type: 'text',
+          text: `❌ **Error counting documents in collection "${collectionSlug}":** ${errorMessage}`,
+        },
+      ],
+      isError: true,
+    }
+  }
+})

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

@@ -0,0 +1,73 @@
+import { z } from 'zod'
+
+import { defaultAccess } from '../../../defaultAccess.js'
+import { defineCollectionTool } from '../../../defineTool.js'
+import { getLogger } from '../../../utils/getLogger.js'
+import { localAPIDefaults } from '../../../utils/localAPIDefaults.js'
+import { whereSchema } from '../../../utils/whereSchema.js'
+
+const DEFAULT_DESCRIPTION =
+  'Count document versions in any version-enabled collection by passing the collection slug and optional where clause.'
+
+export const countVersionsTool = defineCollectionTool({
+  access: (args) =>
+    defaultAccess(args) &&
+    Boolean(args.permissions?.collections?.[args.collectionSlug]?.readVersions),
+  annotations: {
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: false,
+    readOnlyHint: true,
+    title: 'Count Versions',
+  },
+  description: DEFAULT_DESCRIPTION,
+  input: z.object({
+    locale: z
+      .string()
+      .describe('Optional: locale code to count versions in')
+      .optional(),
+    where: whereSchema
+      .describe(
+        'Optional: where clause for filtering versions. Version document fields are usually under "version". Example: {"version.title":{"contains":"test"}}',
+      )
+      .optional(),
+  }),
+}).handler(async ({ authorizedMCP, collectionSlug, input, req }) => {
+  const payload = req.payload
+  const logger = getLogger({ payload })
+  const { locale, where } = input
+
+  logger.info(`Counting versions in collection: ${collectionSlug}`)
+
+  try {
+    const result = await payload.countVersions({
+      collection: collectionSlug,
+      req,
+      ...localAPIDefaults(authorizedMCP),
+      ...(locale ? { locale } : {}),
+      ...(where ? { where } : {}),
+    })
+
+    return {
+      content: [
+        {
+          type: 'text',
+          text: `Collection "${collectionSlug}" contains ${result.totalDocs} matching versions.\n\`\`\`json\n${JSON.stringify(result)}\n\`\`\``,
+        },
+      ],
+      doc: result,
+    }
+  } catch (error) {
+    const errorMessage = error instanceof Error ? error.message : 'Unknown error'
+    logger.error(`Error counting versions in ${collectionSlug}: ${errorMessage}`)
+    return {
+      content: [
+        {
+          type: 'text',
+          text: `❌ **Error counting versions in collection "${collectionSlug}":** ${errorMessage}`,
+        },
+      ],
+      isError: true,
+    }
+  }
+})