@payloadcms/plugin-mcp 3.91.0-internal.c1569dc → 3.92.0

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

@@ -1,5 +1,5 @@
 import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
-import type { PayloadRequest, SelectType, TypedUser } from 'payload'
+import type { PayloadRequest, PopulateType, SelectType, TypedUser } from 'payload'
 
 import type { MCPPluginConfig } from '../../../types.js'
 
@@ -18,7 +18,8 @@ export const findGlobalTool = (
     depth: number = 0,
     locale?: string,
     fallbackLocale?: string,
-    select?: string,
+    select?: Record<string, unknown>,
+    populate?: Record<string, unknown>,
   ): Promise<{
     content: Array<{
       text: string
@@ -42,24 +43,6 @@ export const findGlobalTool = (
         user,
       }
 
-      let selectClause: SelectType | undefined
-      if (select) {
-        try {
-          selectClause = JSON.parse(select) as SelectType
-        } catch (_parseError) {
-          payload.logger.warn(`[payload-mcp] Invalid select clause JSON for global: ${select}`)
-          const response = {
-            content: [{ type: 'text' as const, text: 'Error: Invalid JSON in select clause' }],
-          }
-          return (globals?.[globalSlug]?.overrideResponse?.(response, {}, req) || response) as {
-            content: Array<{
-              text: string
-              type: 'text'
-            }>
-          }
-        }
-      }
-
       // Add locale parameters if provided
       if (locale) {
         findOptions.locale = locale
@@ -67,8 +50,11 @@ export const findGlobalTool = (
       if (fallbackLocale) {
         findOptions.fallbackLocale = fallbackLocale
       }
-      if (selectClause) {
-        findOptions.select = selectClause
+      if (select) {
+        findOptions.select = select as SelectType
+      }
+      if (populate) {
+        findOptions.populate = populate as PopulateType
       }
 
       const result = await payload.findGlobal(findOptions)
@@ -122,8 +108,8 @@ ${JSON.stringify(result)}
         description: `${toolSchemas.findGlobal.description.trim()}\n\n${globals?.[globalSlug]?.description || ''}`,
         inputSchema: toolSchemas.findGlobal.parameters.shape,
       },
-      async ({ depth, fallbackLocale, locale, select }) => {
-        return await tool(depth, locale, fallbackLocale, select)
+      async ({ depth, fallbackLocale, locale, populate, select }) => {
+        return await tool(depth, locale, fallbackLocale, select, populate)
       },
     )
   }

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

@@ -29,7 +29,7 @@ export const updateGlobalTool = (
     depth: number = 0,
     locale?: string,
     fallbackLocale?: string,
-    select?: string,
+    select?: Record<string, unknown>,
   ): Promise<{
     content: Array<{
       text: string
@@ -71,24 +71,6 @@ export const updateGlobalTool = (
         }
       }
 
-      let selectClause: SelectType | undefined
-      if (select) {
-        try {
-          selectClause = JSON.parse(select) as SelectType
-        } catch (_parseError) {
-          payload.logger.warn(`[payload-mcp] Invalid select clause JSON for global: ${select}`)
-          const response = {
-            content: [{ type: 'text' as const, text: 'Error: Invalid JSON in select clause' }],
-          }
-          return (globals?.[globalSlug]?.overrideResponse?.(response, {}, req) || response) as {
-            content: Array<{
-              text: string
-              type: 'text'
-            }>
-          }
-        }
-      }
-
       const updateOptions: Parameters<typeof payload.updateGlobal>[0] = {
         slug: globalSlug,
         data: parsedData,
@@ -106,8 +88,8 @@ export const updateGlobalTool = (
       if (fallbackLocale) {
         updateOptions.fallbackLocale = fallbackLocale
       }
-      if (selectClause) {
-        updateOptions.select = selectClause
+      if (select) {
+        updateOptions.select = select as SelectType
       }
 
       const result = await payload.updateGlobal(updateOptions)
@@ -179,10 +161,10 @@ ${JSON.stringify(result)}
           'Optional: locale code to update data in (e.g., "en", "es"). Use "all" to update all locales for localized fields',
         ),
       select: z
-        .string()
+        .record(z.string(), z.unknown())
         .optional()
         .describe(
-          'Optional: define exactly which fields you\'d like to return in the response (JSON), e.g., \'{"siteName": "My Site"}\'',
+          "Optional: define exactly which fields you'd like to return in the response, e.g., {\"siteName\": true}",
         ),
     })
 
@@ -201,7 +183,7 @@ ${JSON.stringify(result)}
           depth as number,
           locale as string,
           fallbackLocale as string,
-          select as string | undefined,
+          select as Record<string, unknown> | undefined,
         )
       },
     )

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

@@ -29,7 +29,7 @@ export const createResourceTool = (
     draft: boolean,
     locale?: string,
     fallbackLocale?: string,
-    select?: string,
+    select?: Record<string, unknown>,
   ): Promise<{
     content: Array<{
       text: string
@@ -68,25 +68,6 @@ export const createResourceTool = (
         }
       }
 
-      let selectClause: SelectType | undefined
-      if (select) {
-        try {
-          selectClause = JSON.parse(select) as SelectType
-        } catch (_parseError) {
-          payload.logger.warn(`[payload-mcp] Invalid select clause JSON: ${select}`)
-          const response = {
-            content: [{ type: 'text' as const, text: 'Error: Invalid JSON in select clause' }],
-          }
-          return (collections?.[collectionSlug]?.overrideResponse?.(response, {}, req) ||
-            response) as {
-            content: Array<{
-              text: string
-              type: 'text'
-            }>
-          }
-        }
-      }
-
       // Create the resource
       const result = await payload.create({
         collection: collectionSlug,
@@ -98,7 +79,7 @@ export const createResourceTool = (
         user,
         ...(locale && { locale }),
         ...(fallbackLocale && { fallbackLocale }),
-        ...(selectClause && { select: selectClause }),
+        ...(select && { select: select as SelectType }),
       })
 
       if (verboseLogs) {
@@ -181,10 +162,10 @@ ${JSON.stringify(result)}
           'Optional: locale code to create the document in (e.g., "en", "es"). Defaults to the default locale',
         ),
       select: z
-        .string()
+        .record(z.string(), z.unknown())
         .optional()
         .describe(
-          'Optional: define exactly which fields you\'d like to create (JSON), e.g., \'{"title": "My Post"}\'',
+          "Optional: define exactly which fields you'd like to return in the response, e.g., {\"title\": true}",
         ),
     })
 
@@ -203,7 +184,7 @@ ${JSON.stringify(result)}
           draft as boolean,
           locale as string | undefined,
           fallbackLocale as string | undefined,
-          select as string | undefined,
+          select as Record<string, unknown> | undefined,
         )
       },
     )

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

@@ -1,5 +1,5 @@
 import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
-import type { PayloadRequest, SelectType, TypedUser } from 'payload'
+import type { JoinQuery, PayloadRequest, PopulateType, SelectType, TypedUser } from 'payload'
 
 import type { MCPPluginConfig } from '../../../types.js'
 
@@ -20,11 +20,15 @@ export const findResourceTool = (
     page: number = 1,
     sort?: string,
     where?: string,
-    select?: string,
+    select?: Record<string, unknown>,
     depth: number = 0,
     locale?: string,
     fallbackLocale?: string,
     draft?: boolean,
+    populate?: Record<string, unknown>,
+    joins?: false | Record<string, unknown>,
+    trash?: boolean,
+    pagination?: boolean,
   ): Promise<{
     content: Array<{
       text: string
@@ -63,26 +67,6 @@ export const findResourceTool = (
         }
       }
 
-      // Parse select clause if provided
-      let selectClause: SelectType | undefined
-      if (select) {
-        try {
-          selectClause = JSON.parse(select) as SelectType
-        } catch (_parseError) {
-          payload.logger.warn(`[payload-mcp] Invalid select clause JSON: ${select}`)
-          const response = {
-            content: [{ type: 'text' as const, text: 'Error: Invalid JSON in select clause' }],
-          }
-          return (collections?.[collectionSlug]?.overrideResponse?.(response, {}, req) ||
-            response) as {
-            content: Array<{
-              text: string
-              type: 'text'
-            }>
-          }
-        }
-      }
-
       // If ID is provided, use findByID
       if (id) {
         try {
@@ -90,13 +74,16 @@ export const findResourceTool = (
             id,
             collection: collectionSlug,
             depth,
-            ...(selectClause && { select: selectClause }),
+            ...(select && { select: select as SelectType }),
+            ...(populate && { populate: populate as PopulateType }),
+            ...(joins !== undefined && { joins: joins as JoinQuery }),
             overrideAccess: false,
             req,
             user,
             ...(locale && { locale }),
             ...(fallbackLocale && { fallbackLocale }),
             ...(draft !== undefined && { draft }),
+            ...(trash !== undefined && { trash }),
           })
 
           if (verboseLogs) {
@@ -151,10 +138,14 @@ ${JSON.stringify(doc)}`,
         page,
         req,
         user,
-        ...(selectClause && { select: selectClause }),
+        ...(select && { select: select as SelectType }),
+        ...(populate && { populate: populate as PopulateType }),
+        ...(joins !== undefined && { joins: joins as JoinQuery }),
         ...(locale && { locale }),
         ...(fallbackLocale && { fallbackLocale }),
         ...(draft !== undefined && { draft }),
+        ...(pagination !== undefined && { pagination }),
+        ...(trash !== undefined && { trash }),
       }
 
       if (sort) {
@@ -227,7 +218,22 @@ Page: ${result.page} of ${result.totalPages}
         description: `${collections?.[collectionSlug]?.description || toolSchemas.findResources.description.trim()}`,
         inputSchema: toolSchemas.findResources.parameters.shape,
       },
-      async ({ id, depth, draft, fallbackLocale, limit, locale, page, select, sort, where }) => {
+      async ({
+        id,
+        depth,
+        draft,
+        fallbackLocale,
+        joins,
+        limit,
+        locale,
+        page,
+        pagination,
+        populate,
+        select,
+        sort,
+        trash,
+        where,
+      }) => {
         return await tool(
           id,
           limit,
@@ -239,6 +245,10 @@ Page: ${result.page} of ${result.totalPages}
           locale,
           fallbackLocale,
           draft,
+          populate,
+          joins,
+          trash,
+          pagination,
         )
       },
     )

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

@@ -32,7 +32,7 @@ export const updateResourceTool = (
     overrideLock: boolean = true,
     locale?: string,
     fallbackLocale?: string,
-    select?: string,
+    select?: Record<string, unknown>,
   ): Promise<{
     content: Array<{
       text: string
@@ -118,25 +118,6 @@ export const updateResourceTool = (
         }
       }
 
-      let selectClause: SelectType | undefined
-      if (select) {
-        try {
-          selectClause = JSON.parse(select) as SelectType
-        } catch (_parseError) {
-          payload.logger.warn(`[payload-mcp] Invalid select clause JSON: ${select}`)
-          const response = {
-            content: [{ type: 'text' as const, text: 'Error: Invalid JSON in select clause' }],
-          }
-          return (collections?.[collectionSlug]?.overrideResponse?.(response, {}, req) ||
-            response) as {
-            content: Array<{
-              text: string
-              type: 'text'
-            }>
-          }
-        }
-      }
-
       // Update by ID or where clause
       if (id) {
         // Single document update
@@ -152,7 +133,7 @@ export const updateResourceTool = (
           user,
           ...(locale && { locale }),
           ...(fallbackLocale && { fallbackLocale }),
-          ...(selectClause && { select: selectClause }),
+          ...(select && { select: select as SelectType }),
         }
 
         if (verboseLogs) {
@@ -201,7 +182,7 @@ ${JSON.stringify(result)}
           where: whereClause,
           ...(locale && { locale }),
           ...(fallbackLocale && { fallbackLocale }),
-          ...(selectClause && { select: selectClause }),
+          ...(select && { select: select as SelectType }),
         }
 
         if (verboseLogs) {
@@ -319,10 +300,10 @@ ${JSON.stringify(errors)}
         .default(true)
         .describe('Whether to override document locks'),
       select: z
-        .string()
+        .record(z.string(), z.unknown())
         .optional()
         .describe(
-          'Optional: define exactly which fields you\'d like to return in the response (JSON), e.g., \'{"title": "My Post"}\'',
+          "Optional: define exactly which fields you'd like to return in the response, e.g., {\"title\": true}",
         ),
       where: z
         .string()
@@ -359,7 +340,7 @@ ${JSON.stringify(errors)}
           overrideLock as boolean,
           locale as string | undefined,
           fallbackLocale as string | undefined,
-          select as string | undefined,
+          select as Record<string, unknown> | undefined,
         )
       },
     )

package/src/mcp/tools/schemas.ts

@@ -22,11 +22,17 @@ export const toolSchemas = {
         .describe(
           'Optional: locale code to retrieve data in (e.g., "en", "es"). Use "all" to retrieve all locales for localized fields',
         ),
+      populate: z
+        .record(z.string(), z.unknown())
+        .optional()
+        .describe(
+          'Optional: control which fields to include from populated relationship or upload documents.',
+        ),
       select: z
-        .string()
+        .record(z.string(), z.unknown())
         .optional()
         .describe(
-          "Optional: define exactly which fields you'd like to return in the response (JSON), e.g., '{\"title\": true}'",
+          "Optional: define exactly which fields you'd like to return in the response, e.g., {\"title\": true}",
         ),
     }),
   },
@@ -58,6 +64,12 @@ export const toolSchemas = {
         .string()
         .optional()
         .describe('Optional: fallback locale code to use when requested locale is not available'),
+      joins: z
+        .union([z.record(z.string(), z.unknown()), z.literal(false)])
+        .optional()
+        .describe(
+          'Optional: configure join field queries, or pass false to disable all join fields.',
+        ),
       limit: z
         .number()
         .int()
@@ -79,16 +91,30 @@ export const toolSchemas = {
         .optional()
         .default(1)
         .describe('Page number for pagination (default: 1)'),
+      pagination: z
+        .boolean()
+        .optional()
+        .describe('Optional: set to false to skip the count query overhead'),
+      populate: z
+        .record(z.string(), z.unknown())
+        .optional()
+        .describe(
+          'Optional: control which fields to include from populated relationship or upload documents.',
+        ),
       select: z
-        .string()
+        .record(z.string(), z.unknown())
         .optional()
         .describe(
-          "Optional: define exactly which fields you'd like to return in the response (JSON), e.g., '{\"title\": true}'",
+          "Optional: define exactly which fields you'd like to return in the response, e.g., {\"title\": true}",
         ),
       sort: z
         .string()
         .optional()
         .describe('Field to sort by (e.g., "createdAt", "-updatedAt" for descending)'),
+      trash: z
+        .boolean()
+        .optional()
+        .describe('Optional: include soft-deleted documents when trash is enabled on the collection'),
       where: z
         .string()
         .optional()
@@ -126,10 +152,10 @@ export const toolSchemas = {
           'Optional: locale code to create the document in (e.g., "en", "es"). Defaults to the default locale',
         ),
       select: z
-        .string()
+        .record(z.string(), z.unknown())
         .optional()
         .describe(
-          "Optional: define exactly which fields you'd like to return in the response (JSON), e.g., '{\"title\": true}'",
+          "Optional: define exactly which fields you'd like to return in the response, e.g., {\"title\": true}",
         ),
     }),
   },
@@ -167,10 +193,10 @@ export const toolSchemas = {
         .default(true)
         .describe('Whether to override document locks'),
       select: z
-        .string()
+        .record(z.string(), z.unknown())
         .optional()
         .describe(
-          "Optional: define exactly which fields you'd like to return in the response (JSON), e.g., '{\"title\": true}'",
+          "Optional: define exactly which fields you'd like to return in the response, e.g., {\"title\": true}",
         ),
       where: z
         .string()
@@ -235,10 +261,10 @@ export const toolSchemas = {
           'Optional: locale code to update data in (e.g., "en", "es"). Use "all" to update all locales for localized fields',
         ),
       select: z
-        .string()
+        .record(z.string(), z.unknown())
         .optional()
         .describe(
-          "Optional: define exactly which fields you'd like to return in the response (JSON), e.g., '{\"siteName\": true}'",
+          "Optional: define exactly which fields you'd like to return in the response, e.g., {\"siteName\": true}",
         ),
     }),
   },
@@ -369,11 +395,9 @@ export const toolSchemas = {
     description: 'Checks authentication status for the current user.',
     parameters: z.object({
       headers: z
-        .string()
+        .record(z.string(), z.string())
         .optional()
-        .describe(
-          'Optional JSON string containing custom headers to send with the authentication request',
-        ),
+        .describe('Optional custom headers to send with the authentication request'),
     }),
   },