@payloadcms/plugin-mcp 4.0.0-canary.0 → 4.0.0-canary.2

package/src/endpoint/access.ts

@@ -25,15 +25,15 @@ export const getAuthorizedMCP: (args: { req: PayloadRequest }) => Promise<Author
     items: pluginConfig.items.filter((item) => {
       switch (item.type) {
         case 'collectionTool':
-          return apiKeyDoc.access.collections?.[item.collectionSlug]?.[item.key] !== false
+          return apiKeyDoc.access.collections?.[item.collectionSlug]?.[item.configKey] !== false
         case 'globalTool':
-          return apiKeyDoc.access.globals?.[item.globalSlug]?.[item.key] !== false
+          return apiKeyDoc.access.globals?.[item.globalSlug]?.[item.configKey] !== false
         case 'prompt':
-          return apiKeyDoc.access.prompts?.[item.key] !== false
+          return apiKeyDoc.access.prompts?.[item.configKey] !== false
         case 'resource':
-          return apiKeyDoc.access.resources?.[item.key] !== false
+          return apiKeyDoc.access.resources?.[item.configKey] !== false
         case 'tool':
-          return apiKeyDoc.access.tools?.[item.key] !== false
+          return apiKeyDoc.access.tools?.[item.configKey] !== false
       }
     }),
     overrideAccess:
@@ -121,6 +121,18 @@ const getAPIKeyDoc = async ({
     throw new UnauthorizedError()
   }
 
+  try {
+    await req.payload.db.updateOne({
+      id: doc.id,
+      collection: 'payload-mcp-api-keys',
+      data: { lastUsed: new Date().toISOString() },
+      req,
+      returning: false,
+    })
+  } catch (err) {
+    logger.warn({ err, msg: 'Failed to update MCP API key last-used timestamp' })
+  }
+
   return {
     ...doc,
     user: {

package/src/exports/client.ts

@@ -1,2 +1,5 @@
 'use client'
 export { AccessField } from '../components/AccessField/index.client.js'
+export { APIKeyField } from '../components/APIKeyField/index.client.js'
+export { APIKeysEmptyState } from '../components/APIKeysEmptyState/index.client.js'
+export { MCPSettingsMenu } from '../components/SettingsMenu/index.client.js'

package/src/index.ts

@@ -1,10 +1,14 @@
+import type { AcceptedLanguages } from '@payloadcms/translations'
+
 import { defaultUserCollection, definePlugin } from 'payload'
 
+import type { PluginDefaultTranslationsObject } from './translations/types.js'
 import type { AuthorizedMCP, MCPPluginConfig, SanitizedMCPPluginConfig } from './types.js'
 
 import { getAPIKeysCollection } from './collection/index.js'
 import { mcpEndpoint } from './endpoint/index.js'
 import { sanitizeMCPConfig } from './mcp/sanitizeMCPConfig.js'
+import { translations } from './translations/index.js'
 
 declare module 'payload' {
   export interface PayloadRequest {
@@ -24,9 +28,8 @@ export const mcpPlugin = definePlugin<MCPPluginConfig>({
   slug: '@payloadcms/plugin-mcp',
   order: 10,
   plugin: ({ config, plugins, ...rawConfig }) => {
-    // Our `payload-mcp-api-keys` is auth-enabled; if it'd be the only auth
-    // collection, Payload's later sanitize would pick it as `admin.user`.
-    // Pre-seed the default user collection to prevent that.
+    // If a project has no auth collection yet, add the default users collection
+    // so the relationship target and default `userCollection` exist.
     if (!config.admin?.user) {
       const firstCollectionWithAuth = (config.collections ?? []).find(({ auth }) => Boolean(auth))
       if (!firstCollectionWithAuth) {
@@ -45,6 +48,32 @@ export const mcpPlugin = definePlugin<MCPPluginConfig>({
 
     ;(config.collections ??= []).push(getAPIKeysCollection({ pluginConfig }))
 
+    if (!config.i18n) {
+      config.i18n = {}
+    }
+
+    if (!config.i18n.translations) {
+      config.i18n.translations = {}
+    }
+
+    const supportedLanguageKeys = config.i18n.supportedLanguages
+      ? Object.keys(config.i18n.supportedLanguages)
+      : ['en']
+
+    for (const lang of supportedLanguageKeys) {
+      const pluginEntry = translations[lang as keyof typeof translations]
+      if (!pluginEntry) {
+        continue
+      }
+
+      const typedLocale = lang as AcceptedLanguages
+      const existing = (config.i18n.translations[typedLocale] ?? {}) as Record<string, unknown>
+      config.i18n.translations[typedLocale] = {
+        ...existing,
+        'plugin-mcp': pluginEntry.translations['plugin-mcp'],
+      } as PluginDefaultTranslationsObject
+    }
+
     // Keep the API-keys collection registered even when disabled, so DB schema
     // and generated types don't drift between enabled/disabled environments.
     if (pluginConfig.disabled) {
@@ -53,10 +82,27 @@ export const mcpPlugin = definePlugin<MCPPluginConfig>({
 
     return {
       ...config,
+      admin: {
+        ...config.admin,
+        components: {
+          ...config.admin?.components,
+          userMenuSettingsItems: [
+            ...(config.admin?.components?.userMenuSettingsItems ?? []),
+            '@payloadcms/plugin-mcp/client#MCPSettingsMenu',
+          ],
+        },
+      },
       endpoints: [
         ...(config.endpoints ?? []),
         // Payload prefixes /api, so the full path is /api/mcp.
         { handler: mcpEndpoint, method: 'post', path: '/mcp' },
+        // Streamable HTTP's optional server=>client GET stream. We don't offer
+        // one, so answer 405 per spec-— clients then skip it cleanly
+        {
+          handler: () => new Response(null, { headers: { Allow: 'POST' }, status: 405 }),
+          method: 'get',
+          path: '/mcp',
+        },
       ],
     }
   },

package/src/mcp/buildMcpServer.ts

@@ -1,29 +1,21 @@
 import { McpServer, type ServerContext } from '@modelcontextprotocol/server'
-import { APIError, configToJSONSchema, type PayloadRequest } from 'payload'
+import { APIError, type PayloadRequest } from 'payload'
+import { z } from 'zod'
 
 import type {
   AuthorizedMCP,
+  CollectionMCPItem,
+  GlobalMCPItem,
   JsonSchemaType,
   MCPResponseOverride,
   MCPToolResponse,
   SanitizedMCPPluginConfig,
+  ToolInputSchema,
 } from '../types.js'
 
-import { toCamelCase } from '../utils/camelCase.js'
 import { getLogger } from '../utils/getLogger.js'
-import {
-  getCollectionVirtualFieldNames,
-  getGlobalVirtualFieldNames,
-} from '../utils/getVirtualFieldNames.js'
-import { removeVirtualFieldsFromSchema } from '../utils/schemaConversion/removeVirtualFieldsFromSchema.js'
 import { toStandardSchema } from '../utils/toStandardSchema.js'
 
-/** `findPosts`, `updateSiteSettings` — auto-prefixed wire name for collection/global tools. */
-const wireName = (key: string, slug: string): string => {
-  const camel = toCamelCase(slug)
-  return `${key}${camel.charAt(0).toUpperCase()}${camel.slice(1)}`
-}
-
 /**
  * Transport-agnostic core: registers every authorized MCP item onto a fresh
  * `McpServer` and returns it. The caller is responsible for picking a transport
@@ -64,96 +56,100 @@ export const buildMcpServer = ({
     return rest
   }
 
-  const configSchema = configToJSONSchema(
-    req.payload.config,
-    req.payload.db.defaultIDType,
-    req.i18n,
-    { forceInlineBlocks: true },
-  ) as JsonSchemaType
+  /**
+   * Runs a collection/global tool call:
+   * - reads `collectionSlug` / `globalSlug` from the input
+   * - runs access control: errors if `authorizedMCP.items` has no entry for this tool + slug
+   * - runs the tool handler and finalizes its response
+   */
+  const callEntityTool = async ({
+    input,
+    item,
+    serverContext,
+  }: {
+    input: unknown
+    item: CollectionMCPItem | GlobalMCPItem
+    serverContext: ServerContext
+  }): Promise<MCPToolResponse> => {
+    const entity = item.type === 'collectionTool' ? 'collection' : 'global'
+    const slugKey = item.type === 'collectionTool' ? 'collectionSlug' : 'globalSlug'
+    const toolInput = (input ?? {}) as Record<string, unknown>
+    const slug = toolInput[slugKey] as string | undefined
+
+    if (!slug) {
+      return {
+        content: [
+          {
+            type: 'text',
+            text: `Error: "${item.mcpName}" requires ${slugKey}. Use getConfigInfo to inspect ${entity} slugs.`,
+          },
+        ],
+        isError: true,
+      }
+    }
+
+    const match = authorizedMCP.items.find(
+      (candidate): candidate is CollectionMCPItem | GlobalMCPItem =>
+        candidate.type === item.type &&
+        candidate.mcpName === item.mcpName &&
+        (candidate.type === 'collectionTool'
+          ? candidate.collectionSlug === slug
+          : candidate.type === 'globalTool' && candidate.globalSlug === slug),
+    )
+
+    if (!match) {
+      return {
+        content: [
+          {
+            type: 'text',
+            text: `Error: MCP access to "${item.mcpName}" is not enabled for ${entity} "${slug}"`,
+          },
+        ],
+        isError: true,
+      }
+    }
+
+    const handlerArgs = { authorizedMCP, input: toolInput, req, serverContext }
+    const response = await (match.type === 'collectionTool'
+      ? match.tool.handler({ ...handlerArgs, collectionSlug: slug })
+      : match.tool.handler({ ...handlerArgs, globalSlug: slug }))
+
+    return finalizeToolResponse(response, match.tool.overrideResponse)
+  }
 
   try {
+    const registeredEntityTools = new Set<string>()
+
     for (const item of authorizedMCP.items) {
       switch (item.type) {
-        case 'collectionTool': {
-          const tool = item.tool
-          const name = wireName(item.key, item.collectionSlug)
-          let inputSchema = tool.input
-          if (typeof inputSchema === 'function') {
-            const raw = configSchema.$defs?.[item.collectionSlug]
-            if (!raw) {
-              throw new APIError(
-                `Collection schema not found for slug: ${item.collectionSlug}`,
-                500,
-              )
-            }
-            const collectionSchema = removeVirtualFieldsFromSchema(
-              JSON.parse(JSON.stringify(raw)) as JsonSchemaType,
-              getCollectionVirtualFieldNames(req.payload.config, item.collectionSlug),
-            )
-            inputSchema = inputSchema({ collectionSchema })
-          }
-          server.registerTool(
-            name,
-            {
-              description: tool.description,
-              inputSchema: inputSchema ? toStandardSchema(inputSchema) : undefined,
-            },
-            async (input: unknown, ctx: ServerContext) =>
-              finalizeToolResponse(
-                await tool.handler({
-                  authorizedMCP,
-                  collectionSlug: item.collectionSlug,
-                  input: (input ?? {}) as Record<string, unknown>,
-                  req,
-                  serverContext: ctx,
-                }),
-                tool.overrideResponse,
-              ),
-          )
-          logger.info(`✅ Tool: ${name} Registered.`)
-          break
-        }
+        case 'collectionTool':
         case 'globalTool': {
-          const tool = item.tool
-          const name = wireName(item.key, item.globalSlug)
-          let inputSchema = tool.input
-          if (typeof inputSchema === 'function') {
-            const raw = configSchema.$defs?.[item.globalSlug]
-            if (!raw) {
-              throw new APIError(`Global schema not found for slug: ${item.globalSlug}`, 500)
-            }
-            const globalSchema = removeVirtualFieldsFromSchema(
-              JSON.parse(JSON.stringify(raw)) as JsonSchemaType,
-              getGlobalVirtualFieldNames(req.payload.config, item.globalSlug),
-            )
-
-            inputSchema = inputSchema({ globalSchema })
+          if (registeredEntityTools.has(item.mcpName)) {
+            break
           }
+          registeredEntityTools.add(item.mcpName)
+
+          const inputSchema = withSlugInput({
+            name: item.type === 'collectionTool' ? 'collectionSlug' : 'globalSlug',
+            input: item.tool.input,
+          })
+
           server.registerTool(
-            name,
+            item.mcpName,
             {
-              description: tool.description,
-              inputSchema: inputSchema ? toStandardSchema(inputSchema) : undefined,
+              description: item.tool.description,
+              inputSchema: toStandardSchema(inputSchema),
             },
             async (input: unknown, ctx: ServerContext) =>
-              finalizeToolResponse(
-                await tool.handler({
-                  authorizedMCP,
-                  globalSlug: item.globalSlug,
-                  input: (input ?? {}) as Record<string, unknown>,
-                  req,
-                  serverContext: ctx,
-                }),
-                tool.overrideResponse,
-              ),
+              callEntityTool({ input, item, serverContext: ctx }),
           )
-          logger.info(`✅ Tool: ${name} Registered.`)
+          logger.info(`✅ Tool: ${item.mcpName} Registered.`)
           break
         }
         case 'prompt': {
           const prompt = item.prompt
           server.registerPrompt(
-            item.key,
+            item.mcpName,
             {
               argsSchema: prompt.argsSchema ? toStandardSchema(prompt.argsSchema) : undefined,
               description: prompt.description,
@@ -172,7 +168,7 @@ export const buildMcpServer = ({
         case 'resource': {
           const resource = item.resource
           server.registerResource(
-            item.key,
+            item.mcpName,
             // @ts-expect-error - Overload type ambiguity (string OR ResourceTemplate is valid)
             resource.uri,
             {
@@ -195,7 +191,7 @@ export const buildMcpServer = ({
         case 'tool': {
           const tool = item.tool
           server.registerTool(
-            item.key,
+            item.mcpName,
             {
               description: tool.description,
               inputSchema: tool.input ? toStandardSchema(tool.input) : undefined,
@@ -211,7 +207,7 @@ export const buildMcpServer = ({
                 tool.overrideResponse,
               ),
           )
-          logger.info(`✅ Tool: ${item.key} Registered.`)
+          logger.info(`✅ Tool: ${item.mcpName} Registered.`)
           break
         }
       }
@@ -222,3 +218,40 @@ export const buildMcpServer = ({
 
   return server
 }
+
+const withSlugInput = ({
+  name,
+  input,
+}: {
+  input?: ToolInputSchema
+  name: 'collectionSlug' | 'globalSlug'
+}): ToolInputSchema => {
+  const description = name === 'collectionSlug' ? 'The collection slug' : 'The global slug'
+  const slugSchema = z.string().describe(description)
+
+  if (!input) {
+    return z.object({ [name]: slugSchema })
+  }
+
+  if (input instanceof z.ZodObject) {
+    return input.extend({ [name]: slugSchema })
+  }
+
+  const schema = input as {
+    properties?: Record<string, JsonSchemaType>
+    required?: string[]
+  } & JsonSchemaType
+
+  return {
+    ...schema,
+    type: 'object',
+    properties: {
+      ...schema.properties,
+      [name]: {
+        type: 'string',
+        description,
+      },
+    },
+    required: Array.from(new Set([name, ...(schema.required ?? [])])),
+  }
+}

package/src/mcp/builtin/collections/createTool.ts

@@ -9,50 +9,47 @@ import {
   stripVirtualFields,
 } from '../../../utils/getVirtualFieldNames.js'
 import { localAPIDefaults } from '../../../utils/localAPIDefaults.js'
-import { prepareCollectionSchema } from '../../../utils/schemaConversion/prepareCollectionSchema.js'
 import { transformPointDataToPayload } from '../../../utils/transformPointDataToPayload.js'
+import { validateCollectionData } from '../validateEntityData.js'
+import { formatCollectionError } from './formatCollectionError.js'
 
-const DEFAULT_DESCRIPTION = 'Create a document in a collection.'
+const DEFAULT_DESCRIPTION =
+  'Create a document in any collection by passing the collection slug and data.'
 
-export const createCollectionTool = defineCollectionTool({
+export const createDocumentTool = defineCollectionTool({
   description: DEFAULT_DESCRIPTION,
-  input: ({ collectionSchema }) =>
-    z.object({
-      data: z
-        .fromJSONSchema(
-          prepareCollectionSchema(collectionSchema) as unknown as z.core.JSONSchema.JSONSchema,
-        )
-        .describe('The document fields to create'),
-      depth: z
-        .number()
-        .int()
-        .min(0)
-        .max(10)
-        .describe('How many levels deep to populate relationships in response')
-        .optional()
-        .default(0),
-      draft: z
-        .boolean()
-        .describe('Whether to create the document as a draft')
-        .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 create the document in (e.g., "en", "es"). Defaults to the default locale',
-        )
-        .optional(),
-      select: z
-        .string()
-        .describe(
-          'Optional: define exactly which fields you\'d like to create (JSON), e.g., \'{"title": "My Post"}\'',
-        )
-        .optional(),
-    }),
+  input: z.object({
+    data: z.record(z.string(), z.unknown()).describe('The document fields to create'),
+    depth: z
+      .number()
+      .int()
+      .min(0)
+      .max(10)
+      .describe('How many levels deep to populate relationships in response')
+      .optional()
+      .default(0),
+    draft: z
+      .boolean()
+      .describe('Whether to create the document as a draft')
+      .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 create the document in (e.g., "en", "es"). Defaults to the default locale',
+      )
+      .optional(),
+    select: z
+      .string()
+      .describe(
+        "Optional: define exactly which fields you'd like to return (JSON), e.g., '{\"title\": true}'",
+      )
+      .optional(),
+  }),
 }).handler(async ({ authorizedMCP, collectionSlug, input, req }) => {
   const payload = req.payload
   const logger = getLogger({ payload })
@@ -64,9 +61,15 @@ export const createCollectionTool = defineCollectionTool({
   )
 
   try {
-    let parsedData = transformPointDataToPayload(data as Record<string, unknown>)
     const virtualFieldNames = getCollectionVirtualFieldNames(payload.config, collectionSlug)
-    parsedData = stripVirtualFields(parsedData, virtualFieldNames)
+    const inputData = stripVirtualFields(data, virtualFieldNames)
+    const validationError = validateCollectionData({ collectionSlug, data: inputData, req })
+
+    if (validationError) {
+      return validationError
+    }
+
+    const parsedData = transformPointDataToPayload(inputData)
 
     let selectClause: SelectType | undefined
     if (select) {
@@ -104,13 +107,6 @@ export const createCollectionTool = defineCollectionTool({
   } catch (error) {
     const errorMessage = error instanceof Error ? error.message : 'Unknown error'
     logger.error(`Error creating document in ${collectionSlug}: ${errorMessage}`)
-    return {
-      content: [
-        {
-          type: 'text',
-          text: `Error creating document in collection "${collectionSlug}": ${errorMessage}`,
-        },
-      ],
-    }
+    return formatCollectionError({ action: 'creating', collectionSlug, error, req })
   }
 })

package/src/mcp/builtin/collections/deleteTool.ts

@@ -3,10 +3,12 @@ import { z } from 'zod'
 import { defineCollectionTool } from '../../../defineTool.js'
 import { getLogger } from '../../../utils/getLogger.js'
 import { localAPIDefaults } from '../../../utils/localAPIDefaults.js'
+import { whereSchema } from '../../../utils/whereSchema.js'
 
-const DEFAULT_DESCRIPTION = 'Delete documents in a collection by ID or where clause.'
+const DEFAULT_DESCRIPTION =
+  'Delete documents in any collection by passing the collection slug and ID or where clause.'
 
-export const deleteCollectionTool = defineCollectionTool({
+export const deleteDocumentsTool = defineCollectionTool({
   description: DEFAULT_DESCRIPTION,
   input: z.object({
     id: z
@@ -31,9 +33,10 @@ export const deleteCollectionTool = defineCollectionTool({
         'Optional: locale code for the operation (e.g., "en", "es"). Defaults to the default locale',
       )
       .optional(),
-    where: z
-      .string()
-      .describe('Optional: JSON string for where clause to delete multiple documents')
+    where: whereSchema
+      .describe(
+        'Optional: where clause to delete multiple documents. Use field names with Payload operators, and/or arrays for grouping. Example: {"title":{"contains":"test"}}',
+      )
       .optional(),
   }),
 }).handler(async ({ authorizedMCP, collectionSlug, input, req }) => {
@@ -53,16 +56,6 @@ export const deleteCollectionTool = defineCollectionTool({
       }
     }
 
-    let whereClause: Record<string, unknown> = {}
-    if (where) {
-      try {
-        whereClause = JSON.parse(where) as Record<string, unknown>
-      } catch {
-        logger.warn(`Invalid where clause JSON: ${where}`)
-        return { content: [{ type: 'text', text: 'Error: Invalid JSON in where clause' }] }
-      }
-    }
-
     const deleteOptions: Record<string, unknown> = {
       collection: collectionSlug,
       depth,
@@ -75,7 +68,7 @@ export const deleteCollectionTool = defineCollectionTool({
     if (id) {
       deleteOptions.id = id
     } else {
-      deleteOptions.where = whereClause
+      deleteOptions.where = where
     }
 
     const result = await payload.delete(deleteOptions as Parameters<typeof payload.delete>[0])

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

@@ -5,11 +5,12 @@ import { z } from 'zod'
 import { defineCollectionTool } from '../../../defineTool.js'
 import { getLogger } from '../../../utils/getLogger.js'
 import { localAPIDefaults } from '../../../utils/localAPIDefaults.js'
+import { whereSchema } from '../../../utils/whereSchema.js'
 
 const DEFAULT_DESCRIPTION =
-  'Find documents in a collection by ID or where clause using Find or FindByID.'
+  'Find documents in any collection by passing the collection slug and optional ID or where clause.'
 
-export const findCollectionTool = defineCollectionTool({
+export const findDocumentsTool = defineCollectionTool({
   description: DEFAULT_DESCRIPTION,
   input: z.object({
     id: z
@@ -67,10 +68,9 @@ export const findCollectionTool = defineCollectionTool({
       .string()
       .describe('Field to sort by (e.g., "createdAt", "-updatedAt" for descending)')
       .optional(),
-    where: z
-      .string()
+    where: whereSchema
       .describe(
-        'Optional JSON string for where clause filtering (e.g., \'{"title": {"contains": "test"}}\')',
+        'Optional: where clause for filtering. Use field names with Payload operators, and/or arrays for grouping. Example: {"title":{"contains":"test"}}',
       )
       .optional(),
   }),
@@ -85,16 +85,6 @@ export const findCollectionTool = defineCollectionTool({
   )
 
   try {
-    let whereClause: Record<string, unknown> = {}
-    if (where) {
-      try {
-        whereClause = JSON.parse(where) as Record<string, unknown>
-      } catch {
-        logger.warn(`Invalid where clause JSON: ${where}`)
-        return { content: [{ type: 'text', text: 'Error: Invalid JSON in where clause' }] }
-      }
-    }
-
     let selectClause: SelectType | undefined
     if (select) {
       try {
@@ -157,8 +147,8 @@ export const findCollectionTool = defineCollectionTool({
     if (sort) {
       findOptions.sort = sort
     }
-    if (Object.keys(whereClause).length > 0) {
-      findOptions.where = whereClause as Parameters<typeof payload.find>[0]['where']
+    if (where) {
+      findOptions.where = where
     }
 
     const result = await payload.find(findOptions)