@payloadcms/plugin-mcp 3.65.0-canary.0 → 3.65.0-canary.10

package/src/mcp/tools/resource/create.ts

@@ -2,6 +2,8 @@ import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
 import type { JSONSchema4 } from 'json-schema'
 import type { PayloadRequest, TypedUser } from 'payload'
 
+import { z } from 'zod'
+
 import type { PluginMCPServerConfig } from '../../../types.js'
 
 import { toCamelCase } from '../../../utils/camelCase.js'
@@ -18,6 +20,9 @@ export const createResourceTool = (
 ) => {
   const tool = async (
     data: string,
+    draft: boolean,
+    locale?: string,
+    fallbackLocale?: string,
   ): Promise<{
     content: Array<{
       text: string
@@ -27,7 +32,9 @@ export const createResourceTool = (
     const payload = req.payload
 
     if (verboseLogs) {
-      payload.logger.info(`[payload-mcp] Creating resource in collection: ${collectionSlug}`)
+      payload.logger.info(
+        `[payload-mcp] Creating resource in collection: ${collectionSlug}${locale ? ` with locale: ${locale}` : ''}`,
+      )
     }
 
     try {
@@ -50,11 +57,13 @@ export const createResourceTool = (
       // Create the resource
       const result = await payload.create({
         collection: collectionSlug,
-        req,
-        // TODO: Move the override to a `beforeChange` hook and extend the payloadAPI context req to include MCP request info.
-        data: collections?.[collectionSlug]?.override?.(parsedData, req) || parsedData,
+        data: parsedData,
+        draft,
         overrideAccess: false,
+        req,
         user,
+        ...(locale && { locale }),
+        ...(fallbackLocale && { fallbackLocale }),
       })
 
       if (verboseLogs) {
@@ -110,13 +119,39 @@ ${JSON.stringify(result, null, 2)}
   if (collections?.[collectionSlug]?.enabled) {
     const convertedFields = convertCollectionSchemaToZod(schema)
 
+    // Create a new schema that combines the converted fields with create-specific parameters
+    const createResourceSchema = z.object({
+      ...convertedFields.shape,
+      draft: z
+        .boolean()
+        .optional()
+        .default(false)
+        .describe('Whether to create the document as a draft'),
+      fallbackLocale: z
+        .string()
+        .optional()
+        .describe('Optional: fallback locale code to use when requested locale is not available'),
+      locale: z
+        .string()
+        .optional()
+        .describe(
+          'Optional: locale code to create the document in (e.g., "en", "es"). Defaults to the default locale',
+        ),
+    })
+
     server.tool(
       `create${collectionSlug.charAt(0).toUpperCase() + toCamelCase(collectionSlug).slice(1)}`,
       `${collections?.[collectionSlug]?.description || toolSchemas.createResource.description.trim()}`,
-      convertedFields.shape,
+      createResourceSchema.shape,
       async (params: Record<string, unknown>) => {
-        const data = JSON.stringify(params)
-        return await tool(data)
+        const { draft, fallbackLocale, locale, ...fieldData } = params
+        const data = JSON.stringify(fieldData)
+        return await tool(
+          data,
+          draft as boolean,
+          locale as string | undefined,
+          fallbackLocale as string | undefined,
+        )
       },
     )
   }

package/src/mcp/tools/resource/delete.ts

@@ -15,9 +15,11 @@ export const deleteResourceTool = (
   collections: PluginMCPServerConfig['collections'],
 ) => {
   const tool = async (
-    id?: string,
+    id?: number | string,
     where?: string,
     depth: number = 0,
+    locale?: string,
+    fallbackLocale?: string,
   ): Promise<{
     content: Array<{
       text: string
@@ -28,7 +30,7 @@ export const deleteResourceTool = (
 
     if (verboseLogs) {
       payload.logger.info(
-        `[payload-mcp] Deleting resource from collection: ${collectionSlug}${id ? ` with ID: ${id}` : ' with where clause'}`,
+        `[payload-mcp] Deleting resource from collection: ${collectionSlug}${id ? ` with ID: ${id}` : ' with where clause'}${locale ? `, locale: ${locale}` : ''}`,
       )
     }
 
@@ -80,6 +82,8 @@ export const deleteResourceTool = (
         overrideAccess: false,
         req,
         user,
+        ...(locale && { locale }),
+        ...(fallbackLocale && { fallbackLocale }),
       }
 
       // Delete by ID or where clause
@@ -204,8 +208,8 @@ ${JSON.stringify(errors, null, 2)}
       `delete${collectionSlug.charAt(0).toUpperCase() + toCamelCase(collectionSlug).slice(1)}`,
       `${collections?.[collectionSlug]?.description || toolSchemas.deleteResource.description.trim()}`,
       toolSchemas.deleteResource.parameters.shape,
-      async ({ id, depth, where }) => {
-        return await tool(id, where, depth)
+      async ({ id, depth, fallbackLocale, locale, where }) => {
+        return await tool(id, where, depth, locale, fallbackLocale)
       },
     )
   }

package/src/mcp/tools/resource/find.ts

@@ -15,11 +15,13 @@ export const findResourceTool = (
   collections: PluginMCPServerConfig['collections'],
 ) => {
   const tool = async (
-    id?: string,
+    id?: number | string,
     limit: number = 10,
     page: number = 1,
     sort?: string,
     where?: string,
+    locale?: string,
+    fallbackLocale?: string,
   ): Promise<{
     content: Array<{
       text: string
@@ -30,7 +32,7 @@ export const findResourceTool = (
 
     if (verboseLogs) {
       payload.logger.info(
-        `[payload-mcp] Reading resource from collection: ${collectionSlug}${id ? ` with ID: ${id}` : ''}, limit: ${limit}, page: ${page}`,
+        `[payload-mcp] Reading resource from collection: ${collectionSlug}${id ? ` with ID: ${id}` : ''}, limit: ${limit}, page: ${page}${locale ? `, locale: ${locale}` : ''}`,
       )
     }
 
@@ -67,6 +69,8 @@ export const findResourceTool = (
             overrideAccess: false,
             req,
             user,
+            ...(locale && { locale }),
+            ...(fallbackLocale && { fallbackLocale }),
           })
 
           if (verboseLogs) {
@@ -120,6 +124,8 @@ ${JSON.stringify(doc, null, 2)}`,
         page,
         req,
         user,
+        ...(locale && { locale }),
+        ...(fallbackLocale && { fallbackLocale }),
       }
 
       if (sort) {
@@ -190,8 +196,8 @@ Page: ${result.page} of ${result.totalPages}
       `find${collectionSlug.charAt(0).toUpperCase() + toCamelCase(collectionSlug).slice(1)}`,
       `${collections?.[collectionSlug]?.description || toolSchemas.findResources.description.trim()}`,
       toolSchemas.findResources.parameters.shape,
-      async ({ id, limit, page, sort, where }) => {
-        return await tool(id, limit, page, sort, where)
+      async ({ id, fallbackLocale, limit, locale, page, sort, where }) => {
+        return await tool(id, limit, page, sort, where, locale, fallbackLocale)
       },
     )
   }

package/src/mcp/tools/resource/update.ts

@@ -20,13 +20,15 @@ export const updateResourceTool = (
 ) => {
   const tool = async (
     data: string,
-    id?: string,
+    id?: number | string,
     where?: string,
     draft: boolean = false,
     depth: number = 0,
     overrideLock: boolean = true,
     filePath?: string,
     overwriteExistingFiles: boolean = false,
+    locale?: string,
+    fallbackLocale?: string,
   ): Promise<{
     content: Array<{
       text: string
@@ -37,7 +39,7 @@ export const updateResourceTool = (
 
     if (verboseLogs) {
       payload.logger.info(
-        `[payload-mcp] Updating resource in collection: ${collectionSlug}${id ? ` with ID: ${id}` : ' with where clause'}, draft: ${draft}`,
+        `[payload-mcp] Updating resource in collection: ${collectionSlug}${id ? ` with ID: ${id}` : ' with where clause'}, draft: ${draft}${locale ? `, locale: ${locale}` : ''}`,
       )
     }
 
@@ -120,6 +122,8 @@ export const updateResourceTool = (
           user,
           ...(filePath && { filePath }),
           ...(overwriteExistingFiles && { overwriteExistingFiles }),
+          ...(locale && { locale }),
+          ...(fallbackLocale && { fallbackLocale }),
         }
 
         if (verboseLogs) {
@@ -127,7 +131,7 @@ export const updateResourceTool = (
         }
         const result = await payload.update({
           ...updateOptions,
-          data: collections?.[collectionSlug]?.override?.(parsedData, req) || parsedData,
+          data: parsedData,
         } as any)
 
         if (verboseLogs) {
@@ -168,6 +172,8 @@ ${JSON.stringify(result, null, 2)}
           where: whereClause,
           ...(filePath && { filePath }),
           ...(overwriteExistingFiles && { overwriteExistingFiles }),
+          ...(locale && { locale }),
+          ...(fallbackLocale && { fallbackLocale }),
         }
 
         if (verboseLogs) {
@@ -175,7 +181,7 @@ ${JSON.stringify(result, null, 2)}
         }
         const result = await payload.update({
           ...updateOptions,
-          data: collections?.[collectionSlug]?.override?.(parsedData, req) || parsedData,
+          data: parsedData,
         } as any)
 
         const bulkResult = result as { docs?: unknown[]; errors?: unknown[] }
@@ -255,9 +261,10 @@ ${JSON.stringify(errors, null, 2)}
     const convertedFields = convertCollectionSchemaToZod(schema)
 
     // Create a new schema that combines the converted fields with update-specific parameters
+    // Use .partial() to make all fields optional for partial updates
     const updateResourceSchema = z.object({
-      ...convertedFields.shape,
-      id: z.string().optional().describe('The ID of the document to update'),
+      ...convertedFields.partial().shape,
+      id: z.union([z.string(), z.number()]).optional().describe('The ID of the document to update'),
       depth: z
         .number()
         .optional()
@@ -268,7 +275,17 @@ ${JSON.stringify(errors, null, 2)}
         .optional()
         .default(false)
         .describe('Whether to update the document as a draft'),
+      fallbackLocale: z
+        .string()
+        .optional()
+        .describe('Optional: fallback locale code to use when requested locale is not available'),
       filePath: z.string().optional().describe('File path for file uploads'),
+      locale: z
+        .string()
+        .optional()
+        .describe(
+          'Optional: locale code to update the document in (e.g., "en", "es"). Defaults to the default locale',
+        ),
       overrideLock: z
         .boolean()
         .optional()
@@ -294,7 +311,9 @@ ${JSON.stringify(errors, null, 2)}
           id,
           depth,
           draft,
+          fallbackLocale,
           filePath,
+          locale,
           overrideLock,
           overwriteExistingFiles,
           where,
@@ -304,13 +323,15 @@ ${JSON.stringify(errors, null, 2)}
         const data = JSON.stringify(fieldData)
         return await tool(
           data,
-          id as string | undefined,
+          id as number | string | undefined,
           where as string | undefined,
           draft as boolean,
           depth as number,
           overrideLock as boolean,
           filePath as string | undefined,
           overwriteExistingFiles as boolean,
+          locale as string | undefined,
+          fallbackLocale as string | undefined,
         )
       },
     )

package/src/mcp/tools/schemas.ts

@@ -5,11 +5,15 @@ export const toolSchemas = {
     description: 'Find documents in a collection by ID or where clause using Find or FindByID.',
     parameters: z.object({
       id: z
-        .string()
+        .union([z.string(), z.number()])
         .optional()
         .describe(
           'Optional: specific document ID to retrieve. If not provided, returns all documents',
         ),
+      fallbackLocale: z
+        .string()
+        .optional()
+        .describe('Optional: fallback locale code to use when requested locale is not available'),
       limit: z
         .number()
         .int()
@@ -18,6 +22,12 @@ export const toolSchemas = {
         .optional()
         .default(10)
         .describe('Maximum number of documents to return (default: 10, max: 100)'),
+      locale: z
+        .string()
+        .optional()
+        .describe(
+          'Optional: locale code to retrieve data in (e.g., "en", "es"). Use "all" to retrieve all locales for localized fields',
+        ),
       page: z
         .number()
         .int()
@@ -47,13 +57,26 @@ export const toolSchemas = {
         .optional()
         .default(false)
         .describe('Whether to create the document as a draft'),
+      fallbackLocale: z
+        .string()
+        .optional()
+        .describe('Optional: fallback locale code to use when requested locale is not available'),
+      locale: z
+        .string()
+        .optional()
+        .describe(
+          'Optional: locale code to create the document in (e.g., "en", "es"). Defaults to the default locale',
+        ),
     }),
   },
 
   updateResource: {
     description: 'Update documents in a collection by ID or where clause.',
     parameters: z.object({
-      id: z.string().optional().describe('Optional: specific document ID to update'),
+      id: z
+        .union([z.string(), z.number()])
+        .optional()
+        .describe('Optional: specific document ID to update'),
       data: z.string().describe('JSON string containing the data to update'),
       depth: z
         .number()
@@ -64,7 +87,17 @@ export const toolSchemas = {
         .default(0)
         .describe('Depth of population for relationships'),
       draft: z.boolean().optional().default(false).describe('Whether to update as a draft'),
+      fallbackLocale: z
+        .string()
+        .optional()
+        .describe('Optional: fallback locale code to use when requested locale is not available'),
       filePath: z.string().optional().describe('Optional: absolute file path for file uploads'),
+      locale: z
+        .string()
+        .optional()
+        .describe(
+          'Optional: locale code to update the document in (e.g., "en", "es"). Defaults to the default locale',
+        ),
       overrideLock: z
         .boolean()
         .optional()
@@ -85,7 +118,10 @@ export const toolSchemas = {
   deleteResource: {
     description: 'Delete documents in a collection by ID or where clause.',
     parameters: z.object({
-      id: z.string().optional().describe('Optional: specific document ID to delete'),
+      id: z
+        .union([z.string(), z.number()])
+        .optional()
+        .describe('Optional: specific document ID to delete'),
       depth: z
         .number()
         .int()
@@ -94,6 +130,16 @@ export const toolSchemas = {
         .optional()
         .default(0)
         .describe('Depth of population for relationships in response'),
+      fallbackLocale: z
+        .string()
+        .optional()
+        .describe('Optional: fallback locale code to use when requested locale is not available'),
+      locale: z
+        .string()
+        .optional()
+        .describe(
+          'Optional: locale code for the operation (e.g., "en", "es"). Defaults to the default locale',
+        ),
       where: z
         .string()
         .optional()

package/src/types.ts

@@ -1,4 +1,4 @@
-import type { CollectionConfig, CollectionSlug, PayloadRequest } from 'payload'
+import type { CollectionConfig, CollectionSlug, PayloadRequest, TypedUser } from 'payload'
 import type { z } from 'zod'
 
 import { type ResourceTemplate } from '@modelcontextprotocol/sdk/server/mcp.js'
@@ -26,13 +26,6 @@ export type PluginMCPServerConfig = {
               update?: boolean
             }
           | boolean
-        /**
-         * Override the data generated by the MCP client. This allows you to modify the data that is sent to the MCP client. This is useful for adding additional data to the response, data normalization, or verifying data.
-         */
-        override?: (
-          original: Record<string, unknown>,
-          req: PayloadRequest,
-        ) => Record<string, unknown>
 
         /**
          * Override the response generated by the MCP client. This allows you to modify the response that is sent to the MCP client. This is useful for adding additional data to the response, data normalization, or verifying data.
@@ -142,7 +135,29 @@ export type PluginMCPServerConfig = {
       /**
        * Set the handler of the prompt. This is the function that will be called when the prompt is used.
        */
-      handler: (...args: any) => any
+      handler: (
+        args: Record<string, unknown>,
+        req: PayloadRequest,
+        _extra: unknown,
+      ) =>
+        | {
+            messages: Array<{
+              content: {
+                text: string
+                type: 'text'
+              }
+              role: 'assistant' | 'user'
+            }>
+          }
+        | Promise<{
+            messages: Array<{
+              content: {
+                text: string
+                type: 'text'
+              }
+              role: 'assistant' | 'user'
+            }>
+          }>
       /**
        * Set the function name of the prompt.
        */
@@ -164,8 +179,21 @@ export type PluginMCPServerConfig = {
       description: string
       /**
        * Set the handler of the resource. This is the function that will be called when the resource is used.
+       * The handler can have either 3 arguments (when no args are passed) or 4 arguments (when args are passed).
        */
-      handler: (...args: any) => any
+      handler: (...args: any[]) =>
+        | {
+            contents: Array<{
+              text: string
+              uri: string
+            }>
+          }
+        | Promise<{
+            contents: Array<{
+              text: string
+              uri: string
+            }>
+          }>
       /**
        * Set the mime type of the resource.
        * example: 'text/plain'
@@ -199,12 +227,25 @@ export type PluginMCPServerConfig = {
       /**
        * Set the handler of the tool. This is the function that will be called when the tool is used.
        */
-      handler: (args: Record<string, unknown>) => Promise<{
-        content: Array<{
-          text: string
-          type: 'text'
-        }>
-      }>
+      handler: (
+        args: Record<string, unknown>,
+        req: PayloadRequest,
+        _extra: unknown,
+      ) =>
+        | {
+            content: Array<{
+              text: string
+              type: 'text'
+            }>
+            role?: string
+          }
+        | Promise<{
+            content: Array<{
+              text: string
+              type: 'text'
+            }>
+            role?: string
+          }>
       /**
        * Set the name of the tool. This is the name that will be used to identify the tool. LLMs will interperate the name to determine when to use the tool.
        */
@@ -316,6 +357,7 @@ export type MCPAccessSettings = {
   'payload-mcp-prompt'?: Record<string, boolean>
   'payload-mcp-resource'?: Record<string, boolean>
   'payload-mcp-tool'?: Record<string, boolean>
+  user: TypedUser
 } & Record<string, unknown>
 
 export type FieldDefinition = {

package/src/utils/convertCollectionSchemaToZod.ts

@@ -30,6 +30,5 @@ export const convertCollectionSchemaToZod = (schema: JSONSchema4) => {
    * 5. No user input or external data is involved in the schema generation process
    */
   // eslint-disable-next-line @typescript-eslint/no-implied-eval
-  const zodSchema = new Function('z', `return ${transpileResult.outputText}`)(z)
-  return zodSchema
+  return new Function('z', `return ${transpileResult.outputText}`)(z)
 }