@payloadcms/plugin-mcp 4.0.0-internal.688c4d0 → 4.0.0-internal.697830c

package/src/mcp/builtin/validateEntityData.ts

@@ -1,6 +1,6 @@
 import type { CollectionSlug, GlobalSlug, PayloadRequest, SanitizedConfig } from 'payload'
 
-import { CfWorkerJsonSchemaValidator } from '@modelcontextprotocol/server'
+import { CfWorkerJsonSchemaValidator } from '@modelcontextprotocol/server/validators/cf-worker'
 
 import type { JsonSchemaType, MCPToolResponse } from '../../types.js'
 

package/src/mcp/builtinTools.ts

@@ -8,19 +8,43 @@ import {
   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: { label: 'Config Info', mcpName: 'getConfigInfo', tool: getConfigInfoTool },
-} satisfies Record<string, { label: string; mcpName: string; tool: Tool }>
+  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
@@ -28,44 +52,76 @@ export const TOOL_BUILTINS = {
  * 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, { mcpName: string; tool: CollectionTool }>
+} satisfies Record<string, CollectionBuiltin>
 
 /**
- * The static auth tools surfaced under auth-enabled collections. Each entry
- * carries the admin-UI label alongside the tool. Keys are the source of truth
- * for `MCPCollectionAuthToolName`.
+ * The static auth tools surfaced under auth-enabled collections. Keys are the
+ * source of truth for `MCPCollectionAuthToolName`.
  */
 export const COLLECTION_AUTH_BUILTINS = {
-  auth: { label: 'Check Auth Status', mcpName: 'auth', tool: authCollectionTool },
+  auth: { mcpName: 'auth', tool: authCollectionTool },
   forgotPassword: {
-    label: 'Forgot Password',
     mcpName: 'forgotPassword',
     tool: forgotPasswordCollectionTool,
   },
-  login: { label: 'User Login', mcpName: 'login', tool: loginCollectionTool },
+  login: { mcpName: 'login', tool: loginCollectionTool },
   resetPassword: {
-    label: 'Reset Password',
     mcpName: 'resetPassword',
     tool: resetPasswordCollectionTool,
   },
-  unlock: { label: 'Unlock Account', mcpName: 'unlock', tool: unlockCollectionTool },
-  verify: { label: 'Email Verification', mcpName: 'verify', tool: verifyCollectionTool },
-} satisfies Record<string, { label: string; mcpName: string; tool: CollectionTool }>
+  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, { mcpName: string; tool: GlobalTool }>
+} satisfies Record<string, GlobalBuiltin>
 
 export type MCPCollectionBuiltinName = keyof typeof COLLECTION_BUILTINS
 
@@ -86,7 +142,7 @@ export const TOOL_BUILTIN_ENTRIES = Object.entries(TOOL_BUILTINS) as Array<
 >
 
 export const COLLECTION_BUILTIN_ENTRIES = Object.entries(COLLECTION_BUILTINS) as Array<
-  [MCPCollectionBuiltinName, (typeof COLLECTION_BUILTINS)[MCPCollectionBuiltinName]]
+  [MCPCollectionBuiltinName, CollectionBuiltin]
 >
 
 export const COLLECTION_AUTH_BUILTIN_ENTRIES = Object.entries(COLLECTION_AUTH_BUILTINS) as Array<
@@ -94,5 +150,5 @@ export const COLLECTION_AUTH_BUILTIN_ENTRIES = Object.entries(COLLECTION_AUTH_BU
 >
 
 export const GLOBAL_BUILTIN_ENTRIES = Object.entries(GLOBAL_BUILTINS) as Array<
-  [MCPGlobalBuiltinName, (typeof GLOBAL_BUILTINS)[MCPGlobalBuiltinName]]
+  [MCPGlobalBuiltinName, GlobalBuiltin]
 >

package/src/mcp/sanitizeMCPConfig.ts

@@ -17,6 +17,7 @@ import type {
   SanitizedMCPPluginConfig,
 } from '../types.js'
 
+import { defaultAccess } from '../defaultAccess.js'
 import {
   COLLECTION_AUTH_BUILTIN_ENTRIES,
   COLLECTION_AUTH_BUILTINS,
@@ -33,7 +34,6 @@ import {
  *  - 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.
- *  - Applies the `userCollection` default
  *
  * Called once during plugin init. After that, `plugins['@payloadcms/plugin-mcp']
  * ?.options` holds the sanitized result
@@ -55,13 +55,13 @@ export const sanitizeMCPConfig = ({
     items.push(...sanitizeGlobalConfig({ global, pluginConfig }))
   }
 
-  for (const [configKey, { label, mcpName, tool }] of TOOL_BUILTIN_ENTRIES) {
+  for (const [configKey, { mcpName, tool }] of TOOL_BUILTIN_ENTRIES) {
     items.push({
       type: 'tool',
       configKey,
-      label,
+      label: tool.annotations?.title ?? configKey,
       mcpName,
-      tool,
+      tool: { ...tool, access: tool.access ?? defaultAccess },
     })
   }
 
@@ -72,9 +72,9 @@ export const sanitizeMCPConfig = ({
     items.push({
       type: 'tool',
       configKey,
-      label: configKey,
+      label: tool.annotations?.title ?? configKey,
       mcpName: configKey,
-      tool,
+      tool: { ...tool, access: tool.access ?? defaultAccess },
     })
   }
 
@@ -84,7 +84,7 @@ export const sanitizeMCPConfig = ({
       configKey,
       label: prompt.title ?? configKey,
       mcpName: configKey,
-      prompt,
+      prompt: { ...prompt, access: prompt.access ?? defaultAccess },
     })
   }
 
@@ -94,21 +94,16 @@ export const sanitizeMCPConfig = ({
       configKey,
       label: resource.title ?? configKey,
       mcpName: configKey,
-      resource,
+      resource: { ...resource, access: resource.access ?? defaultAccess },
     })
   }
 
-  // Mirror Payload's own admin.user detection (sanitize.ts) since plugins run first.
-  const firstCollectionWithAuth = config.collections!.find(({ auth }) => Boolean(auth))
-
   return {
     disabled: pluginConfig.disabled,
+    hooks: pluginConfig.hooks,
     items,
     mcp: pluginConfig.mcp,
-    overrideApiKeyCollection: pluginConfig.overrideApiKeyCollection,
-    overrideAuth: pluginConfig.overrideAuth,
-    userCollection:
-      pluginConfig.userCollection ?? config.admin?.user ?? firstCollectionWithAuth?.slug ?? 'users',
+    overrideGetAuthorizedMCP: pluginConfig.overrideGetAuthorizedMCP,
   }
 }
 
@@ -119,27 +114,43 @@ const sanitizeCollectionConfig = ({
   collection: CollectionConfig | SanitizedCollectionConfig
   pluginConfig: MCPPluginConfig
 }): CollectionMCPItem[] => {
-  if (collection.slug === 'payload-mcp-api-keys') {
-    return []
-  }
   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, tool }] of COLLECTION_BUILTIN_ENTRIES) {
+  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: capitalize(toolKey),
+      label: annotations.title ?? toolKey,
       mcpName,
       tool: {
         ...tool,
+        access: override?.access ?? tool.access ?? defaultAccess,
+        annotations,
         description: override?.description ?? tool.description,
         overrideResponse:
           override?.overrideResponse ??
@@ -150,21 +161,24 @@ const sanitizeCollectionConfig = ({
   }
 
   if (collection.auth) {
-    for (const [authToolKey, { label, mcpName, tool }] of COLLECTION_AUTH_BUILTIN_ENTRIES) {
+    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,
+        label: annotations.title ?? authToolKey,
         mcpName,
         tool: {
           ...tool,
+          access: override?.access ?? tool.access ?? defaultAccess,
+          annotations,
           description: override?.description ?? tool.description,
           overrideResponse:
             override?.overrideResponse ??
@@ -191,9 +205,9 @@ const sanitizeCollectionConfig = ({
       type: 'collectionTool',
       collectionSlug: slug,
       configKey,
-      label: configKey,
+      label: customTool.annotations?.title ?? configKey,
       mcpName: configKey,
-      tool: customTool,
+      tool: { ...customTool, access: customTool.access ?? defaultAccess },
     })
   }
 
@@ -211,20 +225,26 @@ const sanitizeGlobalConfig = ({
   const globalPluginConfig = pluginConfig.globals?.[slug]
   const items: GlobalMCPItem[] = []
 
-  for (const [toolKey, { mcpName, tool }] of GLOBAL_BUILTIN_ENTRIES) {
+  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: capitalize(toolKey),
+      label: annotations.title ?? toolKey,
       mcpName,
       tool: {
         ...tool,
+        access: override?.access ?? tool.access ?? defaultAccess,
+        annotations,
         description: override?.description ?? tool.description,
         overrideResponse:
           override?.overrideResponse ??
@@ -248,13 +268,11 @@ const sanitizeGlobalConfig = ({
       type: 'globalTool',
       configKey,
       globalSlug: slug,
-      label: configKey,
+      label: customTool.annotations?.title ?? configKey,
       mcpName: configKey,
-      tool: customTool,
+      tool: { ...customTool, access: customTool.access ?? defaultAccess },
     })
   }
 
   return items
 }
-
-const capitalize = (s: string): string => s.charAt(0).toUpperCase() + s.slice(1)

package/src/stdio.ts

@@ -1,35 +1,28 @@
-import type { MaybePromise, Plugin, SanitizedConfig } from 'payload'
+import type { Config, Plugin, SanitizedConfig } from 'payload'
 
 /* eslint-disable no-console */
-import { StdioServerTransport } from '@modelcontextprotocol/server'
+import { serveStdio } from '@modelcontextprotocol/server/stdio'
 import { fileURLToPath, pathToFileURL } from 'node:url'
 import { createLocalReq, getPayload } from 'payload'
 import { findConfig } from 'payload/node'
 
-import type { AuthorizedMCP, SanitizedMCPPluginConfig } from './types.js'
+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'
 
 /**
- * Stdio adapter for the Payload MCP server.
+ * Starts Payload's MCP server over stdin and stdout.
  *
- * Do not use in production. There's no auth; whoever can spawn the process gets
- * full access to your local data.
+ * Set `PAYLOAD_MCP_AUTHORIZATION` to authenticate. In development,
+ * `PAYLOAD_MCP_OVERRIDE_ACCESS=true` skips access checks.
  */
 export const runMcpStdio = async (): Promise<void> => {
-  /**
-   * If MCP clients spawn stdio servers from an arbitrary working directory,
-   * Payload's cwd-anchored `findConfig()` can't locate the project on
-   * its own. This module always lives inside the project's `node_modules`, so
-   * we derive the project root from its own path and `chdir` into it.
-   *
-   * An absolute `PAYLOAD_CONFIG_PATH` still overrides everything; unusual
-   * layouts (e.g. a monorepo where the package is hoisted above the app) can
-   * fall back to it. See the implementation of findConfig for details.
-   */
+  // 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)
@@ -37,62 +30,101 @@ export const runMcpStdio = async (): Promise<void> => {
 
   const configPath = findConfig()
   const configModule = await import(pathToFileURL(configPath).toString())
-  const config = (await (configModule.default ?? configModule)) as MaybePromise<SanitizedConfig>
-
-  const payload = await getPayload({ config })
+  const config = (await (configModule.default ?? configModule)) as SanitizedConfig
 
   /**
-   * If the user added `mcpPlugin({...})` to their `plugins` array, read the
-   * sanitized config they registered. Otherwise fall back to the defaults. That way,
-   * the mcp works on any project that has `@payloadcms/plugin-mcp` installed,
-   * even if the plugin is not added to the plugins array.
+   * 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 fakePluginFn: Plugin = (config) => config
-    fakePluginFn.slug = '@payloadcms/plugin-mcp'
-    // @ts-expect-error
-    fakePluginFn.sanitizedOptions = 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".')
+  }
 
-    // Push to payload config, to ensure consecutive calls to `getPluginConfig()` work
-    ;(payload.config.plugins ??= []).push(fakePluginFn)
+  if (overrideAccess && process.env.NODE_ENV !== 'development') {
+    throw new Error('PAYLOAD_MCP_OVERRIDE_ACCESS is only available in development.')
   }
 
-  const authorizedMCP: AuthorizedMCP = {
-    items: pluginConfig.items,
-    overrideAccess: true,
-    user: null,
+  const headers = new Headers()
+  if (process.env.PAYLOAD_MCP_AUTHORIZATION) {
+    headers.set('Authorization', process.env.PAYLOAD_MCP_AUTHORIZATION)
   }
 
-  const req = await createLocalReq({}, payload)
+  const req = await createLocalReq({ req: { headers } }, payload)
   req.payloadAPI = 'MCP' as const
+  const authorizedMCP = await getAuthorizedMCP({ overrideAccess, req })
 
-  const server = buildMcpServer({ authorizedMCP, pluginConfig, 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)
+    },
+  })
 
-  const transport = new StdioServerTransport()
-  await server.connect(transport)
+  // 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
 
-  // Process now lives until stdin closes. Wire graceful shutdown so DB
-  // connections (and any other Payload-managed resources) get released.
-  const shutdown = async (code = 0) => {
     try {
-      await server.close()
+      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(code)
+
+    process.exit(0)
   }
 
-  process.on('SIGINT', () => void shutdown(0))
-  process.on('SIGTERM', () => void shutdown(0))
-  process.stdin.on('close', () => void shutdown(0))
+  process.once('SIGINT', () => void shutdown())
+  process.once('SIGTERM', () => void shutdown())
+  process.stdin.once('close', () => void shutdown())
 }