@payloadcms/plugin-mcp 4.0.0-internal.d21c039 → 4.0.0-internal.d3909a9

package/package.json

@@ -1,17 +1,12 @@
 {
   "name": "@payloadcms/plugin-mcp",
-  "version": "4.0.0-internal.d21c039",
+  "version": "4.0.0-internal.d3909a9",
   "description": "MCP (Model Context Protocol) capabilities with Payload",
   "keywords": [
-    "plugin",
     "mcp",
-    "model context protocol"
+    "model context protocol",
+    "plugin"
   ],
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/payloadcms/payload.git",
-    "directory": "packages/plugin-mcp"
-  },
   "license": "MIT",
   "author": "Payload <dev@payloadcms.com> (https://payloadcms.com)",
   "maintainers": [
@@ -21,7 +16,22 @@
       "url": "https://payloadcms.com"
     }
   ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/payloadcms/payload.git",
+    "directory": "packages/plugin-mcp"
+  },
+  "bin": {
+    "payload-mcp": "./bin.js"
+  },
+  "files": [
+    "src",
+    "dist",
+    "bin.js"
+  ],
   "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
   "exports": {
     ".": {
       "import": "./dist/index.js",
@@ -44,26 +54,15 @@
       "default": "./dist/exports/internal.js"
     }
   },
-  "main": "./dist/index.js",
-  "types": "./dist/index.d.ts",
-  "bin": {
-    "payload-mcp": "./bin.js"
-  },
-  "files": [
-    "src",
-    "dist",
-    "bin.js"
-  ],
   "dependencies": {
-    "@modelcontextprotocol/server": "2.0.0",
-    "tsx": "4.22.4"
+    "@modelcontextprotocol/server": "2.3.1",
+    "tsx": "4.23.15"
   },
   "devDependencies": {
-    "@payloadcms/eslint-config": "3.28.0",
-    "payload": "4.0.0-internal.d21c039"
+    "payload": "4.0.0-internal.d3909a9"
   },
   "peerDependencies": {
-    "payload": "4.0.0-internal.d21c039"
+    "payload": "4.0.0-internal.d3909a9"
   },
   "//deps_notes": {
     "tsx": "Required by the `bin.js` stdio mcp. Keep the version pinned to whatever `payload` ships to avoid duplicate installs."
@@ -76,8 +75,6 @@
     "build:types": "tsc --emitDeclarationOnly --outDir dist",
     "clean": "rimraf {dist,*.tsbuildinfo}",
     "copyfiles": "copyfiles -u 1 -e \"**/*.spec.*\" \"src/**/*.{html,css,scss,ttf,woff,woff2,eot,svg,jpg,png,json}\" dist/",
-    "lint": "eslint .",
-    "lint:fix": "eslint . --fix",
     "pack:plugin": "pnpm build && pnpm pack"
   }
 }

package/src/endpoint/index.ts

@@ -3,6 +3,7 @@ import type { PayloadHandler, PayloadRequest } from 'payload'
 import {
   createMcpHandler,
   isLegacyRequest,
+  readRequestBody,
   WebStandardStreamableHTTPServerTransport,
 } from '@modelcontextprotocol/server'
 import { APIError } from 'payload'
@@ -33,14 +34,17 @@ export const mcpEndpoint: PayloadHandler = async (req) => {
   }
 
   const authorizedMCP = await getAuthorizedMCP({ overrideAccess, req })
+  const maxRequestBodySize = pluginConfig.mcp?.maxRequestBodySize
   // Payload augments the original web-standard Request in place.
   const mcpRequest = req as PayloadRequest & Request
+  const parsedBody = await parseRequestBody({ maxRequestBodySize, request: mcpRequest })
 
   // Keep the old JSON-only, stateless behavior because the SDK's 2025 fallback uses SSE.
-  if (await isLegacyRequest(mcpRequest)) {
+  if (await isLegacyRequest(mcpRequest, parsedBody, { maxRequestBodySize })) {
     const server = buildMcpServer({ authorizedMCP, pluginConfig, req })
     const transport = new WebStandardStreamableHTTPServerTransport({
       enableJsonResponse: true,
+      maxRequestBodySize,
       sessionIdGenerator: undefined, // stateless mode
     })
     transport.onerror = (err) => {
@@ -49,7 +53,7 @@ export const mcpEndpoint: PayloadHandler = async (req) => {
 
     try {
       await server.connect(transport)
-      return await transport.handleRequest(mcpRequest)
+      return await transport.handleRequest(mcpRequest, { parsedBody })
     } finally {
       await server.close().catch((err) => {
         req.payload.logger.error({ err, msg: 'Error closing MCP server' })
@@ -59,6 +63,7 @@ export const mcpEndpoint: PayloadHandler = async (req) => {
 
   const handler = createMcpHandler(() => buildMcpServer({ authorizedMCP, pluginConfig, req }), {
     legacy: 'reject',
+    maxRequestBodySize,
     // SDK subscriptions always use SSE, so disable them to keep every response JSON-only.
     maxSubscriptions: 0,
     onerror: (err) => {
@@ -68,10 +73,35 @@ export const mcpEndpoint: PayloadHandler = async (req) => {
   })
 
   try {
-    return await handler.fetch(mcpRequest)
+    return await handler.fetch(mcpRequest, { parsedBody })
   } finally {
     await handler.close().catch((err) => {
       req.payload.logger.error({ err, msg: 'Error closing modern MCP handler' })
     })
   }
 }
+
+/**
+ * Parses a POST body once so the era check and the SDK handler can share it. The SDK
+ * skips its size limit for a pre-parsed body, so this reads with the same limit. It reads
+ * a clone and returns `undefined` for any body the SDK should reject (too large, unreadable,
+ * or not JSON), leaving the original request for the SDK to read and answer.
+ */
+const parseRequestBody = async ({
+  maxRequestBodySize,
+  request,
+}: {
+  maxRequestBodySize?: number
+  request: Request
+}): Promise<unknown> => {
+  if (request.method.toUpperCase() !== 'POST') {
+    return undefined
+  }
+
+  try {
+    const body = await readRequestBody(request.clone(), maxRequestBodySize)
+    return body.tooLarge ? undefined : JSON.parse(body.text)
+  } catch {
+    return undefined
+  }
+}

package/src/index.ts

@@ -29,7 +29,7 @@ export const mcpPlugin = definePlugin<MCPPluginConfig>({
     const registered = plugins['@payloadcms/plugin-mcp']
     if (registered) {
       // @ts-expect-error
-      registered.sanitizedOptions = pluginConfig as unknown as typeof registered.options
+      registered.sanitizedOptions = pluginConfig
     }
 
     if (pluginConfig.disabled) {

package/src/mcp/buildMcpServer.ts

@@ -25,7 +25,7 @@ import { toStandardSchema } from '../utils/toStandardSchema.js'
  *
  * `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`.
+ * synthesized one built via `createPayloadRequest`.
  */
 export const buildMcpServer = ({
   authorizedMCP,
@@ -250,7 +250,7 @@ const withSlugInput = ({ input }: { input?: ToolInputSchema }): ToolInputSchema
   const slugSchema = z.string().check(z.describe(description))
 
   if (!input) {
-    return strictObject({ slug: slugSchema }) as unknown as ToolInputSchema
+    return strictObject({ slug: slugSchema })
   }
 
   if (typeof input === 'object' && input !== null && '~standard' in input) {
@@ -261,7 +261,7 @@ const withSlugInput = ({ input }: { input?: ToolInputSchema }): ToolInputSchema
       return input
     }
 
-    return addSlugToJSONSchema({ description, schema: schema as JsonSchemaType })
+    return addSlugToJSONSchema({ description, schema })
   }
 
   return addSlugToJSONSchema({ description, schema: input })

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

@@ -1,4 +1,4 @@
-import { createLocalReq, strictObject, z } from 'payload'
+import { createPayloadRequest, strictObject, z } from 'payload'
 
 import type { MCPToolResponse } from '../../../types.js'
 
@@ -53,7 +53,10 @@ export const authCollectionTool = defineCollectionTool({
     if (input.headers) {
       authHeaders = new Headers(input.headers)
     }
-    const authReq = await createLocalReq({ req: { headers: authHeaders } }, req.payload)
+    const authReq = await createPayloadRequest({
+      payload: req.payload,
+      req: { headers: authHeaders },
+    })
     const result = await req.payload.auth({ headers: authHeaders, req: authReq })
 
     if (result.user) {
@@ -232,7 +235,7 @@ export const unlockCollectionTool = defineCollectionTool({
           text: `# Account Unlocked\n\n**Collection:** ${slug}\n**Email:** ${input.email}\n**Result:** ${result ? 'Success' : 'Failed'}`,
         },
       ],
-      doc: { result } as Record<string, unknown>,
+      doc: { result },
     }
   } catch (error) {
     const errorMessage = error instanceof Error ? error.message : 'Unknown error'
@@ -267,7 +270,7 @@ export const verifyCollectionTool = defineCollectionTool({
           text: `# Email Verification Successful\n\n**Collection:** ${slug}\n**Result:** ${result ? 'Success' : 'Failed'}`,
         },
       ],
-      doc: { result } as Record<string, unknown>,
+      doc: { result },
     }
   } catch (error) {
     const errorMessage = error instanceof Error ? error.message : 'Unknown error'

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

@@ -83,9 +83,7 @@ export const createDocumentsTool = defineCollectionTool({
           select: returning ? select : { id: true },
         })
 
-        docs.push(
-          returning ? { doc: result as Record<string, unknown>, index } : { id: result.id, index },
-        )
+        docs.push(returning ? { doc: result, index } : { id: result.id, index })
       } catch (error) {
         const message = error instanceof Error ? error.message : 'Unknown error'
         const formattedError = formatEntityError({

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

@@ -48,7 +48,7 @@ export const deleteDocumentsTool = defineCollectionTool({
             text: `Document deleted successfully from collection "${slug}"!\nDeleted document:\n\`\`\`json\n${JSON.stringify(result)}\n\`\`\``,
           },
         ],
-        doc: result as Record<string, unknown>,
+        doc: result,
       }
     }
 

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

@@ -74,7 +74,7 @@ export const duplicateDocumentTool = defineCollectionTool({
           text: `Document duplicated successfully in collection "${slug}"!\nDuplicated document:\n\`\`\`json\n${JSON.stringify(result)}\n\`\`\``,
         },
       ],
-      doc: result as Record<string, unknown>,
+      doc: result,
     }
   } catch (error) {
     const errorMessage = error instanceof Error ? error.message : 'Unknown error'

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

@@ -69,7 +69,7 @@ export const findDocumentsTool = defineCollectionTool({
               text: `Document from collection "${slug}":\n${JSON.stringify(doc)}`,
             },
           ],
-          doc: doc as Record<string, unknown>,
+          doc,
         }
       } catch {
         logger.warn(`Document not found with ID: ${id} in collection: ${slug}`)

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

@@ -1,4 +1,5 @@
 import { getAccessResults, getCollectionInputSchema, getCollectionSchemaInputSchema } from 'payload'
+import { getLLMInstructions } from 'payload/internal'
 
 import { defaultAccess } from '../../../defaultAccess.js'
 import { defineCollectionTool } from '../../../defineTool.js'
@@ -16,7 +17,8 @@ export const getCollectionSchemaTool = defineCollectionTool({
     readOnlyHint: true,
     title: 'Get Collection Schema',
   },
-  description: 'Get the input schema for creating or updating documents in a collection.',
+  description:
+    'Get the input schema and LLM instructions before creating or updating documents in a collection.',
   input: getCollectionSchemaInputSchema,
 }).handler(async ({ slug, authorizedMCP, req }) => {
   const permissions = authorizedMCP.overrideAccess
@@ -64,17 +66,26 @@ export const getCollectionSchemaTool = defineCollectionTool({
       }
     : { enabled: false }
 
+  const instructions = await getLLMInstructions({
+    slug,
+    type: 'collection',
+    overrideAccess: authorizedMCP.overrideAccess,
+    req,
+  })
+
   return {
     content: [
       {
         type: 'text',
         text: `Schema for collection "${slug}":\n\`\`\`json\n${JSON.stringify(inputSchema)}\n\`\`\`\nUpload configuration:\n\`\`\`json\n${JSON.stringify(upload)}\n\`\`\``,
       },
+      ...(instructions ? [{ type: 'text' as const, text: instructions }] : []),
     ],
     structuredContent: {
       slug,
       schema: inputSchema,
       upload,
+      ...(instructions ? { instructions } : {}),
     },
   }
 })

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

@@ -47,7 +47,7 @@ export const restoreVersionTool = defineCollectionTool({
           text: `Version "${id}" restored successfully in collection "${slug}"!\nRestored document:\n\`\`\`json\n${JSON.stringify(result)}\n\`\`\``,
         },
       ],
-      doc: result as Record<string, unknown>,
+      doc: result,
     }
   } catch (error) {
     const errorMessage = error instanceof Error ? error.message : 'Unknown error'

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

@@ -103,7 +103,7 @@ export const updateDocumentTool = defineCollectionTool({
             text: `Document updated successfully in collection "${slug}"!\nResult:\n\`\`\`json\n${JSON.stringify(responseResult)}\n\`\`\``,
           },
         ],
-        doc: responseResult as Record<string, unknown>,
+        doc: responseResult,
       }
     }
 

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

@@ -9,7 +9,7 @@ export const getUploadInstructionsTool = defineCollectionTool({
     defaultAccess(args) &&
     Boolean(
       args.permissions?.collections?.[args.slug]?.create ||
-        args.permissions?.collections?.[args.slug]?.update,
+      args.permissions?.collections?.[args.slug]?.update,
     ),
   annotations: {
     destructiveHint: false,

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

@@ -54,7 +54,7 @@ export const findGlobalTool = defineGlobalTool({
           text: `Global "${slug}":\n\`\`\`json\n${JSON.stringify(result)}\n\`\`\``,
         },
       ],
-      doc: result as Record<string, unknown>,
+      doc: result,
     }
   } catch (error) {
     const errorMessage = error instanceof Error ? error.message : 'Unknown error'

package/src/mcp/builtin/globals/getGlobalSchemaTool.ts

@@ -1,4 +1,5 @@
 import { getAccessResults, getGlobalInputSchema, getGlobalSchemaInputSchema } from 'payload'
+import { getLLMInstructions } from 'payload/internal'
 
 import { defaultAccess } from '../../../defaultAccess.js'
 import { defineGlobalTool } from '../../../defineTool.js'
@@ -16,7 +17,7 @@ export const getGlobalSchemaTool = defineGlobalTool({
     readOnlyHint: true,
     title: 'Get Global Schema',
   },
-  description: 'Get the input schema for updating a global.',
+  description: 'Get the input schema and LLM instructions before updating a global.',
   input: getGlobalSchemaInputSchema,
 }).handler(async ({ slug, authorizedMCP, req }) => {
   const permissions = authorizedMCP.overrideAccess
@@ -48,16 +49,25 @@ export const getGlobalSchemaTool = defineGlobalTool({
     }
   }
 
+  const instructions = await getLLMInstructions({
+    slug,
+    type: 'global',
+    overrideAccess: authorizedMCP.overrideAccess,
+    req,
+  })
+
   return {
     content: [
       {
         type: 'text',
         text: `Schema for global "${slug}":\n\`\`\`json\n${JSON.stringify(inputSchema)}\n\`\`\``,
       },
+      ...(instructions ? [{ type: 'text' as const, text: instructions }] : []),
     ],
     structuredContent: {
       slug,
       schema: inputSchema,
+      ...(instructions ? { instructions } : {}),
     },
   }
 })

package/src/mcp/builtin/globals/updateTool.ts

@@ -82,7 +82,7 @@ export const updateGlobalTool = defineGlobalTool({
           text: `Global "${slug}" updated successfully!\n\`\`\`json\n${JSON.stringify(result)}\n\`\`\``,
         },
       ],
-      doc: result as Record<string, unknown>,
+      doc: result,
     }
   } catch (error) {
     const message = error instanceof Error ? error.message : 'Unknown error'

package/src/stdio.ts

@@ -3,7 +3,7 @@ import type { Config, Plugin, SanitizedConfig } from 'payload'
 /* eslint-disable no-console */
 import { serveStdio } from '@modelcontextprotocol/server/stdio'
 import { fileURLToPath, pathToFileURL } from 'node:url'
-import { createLocalReq, getPayload } from 'payload'
+import { createPayloadRequest, getPayload } from 'payload'
 import { findConfig, loadEnv } from 'payload/node'
 
 import type { SanitizedMCPPluginConfig } from './types.js'
@@ -91,7 +91,7 @@ export const runMcpStdio = async (): Promise<void> => {
     headers.set('Authorization', process.env.PAYLOAD_MCP_AUTHORIZATION)
   }
 
-  const req = await createLocalReq({ req: { headers } }, payload)
+  const req = await createPayloadRequest({ payload, req: { headers } })
   req.payloadAPI = 'MCP' as const
   const authorizedMCP = await getAuthorizedMCP({ overrideAccess, req })
 

package/src/types.ts

@@ -1,8 +1,9 @@
 import type {
   CallToolResult,
   ContentBlock,
+  Implementation,
   JsonSchemaType,
-  McpServer,
+  McpServerOptions,
   ResourceTemplate,
   ServerContext,
   StandardSchemaWithJSON,
@@ -279,6 +280,13 @@ export type MCPPluginConfig = {
     afterToolCall?: MCPAfterToolCallHook[]
   }
   mcp?: {
+    /**
+     * Largest HTTP request body, in bytes, that the MCP endpoint accepts. Larger requests
+     * are answered with `413`. Base64 file uploads count toward this limit.
+     *
+     * @default 4194304 (4 MiB, the MCP SDK default)
+     */
+    maxRequestBodySize?: number
     serverOptions?: MCPServerOptions
     verboseLogs?: boolean
   }
@@ -304,8 +312,8 @@ export type SanitizedMCPPluginConfig = {
 } & Pick<MCPPluginConfig, 'disabled' | 'hooks' | 'mcp' | 'overrideGetAuthorizedMCP'>
 
 export type MCPServerOptions = {
-  options?: ConstructorParameters<typeof McpServer>[1]
-  serverInfo?: Partial<ConstructorParameters<typeof McpServer>[0]>
+  options?: McpServerOptions
+  serverInfo?: Partial<Implementation>
 }
 
 /**

package/src/utils/toStandardSchema.ts

@@ -5,5 +5,5 @@ import type { ToolInputSchema } from '../types.js'
 /** Normalize a tool/prompt input to a Standard Schema. Raw JSON Schema gets wrapped; Standard Schema instances pass through. */
 export const toStandardSchema = (schema: ToolInputSchema): StandardSchemaWithJSON =>
   typeof schema === 'object' && schema !== null && '~standard' in schema
-    ? (schema as StandardSchemaWithJSON)
+    ? schema
     : fromJsonSchema(schema)