@payloadcms/plugin-mcp 4.0.0-internal.e16cf59 → 4.0.0-internal.e55ccef

package/dist/utils/whereSchema.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/utils/whereSchema.ts"],"sourcesContent":["import type { Where } from 'payload'\n\nimport { validOperators } from 'payload/shared'\nimport { z } from 'zod'\n\nconst whereFieldSchema = z\n  .partialRecord(z.enum(validOperators), z.unknown())\n  .describe('Field query operators')\n\n/**\n * - Validates the `where` input of collection tools against Payload's `Where` shape\n * - Field keys map to operator objects restricted to `validOperators`\n * - `and` / `or` nest recursively\n */\nexport const whereSchema: z.ZodType<Where> = z\n  .lazy(() =>\n    z\n      .object({\n        and: z.array(whereSchema).optional(),\n        or: z.array(whereSchema).optional(),\n      })\n      .catchall(whereFieldSchema),\n  )\n  .describe('Where clause using field names with Payload query operators, plus and/or groups')\n"],"names":["validOperators","z","whereFieldSchema","partialRecord","enum","unknown","describe","whereSchema","lazy","object","and","array","optional","or","catchall"],"mappings":"AAEA,SAASA,cAAc,QAAQ,iBAAgB;AAC/C,SAASC,CAAC,QAAQ,MAAK;AAEvB,MAAMC,mBAAmBD,EACtBE,aAAa,CAACF,EAAEG,IAAI,CAACJ,iBAAiBC,EAAEI,OAAO,IAC/CC,QAAQ,CAAC;AAEZ;;;;CAIC,GACD,OAAO,MAAMC,cAAgCN,EAC1CO,IAAI,CAAC,IACJP,EACGQ,MAAM,CAAC;QACNC,KAAKT,EAAEU,KAAK,CAACJ,aAAaK,QAAQ;QAClCC,IAAIZ,EAAEU,KAAK,CAACJ,aAAaK,QAAQ;IACnC,GACCE,QAAQ,CAACZ,mBAEbI,QAAQ,CAAC,mFAAkF"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@payloadcms/plugin-mcp",
-  "version": "4.0.0-internal.e16cf59",
+  "version": "4.0.0-internal.e55ccef",
   "description": "MCP (Model Context Protocol) capabilities with Payload",
   "keywords": [
     "plugin",
@@ -21,34 +21,54 @@
       "url": "https://payloadcms.com"
     }
   ],
-  "sideEffects": false,
   "type": "module",
   "exports": {
     ".": {
       "import": "./dist/index.js",
       "types": "./dist/index.d.ts",
       "default": "./dist/index.js"
+    },
+    "./client": {
+      "import": "./dist/exports/client.js",
+      "types": "./dist/exports/client.d.ts",
+      "default": "./dist/exports/client.js"
+    },
+    "./stdio": {
+      "import": "./dist/stdio.js",
+      "types": "./dist/stdio.d.ts",
+      "default": "./dist/stdio.js"
+    },
+    "./internal": {
+      "import": "./dist/exports/internal.js",
+      "types": "./dist/exports/internal.d.ts",
+      "default": "./dist/exports/internal.js"
     }
   },
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
+  "bin": {
+    "payload-mcp": "./bin.js"
+  },
   "files": [
     "src",
-    "dist"
+    "dist",
+    "bin.js"
   ],
   "dependencies": {
-    "@modelcontextprotocol/sdk": "1.27.1",
-    "@types/json-schema": "7.0.15",
-    "json-schema-to-zod": "2.6.1",
-    "mcp-handler": "^1.0.7",
-    "zod": "^3.25.50"
+    "@modelcontextprotocol/server": "2.0.0-beta.3",
+    "tsx": "4.22.4",
+    "zod": "^4.2.0"
   },
   "devDependencies": {
     "@payloadcms/eslint-config": "3.28.0",
-    "payload": "4.0.0-internal.e16cf59"
+    "payload": "4.0.0-internal.e55ccef"
   },
   "peerDependencies": {
-    "payload": "4.0.0-internal.e16cf59"
+    "payload": "4.0.0-internal.e55ccef"
+  },
+  "//deps_notes": {
+    "zod": "zod is a hard dependency of @modelcontextprotocol/server, thus we can safely use it without it impacting bundle size. Make extra sure the zod version here matches exactly what's defined in the dependencies of @modelcontextprotocol/server to avoid duplicate versions being installed.",
+    "tsx": "Required by the `bin.js` stdio mcp. Keep the version pinned to whatever `payload` ships to avoid duplicate installs."
   },
   "homepage:": "https://payloadcms.com",
   "scripts": {

package/src/defaultAccess.ts

@@ -0,0 +1,3 @@
+import type { MCPAccessArgs } from './types.js'
+
+export const defaultAccess = ({ req }: MCPAccessArgs): boolean => Boolean(req.user)

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,112 @@
+import type { PayloadRequest, SanitizedPermissions } from 'payload'
+
+import { getAccessResults, UnauthorizedError } from 'payload'
+
+import type { AuthorizedMCP, MCPItem } from '../types.js'
+
+import { getPluginConfig } from '../utils/getPluginConfig.js'
+
+export type GetAuthorizedMCPArgs = {
+  overrideAccess: boolean
+  req: PayloadRequest
+}
+
+/**
+ * Authenticates an MCP request and removes items the user cannot access.
+ * `overrideAccess` skips Payload and MCP item access checks.
+ */
+export const getAuthorizedMCP: (args: GetAuthorizedMCPArgs) => Promise<AuthorizedMCP> = async ({
+  overrideAccess,
+  req,
+}) => {
+  const pluginConfig = getPluginConfig({ config: req.payload.config })
+
+  if (pluginConfig.overrideGetAuthorizedMCP) {
+    return await pluginConfig.overrideGetAuthorizedMCP({
+      overrideAccess,
+      pluginConfig,
+      req,
+    })
+  }
+
+  if (req.headers) {
+    const headers = new Headers(req.headers)
+    const hasAuthorization = headers.has('Authorization')
+
+    headers.set('DisableAutologin', 'true')
+    req.user = (await req.payload.auth({ headers, req })).user
+
+    if (hasAuthorization && !req.user) {
+      throw new UnauthorizedError(req.t)
+    }
+  }
+
+  return {
+    items: await filterMCPItems({
+      items: pluginConfig.items,
+      overrideAccess,
+      req,
+    }),
+    overrideAccess,
+  }
+}
+
+export const filterMCPItems = async ({
+  items,
+  overrideAccess,
+  req,
+}: {
+  items: MCPItem[]
+  overrideAccess: boolean
+  req: PayloadRequest
+}): Promise<MCPItem[]> => {
+  // Match Payload core: overrideAccess bypasses access evaluation
+  if (overrideAccess) {
+    return items
+  }
+
+  const authorizedItems: MCPItem[] = []
+
+  const permissions = await getAccessResults({ req })
+
+  for (const item of items) {
+    if (!(await checkItemAccess({ item, permissions, req }))) {
+      continue
+    }
+    authorizedItems.push(item)
+  }
+
+  return authorizedItems
+}
+
+/**
+ * Runs MCP item access callbacks
+ */
+const checkItemAccess = async ({
+  item,
+  permissions,
+  req,
+}: {
+  item: MCPItem
+  permissions?: SanitizedPermissions
+  req: PayloadRequest
+}): Promise<boolean> => {
+  switch (item.type) {
+    case 'collectionTool':
+      return (
+        !item.tool.access ||
+        (await item.tool.access({ collectionSlug: item.collectionSlug, permissions, req }))
+      )
+    case 'globalTool':
+      return (
+        !item.tool.access ||
+        (await item.tool.access({ globalSlug: item.globalSlug, permissions, req }))
+      )
+    case 'prompt':
+      return !item.prompt.access || (await item.prompt.access({ permissions, req }))
+    case 'resource':
+      return !item.resource.access || (await item.resource.access({ permissions, req }))
+    case 'tool':
+      return !item.tool.access || (await item.tool.access({ permissions, req }))
+  }
+}

package/src/endpoint/index.ts

@@ -0,0 +1,77 @@
+import type { PayloadHandler, PayloadRequest } from 'payload'
+
+import {
+  createMcpHandler,
+  isLegacyRequest,
+  WebStandardStreamableHTTPServerTransport,
+} from '@modelcontextprotocol/server'
+import { APIError } 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 overrideAccessParam = new URL(req.url).searchParams.get('overrideAccess')
+
+  if (overrideAccessParam !== null && process.env.NODE_ENV !== 'development') {
+    throw new APIError('MCP overrideAccess is only available in development.', 400)
+  }
+
+  let overrideAccess = false
+  if (overrideAccessParam === 'true') {
+    overrideAccess = true
+  } else if (overrideAccessParam !== null && overrideAccessParam !== 'false') {
+    throw new APIError('MCP overrideAccess must be "true" or "false".', 400)
+  }
+
+  const authorizedMCP = await getAuthorizedMCP({ overrideAccess, req })
+  // Payload augments the original web-standard Request in place.
+  const mcpRequest = req as PayloadRequest & Request
+
+  // Keep the old JSON-only, stateless behavior because the SDK's 2025 fallback uses SSE.
+  if (await isLegacyRequest(mcpRequest)) {
+    const server = buildMcpServer({ authorizedMCP, pluginConfig, req })
+    const transport = new WebStandardStreamableHTTPServerTransport({
+      enableJsonResponse: true,
+      sessionIdGenerator: undefined, // stateless mode
+    })
+    transport.onerror = (err) => {
+      req.payload.logger.error({ err, msg: 'Error serving legacy MCP request' })
+    }
+
+    try {
+      await server.connect(transport)
+      return await transport.handleRequest(mcpRequest)
+    } finally {
+      await server.close().catch((err) => {
+        req.payload.logger.error({ err, msg: 'Error closing MCP server' })
+      })
+    }
+  }
+
+  const handler = createMcpHandler(() => buildMcpServer({ authorizedMCP, pluginConfig, req }), {
+    legacy: 'reject',
+    // SDK subscriptions always use SSE, so disable them to keep every response JSON-only.
+    maxSubscriptions: 0,
+    onerror: (err) => {
+      req.payload.logger.error({ err, msg: 'Error serving modern MCP request' })
+    },
+    responseMode: 'json',
+  })
+
+  try {
+    return await handler.fetch(mcpRequest)
+  } finally {
+    await handler.close().catch((err) => {
+      req.payload.logger.error({ err, msg: 'Error closing modern MCP handler' })
+    })
+  }
+}

package/src/exports/client.ts

@@ -0,0 +1,3 @@
+'use client'
+
+export {}

package/src/exports/internal.ts

@@ -0,0 +1 @@
+export { filterMCPItems, getAuthorizedMCP } from '../endpoint/access.js'

package/src/index.ts

@@ -1,113 +1,55 @@
 import { 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 { mcpEndpoint } from './endpoint/index.js'
+import { sanitizeMCPConfig } from './mcp/sanitizeMCPConfig.js'
 
 declare module 'payload' {
-  export interface PayloadRequest {
-    payloadAPI: 'GraphQL' | 'local' | 'MCP' | 'REST'
+  export interface PayloadRequestAPI {
+    MCP: true
   }
   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, options, plugins }) => {
+    const pluginConfig = sanitizeMCPConfig({ config, pluginConfig: options })
+
+    // 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
     }
 
-    // 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)
-    }
-
-    /**
-     * 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) {
+    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' },
+        // 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',
+        },
+      ],
     }
-
-    /**
-     * 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
   },
 })