@payloadcms/plugin-mcp 4.0.0-internal.a0ef1b8 → 4.0.0-internal.bc5cf8c

package/src/mcp/builtinTools.ts

@@ -1,4 +1,4 @@
-import type { CollectionTool, GlobalTool } from '../types.js'
+import type { CollectionTool, GlobalTool, Tool } from '../types.js'
 
 import {
   authCollectionTool,
@@ -8,62 +8,128 @@ import {
   unlockCollectionTool,
   verifyCollectionTool,
 } from './builtin/collections/authTools.js'
-import { createCollectionTool } from './builtin/collections/createTool.js'
-import { deleteCollectionTool } from './builtin/collections/deleteTool.js'
-import { findCollectionTool } from './builtin/collections/findTool.js'
-import { updateCollectionTool } from './builtin/collections/updateTool.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: Record<MCPCollectionBuiltinName, CollectionTool> = {
-  create: createCollectionTool,
-  delete: deleteCollectionTool,
-  find: findCollectionTool,
-  update: updateCollectionTool,
-}
+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. 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: Record<
-  MCPCollectionAuthToolName,
-  { label: string; tool: CollectionTool }
-> = {
-  auth: { label: 'Check Auth Status', tool: authCollectionTool },
-  forgotPassword: { label: 'Forgot Password', tool: forgotPasswordCollectionTool },
-  login: { label: 'User Login', tool: loginCollectionTool },
-  resetPassword: { label: 'Reset Password', tool: resetPasswordCollectionTool },
-  unlock: { label: 'Unlock Account', tool: unlockCollectionTool },
-  verify: { label: 'Email Verification', tool: verifyCollectionTool },
-}
+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: Record<MCPGlobalBuiltinName, GlobalTool> = {
-  find: findGlobalTool,
-  update: updateGlobalTool,
-}
+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 MCPCollectionBuiltinName = 'create' | 'delete' | 'find' | 'update'
+export type MCPCollectionAuthToolName = keyof typeof COLLECTION_AUTH_BUILTINS
 
-export type MCPCollectionAuthToolName =
-  | 'auth'
-  | 'forgotPassword'
-  | 'login'
-  | 'resetPassword'
-  | 'unlock'
-  | 'verify'
+export type MCPGlobalBuiltinName = keyof typeof GLOBAL_BUILTINS
 
-export type MCPGlobalBuiltinName = 'find' | 'update'
+export type MCPTopLevelBuiltinName = keyof typeof TOOL_BUILTINS
 
 /**
  * Pre-typed `Object.entries` for each registry. The cast from `string` to the
@@ -71,14 +137,18 @@ export type MCPGlobalBuiltinName = 'find' | 'update'
  * 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, CollectionTool]
+  [MCPCollectionBuiltinName, CollectionBuiltin]
 >
 
 export const COLLECTION_AUTH_BUILTIN_ENTRIES = Object.entries(COLLECTION_AUTH_BUILTINS) as Array<
-  [MCPCollectionAuthToolName, { label: string; tool: CollectionTool }]
+  [MCPCollectionAuthToolName, (typeof COLLECTION_AUTH_BUILTINS)[MCPCollectionAuthToolName]]
 >
 
 export const GLOBAL_BUILTIN_ENTRIES = Object.entries(GLOBAL_BUILTINS) as Array<
-  [MCPGlobalBuiltinName, GlobalTool]
+  [MCPGlobalBuiltinName, GlobalBuiltin]
 >

package/src/mcp/sanitizeMCPConfig.ts

@@ -8,16 +8,16 @@ import type {
 } from 'payload'
 
 import type {
+  CollectionMCPItem,
   CollectionTool,
+  GlobalMCPItem,
   GlobalTool,
-  MCPBuiltInToolOverride,
   MCPItem,
-  MCPPluginCollectionConfig,
   MCPPluginConfig,
-  MCPPluginGlobalConfig,
   SanitizedMCPPluginConfig,
 } from '../types.js'
 
+import { defaultAccess } from '../defaultAccess.js'
 import {
   COLLECTION_AUTH_BUILTIN_ENTRIES,
   COLLECTION_AUTH_BUILTINS,
@@ -25,6 +25,8 @@ import {
   COLLECTION_BUILTINS,
   GLOBAL_BUILTIN_ENTRIES,
   GLOBAL_BUILTINS,
+  TOOL_BUILTIN_ENTRIES,
+  TOOL_BUILTINS,
 } from './builtinTools.js'
 
 /**
@@ -32,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
@@ -54,44 +55,54 @@ export const sanitizeMCPConfig = ({
     items.push(...sanitizeGlobalConfig({ global, pluginConfig }))
   }
 
-  for (const [key, tool] of Object.entries(pluginConfig.tools ?? {})) {
+  for (const [configKey, { mcpName, tool }] of TOOL_BUILTIN_ENTRIES) {
     items.push({
       type: 'tool',
-      key,
-      label: key,
-      tool,
+      configKey,
+      label: tool.annotations?.title ?? configKey,
+      mcpName,
+      tool: { ...tool, access: tool.access ?? defaultAccess },
     })
   }
 
-  for (const [key, prompt] of Object.entries(pluginConfig.prompts ?? {})) {
+  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',
-      key,
-      label: prompt.title ?? key,
-      prompt,
+      configKey,
+      label: prompt.title ?? configKey,
+      mcpName: configKey,
+      prompt: { ...prompt, access: prompt.access ?? defaultAccess },
     })
   }
 
-  for (const [key, resource] of Object.entries(pluginConfig.resources ?? {})) {
+  for (const [configKey, resource] of Object.entries(pluginConfig.resources ?? {})) {
     items.push({
       type: 'resource',
-      key,
-      label: resource.title ?? key,
-      resource,
+      configKey,
+      label: resource.title ?? configKey,
+      mcpName: configKey,
+      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,
     items,
     mcp: pluginConfig.mcp,
-    overrideApiKeyCollection: pluginConfig.overrideApiKeyCollection,
-    overrideAuth: pluginConfig.overrideAuth,
-    userCollection:
-      pluginConfig.userCollection ?? config.admin?.user ?? firstCollectionWithAuth?.slug ?? 'users',
+    overrideGetAuthorizedMCP: pluginConfig.overrideGetAuthorizedMCP,
   }
 }
 
@@ -101,42 +112,78 @@ const sanitizeCollectionConfig = ({
 }: {
   collection: CollectionConfig | SanitizedCollectionConfig
   pluginConfig: MCPPluginConfig
-}): MCPItem[] => {
-  if (collection.slug === 'payload-mcp-api-keys') {
-    return []
-  }
+}): CollectionMCPItem[] => {
   const slug = collection.slug
   const collectionPluginConfig = pluginConfig.collections?.[slug]
-  const items: MCPItem[] = []
+  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, 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,
-      key: toolKey,
-      label: capitalize(toolKey),
-      tool: overrideBuiltinTool(tool, matchedConfigEntry, collectionPluginConfig),
+      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, { label, 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,
-        key: authToolKey,
-        label,
-        tool: overrideBuiltinTool(tool, override, collectionPluginConfig),
+        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,
+        },
       })
     }
   }
@@ -146,8 +193,8 @@ const sanitizeCollectionConfig = ({
   const customEntries = Object.entries(collectionPluginConfig?.tools ?? {}) as Array<
     [string, CollectionTool | undefined]
   >
-  for (const [key, customTool] of customEntries) {
-    if (key in COLLECTION_BUILTINS || key in COLLECTION_AUTH_BUILTINS) {
+  for (const [configKey, customTool] of customEntries) {
+    if (configKey in COLLECTION_BUILTINS || configKey in COLLECTION_AUTH_BUILTINS) {
       continue
     }
     if (!customTool) {
@@ -156,9 +203,10 @@ const sanitizeCollectionConfig = ({
     items.push({
       type: 'collectionTool',
       collectionSlug: slug,
-      key,
-      label: key,
-      tool: customTool,
+      configKey,
+      label: customTool.annotations?.title ?? configKey,
+      mcpName: configKey,
+      tool: { ...customTool, access: customTool.access ?? defaultAccess },
     })
   }
 
@@ -171,30 +219,45 @@ const sanitizeGlobalConfig = ({
 }: {
   global: GlobalConfig | SanitizedGlobalConfig
   pluginConfig: MCPPluginConfig
-}): MCPItem[] => {
+}): GlobalMCPItem[] => {
   const slug = global.slug
   const globalPluginConfig = pluginConfig.globals?.[slug]
-  const items: MCPItem[] = []
+  const items: GlobalMCPItem[] = []
 
-  for (const [toolKey, baseTool] 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,
-      key: toolKey,
-      label: capitalize(toolKey),
-      tool: overrideBuiltinTool(baseTool, matchedConfigEntry, globalPluginConfig),
+      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 [key, customTool] of customEntries) {
-    if (key in GLOBAL_BUILTINS) {
+  for (const [configKey, customTool] of customEntries) {
+    if (configKey in GLOBAL_BUILTINS) {
       continue
     }
     if (!customTool) {
@@ -202,38 +265,13 @@ const sanitizeGlobalConfig = ({
     }
     items.push({
       type: 'globalTool',
+      configKey,
       globalSlug: slug,
-      key,
-      label: key,
-      tool: customTool,
+      label: customTool.annotations?.title ?? configKey,
+      mcpName: configKey,
+      tool: { ...customTool, access: customTool.access ?? defaultAccess },
     })
   }
 
   return items
 }
-
-const capitalize = (s: string): string => s.charAt(0).toUpperCase() + s.slice(1)
-
-/**
- * Spread the static built-in tool and apply consumer-side overrides.
- * Precedence: per-tool override > scope-level (collection/global) override >
- * the static tool's defaults. `toolEntry` is whatever the user put under
- * `tools: { find: ... }` — could be `true`, `false`, or an override object —
- * so it's narrowed internally.
- */
-const overrideBuiltinTool = <TTool extends CollectionTool | GlobalTool>(
-  tool: TTool,
-  toolOverride?: MCPBuiltInToolOverride,
-  entityPluginConfig?: TTool extends CollectionTool
-    ? MCPPluginCollectionConfig<any>
-    : MCPPluginGlobalConfig,
-): TTool => {
-  return {
-    ...tool,
-    description: toolOverride?.description ?? entityPluginConfig?.description ?? tool.description,
-    overrideResponse:
-      toolOverride?.overrideResponse ??
-      entityPluginConfig?.overrideResponse ??
-      tool.overrideResponse,
-  }
-}

package/src/stdio.ts

@@ -6,8 +6,9 @@ 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'
@@ -16,8 +17,9 @@ import { resolveProjectRoot } from './utils/resolveProjectRoot.js'
 /**
  * Stdio adapter for the Payload MCP server.
  *
- * Do not use in production. There's no auth; whoever can spawn the process gets
- * full access to your local data.
+ * Pass PAYLOAD_MCP_AUTHORIZATION when stdio should authenticate with the same
+ * Payload auth header as HTTP. In development, PAYLOAD_MCP_OVERRIDE_ACCESS=true
+ * skips access control for local setup.
  */
 export const runMcpStdio = async (): Promise<void> => {
   /**
@@ -62,14 +64,27 @@ export const runMcpStdio = async (): Promise<void> => {
     ;(payload.config.plugins ??= []).push(fakePluginFn)
   }
 
-  const authorizedMCP: AuthorizedMCP = {
-    items: pluginConfig.items,
-    overrideAccess: true,
-    user: null,
+  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({}, 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 })