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

package/src/endpoint/access.ts

@@ -0,0 +1,144 @@
+import type { DefaultDocumentIDType, PayloadRequest, TypedUser } from 'payload'
+
+import crypto from 'crypto'
+import { UnauthorizedError } from 'payload'
+
+import type { AuthorizedMCP, MCPAPIKeysDoc } from '../types.js'
+
+import { getLogger } from '../utils/getLogger.js'
+import { getPluginConfig } from '../utils/getPluginConfig.js'
+
+/**
+ * Resolves the API key (or dev-mode session) and returns the items the caller
+ * may use. Denied items are dropped from the array.
+ */
+export const getAuthorizedMCP: (args: { req: PayloadRequest }) => Promise<AuthorizedMCP> = async ({
+  req,
+}) => {
+  const logger = getLogger({ payload: req.payload })
+  const pluginConfig = getPluginConfig({ config: req.payload.config })
+
+  const authHeader = req.headers.get('Authorization')
+  const hasBearerToken = authHeader?.startsWith('Bearer ')
+
+  const buildAuthorized = (apiKeyDoc: MCPAPIKeysDoc): AuthorizedMCP => ({
+    items: pluginConfig.items.filter((item) => {
+      switch (item.type) {
+        case 'collectionTool':
+          return apiKeyDoc.access.collections?.[item.collectionSlug]?.[item.configKey] !== false
+        case 'globalTool':
+          return apiKeyDoc.access.globals?.[item.globalSlug]?.[item.configKey] !== false
+        case 'prompt':
+          return apiKeyDoc.access.prompts?.[item.configKey] !== false
+        case 'resource':
+          return apiKeyDoc.access.resources?.[item.configKey] !== false
+        case 'tool':
+          return apiKeyDoc.access.tools?.[item.configKey] !== false
+      }
+    }),
+    overrideAccess:
+      typeof apiKeyDoc.overrideAccess === 'boolean' ? apiKeyDoc.overrideAccess : false,
+    user: apiKeyDoc.user,
+  })
+
+  if (pluginConfig.overrideAuth) {
+    return await pluginConfig.overrideAuth({
+      getAPIKeyDoc: (overrideApiKey) => getAPIKeyDoc({ logger, overrideApiKey, pluginConfig, req }),
+      getAuthorizedMCP: ({ apiKeyDoc }) => buildAuthorized(apiKeyDoc),
+      pluginConfig,
+      req,
+    })
+  }
+
+  if (process.env.NODE_ENV === 'development' && !hasBearerToken) {
+    logger.info('Dev mode: skipping API key check, using session user')
+    return buildAuthorized({
+      id: -1,
+      access: {},
+      overrideAccess: true,
+      user: req.user ?? null,
+    })
+  }
+
+  return buildAuthorized(await getAPIKeyDoc({ logger, pluginConfig, req }))
+}
+
+const getAPIKeyDoc = async ({
+  logger,
+  overrideApiKey,
+  pluginConfig,
+  req,
+}: {
+  logger: ReturnType<typeof getLogger>
+  overrideApiKey?: string
+  pluginConfig: ReturnType<typeof getPluginConfig>
+  req: PayloadRequest
+}): Promise<MCPAPIKeysDoc> => {
+  const authHeader = req.headers.get('Authorization')
+  const hasBearerToken = authHeader?.startsWith('Bearer ')
+
+  const apiKey =
+    overrideApiKey ?? (hasBearerToken ? authHeader?.replace('Bearer ', '').trim() || null : null)
+
+  if (!apiKey) {
+    throw new UnauthorizedError()
+  }
+
+  const sha256APIKeyIndex = crypto
+    .createHmac('sha256', req.payload.secret)
+    .update(apiKey)
+    .digest('hex')
+
+  const doc = await req.payload.db.findOne<MCPAPIKeysDoc>({
+    collection: 'payload-mcp-api-keys',
+    req,
+    where: {
+      apiKeyIndex: { equals: sha256APIKeyIndex },
+    },
+  })
+
+  if (!doc || !doc.user) {
+    throw new UnauthorizedError()
+  }
+
+  logger.info('API Key is valid')
+
+  const userRef = doc.user
+  const userID =
+    typeof userRef === 'object' && userRef !== null && 'id' in userRef
+      ? userRef.id
+      : (userRef as unknown as DefaultDocumentIDType)
+
+  const user = (await req.payload.findByID({
+    id: userID,
+    collection: pluginConfig.userCollection,
+    depth: 0,
+    disableErrors: true,
+    req,
+  })) as null | TypedUser
+
+  if (!user) {
+    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: {
+      ...user,
+      _strategy: 'mcp-api-key' as const,
+      collection: pluginConfig.userCollection,
+    },
+  }
+}

package/src/endpoint/index.ts

@@ -0,0 +1,35 @@
+import { WebStandardStreamableHTTPServerTransport } from '@modelcontextprotocol/server'
+import { APIError, type PayloadHandler } from 'payload'
+
+import { buildMcpServer } from '../mcp/buildMcpServer.js'
+import { getPluginConfig } from '../utils/getPluginConfig.js'
+import { getAuthorizedMCP } from './access.js'
+
+export const mcpEndpoint: PayloadHandler = async (req) => {
+  if (!req.url) {
+    throw new APIError('Missing request URL', 400)
+  }
+
+  req.payloadAPI = 'MCP' as const
+
+  const pluginConfig = getPluginConfig({ config: req.payload.config })
+  const authorizedMCP = await getAuthorizedMCP({ req })
+
+  const server = buildMcpServer({ authorizedMCP, pluginConfig, req })
+
+  const transport = new WebStandardStreamableHTTPServerTransport({
+    enableJsonResponse: true,
+    sessionIdGenerator: undefined, // stateless mode
+  })
+
+  await server.connect(transport)
+
+  const mcpRequest = new Request(req.url, {
+    body: req.body,
+    duplex: 'half',
+    headers: req.headers,
+    method: req.method,
+  } as { duplex: 'half' } & RequestInit)
+
+  return await transport.handleRequest(mcpRequest)
+}

package/src/exports/client.ts

@@ -0,0 +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,113 +1,109 @@
-import { definePlugin } from 'payload'
+import type { AcceptedLanguages } from '@payloadcms/translations'
 
-import type { MCPAccessSettings, MCPPluginConfig } from './types.js'
+import { defaultUserCollection, definePlugin } from 'payload'
 
-import { createAPIKeysCollection } from './collections/createApiKeysCollection.js'
-import { initializeMCPHandler } from './endpoints/mcp.js'
+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 {
     payloadAPI: 'GraphQL' | 'local' | 'MCP' | 'REST'
   }
   interface RegisteredPlugins {
+    /** After the plugin's `plugin` callback runs, `options` holds the sanitized config. */
     '@payloadcms/plugin-mcp': MCPPluginConfig
   }
 }
 
-import { defaults } from './defaults.js'
+export type { AuthorizedMCP, MCPPluginConfig, SanitizedMCPPluginConfig }
 
-export type { MCPAccessSettings, MCPPluginConfig }
+export { defineCollectionTool, defineGlobalTool, definePrompt, defineTool } from './defineTool.js'
 
-/**
- * The MCP Plugin for Payload. This plugin allows you to add MCP capabilities to your Payload project.
- *
- * @param pluginOptions - The options for the MCP plugin.
- */
 export const mcpPlugin = definePlugin<MCPPluginConfig>({
   slug: '@payloadcms/plugin-mcp',
   order: 10,
-  plugin: ({ config, plugins: _plugins, ...pluginOptions }) => {
-    if (!config.collections) {
-      config.collections = []
+  plugin: ({ config, plugins, ...rawConfig }) => {
+    // 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) {
+        ;(config.collections ??= []).push(defaultUserCollection)
+      }
     }
 
-    // Collections
-    const collections = pluginOptions.collections || {}
-    // Globals
-    const globals = pluginOptions.globals || {}
-    // Extract custom tools for the global config
-    const customTools =
-      pluginOptions.mcp?.tools?.map((tool) => ({
-        name: tool.name,
-        description: tool.description,
-      })) || []
-
-    // User Collection
-    pluginOptions.userCollection =
-      pluginOptions.userCollection ?? config?.admin?.user ?? defaults.userCollection
-
-    const experimentalTools = pluginOptions?.experimental?.tools || {}
-
-    /**
-     * API Keys
-     * --------
-     * High resolution control over MCP capabilities is crucial when using Payload with LLMs.
-     *
-     * This API Keys collection has ways for admins to create API keys and allow or disallow the MCP capabilities.
-     * This is useful when Admins want to allow or disallow the use of the MCP capabilities in real time.
-     * For example:
-     *  - If a collection has all of its capabilities enabled, admins can allow or disallow the create, update, delete, and find capabilities on that collection.
-     *  - If a collection only has the find capability enabled, admins can only allow or disallow the find capability on that collection.
-     *  - If a global has all of its capabilities enabled, admins can allow or disallow the find and update capabilities on that global.
-     *  - If a custom tool has gone haywire, admins can disallow that tool.
-     *
-     */
-    const apiKeyCollection = createAPIKeysCollection(
-      collections,
-      globals,
-      customTools,
-      experimentalTools,
-      pluginOptions,
-    )
-    if (pluginOptions.overrideApiKeyCollection) {
-      config.collections.push(pluginOptions.overrideApiKeyCollection(apiKeyCollection))
-    } else {
-      config.collections.push(apiKeyCollection)
+    const pluginConfig = sanitizeMCPConfig({ config, pluginConfig: rawConfig })
+
+    // Stash the sanitized config on plugin options so `getPluginConfig()` reads it.
+    const registered = plugins['@payloadcms/plugin-mcp']
+    if (registered) {
+      // @ts-expect-error
+      registered.sanitizedOptions = pluginConfig as unknown as typeof registered.options
     }
 
-    /**
-     * If the plugin is disabled, we still want to keep added collections/fields so the database schema is consistent which is important for migrations.
-     * If your plugin heavily modifies the database schema, you may want to remove this property.
-     */
-    if (pluginOptions.disabled) {
-      return config
+    ;(config.collections ??= []).push(getAPIKeysCollection({ pluginConfig }))
+
+    if (!config.i18n) {
+      config.i18n = {}
+    }
+
+    if (!config.i18n.translations) {
+      config.i18n.translations = {}
     }
 
-    if (!config.endpoints) {
-      config.endpoints = []
+    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) {
+      return config
     }
 
-    /**
-     * This is the primary MCP Server Endpoint.
-     * Payload will automatically add the /api prefix to the path, so the full path is `/api/mcp`
-     * NOTE: This is only transport method until we add full support for SSE which will be another endpoint at `/api/sse`
-     */
-    config.endpoints.push({
-      handler: initializeMCPHandler(pluginOptions),
-      method: 'post',
-      path: '/mcp',
-    })
-
-    /**
-     * The GET response is always: {"jsonrpc":"2.0","error":{"code":-32000,"message":"Method not allowed."},"id":null} -- even with an API key
-     * This is expected behavior and MCP clients should always use the POST endpoint.
-     */
-    config.endpoints.push({
-      handler: initializeMCPHandler(pluginOptions),
-      method: 'get',
-      path: '/mcp',
-    })
-
-    return config
+    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

@@ -0,0 +1,257 @@
+import { McpServer, type ServerContext } from '@modelcontextprotocol/server'
+import { APIError, type PayloadRequest } from 'payload'
+import { z } from 'zod'
+
+import type {
+  AuthorizedMCP,
+  CollectionMCPItem,
+  GlobalMCPItem,
+  JsonSchemaType,
+  MCPResponseOverride,
+  MCPToolResponse,
+  SanitizedMCPPluginConfig,
+  ToolInputSchema,
+} from '../types.js'
+
+import { getLogger } from '../utils/getLogger.js'
+import { toStandardSchema } from '../utils/toStandardSchema.js'
+
+/**
+ * Transport-agnostic core: registers every authorized MCP item onto a fresh
+ * `McpServer` and returns it. The caller is responsible for picking a transport
+ * (`WebStandardStreamableHTTPServerTransport`, `StdioServerTransport`, …) and
+ * calling `server.connect(transport)`.
+ *
+ * `req` is the request context handlers see. For HTTP it's the live
+ * `PayloadRequest` derived from the incoming HTTP request; for stdio it's a
+ * synthesized one built via `createLocalReq`.
+ */
+export const buildMcpServer = ({
+  authorizedMCP,
+  pluginConfig,
+  req,
+}: {
+  authorizedMCP: AuthorizedMCP
+  pluginConfig: SanitizedMCPPluginConfig
+  req: PayloadRequest
+}): McpServer => {
+  const serverOptions = pluginConfig.mcp?.serverOptions || {}
+  const server = new McpServer(
+    { name: 'Payload MCP Server', version: '1.0.0', ...serverOptions.serverInfo },
+    serverOptions.options,
+  )
+
+  const logger = getLogger({ payload: req.payload })
+
+  /**
+   * Wrap a tool handler's response with the tool's `overrideResponse`, then
+   * strip the internal `doc` field so it doesn't leak onto the wire.
+   */
+  const finalizeToolResponse = (
+    response: MCPToolResponse,
+    overrideResponse?: MCPResponseOverride,
+  ): MCPToolResponse => {
+    const overridden = overrideResponse?.(response, response.doc ?? {}, req) ?? response
+    const { doc: _doc, ...rest } = overridden
+    return rest
+  }
+
+  /**
+   * 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':
+        case 'globalTool': {
+          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(
+            item.mcpName,
+            {
+              description: item.tool.description,
+              inputSchema: toStandardSchema(inputSchema),
+            },
+            async (input: unknown, ctx: ServerContext) =>
+              callEntityTool({ input, item, serverContext: ctx }),
+          )
+          logger.info(`✅ Tool: ${item.mcpName} Registered.`)
+          break
+        }
+        case 'prompt': {
+          const prompt = item.prompt
+          server.registerPrompt(
+            item.mcpName,
+            {
+              argsSchema: prompt.argsSchema ? toStandardSchema(prompt.argsSchema) : undefined,
+              description: prompt.description,
+              title: prompt.title,
+            },
+            async (input: unknown, ctx: ServerContext) =>
+              prompt.handler({
+                input: (input ?? {}) as Record<string, unknown>,
+                req,
+                serverContext: ctx,
+              }),
+          )
+          logger.info(`✅ Prompt: ${prompt.title} Registered.`)
+          break
+        }
+        case 'resource': {
+          const resource = item.resource
+          server.registerResource(
+            item.mcpName,
+            // @ts-expect-error - Overload type ambiguity (string OR ResourceTemplate is valid)
+            resource.uri,
+            {
+              description: resource.description,
+              mimeType: resource.mimeType,
+              title: resource.title,
+            },
+            // Static URIs call (uri, ctx); ResourceTemplates call (uri, params, ctx).
+            // The rest-params shape lets us collect either signature uniformly.
+            async (...sdkArgs: unknown[]) => {
+              const ctx = sdkArgs[sdkArgs.length - 1] as ServerContext
+              const uri = sdkArgs[0] as URL
+              const params = (sdkArgs.length > 2 ? sdkArgs[1] : {}) as Record<string, string>
+              return resource.handler({ params, req, serverContext: ctx, uri })
+            },
+          )
+          logger.info(`✅ Resource: ${resource.title} Registered.`)
+          break
+        }
+        case 'tool': {
+          const tool = item.tool
+          server.registerTool(
+            item.mcpName,
+            {
+              description: tool.description,
+              inputSchema: tool.input ? toStandardSchema(tool.input) : undefined,
+            },
+            async (input: unknown, ctx: ServerContext) =>
+              finalizeToolResponse(
+                await tool.handler({
+                  authorizedMCP,
+                  input: (input ?? {}) as Record<string, unknown>,
+                  req,
+                  serverContext: ctx,
+                }),
+                tool.overrideResponse,
+              ),
+          )
+          logger.info(`✅ Tool: ${item.mcpName} Registered.`)
+          break
+        }
+      }
+    }
+  } catch (error) {
+    throw new APIError(`Error initializing MCP handler: ${String(error)}`, 500)
+  }
+
+  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 ?? [])])),
+  }
+}