@payloadcms/plugin-mcp 4.0.0-internal.5b1e7cd → 4.0.0-internal.a0ef1b8

package/src/mcp/builtin/globals/findTool.ts

@@ -0,0 +1,96 @@
+import type { SelectType } from 'payload'
+
+import { z } from 'zod'
+
+import { defineGlobalTool } from '../../../defineTool.js'
+import { getLogger } from '../../../utils/getLogger.js'
+import { localAPIDefaults } from '../../../utils/localAPIDefaults.js'
+
+const DEFAULT_DESCRIPTION = 'Find a Payload global singleton configuration.'
+
+export const findGlobalTool = defineGlobalTool({
+  description: DEFAULT_DESCRIPTION,
+  input: z.object({
+    depth: z
+      .number()
+      .int()
+      .min(0)
+      .max(10)
+      .describe('Depth of population for relationships')
+      .optional()
+      .default(0),
+    fallbackLocale: z
+      .string()
+      .describe('Optional: fallback locale code to use when requested locale is not available')
+      .optional(),
+    locale: z
+      .string()
+      .describe(
+        'Optional: locale code to retrieve data in (e.g., "en", "es"). Use "all" to retrieve all locales for localized fields',
+      )
+      .optional(),
+    select: z
+      .string()
+      .describe(
+        "Optional: define exactly which fields you'd like to return in the response (JSON), e.g., '{\"title\": true}'",
+      )
+      .optional(),
+  }),
+}).handler(async ({ authorizedMCP, globalSlug, input, req }) => {
+  const payload = req.payload
+  const logger = getLogger({ payload })
+
+  const { depth, fallbackLocale, locale, select } = input
+
+  logger.info(
+    `Reading global: ${globalSlug}, depth: ${depth}${locale ? `, locale: ${locale}` : ''}`,
+  )
+
+  try {
+    const findOptions: Parameters<typeof payload.findGlobal>[0] = {
+      slug: globalSlug,
+      depth,
+      ...localAPIDefaults(authorizedMCP),
+    }
+
+    let selectClause: SelectType | undefined
+    if (select) {
+      try {
+        selectClause = JSON.parse(select) as SelectType
+      } catch {
+        logger.warn(`Invalid select clause JSON for global: ${select}`)
+        return { content: [{ type: 'text', text: 'Error: Invalid JSON in select clause' }] }
+      }
+    }
+
+    if (locale) {
+      findOptions.locale = locale
+    }
+    if (fallbackLocale) {
+      findOptions.fallbackLocale = fallbackLocale
+    }
+    if (selectClause) {
+      findOptions.select = selectClause
+    }
+
+    const result = await payload.findGlobal(findOptions)
+
+    return {
+      content: [
+        {
+          type: 'text',
+          text: `Global "${globalSlug}":\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 reading global ${globalSlug}: ${errorMessage}`)
+    return {
+      content: [
+        { type: 'text', text: `❌ **Error reading global "${globalSlug}":** ${errorMessage}` },
+      ],
+    }
+  }
+})

package/src/mcp/builtin/globals/updateTool.ts

@@ -0,0 +1,120 @@
+import type { SelectType } from 'payload'
+
+import { z } from 'zod'
+
+import { defineGlobalTool } from '../../../defineTool.js'
+import { getLogger } from '../../../utils/getLogger.js'
+import {
+  getGlobalVirtualFieldNames,
+  stripVirtualFields,
+} from '../../../utils/getVirtualFieldNames.js'
+import { localAPIDefaults } from '../../../utils/localAPIDefaults.js'
+import { buildToolInput } from '../../../utils/schemaConversion/buildToolInput.js'
+import { sanitizeEntitySchema } from '../../../utils/schemaConversion/sanitizeEntitySchema.js'
+
+const DEFAULT_DESCRIPTION = 'Update a Payload global singleton configuration.'
+
+export const updateGlobalTool = defineGlobalTool({
+  description: DEFAULT_DESCRIPTION,
+  input: ({ globalSchema }) => {
+    const partialSchema = sanitizeEntitySchema(globalSchema)
+    // Global updates do not require all required fields to be passed => delete .required.
+    //
+    // Local API equivalent: packages/payload/src/global/operations/local/update.ts#BaseOptions#data:
+    // data: DeepPartial<Omit<DataFromGlobalSlug<TSlug>, 'id'>>
+    delete partialSchema.required
+
+    return buildToolInput({
+      controls: {
+        depth: z
+          .number()
+          .describe('Optional: Depth of relationships to populate')
+          .optional()
+          .default(0),
+        draft: z
+          .boolean()
+          .describe('Optional: Whether to save as draft (default: false)')
+          .optional()
+          .default(false),
+        fallbackLocale: z
+          .string()
+          .describe('Optional: fallback locale code to use when requested locale is not available')
+          .optional(),
+        locale: z
+          .string()
+          .describe(
+            'Optional: locale code to update data in (e.g., "en", "es"). Use "all" to update all locales for localized fields',
+          )
+          .optional(),
+        select: z
+          .string()
+          .describe(
+            'Optional: define exactly which fields you\'d like to return in the response (JSON), e.g., \'{"siteName": "My Site"}\'',
+          )
+          .optional(),
+      },
+      dataDescription: 'The fields to update',
+      dataSchema: partialSchema,
+    })
+  },
+}).handler(async ({ authorizedMCP, globalSlug, input, req }) => {
+  const payload = req.payload
+  const logger = getLogger({ payload })
+
+  const { data, depth, draft, fallbackLocale, locale, select } = input
+
+  logger.info(
+    `Updating global: ${globalSlug}, draft: ${draft}${locale ? `, locale: ${locale}` : ''}`,
+  )
+
+  try {
+    const virtualFieldNames = getGlobalVirtualFieldNames(payload.config, globalSlug)
+    const parsedData = stripVirtualFields(data, virtualFieldNames)
+
+    let selectClause: SelectType | undefined
+    if (select) {
+      try {
+        selectClause = JSON.parse(select) as SelectType
+      } catch {
+        logger.warn(`Invalid select clause JSON for global: ${select}`)
+        return { content: [{ type: 'text', text: 'Error: Invalid JSON in select clause' }] }
+      }
+    }
+
+    const updateOptions: Parameters<typeof payload.updateGlobal>[0] = {
+      slug: globalSlug,
+      data: parsedData,
+      depth,
+      draft,
+      ...localAPIDefaults(authorizedMCP),
+    }
+
+    if (locale) {
+      updateOptions.locale = locale
+    }
+    if (fallbackLocale) {
+      updateOptions.fallbackLocale = fallbackLocale
+    }
+    if (selectClause) {
+      updateOptions.select = selectClause
+    }
+
+    const result = await payload.updateGlobal(updateOptions)
+
+    return {
+      content: [
+        {
+          type: 'text',
+          text: `Global "${globalSlug}" updated successfully!\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 updating global ${globalSlug}: ${errorMessage}`)
+    return {
+      content: [{ type: 'text', text: `Error updating global "${globalSlug}": ${errorMessage}` }],
+    }
+  }
+})

package/src/mcp/builtinTools.ts

@@ -0,0 +1,84 @@
+import type { CollectionTool, GlobalTool } from '../types.js'
+
+import {
+  authCollectionTool,
+  forgotPasswordCollectionTool,
+  loginCollectionTool,
+  resetPasswordCollectionTool,
+  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 { findGlobalTool } from './builtin/globals/findTool.js'
+import { updateGlobalTool } from './builtin/globals/updateTool.js'
+
+/**
+ * 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,
+}
+
+/**
+ * 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`.
+ */
+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 },
+}
+
+/**
+ * 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 type MCPCollectionBuiltinName = 'create' | 'delete' | 'find' | 'update'
+
+export type MCPCollectionAuthToolName =
+  | 'auth'
+  | 'forgotPassword'
+  | 'login'
+  | 'resetPassword'
+  | 'unlock'
+  | 'verify'
+
+export type MCPGlobalBuiltinName = 'find' | 'update'
+
+/**
+ * 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 COLLECTION_BUILTIN_ENTRIES = Object.entries(COLLECTION_BUILTINS) as Array<
+  [MCPCollectionBuiltinName, CollectionTool]
+>
+
+export const COLLECTION_AUTH_BUILTIN_ENTRIES = Object.entries(COLLECTION_AUTH_BUILTINS) as Array<
+  [MCPCollectionAuthToolName, { label: string; tool: CollectionTool }]
+>
+
+export const GLOBAL_BUILTIN_ENTRIES = Object.entries(GLOBAL_BUILTINS) as Array<
+  [MCPGlobalBuiltinName, GlobalTool]
+>

package/src/mcp/sanitizeMCPConfig.ts

@@ -0,0 +1,239 @@
+import type {
+  CollectionConfig,
+  Config,
+  GlobalConfig,
+  SanitizedCollectionConfig,
+  SanitizedConfig,
+  SanitizedGlobalConfig,
+} from 'payload'
+
+import type {
+  CollectionTool,
+  GlobalTool,
+  MCPBuiltInToolOverride,
+  MCPItem,
+  MCPPluginCollectionConfig,
+  MCPPluginConfig,
+  MCPPluginGlobalConfig,
+  SanitizedMCPPluginConfig,
+} from '../types.js'
+
+import {
+  COLLECTION_AUTH_BUILTIN_ENTRIES,
+  COLLECTION_AUTH_BUILTINS,
+  COLLECTION_BUILTIN_ENTRIES,
+  COLLECTION_BUILTINS,
+  GLOBAL_BUILTIN_ENTRIES,
+  GLOBAL_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.
+ *  - Applies the `userCollection` default
+ *
+ * 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 [key, tool] of Object.entries(pluginConfig.tools ?? {})) {
+    items.push({
+      type: 'tool',
+      key,
+      label: key,
+      tool,
+    })
+  }
+
+  for (const [key, prompt] of Object.entries(pluginConfig.prompts ?? {})) {
+    items.push({
+      type: 'prompt',
+      key,
+      label: prompt.title ?? key,
+      prompt,
+    })
+  }
+
+  for (const [key, resource] of Object.entries(pluginConfig.resources ?? {})) {
+    items.push({
+      type: 'resource',
+      key,
+      label: resource.title ?? key,
+      resource,
+    })
+  }
+
+  // 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',
+  }
+}
+
+const sanitizeCollectionConfig = ({
+  collection,
+  pluginConfig,
+}: {
+  collection: CollectionConfig | SanitizedCollectionConfig
+  pluginConfig: MCPPluginConfig
+}): MCPItem[] => {
+  if (collection.slug === 'payload-mcp-api-keys') {
+    return []
+  }
+  const slug = collection.slug
+  const collectionPluginConfig = pluginConfig.collections?.[slug]
+  const items: MCPItem[] = []
+
+  for (const [toolKey, tool] of COLLECTION_BUILTIN_ENTRIES) {
+    const matchedConfigEntry = collectionPluginConfig?.tools?.[toolKey]
+    if (matchedConfigEntry === false) {
+      continue
+    }
+    items.push({
+      type: 'collectionTool',
+      collectionSlug: slug,
+      key: toolKey,
+      label: capitalize(toolKey),
+      tool: overrideBuiltinTool(tool, matchedConfigEntry, collectionPluginConfig),
+    })
+  }
+
+  if (collection.auth) {
+    for (const [authToolKey, { label, 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
+      items.push({
+        type: 'collectionTool',
+        collectionSlug: slug,
+        key: authToolKey,
+        label,
+        tool: overrideBuiltinTool(tool, override, collectionPluginConfig),
+      })
+    }
+  }
+
+  // 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 [key, customTool] of customEntries) {
+    if (key in COLLECTION_BUILTINS || key in COLLECTION_AUTH_BUILTINS) {
+      continue
+    }
+    if (!customTool) {
+      continue
+    }
+    items.push({
+      type: 'collectionTool',
+      collectionSlug: slug,
+      key,
+      label: key,
+      tool: customTool,
+    })
+  }
+
+  return items
+}
+
+const sanitizeGlobalConfig = ({
+  global,
+  pluginConfig,
+}: {
+  global: GlobalConfig | SanitizedGlobalConfig
+  pluginConfig: MCPPluginConfig
+}): MCPItem[] => {
+  const slug = global.slug
+  const globalPluginConfig = pluginConfig.globals?.[slug]
+  const items: MCPItem[] = []
+
+  for (const [toolKey, baseTool] of GLOBAL_BUILTIN_ENTRIES) {
+    const matchedConfigEntry = globalPluginConfig?.tools?.[toolKey]
+    if (matchedConfigEntry === false) {
+      continue
+    }
+    items.push({
+      type: 'globalTool',
+      globalSlug: slug,
+      key: toolKey,
+      label: capitalize(toolKey),
+      tool: overrideBuiltinTool(baseTool, matchedConfigEntry, globalPluginConfig),
+    })
+  }
+
+  const customEntries = Object.entries(globalPluginConfig?.tools ?? {}) as Array<
+    [string, GlobalTool | undefined]
+  >
+  for (const [key, customTool] of customEntries) {
+    if (key in GLOBAL_BUILTINS) {
+      continue
+    }
+    if (!customTool) {
+      continue
+    }
+    items.push({
+      type: 'globalTool',
+      globalSlug: slug,
+      key,
+      label: key,
+      tool: customTool,
+    })
+  }
+
+  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

@@ -0,0 +1,98 @@
+import type { MaybePromise, Plugin, SanitizedConfig } from 'payload'
+
+/* eslint-disable no-console */
+import { StdioServerTransport } from '@modelcontextprotocol/server'
+import { fileURLToPath, pathToFileURL } from 'node:url'
+import { createLocalReq, getPayload } from 'payload'
+import { findConfig } from 'payload/node'
+
+import type { AuthorizedMCP, SanitizedMCPPluginConfig } from './types.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.
+ *
+ * Do not use in production. There's no auth; whoever can spawn the process gets
+ * full access to your local data.
+ */
+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.
+   */
+  const projectRoot = resolveProjectRoot(fileURLToPath(import.meta.url))
+  if (projectRoot) {
+    process.chdir(projectRoot)
+  }
+
+  const configPath = findConfig()
+  const configModule = await import(pathToFileURL(configPath).toString())
+  const config = (await (configModule.default ?? configModule)) as MaybePromise<SanitizedConfig>
+
+  const payload = await getPayload({ config })
+
+  /**
+   * 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.
+   */
+  let pluginConfig: SanitizedMCPPluginConfig
+  try {
+    pluginConfig = getPluginConfig({ config: payload.config })
+  } catch {
+    pluginConfig = sanitizeMCPConfig({ config: payload.config, pluginConfig: {} })
+
+    const fakePluginFn: Plugin = (config) => config
+    fakePluginFn.slug = '@payloadcms/plugin-mcp'
+    // @ts-expect-error
+    fakePluginFn.sanitizedOptions = pluginConfig
+
+    // Push to payload config, to ensure consecutive calls to `getPluginConfig()` work
+    ;(payload.config.plugins ??= []).push(fakePluginFn)
+  }
+
+  const authorizedMCP: AuthorizedMCP = {
+    items: pluginConfig.items,
+    overrideAccess: true,
+    user: null,
+  }
+
+  const req = await createLocalReq({}, payload)
+  req.payloadAPI = 'MCP' as const
+
+  const server = buildMcpServer({ authorizedMCP, pluginConfig, req })
+
+  const transport = new StdioServerTransport()
+  await server.connect(transport)
+
+  // 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()
+    } 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.on('SIGINT', () => void shutdown(0))
+  process.on('SIGTERM', () => void shutdown(0))
+  process.stdin.on('close', () => void shutdown(0))
+}