@payloadcms/plugin-mcp 4.0.0-internal.38b7f1d → 4.0.0-internal.c2b57ce

package/src/defineTool.ts

@@ -0,0 +1,44 @@
+import type { CollectionTool, GlobalTool, Prompt, Tool, ToolInputSchema } from './types.js'
+
+/**
+ * Two-stage builder: pass the schema/metadata first, then chain `.handler(fn)`. Splitting the
+ * call lets TypeScript resolve `TSchema` from `input` (call 1) before contextually typing the
+ * handler (call 2). A single-call API hit a TS limitation where property order in the literal
+ * decided whether `TSchema` was inferred or pinned to its default.
+ *
+ *     defineCollectionTool({ description, input })
+ *       .handler(({ input }) => …)   // ← input is fully typed here regardless of order
+ *
+ * Config and handler signatures are derived from `Tool` / `CollectionTool` / `GlobalTool` /
+ * `Prompt` via `Omit` + indexed access so there's no duplication with `types.ts`.
+ */
+
+export const defineTool = <
+  TSchema extends ToolInputSchema | undefined = ToolInputSchema | undefined,
+>(
+  args: Omit<Tool<TSchema>, 'handler'>,
+): { handler: (fn: Tool<TSchema>['handler']) => Tool } => ({
+  handler: (fn) => ({ ...args, handler: fn }) as unknown as Tool,
+})
+
+export const defineCollectionTool = <
+  TSchema extends ToolInputSchema | undefined = ToolInputSchema | undefined,
+>(
+  args: Omit<CollectionTool<TSchema>, 'handler'>,
+): { handler: (fn: CollectionTool<TSchema>['handler']) => CollectionTool } => ({
+  handler: (fn) => ({ ...args, handler: fn }) as unknown as CollectionTool,
+})
+
+export const defineGlobalTool = <
+  TSchema extends ToolInputSchema | undefined = ToolInputSchema | undefined,
+>(
+  args: Omit<GlobalTool<TSchema>, 'handler'>,
+): { handler: (fn: GlobalTool<TSchema>['handler']) => GlobalTool } => ({
+  handler: (fn) => ({ ...args, handler: fn }) as unknown as GlobalTool,
+})
+
+export const definePrompt = <TSchema extends ToolInputSchema = ToolInputSchema>(
+  args: Omit<Prompt<TSchema>, 'handler'>,
+): { handler: (fn: Prompt<TSchema>['handler']) => Prompt } => ({
+  handler: (fn) => ({ ...args, handler: fn }) as unknown as Prompt,
+})

package/src/endpoint/access.ts

@@ -0,0 +1,132 @@
+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.key] !== false
+        case 'globalTool':
+          return apiKeyDoc.access.globals?.[item.globalSlug]?.[item.key] !== false
+        case 'prompt':
+          return apiKeyDoc.access.prompts?.[item.key] !== false
+        case 'resource':
+          return apiKeyDoc.access.resources?.[item.key] !== false
+        case 'tool':
+          return apiKeyDoc.access.tools?.[item.key] !== 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()
+  }
+
+  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 { AuthenticationError, 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 AuthenticationError()
+  }
+
+  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,2 @@
+'use client'
+export { AccessField } from '../components/AccessField/index.client.js'

package/src/index.ts

@@ -1,113 +1,63 @@
-import { definePlugin } from 'payload'
+import { defaultUserCollection, definePlugin } from 'payload'
 
-import type { MCPAccessSettings, MCPPluginConfig } from './types.js'
+import type { AuthorizedMCP, MCPPluginConfig, SanitizedMCPPluginConfig } from './types.js'
 
-import { createAPIKeysCollection } from './collections/createApiKeysCollection.js'
-import { initializeMCPHandler } from './endpoints/mcp.js'
+import { getAPIKeysCollection } from './collection/index.js'
+import { mcpEndpoint } from './endpoint/index.js'
+import { sanitizeMCPConfig } from './mcp/sanitizeMCPConfig.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 }) => {
+    // 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 (!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,
-      })) || []
+    const pluginConfig = sanitizeMCPConfig({ config, pluginConfig: rawConfig })
 
-    // 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)
+    // 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) {
+    ;(config.collections ??= []).push(getAPIKeysCollection({ pluginConfig }))
+
+    // 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
     }
 
-    if (!config.endpoints) {
-      config.endpoints = []
+    return {
+      ...config,
+      endpoints: [
+        ...(config.endpoints ?? []),
+        // Payload prefixes /api, so the full path is /api/mcp.
+        { handler: mcpEndpoint, method: 'post', path: '/mcp' },
+      ],
     }
-
-    /**
-     * 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
   },
 })

package/src/mcp/buildMcpServer.ts

@@ -0,0 +1,224 @@
+import { McpServer, type ServerContext } from '@modelcontextprotocol/server'
+import { APIError, configToJSONSchema, type PayloadRequest } from 'payload'
+
+import type {
+  AuthorizedMCP,
+  JsonSchemaType,
+  MCPResponseOverride,
+  MCPToolResponse,
+  SanitizedMCPPluginConfig,
+} 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
+ * (`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
+  }
+
+  const configSchema = configToJSONSchema(
+    req.payload.config,
+    req.payload.db.defaultIDType,
+    req.i18n,
+    { forceInlineBlocks: true },
+  ) as JsonSchemaType
+
+  try {
+    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.definitions?.[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 'globalTool': {
+          const tool = item.tool
+          const name = wireName(item.key, item.globalSlug)
+          let inputSchema = tool.input
+          if (typeof inputSchema === 'function') {
+            const raw = configSchema.definitions?.[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 })
+          }
+          server.registerTool(
+            name,
+            {
+              description: tool.description,
+              inputSchema: inputSchema ? toStandardSchema(inputSchema) : undefined,
+            },
+            async (input: unknown, ctx: ServerContext) =>
+              finalizeToolResponse(
+                await tool.handler({
+                  authorizedMCP,
+                  globalSlug: item.globalSlug,
+                  input: (input ?? {}) as Record<string, unknown>,
+                  req,
+                  serverContext: ctx,
+                }),
+                tool.overrideResponse,
+              ),
+          )
+          logger.info(`✅ Tool: ${name} Registered.`)
+          break
+        }
+        case 'prompt': {
+          const prompt = item.prompt
+          server.registerPrompt(
+            item.key,
+            {
+              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.key,
+            // @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.key,
+            {
+              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.key} Registered.`)
+          break
+        }
+      }
+    }
+  } catch (error) {
+    throw new APIError(`Error initializing MCP handler: ${String(error)}`, 500)
+  }
+
+  return server
+}