@payloadcms/plugin-mcp 3.65.0-canary.6 → 3.65.0-canary.8

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 {
@@ -51,9 +58,12 @@ export const createResourceTool = (
       const result = await payload.create({
         collection: collectionSlug,
         data: parsedData,
+        draft,
         overrideAccess: false,
         req,
         user,
+        ...(locale && { locale }),
+        ...(fallbackLocale && { fallbackLocale }),
       })
 
       if (verboseLogs) {
@@ -109,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) {
@@ -168,6 +172,8 @@ ${JSON.stringify(result, null, 2)}
           where: whereClause,
           ...(filePath && { filePath }),
           ...(overwriteExistingFiles && { overwriteExistingFiles }),
+          ...(locale && { locale }),
+          ...(fallbackLocale && { fallbackLocale }),
         }
 
         if (verboseLogs) {
@@ -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'
@@ -135,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.
        */
@@ -157,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'
@@ -192,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.
        */
@@ -309,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)
 }