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

package/src/mcp/builtin/validateEntityData.ts

@@ -0,0 +1,132 @@
+import type { CollectionSlug, GlobalSlug, PayloadRequest, SanitizedConfig } from 'payload'
+
+import { CfWorkerJsonSchemaValidator } from '@modelcontextprotocol/server'
+
+import type { JsonSchemaType, MCPToolResponse } from '../../types.js'
+
+import {
+  getCollectionInputSchema,
+  getGlobalInputSchema,
+} from '../../utils/schemaConversion/getEntityInputSchema.js'
+
+/**
+ * Keep the default `shortcircuit: true` - `false` makes validating nested rich text exponentially slow.
+ */
+const validator = new CfWorkerJsonSchemaValidator({ shortcircuit: true })
+
+type EntityValidator = {
+  schema: JsonSchemaType
+  validate: ReturnType<(typeof validator)['getValidator']>
+}
+
+/**
+ * - Caches each entity's schema and validator, so both are only built on the first request.
+ * - Keyed by payload config, then by entity type, slug, partial and language.
+ */
+const validatorCache = new WeakMap<SanitizedConfig, Map<string, EntityValidator>>()
+
+export const validateCollectionData = ({
+  collectionSlug,
+  data,
+  partial,
+  req,
+}: {
+  collectionSlug: CollectionSlug
+  data: Record<string, unknown>
+  partial?: boolean
+  req: PayloadRequest
+}): MCPToolResponse | null =>
+  validateData({
+    slug: collectionSlug,
+    buildSchema: () => getCollectionInputSchema({ collectionSlug, req }),
+    data,
+    entity: 'collection',
+    partial,
+    req,
+  })
+
+export const validateGlobalData = ({
+  data,
+  globalSlug,
+  req,
+}: {
+  data: Record<string, unknown>
+  globalSlug: GlobalSlug
+  req: PayloadRequest
+}): MCPToolResponse | null =>
+  validateData({
+    slug: globalSlug,
+    buildSchema: () => getGlobalInputSchema({ globalSlug, req }),
+    data,
+    entity: 'global',
+    partial: true,
+    req,
+  })
+
+const validateData = ({
+  slug,
+  buildSchema,
+  data,
+  entity,
+  partial,
+  req,
+}: {
+  buildSchema: () => JsonSchemaType | null
+  data: Record<string, unknown>
+  entity: 'collection' | 'global'
+  partial?: boolean
+  req: PayloadRequest
+  slug: string
+}): MCPToolResponse | null => {
+  let cache = validatorCache.get(req.payload.config)
+  if (!cache) {
+    cache = new Map()
+    validatorCache.set(req.payload.config, cache)
+  }
+
+  const cacheKey = `${entity}:${slug}:${partial ? 'partial' : 'full'}:${req.i18n.language}`
+  let entityValidator = cache.get(cacheKey)
+
+  if (!entityValidator) {
+    const schema = buildSchema()
+
+    if (!schema) {
+      return null
+    }
+
+    entityValidator = {
+      schema,
+      validate: validator.getValidator(partial ? withoutRequired(schema) : schema),
+    }
+    cache.set(cacheKey, entityValidator)
+  }
+
+  const result = entityValidator.validate(data)
+
+  if (result.valid) {
+    return null
+  }
+
+  const { schema } = entityValidator
+
+  return {
+    content: [
+      {
+        type: 'text',
+        text: `Invalid data for ${entity} "${slug}": ${result.errorMessage}\n\nUse this schema for data:\n\`\`\`json\n${JSON.stringify(schema)}\n\`\`\``,
+      },
+    ],
+    isError: true,
+    structuredContent: {
+      [`${entity}Slug`]: slug,
+      errors: [{ message: result.errorMessage }],
+      schema,
+    },
+  }
+}
+
+/** Updates are partial — drop the schema's top-level `required` before validating. */
+const withoutRequired = (schema: JsonSchemaType): JsonSchemaType => {
+  const { required: _required, ...rest } = schema
+  return rest
+}

package/src/mcp/builtinTools.ts

@@ -0,0 +1,98 @@
+import type { CollectionTool, GlobalTool, Tool } from '../types.js'
+
+import {
+  authCollectionTool,
+  forgotPasswordCollectionTool,
+  loginCollectionTool,
+  resetPasswordCollectionTool,
+  unlockCollectionTool,
+  verifyCollectionTool,
+} from './builtin/collections/authTools.js'
+import { createDocumentTool } from './builtin/collections/createTool.js'
+import { deleteDocumentsTool } from './builtin/collections/deleteTool.js'
+import { findDocumentsTool } from './builtin/collections/findTool.js'
+import { getCollectionSchemaTool } from './builtin/collections/getCollectionSchemaTool.js'
+import { updateDocumentTool } from './builtin/collections/updateTool.js'
+import { getConfigInfoTool } from './builtin/getConfigInfoTool.js'
+import { findGlobalTool } from './builtin/globals/findTool.js'
+import { getGlobalSchemaTool } from './builtin/globals/getGlobalSchemaTool.js'
+import { updateGlobalTool } from './builtin/globals/updateTool.js'
+
+export const TOOL_BUILTINS = {
+  getConfigInfo: { label: 'Config Info', mcpName: 'getConfigInfo', tool: getConfigInfoTool },
+} satisfies Record<string, { label: 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 = {
+  create: { mcpName: 'createDocument', tool: createDocumentTool },
+  delete: { mcpName: 'deleteDocuments', tool: deleteDocumentsTool },
+  find: { mcpName: 'findDocuments', tool: findDocumentsTool },
+  getCollectionSchema: { mcpName: 'getCollectionSchema', tool: getCollectionSchemaTool },
+  update: { mcpName: 'updateDocument', tool: updateDocumentTool },
+} satisfies Record<string, { mcpName: string; tool: CollectionTool }>
+
+/**
+ * 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 = {
+  auth: { label: 'Check Auth Status', mcpName: 'auth', tool: authCollectionTool },
+  forgotPassword: {
+    label: 'Forgot Password',
+    mcpName: 'forgotPassword',
+    tool: forgotPasswordCollectionTool,
+  },
+  login: { label: 'User 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 }>
+
+/**
+ * The static built-in global tools. Keys are the source of truth for
+ * `MCPGlobalBuiltinName`.
+ */
+export const GLOBAL_BUILTINS = {
+  find: { mcpName: 'findGlobal', tool: findGlobalTool },
+  getGlobalSchema: { mcpName: 'getGlobalSchema', tool: getGlobalSchemaTool },
+  update: { mcpName: 'updateGlobal', tool: updateGlobalTool },
+} satisfies Record<string, { mcpName: string; tool: GlobalTool }>
+
+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, (typeof COLLECTION_BUILTINS)[MCPCollectionBuiltinName]]
+>
+
+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, (typeof GLOBAL_BUILTINS)[MCPGlobalBuiltinName]]
+>

package/src/mcp/sanitizeMCPConfig.ts

@@ -0,0 +1,260 @@
+import type {
+  CollectionConfig,
+  Config,
+  GlobalConfig,
+  SanitizedCollectionConfig,
+  SanitizedConfig,
+  SanitizedGlobalConfig,
+} from 'payload'
+
+import type {
+  CollectionMCPItem,
+  CollectionTool,
+  GlobalMCPItem,
+  GlobalTool,
+  MCPItem,
+  MCPPluginConfig,
+  SanitizedMCPPluginConfig,
+} from '../types.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.
+ *  - 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 [configKey, { label, mcpName, tool }] of TOOL_BUILTIN_ENTRIES) {
+    items.push({
+      type: 'tool',
+      configKey,
+      label,
+      mcpName,
+      tool,
+    })
+  }
+
+  for (const [configKey, tool] of Object.entries(pluginConfig.tools ?? {})) {
+    if (configKey in TOOL_BUILTINS) {
+      continue
+    }
+    items.push({
+      type: 'tool',
+      configKey,
+      label: configKey,
+      mcpName: configKey,
+      tool,
+    })
+  }
+
+  for (const [configKey, prompt] of Object.entries(pluginConfig.prompts ?? {})) {
+    items.push({
+      type: 'prompt',
+      configKey,
+      label: prompt.title ?? configKey,
+      mcpName: configKey,
+      prompt,
+    })
+  }
+
+  for (const [configKey, resource] of Object.entries(pluginConfig.resources ?? {})) {
+    items.push({
+      type: 'resource',
+      configKey,
+      label: resource.title ?? configKey,
+      mcpName: configKey,
+      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
+}): CollectionMCPItem[] => {
+  if (collection.slug === 'payload-mcp-api-keys') {
+    return []
+  }
+  const slug = collection.slug
+  const collectionPluginConfig = pluginConfig.collections?.[slug]
+  const items: CollectionMCPItem[] = []
+
+  for (const [toolKey, { mcpName, tool }] of COLLECTION_BUILTIN_ENTRIES) {
+    const matchedConfigEntry = collectionPluginConfig?.tools?.[toolKey]
+    if (matchedConfigEntry === false) {
+      continue
+    }
+    const override = typeof matchedConfigEntry === 'object' ? matchedConfigEntry : undefined
+    items.push({
+      type: 'collectionTool',
+      collectionSlug: slug,
+      configKey: toolKey,
+      label: capitalize(toolKey),
+      mcpName,
+      tool: {
+        ...tool,
+        description: override?.description ?? tool.description,
+        overrideResponse:
+          override?.overrideResponse ??
+          collectionPluginConfig?.overrideResponse ??
+          tool.overrideResponse,
+      },
+    })
+  }
+
+  if (collection.auth) {
+    for (const [authToolKey, { label, 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
+      items.push({
+        type: 'collectionTool',
+        collectionSlug: slug,
+        configKey: authToolKey,
+        label,
+        mcpName,
+        tool: {
+          ...tool,
+          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: configKey,
+      mcpName: configKey,
+      tool: customTool,
+    })
+  }
+
+  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, tool }] of GLOBAL_BUILTIN_ENTRIES) {
+    const matchedConfigEntry = globalPluginConfig?.tools?.[toolKey]
+    if (matchedConfigEntry === false) {
+      continue
+    }
+    const override = typeof matchedConfigEntry === 'object' ? matchedConfigEntry : undefined
+    items.push({
+      type: 'globalTool',
+      configKey: toolKey,
+      globalSlug: slug,
+      label: capitalize(toolKey),
+      mcpName,
+      tool: {
+        ...tool,
+        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: configKey,
+      mcpName: configKey,
+      tool: customTool,
+    })
+  }
+
+  return items
+}
+
+const capitalize = (s: string): string => s.charAt(0).toUpperCase() + s.slice(1)

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))
+}

package/src/translations/index.ts

@@ -0,0 +1,108 @@
+import type {
+  NestedKeysStripped,
+  SupportedLanguages,
+} from '@payloadcms/translations'
+
+import type { PluginDefaultTranslationsObject } from './types.js'
+
+import { ar } from './languages/ar.js'
+import { az } from './languages/az.js'
+import { bg } from './languages/bg.js'
+import { bnBd } from './languages/bnBd.js'
+import { bnIn } from './languages/bnIn.js'
+import { ca } from './languages/ca.js'
+import { cs } from './languages/cs.js'
+import { da } from './languages/da.js'
+import { de } from './languages/de.js'
+import { en } from './languages/en.js'
+import { es } from './languages/es.js'
+import { et } from './languages/et.js'
+import { fa } from './languages/fa.js'
+import { fr } from './languages/fr.js'
+import { he } from './languages/he.js'
+import { hr } from './languages/hr.js'
+import { hu } from './languages/hu.js'
+import { hy } from './languages/hy.js'
+import { id } from './languages/id.js'
+import { is } from './languages/is.js'
+import { it } from './languages/it.js'
+import { ja } from './languages/ja.js'
+import { ko } from './languages/ko.js'
+import { lt } from './languages/lt.js'
+import { lv } from './languages/lv.js'
+import { my } from './languages/my.js'
+import { nb } from './languages/nb.js'
+import { nl } from './languages/nl.js'
+import { pl } from './languages/pl.js'
+import { pt } from './languages/pt.js'
+import { ro } from './languages/ro.js'
+import { rs } from './languages/rs.js'
+import { rsLatin } from './languages/rsLatin.js'
+import { ru } from './languages/ru.js'
+import { sk } from './languages/sk.js'
+import { sl } from './languages/sl.js'
+import { sv } from './languages/sv.js'
+import { ta } from './languages/ta.js'
+import { th } from './languages/th.js'
+import { tr } from './languages/tr.js'
+import { uk } from './languages/uk.js'
+import { vi } from './languages/vi.js'
+import { zh } from './languages/zh.js'
+import { zhTw } from './languages/zhTw.js'
+
+export const translations = {
+  id,
+  ar,
+  az,
+  bg,
+  'bn-BD': bnBd,
+  'bn-IN': bnIn,
+  ca,
+  cs,
+  da,
+  de,
+  en,
+  es,
+  et,
+  fa,
+  fr,
+  he,
+  hr,
+  hu,
+  hy,
+  is,
+  it,
+  ja,
+  ko,
+  lt,
+  lv,
+  my,
+  nb,
+  nl,
+  pl,
+  pt,
+  ro,
+  rs,
+  'rs-latin': rsLatin,
+  ru,
+  sk,
+  sl,
+  sv,
+  ta,
+  th,
+  tr,
+  uk,
+  vi,
+  zh,
+  'zh-TW': zhTw,
+} as SupportedLanguages<PluginDefaultTranslationsObject>
+
+export type PluginMCPTranslations = PluginDefaultTranslationsObject
+
+export type PluginMCPTranslationKeys = NestedKeysStripped<PluginMCPTranslations>
+
+declare module '@payloadcms/translations' {
+  interface CustomTranslationKeys {
+    'plugin-mcp': PluginMCPTranslationKeys
+  }
+}