@payloadcms/plugin-mcp 4.0.0-internal.d28e9fb → 4.0.0-internal.d927017

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.d28e9fb",
+  "version": "4.0.0-internal.d927017",
   "description": "MCP (Model Context Protocol) capabilities with Payload",
   "keywords": [
     "plugin",
@@ -21,34 +21,67 @@
       "url": "https://payloadcms.com"
     }
   ],
-  "sideEffects": false,
   "type": "module",
   "exports": {
     ".": {
       "import": "./dist/index.js",
       "types": "./dist/index.d.ts",
       "default": "./dist/index.js"
+    },
+    "./bin": {
+      "import": "./dist/bin/index.js",
+      "types": "./dist/bin/index.d.ts",
+      "default": "./dist/bin/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": {
+    "vite": "~8.1.4",
     "@payloadcms/eslint-config": "3.28.0",
-    "payload": "4.0.0-internal.d28e9fb"
+    "payload": "4.0.0-internal.d927017"
   },
   "peerDependencies": {
-    "payload": "4.0.0-internal.d28e9fb"
+    "vite": "~8.1.4",
+    "payload": "4.0.0-internal.d927017"
+  },
+  "peerDependenciesMeta": {
+    "vite": {
+      "optional": true
+    }
+  },
+  "//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.",
+    "vite": "Vite is an optional peer used by stdio development HMR and duplicated in devDependencies for this package's build and tests. Keep the Vite minor pinned while its server module runner API is experimental."
   },
   "homepage:": "https://payloadcms.com",
   "scripts": {

package/src/bin/index.ts

@@ -0,0 +1,16 @@
+import { runMcpStdio } from '../stdio.js'
+
+export const bin = async (): Promise<void> => {
+  let viteHMR
+  if (
+    process.env.NODE_ENV !== 'production' &&
+    process.env.NODE_ENV !== 'test' &&
+    process.env.DISABLE_PAYLOAD_HMR !== 'true'
+  ) {
+    const { initializeViteHMR } = await import('./initializeViteHMR.js')
+    viteHMR = await initializeViteHMR()
+  }
+
+  await runMcpStdio(viteHMR?.config)
+  await viteHMR?.connect()
+}

package/src/bin/initializeViteHMR.ts

@@ -0,0 +1,60 @@
+import type { SanitizedConfig } from 'payload'
+
+/* eslint-disable no-console */
+import { fileURLToPath } from 'node:url'
+import { getPayload, reload } from 'payload'
+import { findConfig } from 'payload/node'
+import { createServer, createServerModuleRunner, normalizePath } from 'vite'
+
+import type * as ConfigBoundary from './viteConfigBoundary.js'
+
+import { resolveProjectRoot } from '../utils/resolveProjectRoot.js'
+
+type ViteHMR = {
+  config: SanitizedConfig
+  connect: () => Promise<void>
+}
+
+export const initializeViteHMR = async (): Promise<ViteHMR> => {
+  const projectRoot = resolveProjectRoot(fileURLToPath(import.meta.url))
+  if (projectRoot) {
+    process.chdir(projectRoot)
+  }
+
+  const vite = await createServer({
+    clearScreen: false,
+    configFile: false,
+    envDir: false,
+    logLevel: 'error',
+    optimizeDeps: { noDiscovery: true },
+    publicDir: false,
+    resolve: { alias: { 'payload-mcp:config': normalizePath(findConfig()) }, tsconfigPaths: true },
+    server: { middlewareMode: true, ws: false },
+    ssr: { noExternal: [/^@payloadcms\//, /^payload$/] },
+  })
+  const runner = createServerModuleRunner(vite.environments.ssr)
+  const boundaryPath = fileURLToPath(new URL('./viteConfigBoundary.js', import.meta.url))
+  const boundary = await runner.import<typeof ConfigBoundary>(boundaryPath)
+  const config = boundary.getConfig()
+
+  return {
+    config,
+    connect: async () => {
+      const payload = await getPayload({ config, cron: false, disableOnInit: true })
+      let payloadReloadQueue = Promise.resolve()
+      const reloadPayload = (nextConfig: SanitizedConfig): Promise<void> => {
+        payloadReloadQueue = payloadReloadQueue
+          .then(() => reload(nextConfig, payload, false))
+          .catch((error) => console.error('[payload-mcp] config reload failed:', error))
+        return payloadReloadQueue
+      }
+
+      boundary.subscribe(reloadPayload)
+
+      const latestConfig = boundary.getConfig()
+      if (config !== latestConfig) {
+        await reloadPayload(latestConfig)
+      }
+    },
+  }
+}

package/src/bin/viteConfigBoundary.ts

@@ -0,0 +1,39 @@
+/// <reference types="vite/client" />
+
+import type { SanitizedConfig } from 'payload'
+
+/* eslint-disable no-console */
+// @ts-expect-error - The Vite initializer resolves this ID to the Payload config.
+import * as configModule from 'payload-mcp:config'
+
+type ConfigListener = (config: SanitizedConfig) => Promise<void> | void
+
+let listener: ConfigListener | undefined
+let configQueue = Promise.resolve()
+
+const resolveConfig = async (module: unknown): Promise<SanitizedConfig> => {
+  const config = module as { default?: unknown }
+
+  return (await (config.default ?? module)) as SanitizedConfig
+}
+
+let config = await resolveConfig(configModule)
+
+export const getConfig = (): SanitizedConfig => config
+
+export const subscribe = (nextListener: ConfigListener): void => {
+  listener = nextListener
+}
+
+import.meta.hot?.accept('payload-mcp:config', (nextModule) => {
+  if (!nextModule) {
+    return
+  }
+
+  configQueue = configQueue
+    .then(async () => {
+      config = await resolveConfig(nextModule)
+      await listener?.(config)
+    })
+    .catch((error) => console.error('[payload-mcp] config reload failed:', error))
+})

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