@payloadcms/plugin-mcp 4.0.0-internal.d28e9fb → 4.0.0-internal.d927017

package/src/mcp/builtinTools.ts

@@ -0,0 +1,154 @@
+import type { CollectionTool, GlobalTool, Tool } from '../types.js'
+
+import {
+  authCollectionTool,
+  forgotPasswordCollectionTool,
+  loginCollectionTool,
+  resetPasswordCollectionTool,
+  unlockCollectionTool,
+  verifyCollectionTool,
+} from './builtin/collections/authTools.js'
+import { countDocumentsTool } from './builtin/collections/countTool.js'
+import { countVersionsTool } from './builtin/collections/countVersionsTool.js'
+import { createDocumentTool } from './builtin/collections/createTool.js'
+import { deleteDocumentsTool } from './builtin/collections/deleteTool.js'
+import { duplicateDocumentTool } from './builtin/collections/duplicateTool.js'
+import { findDistinctTool } from './builtin/collections/findDistinctTool.js'
+import { findDocumentsTool } from './builtin/collections/findTool.js'
+import { findVersionByIDTool } from './builtin/collections/findVersionByIDTool.js'
+import { findVersionsTool } from './builtin/collections/findVersionsTool.js'
+import { getCollectionSchemaTool } from './builtin/collections/getCollectionSchemaTool.js'
+import { restoreVersionTool } from './builtin/collections/restoreVersionTool.js'
+import { updateDocumentTool } from './builtin/collections/updateTool.js'
+import { getConfigInfoTool } from './builtin/getConfigInfoTool.js'
+import { countGlobalVersionsTool } from './builtin/globals/countVersionsTool.js'
+import { findGlobalTool } from './builtin/globals/findTool.js'
+import { findGlobalVersionByIDTool } from './builtin/globals/findVersionByIDTool.js'
+import { findGlobalVersionsTool } from './builtin/globals/findVersionsTool.js'
+import { getGlobalSchemaTool } from './builtin/globals/getGlobalSchemaTool.js'
+import { restoreGlobalVersionTool } from './builtin/globals/restoreVersionTool.js'
+import { updateGlobalTool } from './builtin/globals/updateTool.js'
+
+type CollectionBuiltin = {
+  mcpName: string
+  requiresDuplicateEnabled?: boolean
+  requiresVersions?: boolean
+  tool: CollectionTool
+}
+
+type GlobalBuiltin = {
+  mcpName: string
+  requiresVersions?: boolean
+  tool: GlobalTool
+}
+
+export const TOOL_BUILTINS = {
+  getConfigInfo: { mcpName: 'getConfigInfo', tool: getConfigInfoTool },
+} satisfies Record<string, { mcpName: string; tool: Tool }>
+
+/**
+ * The static built-in collection CRUD tools. Keys here are the source of truth
+ * for `MCPCollectionBuiltinName` — adding/removing an entry updates the type
+ * automatically.
+ */
+export const COLLECTION_BUILTINS = {
+  count: { mcpName: 'countDocuments', tool: countDocumentsTool },
+  countVersions: { mcpName: 'countVersions', requiresVersions: true, tool: countVersionsTool },
+  create: { mcpName: 'createDocument', tool: createDocumentTool },
+  delete: { mcpName: 'deleteDocuments', tool: deleteDocumentsTool },
+  duplicate: {
+    mcpName: 'duplicateDocument',
+    requiresDuplicateEnabled: true,
+    tool: duplicateDocumentTool,
+  },
+  find: { mcpName: 'findDocuments', tool: findDocumentsTool },
+  findDistinct: { mcpName: 'findDistinct', tool: findDistinctTool },
+  findVersionByID: {
+    mcpName: 'findVersionByID',
+    requiresVersions: true,
+    tool: findVersionByIDTool,
+  },
+  findVersions: { mcpName: 'findVersions', requiresVersions: true, tool: findVersionsTool },
+  getCollectionSchema: { mcpName: 'getCollectionSchema', tool: getCollectionSchemaTool },
+  restoreVersion: { mcpName: 'restoreVersion', requiresVersions: true, tool: restoreVersionTool },
+  update: { mcpName: 'updateDocument', tool: updateDocumentTool },
+} satisfies Record<string, CollectionBuiltin>
+
+/**
+ * The static auth tools surfaced under auth-enabled collections. Keys are the
+ * source of truth for `MCPCollectionAuthToolName`.
+ */
+export const COLLECTION_AUTH_BUILTINS = {
+  auth: { mcpName: 'auth', tool: authCollectionTool },
+  forgotPassword: {
+    mcpName: 'forgotPassword',
+    tool: forgotPasswordCollectionTool,
+  },
+  login: { mcpName: 'login', tool: loginCollectionTool },
+  resetPassword: {
+    mcpName: 'resetPassword',
+    tool: resetPasswordCollectionTool,
+  },
+  unlock: { mcpName: 'unlock', tool: unlockCollectionTool },
+  verify: { mcpName: 'verify', tool: verifyCollectionTool },
+} satisfies Record<string, { mcpName: string; tool: CollectionTool }>
+
+/**
+ * The static built-in global tools. Keys are the source of truth for
+ * `MCPGlobalBuiltinName`.
+ */
+export const GLOBAL_BUILTINS = {
+  countGlobalVersions: {
+    mcpName: 'countGlobalVersions',
+    requiresVersions: true,
+    tool: countGlobalVersionsTool,
+  },
+  find: { mcpName: 'findGlobal', tool: findGlobalTool },
+  findGlobalVersionByID: {
+    mcpName: 'findGlobalVersionByID',
+    requiresVersions: true,
+    tool: findGlobalVersionByIDTool,
+  },
+  findGlobalVersions: {
+    mcpName: 'findGlobalVersions',
+    requiresVersions: true,
+    tool: findGlobalVersionsTool,
+  },
+  getGlobalSchema: { mcpName: 'getGlobalSchema', tool: getGlobalSchemaTool },
+  restoreGlobalVersion: {
+    mcpName: 'restoreGlobalVersion',
+    requiresVersions: true,
+    tool: restoreGlobalVersionTool,
+  },
+  update: { mcpName: 'updateGlobal', tool: updateGlobalTool },
+} satisfies Record<string, GlobalBuiltin>
+
+export type MCPCollectionBuiltinName = keyof typeof COLLECTION_BUILTINS
+
+export type MCPCollectionAuthToolName = keyof typeof COLLECTION_AUTH_BUILTINS
+
+export type MCPGlobalBuiltinName = keyof typeof GLOBAL_BUILTINS
+
+export type MCPTopLevelBuiltinName = keyof typeof TOOL_BUILTINS
+
+/**
+ * Pre-typed `Object.entries` for each registry. The cast from `string` to the
+ * literal key union lives here once so consumers can iterate without their own
+ * cast — TypeScript's `Object.entries` always widens keys to `string`, which
+ * defeats the narrow type lookups on `MCPCollectionToolsMap`.
+ */
+export const TOOL_BUILTIN_ENTRIES = Object.entries(TOOL_BUILTINS) as Array<
+  [MCPTopLevelBuiltinName, (typeof TOOL_BUILTINS)[MCPTopLevelBuiltinName]]
+>
+
+export const COLLECTION_BUILTIN_ENTRIES = Object.entries(COLLECTION_BUILTINS) as Array<
+  [MCPCollectionBuiltinName, CollectionBuiltin]
+>
+
+export const COLLECTION_AUTH_BUILTIN_ENTRIES = Object.entries(COLLECTION_AUTH_BUILTINS) as Array<
+  [MCPCollectionAuthToolName, (typeof COLLECTION_AUTH_BUILTINS)[MCPCollectionAuthToolName]]
+>
+
+export const GLOBAL_BUILTIN_ENTRIES = Object.entries(GLOBAL_BUILTINS) as Array<
+  [MCPGlobalBuiltinName, GlobalBuiltin]
+>

package/src/mcp/sanitizeMCPConfig.ts

@@ -0,0 +1,278 @@
+import type {
+  CollectionConfig,
+  Config,
+  GlobalConfig,
+  SanitizedCollectionConfig,
+  SanitizedConfig,
+  SanitizedGlobalConfig,
+} from 'payload'
+
+import type {
+  CollectionMCPItem,
+  CollectionTool,
+  GlobalMCPItem,
+  GlobalTool,
+  MCPItem,
+  MCPPluginConfig,
+  SanitizedMCPPluginConfig,
+} from '../types.js'
+
+import { defaultAccess } from '../defaultAccess.js'
+import {
+  COLLECTION_AUTH_BUILTIN_ENTRIES,
+  COLLECTION_AUTH_BUILTINS,
+  COLLECTION_BUILTIN_ENTRIES,
+  COLLECTION_BUILTINS,
+  GLOBAL_BUILTIN_ENTRIES,
+  GLOBAL_BUILTINS,
+  TOOL_BUILTIN_ENTRIES,
+  TOOL_BUILTINS,
+} from './builtinTools.js'
+
+/**
+ * Converts the user-configured `MCPPluginConfig` into a `SanitizedMCPPluginConfig`:
+ *  - Flattens `tools` / `prompts` / `resources` / per-collection / per-global
+ *    tool maps into a single `items` array.
+ *  - Applies built-in tools for collections and globals, respecting opt-out user overrides.
+ *
+ * Called once during plugin init. After that, `plugins['@payloadcms/plugin-mcp']
+ * ?.options` holds the sanitized result
+ */
+export const sanitizeMCPConfig = ({
+  config,
+  pluginConfig,
+}: {
+  config: Config | SanitizedConfig
+  pluginConfig: MCPPluginConfig
+}): SanitizedMCPPluginConfig => {
+  const items: MCPItem[] = []
+
+  for (const collection of config.collections ?? []) {
+    items.push(...sanitizeCollectionConfig({ collection, pluginConfig }))
+  }
+
+  for (const global of config.globals ?? []) {
+    items.push(...sanitizeGlobalConfig({ global, pluginConfig }))
+  }
+
+  for (const [configKey, { mcpName, tool }] of TOOL_BUILTIN_ENTRIES) {
+    items.push({
+      type: 'tool',
+      configKey,
+      label: tool.annotations?.title ?? configKey,
+      mcpName,
+      tool: { ...tool, access: tool.access ?? defaultAccess },
+    })
+  }
+
+  for (const [configKey, tool] of Object.entries(pluginConfig.tools ?? {})) {
+    if (configKey in TOOL_BUILTINS) {
+      continue
+    }
+    items.push({
+      type: 'tool',
+      configKey,
+      label: tool.annotations?.title ?? configKey,
+      mcpName: configKey,
+      tool: { ...tool, access: tool.access ?? defaultAccess },
+    })
+  }
+
+  for (const [configKey, prompt] of Object.entries(pluginConfig.prompts ?? {})) {
+    items.push({
+      type: 'prompt',
+      configKey,
+      label: prompt.title ?? configKey,
+      mcpName: configKey,
+      prompt: { ...prompt, access: prompt.access ?? defaultAccess },
+    })
+  }
+
+  for (const [configKey, resource] of Object.entries(pluginConfig.resources ?? {})) {
+    items.push({
+      type: 'resource',
+      configKey,
+      label: resource.title ?? configKey,
+      mcpName: configKey,
+      resource: { ...resource, access: resource.access ?? defaultAccess },
+    })
+  }
+
+  return {
+    disabled: pluginConfig.disabled,
+    hooks: pluginConfig.hooks,
+    items,
+    mcp: pluginConfig.mcp,
+    overrideGetAuthorizedMCP: pluginConfig.overrideGetAuthorizedMCP,
+  }
+}
+
+const sanitizeCollectionConfig = ({
+  collection,
+  pluginConfig,
+}: {
+  collection: CollectionConfig | SanitizedCollectionConfig
+  pluginConfig: MCPPluginConfig
+}): CollectionMCPItem[] => {
+  const slug = collection.slug
+  const collectionPluginConfig = pluginConfig.collections?.[slug]
+  const items: CollectionMCPItem[] = []
+  /**
+   * Payload disables duplicate for auth collections by default unless the
+   * collection explicitly opts back in with `disableDuplicate: false`.
+   */
+  const isDuplicateDisabled =
+    collection.disableDuplicate === true ||
+    (Boolean(collection.auth) && collection.disableDuplicate !== false)
+
+  for (const [
+    toolKey,
+    { mcpName, requiresDuplicateEnabled, requiresVersions, tool },
+  ] of COLLECTION_BUILTIN_ENTRIES) {
+    if (requiresVersions && !collection.versions) {
+      continue
+    }
+    if (requiresDuplicateEnabled && isDuplicateDisabled) {
+      continue
+    }
+    const matchedConfigEntry = collectionPluginConfig?.tools?.[toolKey]
+    if (matchedConfigEntry === false) {
+      continue
+    }
+    const override = typeof matchedConfigEntry === 'object' ? matchedConfigEntry : undefined
+    const annotations = { ...tool.annotations, ...override?.annotations }
+    items.push({
+      type: 'collectionTool',
+      collectionSlug: slug,
+      configKey: toolKey,
+      label: annotations.title ?? toolKey,
+      mcpName,
+      tool: {
+        ...tool,
+        access: override?.access ?? tool.access ?? defaultAccess,
+        annotations,
+        description: override?.description ?? tool.description,
+        overrideResponse:
+          override?.overrideResponse ??
+          collectionPluginConfig?.overrideResponse ??
+          tool.overrideResponse,
+      },
+    })
+  }
+
+  if (collection.auth) {
+    for (const [authToolKey, { mcpName, tool }] of COLLECTION_AUTH_BUILTIN_ENTRIES) {
+      const matchedConfigEntry = collectionPluginConfig?.tools?.[authToolKey]
+      if (!matchedConfigEntry) {
+        continue
+      }
+      // `true` means "enable, no override"; only the object form carries fields.
+      const override = typeof matchedConfigEntry === 'object' ? matchedConfigEntry : undefined
+      const annotations = { ...tool.annotations, ...override?.annotations }
+      items.push({
+        type: 'collectionTool',
+        collectionSlug: slug,
+        configKey: authToolKey,
+        label: annotations.title ?? authToolKey,
+        mcpName,
+        tool: {
+          ...tool,
+          access: override?.access ?? tool.access ?? defaultAccess,
+          annotations,
+          description: override?.description ?? tool.description,
+          overrideResponse:
+            override?.overrideResponse ??
+            collectionPluginConfig?.overrideResponse ??
+            tool.overrideResponse,
+        },
+      })
+    }
+  }
+
+  // Cast: builtin keys are filtered out below, so the remaining values are
+  // always custom tools (`CollectionTool`) or undefined
+  const customEntries = Object.entries(collectionPluginConfig?.tools ?? {}) as Array<
+    [string, CollectionTool | undefined]
+  >
+  for (const [configKey, customTool] of customEntries) {
+    if (configKey in COLLECTION_BUILTINS || configKey in COLLECTION_AUTH_BUILTINS) {
+      continue
+    }
+    if (!customTool) {
+      continue
+    }
+    items.push({
+      type: 'collectionTool',
+      collectionSlug: slug,
+      configKey,
+      label: customTool.annotations?.title ?? configKey,
+      mcpName: configKey,
+      tool: { ...customTool, access: customTool.access ?? defaultAccess },
+    })
+  }
+
+  return items
+}
+
+const sanitizeGlobalConfig = ({
+  global,
+  pluginConfig,
+}: {
+  global: GlobalConfig | SanitizedGlobalConfig
+  pluginConfig: MCPPluginConfig
+}): GlobalMCPItem[] => {
+  const slug = global.slug
+  const globalPluginConfig = pluginConfig.globals?.[slug]
+  const items: GlobalMCPItem[] = []
+
+  for (const [toolKey, { mcpName, requiresVersions, tool }] of GLOBAL_BUILTIN_ENTRIES) {
+    if (requiresVersions && !global.versions) {
+      continue
+    }
+    const matchedConfigEntry = globalPluginConfig?.tools?.[toolKey]
+    if (matchedConfigEntry === false) {
+      continue
+    }
+    const override = typeof matchedConfigEntry === 'object' ? matchedConfigEntry : undefined
+    const annotations = { ...tool.annotations, ...override?.annotations }
+    items.push({
+      type: 'globalTool',
+      configKey: toolKey,
+      globalSlug: slug,
+      label: annotations.title ?? toolKey,
+      mcpName,
+      tool: {
+        ...tool,
+        access: override?.access ?? tool.access ?? defaultAccess,
+        annotations,
+        description: override?.description ?? tool.description,
+        overrideResponse:
+          override?.overrideResponse ??
+          globalPluginConfig?.overrideResponse ??
+          tool.overrideResponse,
+      },
+    })
+  }
+
+  const customEntries = Object.entries(globalPluginConfig?.tools ?? {}) as Array<
+    [string, GlobalTool | undefined]
+  >
+  for (const [configKey, customTool] of customEntries) {
+    if (configKey in GLOBAL_BUILTINS) {
+      continue
+    }
+    if (!customTool) {
+      continue
+    }
+    items.push({
+      type: 'globalTool',
+      configKey,
+      globalSlug: slug,
+      label: customTool.annotations?.title ?? configKey,
+      mcpName: configKey,
+      tool: { ...customTool, access: customTool.access ?? defaultAccess },
+    })
+  }
+
+  return items
+}

package/src/stdio.ts

@@ -0,0 +1,131 @@
+import type { Config, Plugin, SanitizedConfig } from 'payload'
+
+/* eslint-disable no-console */
+import { serveStdio } from '@modelcontextprotocol/server/stdio'
+import { fileURLToPath, pathToFileURL } from 'node:url'
+import { createLocalReq, getPayload } from 'payload'
+import { findConfig } from 'payload/node'
+
+import type { SanitizedMCPPluginConfig } from './types.js'
+
+import { getAuthorizedMCP } from './endpoint/access.js'
+import { buildMcpServer } from './mcp/buildMcpServer.js'
+import { sanitizeMCPConfig } from './mcp/sanitizeMCPConfig.js'
+import { getPluginConfig } from './utils/getPluginConfig.js'
+import { resolveProjectRoot } from './utils/resolveProjectRoot.js'
+
+/**
+ * Starts Payload's MCP server over stdin and stdout.
+ *
+ * Set `PAYLOAD_MCP_AUTHORIZATION` to authenticate. In development,
+ * `PAYLOAD_MCP_OVERRIDE_ACCESS=true` skips access checks.
+ */
+export const runMcpStdio = async (configOverride?: SanitizedConfig): Promise<void> => {
+  // MCP clients may start this command from another folder. Move to the Payload
+  // project so findConfig() can find the config.
+  const projectRoot = resolveProjectRoot(fileURLToPath(import.meta.url))
+  if (projectRoot) {
+    process.chdir(projectRoot)
+  }
+
+  const configPath = findConfig()
+  const configURL = pathToFileURL(configPath).href
+  const configModule = configOverride ? undefined : await import(configURL)
+  const config: SanitizedConfig = configOverride ?? (await (configModule?.default ?? configModule))
+
+  /**
+   * stdout is only for MCP messages. The spec says the server must not write
+   * logs there and may write them to stderr instead.
+   *
+   * The 2.0 client library recovers from stray stdout logs, but that behavior is not
+   * guaranteed. Move Payload logs to stderr so Payload does not add invalid data
+   * to stdout. Keep options from configurable loggers. Replace pre-built loggers
+   * because their output cannot be redirected.
+   *
+   * @see https://modelcontextprotocol.io/specification/2025-11-25/basic/transports#stdio
+   */
+  const loggerConfig: { logger?: Config['logger'] } = config
+  if (
+    loggerConfig.logger &&
+    typeof loggerConfig.logger === 'object' &&
+    'options' in loggerConfig.logger
+  ) {
+    loggerConfig.logger.destination = process.stderr
+  } else {
+    loggerConfig.logger = { destination: process.stderr, options: {} }
+  }
+
+  const payload = await getPayload({ config, cron: false, disableOnInit: true })
+
+  let pluginConfig: SanitizedMCPPluginConfig
+  try {
+    pluginConfig = getPluginConfig({ config: payload.config })
+  } catch {
+    // The command also works when mcpPlugin() is not in the Payload config.
+    pluginConfig = sanitizeMCPConfig({ config: payload.config, pluginConfig: {} })
+
+    const fallbackPlugin: Plugin = (config) => config
+    Object.assign(fallbackPlugin, {
+      slug: '@payloadcms/plugin-mcp',
+      sanitizedOptions: pluginConfig,
+    })
+    payload.config.plugins ??= []
+    payload.config.plugins.push(fallbackPlugin)
+  }
+
+  const overrideAccessEnv = process.env.PAYLOAD_MCP_OVERRIDE_ACCESS
+  let overrideAccess = false
+
+  if (overrideAccessEnv === 'true') {
+    overrideAccess = true
+  } else if (overrideAccessEnv && overrideAccessEnv !== 'false') {
+    throw new Error('PAYLOAD_MCP_OVERRIDE_ACCESS must be "true" or "false".')
+  }
+
+  if (overrideAccess && process.env.NODE_ENV !== 'development') {
+    throw new Error('PAYLOAD_MCP_OVERRIDE_ACCESS is only available in development.')
+  }
+
+  const headers = new Headers()
+  if (process.env.PAYLOAD_MCP_AUTHORIZATION) {
+    headers.set('Authorization', process.env.PAYLOAD_MCP_AUTHORIZATION)
+  }
+
+  const req = await createLocalReq({ req: { headers } }, payload)
+  req.payloadAPI = 'MCP' as const
+  const authorizedMCP = await getAuthorizedMCP({ overrideAccess, req })
+
+  const stdioServer = serveStdio(() => buildMcpServer({ authorizedMCP, pluginConfig, req }), {
+    onerror: (err) => {
+      // MCP messages use stdout, so write SDK errors to stderr.
+      console.error('[payload-mcp] error serving MCP over stdio:', err)
+    },
+  })
+
+  // Close the MCP server and Payload when the client disconnects or the process stops.
+  let isShuttingDown = false
+  const shutdown = async () => {
+    if (isShuttingDown) {
+      return
+    }
+    isShuttingDown = true
+
+    try {
+      await stdioServer.close()
+    } catch (err) {
+      console.error('[payload-mcp] error closing server:', err)
+    }
+
+    try {
+      await payload.destroy()
+    } catch (err) {
+      console.error('[payload-mcp] error destroying payload:', err)
+    }
+
+    process.exit(0)
+  }
+
+  process.once('SIGINT', () => void shutdown())
+  process.once('SIGTERM', () => void shutdown())
+  process.stdin.once('close', () => void shutdown())
+}