@payloadcms/plugin-mcp 4.0.0-canary.13 → 4.0.0-canary.14

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

@@ -1,7 +1,7 @@
 import type { CollectionSlug, File, FileData, PayloadRequest } from 'payload'
 
 import { APIError } from 'payload'
-import { getExternalFile, isURLAllowed } from 'payload/internal'
+import { getExternalFile, getFileFromUploadInstructions, isURLAllowed } from 'payload/internal'
 import { sanitizeFilename } from 'payload/shared'
 import { z } from 'zod'
 
@@ -9,6 +9,13 @@ const mimeTypeSchema = z
   .string()
   .regex(/^[!#$%&'*+.^`|~\w-]+\/[!#$%&'*+.^`|~\w-]+$/, 'MIME type must use the type/subtype format')
 
+const uploadFileSchema = z.object({
+  filename: z.string(),
+  mimeType: z.string(),
+  size: z.number().int().nonnegative(),
+  uploadReference: z.record(z.string(), z.unknown()),
+})
+
 export const fileInputSchema = z
   .discriminatedUnion('source', [
     z.object({
@@ -19,17 +26,21 @@ export const fileInputSchema = z
     }),
     z.object({
       name: z.string().min(1).describe('Optional file name override').optional(),
-      source: z.literal('url'),
+      source: z.literal('externalURL'),
       url: z.url().describe('The http or https URL to download'),
     }),
+    z.object({
+      file: uploadFileSchema.describe('getUploadInstructions file field post-upload'),
+      source: z.literal('uploadReference'),
+    }),
   ])
   .describe(
-    'A file for an upload collection. Use only a source listed by getCollectionSchema: url for an online file or base64 for a local file.',
+    'A file for an upload collection. Prefer uploadReference after its upload succeeds; use base64 only for small local files or externalURL for an online file.',
   )
 
 type FileInput = z.infer<typeof fileInputSchema>
 
-export async function resolveFileInput({
+export async function resolveFile({
   collectionSlug,
   input,
   req,
@@ -42,6 +53,20 @@ export async function resolveFileInput({
     return undefined
   }
 
+  if (input.source === 'uploadReference') {
+    try {
+      return await getFileFromUploadInstructions({ collectionSlug, file: input.file, req })
+    } catch (error) {
+      if (error instanceof Error && error.message === 'Staged upload was not found.') {
+        throw new APIError(
+          'Staged upload not found. Complete the upload action first, or use base64 for small local files.',
+          400,
+        )
+      }
+      throw error
+    }
+  }
+
   const uploadConfig = req.payload.collections[collectionSlug]?.config.upload
 
   if (!uploadConfig) {

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

@@ -55,7 +55,11 @@ export const getCollectionSchemaTool = defineCollectionTool({
         enabled: true,
         filesRequiredOnCreate: uploadConfig.filesRequiredOnCreate !== false,
         mimeTypes: uploadConfig.mimeTypes ?? ['*/*'],
-        sources: [...(uploadConfig.pasteURL !== false ? ['url'] : []), 'base64'],
+        sources: [
+          ...(uploadConfig.pasteURL !== false ? ['externalURL'] : []),
+          'base64',
+          'uploadReference',
+        ],
         ...(typeof maxFileSize === 'number' && Number.isFinite(maxFileSize) ? { maxFileSize } : {}),
       }
     : { enabled: false }

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

@@ -13,11 +13,11 @@ import { getCollectionInputSchema } from '../../../utils/schemaConversion/getEnt
 import { transformPointDataToPayload } from '../../../utils/transformPointDataToPayload.js'
 import { whereSchema } from '../../../utils/whereSchema.js'
 import { validateCollectionData } from '../validateEntityData.js'
-import { fileInputSchema, resolveFileInput } from './fileInput.js'
+import { fileInputSchema, resolveFile } from './fileInput.js'
 import { formatCollectionError } from './formatCollectionError.js'
 
 const DEFAULT_DESCRIPTION =
-  'Update documents in any collection by passing the collection slug and data.'
+  'Update documents. Prefer uploadReference after upload, externalURL for URLs, or base64 for small local files.'
 
 export const updateDocumentTool = defineCollectionTool({
   access: (args) =>
@@ -132,7 +132,7 @@ export const updateDocumentTool = defineCollectionTool({
     }
 
     const parsedData = transformPointDataToPayload(inputData)
-    const file = await resolveFileInput({ collectionSlug, input: fileInput, req })
+    const file = await resolveFile({ collectionSlug, input: fileInput, req })
 
     const whereClause: Where = where ?? {}
 

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

@@ -0,0 +1,64 @@
+import { getUploadInstructions as getPayloadUploadInstructions } from 'payload/internal'
+import { z } from 'zod'
+
+import { defaultAccess } from '../../../defaultAccess.js'
+import { defineCollectionTool } from '../../../defineTool.js'
+
+export const getUploadInstructionsTool = defineCollectionTool({
+  access: (args) =>
+    defaultAccess(args) &&
+    Boolean(
+      args.permissions?.collections?.[args.collectionSlug]?.create ||
+        args.permissions?.collections?.[args.collectionSlug]?.update,
+    ),
+  annotations: {
+    destructiveHint: false,
+    idempotentHint: false,
+    openWorldHint: true,
+    readOnlyHint: false,
+    title: 'Get Upload Instructions',
+  },
+  description:
+    'Prepare uploads for createDocuments or updateDocument. This does not upload bytes; finish the returned action before use.',
+  input: z.object({
+    docPrefix: z.string().describe('Optional document folder or prefix').optional(),
+    filename: z.string().describe('The original file name'),
+    filesize: z.number().int().nonnegative().describe('The file size in bytes'),
+    mimeType: z.string().describe('The file MIME type'),
+  }),
+}).handler(async ({ authorizedMCP, collectionSlug, input, req }) => {
+  try {
+    const instructions = await getPayloadUploadInstructions({
+      ...input,
+      collectionSlug,
+      overrideAccess: authorizedMCP.overrideAccess,
+      req,
+    })
+
+    const nextStep =
+      instructions.type === 'http'
+        ? 'Upload bytes with instructions.request. After success, pass { source: "uploadReference", file: instructions.file }.'
+        : `Call "${instructions.name}" with file and data. After success, pass { source: "uploadReference", file: instructions.file }.`
+
+    return {
+      content: [
+        {
+          type: 'text',
+          text: `Upload instructions for collection "${collectionSlug}":\n\`\`\`json\n${JSON.stringify(instructions)}\n\`\`\`\n${nextStep}`,
+        },
+      ],
+      structuredContent: { instructions },
+    }
+  } catch (error) {
+    const message = error instanceof Error ? error.message : 'Unknown error'
+    return {
+      content: [
+        {
+          type: 'text',
+          text: `Error getting upload instructions for collection "${collectionSlug}": ${message}`,
+        },
+      ],
+      isError: true,
+    }
+  }
+})

package/src/mcp/builtinTools.ts

@@ -10,7 +10,7 @@ import {
 } from './builtin/collections/authTools.js'
 import { countDocumentsTool } from './builtin/collections/countTool.js'
 import { countVersionsTool } from './builtin/collections/countVersionsTool.js'
-import { createDocumentTool } from './builtin/collections/createTool.js'
+import { createDocumentsTool } from './builtin/collections/createTool.js'
 import { deleteDocumentsTool } from './builtin/collections/deleteTool.js'
 import { duplicateDocumentTool } from './builtin/collections/duplicateTool.js'
 import { findDistinctTool } from './builtin/collections/findDistinctTool.js'
@@ -20,6 +20,7 @@ import { findVersionsTool } from './builtin/collections/findVersionsTool.js'
 import { getCollectionSchemaTool } from './builtin/collections/getCollectionSchemaTool.js'
 import { restoreVersionTool } from './builtin/collections/restoreVersionTool.js'
 import { updateDocumentTool } from './builtin/collections/updateTool.js'
+import { getUploadInstructionsTool } from './builtin/collections/uploadInstructionsTool.js'
 import { getConfigInfoTool } from './builtin/getConfigInfoTool.js'
 import { countGlobalVersionsTool } from './builtin/globals/countVersionsTool.js'
 import { findGlobalTool } from './builtin/globals/findTool.js'
@@ -32,6 +33,7 @@ import { updateGlobalTool } from './builtin/globals/updateTool.js'
 type CollectionBuiltin = {
   mcpName: string
   requiresDuplicateEnabled?: boolean
+  requiresUpload?: boolean
   requiresVersions?: boolean
   tool: CollectionTool
 }
@@ -54,7 +56,7 @@ export const TOOL_BUILTINS = {
 export const COLLECTION_BUILTINS = {
   count: { mcpName: 'countDocuments', tool: countDocumentsTool },
   countVersions: { mcpName: 'countVersions', requiresVersions: true, tool: countVersionsTool },
-  create: { mcpName: 'createDocument', tool: createDocumentTool },
+  create: { mcpName: 'createDocuments', tool: createDocumentsTool },
   delete: { mcpName: 'deleteDocuments', tool: deleteDocumentsTool },
   duplicate: {
     mcpName: 'duplicateDocument',
@@ -70,6 +72,11 @@ export const COLLECTION_BUILTINS = {
   },
   findVersions: { mcpName: 'findVersions', requiresVersions: true, tool: findVersionsTool },
   getCollectionSchema: { mcpName: 'getCollectionSchema', tool: getCollectionSchemaTool },
+  getUploadInstructions: {
+    mcpName: 'getUploadInstructions',
+    requiresUpload: true,
+    tool: getUploadInstructionsTool,
+  },
   restoreVersion: { mcpName: 'restoreVersion', requiresVersions: true, tool: restoreVersionTool },
   update: { mcpName: 'updateDocument', tool: updateDocumentTool },
 } satisfies Record<string, CollectionBuiltin>

package/src/mcp/sanitizeMCPConfig.ts

@@ -127,7 +127,7 @@ const sanitizeCollectionConfig = ({
 
   for (const [
     toolKey,
-    { mcpName, requiresDuplicateEnabled, requiresVersions, tool },
+    { mcpName, requiresDuplicateEnabled, requiresUpload, requiresVersions, tool },
   ] of COLLECTION_BUILTIN_ENTRIES) {
     if (requiresVersions && !collection.versions) {
       continue
@@ -135,6 +135,9 @@ const sanitizeCollectionConfig = ({
     if (requiresDuplicateEnabled && isDuplicateDisabled) {
       continue
     }
+    if (requiresUpload && !collection.upload) {
+      continue
+    }
     const matchedConfigEntry = collectionPluginConfig?.tools?.[toolKey]
     if (matchedConfigEntry === false) {
       continue

package/src/stdio.ts

@@ -4,7 +4,7 @@ import type { Config, Plugin, SanitizedConfig } from 'payload'
 import { serveStdio } from '@modelcontextprotocol/server/stdio'
 import { fileURLToPath, pathToFileURL } from 'node:url'
 import { createLocalReq, getPayload } from 'payload'
-import { findConfig } from 'payload/node'
+import { findConfig, loadEnv } from 'payload/node'
 
 import type { SanitizedMCPPluginConfig } from './types.js'
 
@@ -28,6 +28,7 @@ export const runMcpStdio = async (): Promise<void> => {
     process.chdir(projectRoot)
   }
 
+  loadEnv()
   const configPath = findConfig()
   const configModule = await import(pathToFileURL(configPath).toString())
   const config = (await (configModule.default ?? configModule)) as SanitizedConfig