@payloadcms/plugin-mcp 4.0.0-internal.a0ef1b8 → 4.0.0-internal.bc5cf8c

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

@@ -32,13 +32,18 @@ const wrapError =
   }
 
 export const authCollectionTool = defineCollectionTool({
+  annotations: {
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: false,
+    readOnlyHint: true,
+    title: 'Check Auth Status',
+  },
   description: 'Checks authentication status for the current user.',
   input: z.object({
     headers: z
-      .string()
-      .describe(
-        'Optional JSON string containing custom headers to send with the authentication request',
-      )
+      .record(z.string(), z.string())
+      .describe('Optional custom headers to send with the authentication request')
       .optional(),
   }),
 }).handler(async ({ collectionSlug, input, req }) => {
@@ -46,11 +51,7 @@ export const authCollectionTool = defineCollectionTool({
   try {
     let authHeaders = new Headers()
     if (input.headers) {
-      try {
-        authHeaders = new Headers(JSON.parse(input.headers) as Record<string, string>)
-      } catch {
-        logger.warn(`Invalid headers JSON for auth: ${input.headers}, using empty headers`)
-      }
+      authHeaders = new Headers(input.headers)
     }
     const result = await req.payload.auth({ headers: authHeaders })
     return {
@@ -70,6 +71,13 @@ export const authCollectionTool = defineCollectionTool({
 })
 
 export const forgotPasswordCollectionTool = defineCollectionTool({
+  annotations: {
+    destructiveHint: false,
+    idempotentHint: false,
+    openWorldHint: true,
+    readOnlyHint: false,
+    title: 'Forgot Password',
+  },
   description: 'Sends a password reset email to a user.',
   input: z.object({
     disableEmail: z
@@ -104,6 +112,13 @@ export const forgotPasswordCollectionTool = defineCollectionTool({
 })
 
 export const loginCollectionTool = defineCollectionTool({
+  annotations: {
+    destructiveHint: false,
+    idempotentHint: false,
+    openWorldHint: false,
+    readOnlyHint: false,
+    title: 'User Login',
+  },
   description: 'Authenticates a user with email and password.',
   input: z.object({
     depth: z
@@ -148,6 +163,13 @@ export const loginCollectionTool = defineCollectionTool({
 })
 
 export const resetPasswordCollectionTool = defineCollectionTool({
+  annotations: {
+    destructiveHint: false,
+    idempotentHint: false,
+    openWorldHint: false,
+    readOnlyHint: false,
+    title: 'Reset Password',
+  },
   description: 'Resets a user password with a reset token.',
   input: z.object({
     password: z.string().describe('The new password for the user'),
@@ -178,6 +200,13 @@ export const resetPasswordCollectionTool = defineCollectionTool({
 })
 
 export const unlockCollectionTool = defineCollectionTool({
+  annotations: {
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: false,
+    readOnlyHint: false,
+    title: 'Unlock Account',
+  },
   description: 'Unlocks a user account that has been locked due to failed login attempts.',
   input: z.object({ email: emailSchema }),
 }).handler(async ({ collectionSlug, input, req }) => {
@@ -205,6 +234,13 @@ export const unlockCollectionTool = defineCollectionTool({
 })
 
 export const verifyCollectionTool = defineCollectionTool({
+  annotations: {
+    destructiveHint: false,
+    idempotentHint: false,
+    openWorldHint: false,
+    readOnlyHint: false,
+    title: 'Email Verification',
+  },
   description: 'Verifies a user email with a verification token.',
   input: z.object({
     token: z.string().describe('The verification token sent to the user email'),

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

@@ -0,0 +1,74 @@
+import { z } from 'zod'
+
+import { defaultAccess } from '../../../defaultAccess.js'
+import { defineCollectionTool } from '../../../defineTool.js'
+import { getLogger } from '../../../utils/getLogger.js'
+import { localAPIDefaults } from '../../../utils/localAPIDefaults.js'
+import { whereSchema } from '../../../utils/whereSchema.js'
+
+const DEFAULT_DESCRIPTION =
+  'Count documents in any collection by passing the collection slug and optional where clause.'
+
+export const countDocumentsTool = defineCollectionTool({
+  access: (args) =>
+    defaultAccess(args) && Boolean(args.permissions?.collections?.[args.collectionSlug]?.read),
+  annotations: {
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: false,
+    readOnlyHint: true,
+    title: 'Count Documents',
+  },
+  description: DEFAULT_DESCRIPTION,
+  input: z.object({
+    locale: z.string().describe('Optional: locale code to count documents in').optional(),
+    trash: z
+      .boolean()
+      .describe('Optional: include soft-deleted documents when trash is enabled on the collection')
+      .optional(),
+    where: whereSchema
+      .describe(
+        'Optional: where clause for filtering. Use field names with Payload operators, and/or arrays for grouping. Example: {"title":{"contains":"test"}}',
+      )
+      .optional(),
+  }),
+}).handler(async ({ authorizedMCP, collectionSlug, input, req }) => {
+  const payload = req.payload
+  const logger = getLogger({ payload })
+  const { locale, trash, where } = input
+
+  logger.info(`Counting documents in collection: ${collectionSlug}`)
+
+  try {
+    const result = await payload.count({
+      collection: collectionSlug,
+      req,
+      ...localAPIDefaults(authorizedMCP),
+      ...(locale ? { locale } : {}),
+      ...(trash !== undefined ? { trash } : {}),
+      ...(where ? { where } : {}),
+    })
+
+    return {
+      content: [
+        {
+          type: 'text',
+          text: `Collection "${collectionSlug}" contains ${result.totalDocs} matching documents.\n\`\`\`json\n${JSON.stringify(result)}\n\`\`\``,
+        },
+      ],
+      doc: result,
+    }
+  } catch (error) {
+    const errorMessage = error instanceof Error ? error.message : 'Unknown error'
+    logger.error(`Error counting documents in ${collectionSlug}: ${errorMessage}`)
+    return {
+      content: [
+        {
+          type: 'text',
+          text: `❌ **Error counting documents in collection "${collectionSlug}":** ${errorMessage}`,
+        },
+      ],
+      isError: true,
+    }
+  }
+})

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

@@ -0,0 +1,70 @@
+import { z } from 'zod'
+
+import { defaultAccess } from '../../../defaultAccess.js'
+import { defineCollectionTool } from '../../../defineTool.js'
+import { getLogger } from '../../../utils/getLogger.js'
+import { localAPIDefaults } from '../../../utils/localAPIDefaults.js'
+import { whereSchema } from '../../../utils/whereSchema.js'
+
+const DEFAULT_DESCRIPTION =
+  'Count document versions in any version-enabled collection by passing the collection slug and optional where clause.'
+
+export const countVersionsTool = defineCollectionTool({
+  access: (args) =>
+    defaultAccess(args) &&
+    Boolean(args.permissions?.collections?.[args.collectionSlug]?.readVersions),
+  annotations: {
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: false,
+    readOnlyHint: true,
+    title: 'Count Versions',
+  },
+  description: DEFAULT_DESCRIPTION,
+  input: z.object({
+    locale: z.string().describe('Optional: locale code to count versions in').optional(),
+    where: whereSchema
+      .describe(
+        'Optional: where clause for filtering versions. Version document fields are usually under "version". Example: {"version.title":{"contains":"test"}}',
+      )
+      .optional(),
+  }),
+}).handler(async ({ authorizedMCP, collectionSlug, input, req }) => {
+  const payload = req.payload
+  const logger = getLogger({ payload })
+  const { locale, where } = input
+
+  logger.info(`Counting versions in collection: ${collectionSlug}`)
+
+  try {
+    const result = await payload.countVersions({
+      collection: collectionSlug,
+      req,
+      ...localAPIDefaults(authorizedMCP),
+      ...(locale ? { locale } : {}),
+      ...(where ? { where } : {}),
+    })
+
+    return {
+      content: [
+        {
+          type: 'text',
+          text: `Collection "${collectionSlug}" contains ${result.totalDocs} matching versions.\n\`\`\`json\n${JSON.stringify(result)}\n\`\`\``,
+        },
+      ],
+      doc: result,
+    }
+  } catch (error) {
+    const errorMessage = error instanceof Error ? error.message : 'Unknown error'
+    logger.error(`Error counting versions in ${collectionSlug}: ${errorMessage}`)
+    return {
+      content: [
+        {
+          type: 'text',
+          text: `❌ **Error counting versions in collection "${collectionSlug}":** ${errorMessage}`,
+        },
+      ],
+      isError: true,
+    }
+  }
+})

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

@@ -2,6 +2,7 @@ import type { SelectType } from 'payload'
 
 import { z } from 'zod'
 
+import { defaultAccess } from '../../../defaultAccess.js'
 import { defineCollectionTool } from '../../../defineTool.js'
 import { getLogger } from '../../../utils/getLogger.js'
 import {
@@ -9,50 +10,56 @@ import {
   stripVirtualFields,
 } from '../../../utils/getVirtualFieldNames.js'
 import { localAPIDefaults } from '../../../utils/localAPIDefaults.js'
-import { buildToolInput } from '../../../utils/schemaConversion/buildToolInput.js'
-import { sanitizeEntitySchema } from '../../../utils/schemaConversion/sanitizeEntitySchema.js'
 import { transformPointDataToPayload } from '../../../utils/transformPointDataToPayload.js'
+import { validateCollectionData } from '../validateEntityData.js'
+import { formatCollectionError } from './formatCollectionError.js'
 
-const DEFAULT_DESCRIPTION = 'Create a document in a collection.'
+const DEFAULT_DESCRIPTION =
+  'Create a document in any collection by passing the collection slug and data.'
 
-export const createCollectionTool = defineCollectionTool({
+export const createDocumentTool = defineCollectionTool({
+  access: (args) =>
+    defaultAccess(args) && Boolean(args.permissions?.collections?.[args.collectionSlug]?.create),
+  annotations: {
+    destructiveHint: false,
+    idempotentHint: false,
+    openWorldHint: false,
+    readOnlyHint: false,
+    title: 'Create Document',
+  },
   description: DEFAULT_DESCRIPTION,
-  input: ({ collectionSchema }) =>
-    buildToolInput({
-      controls: {
-        depth: z
-          .number()
-          .int()
-          .min(0)
-          .max(10)
-          .describe('How many levels deep to populate relationships in response')
-          .optional()
-          .default(0),
-        draft: z
-          .boolean()
-          .describe('Whether to create the document as a draft')
-          .optional()
-          .default(false),
-        fallbackLocale: z
-          .string()
-          .describe('Optional: fallback locale code to use when requested locale is not available')
-          .optional(),
-        locale: z
-          .string()
-          .describe(
-            'Optional: locale code to create the document in (e.g., "en", "es"). Defaults to the default locale',
-          )
-          .optional(),
-        select: z
-          .string()
-          .describe(
-            'Optional: define exactly which fields you\'d like to create (JSON), e.g., \'{"title": "My Post"}\'',
-          )
-          .optional(),
-      },
-      dataDescription: 'The document fields to create',
-      dataSchema: sanitizeEntitySchema(collectionSchema),
-    }),
+  input: z.object({
+    data: z.record(z.string(), z.unknown()).describe('The document fields to create'),
+    depth: z
+      .number()
+      .int()
+      .min(0)
+      .max(10)
+      .describe('How many levels deep to populate relationships in response')
+      .optional()
+      .default(0),
+    draft: z
+      .boolean()
+      .describe('Whether to create the document as a draft')
+      .optional()
+      .default(false),
+    fallbackLocale: z
+      .string()
+      .describe('Optional: fallback locale code to use when requested locale is not available')
+      .optional(),
+    locale: z
+      .string()
+      .describe(
+        'Optional: locale code to create the document in (e.g., "en", "es"). Defaults to the default locale',
+      )
+      .optional(),
+    select: z
+      .record(z.string(), z.unknown())
+      .describe(
+        'Optional: define exactly which fields you\'d like to return, e.g., {"title": true}',
+      )
+      .optional(),
+  }),
 }).handler(async ({ authorizedMCP, collectionSlug, input, req }) => {
   const payload = req.payload
   const logger = getLogger({ payload })
@@ -64,20 +71,16 @@ export const createCollectionTool = defineCollectionTool({
   )
 
   try {
-    let parsedData = transformPointDataToPayload(data)
     const virtualFieldNames = getCollectionVirtualFieldNames(payload.config, collectionSlug)
-    parsedData = stripVirtualFields(parsedData, virtualFieldNames)
+    const inputData = stripVirtualFields(data, virtualFieldNames)
+    const validationError = validateCollectionData({ collectionSlug, data: inputData, req })
 
-    let selectClause: SelectType | undefined
-    if (select) {
-      try {
-        selectClause = JSON.parse(select) as SelectType
-      } catch {
-        logger.warn(`Invalid select clause JSON: ${select}`)
-        return { content: [{ type: 'text', text: 'Error: Invalid JSON in select clause' }] }
-      }
+    if (validationError) {
+      return validationError
     }
 
+    const parsedData = transformPointDataToPayload(inputData)
+
     const result = await payload.create({
       collection: collectionSlug,
       data: parsedData,
@@ -87,7 +90,7 @@ export const createCollectionTool = defineCollectionTool({
       ...localAPIDefaults(authorizedMCP),
       ...(locale ? { locale } : {}),
       ...(fallbackLocale ? { fallbackLocale } : {}),
-      ...(selectClause ? { select: selectClause } : {}),
+      ...(select ? { select: select as SelectType } : {}),
     })
 
     logger.info(`Successfully created document in ${collectionSlug} with ID: ${result.id}`)
@@ -104,13 +107,6 @@ export const createCollectionTool = defineCollectionTool({
   } catch (error) {
     const errorMessage = error instanceof Error ? error.message : 'Unknown error'
     logger.error(`Error creating document in ${collectionSlug}: ${errorMessage}`)
-    return {
-      content: [
-        {
-          type: 'text',
-          text: `Error creating document in collection "${collectionSlug}": ${errorMessage}`,
-        },
-      ],
-    }
+    return formatCollectionError({ action: 'creating', collectionSlug, error, req })
   }
 })

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

@@ -1,12 +1,24 @@
 import { z } from 'zod'
 
+import { defaultAccess } from '../../../defaultAccess.js'
 import { defineCollectionTool } from '../../../defineTool.js'
 import { getLogger } from '../../../utils/getLogger.js'
 import { localAPIDefaults } from '../../../utils/localAPIDefaults.js'
+import { whereSchema } from '../../../utils/whereSchema.js'
 
-const DEFAULT_DESCRIPTION = 'Delete documents in a collection by ID or where clause.'
+const DEFAULT_DESCRIPTION =
+  'Delete documents in any collection by passing the collection slug and ID or where clause.'
 
-export const deleteCollectionTool = defineCollectionTool({
+export const deleteDocumentsTool = defineCollectionTool({
+  access: (args) =>
+    defaultAccess(args) && Boolean(args.permissions?.collections?.[args.collectionSlug]?.delete),
+  annotations: {
+    destructiveHint: true,
+    idempotentHint: false,
+    openWorldHint: false,
+    readOnlyHint: false,
+    title: 'Delete Documents',
+  },
   description: DEFAULT_DESCRIPTION,
   input: z.object({
     id: z
@@ -31,9 +43,10 @@ export const deleteCollectionTool = defineCollectionTool({
         'Optional: locale code for the operation (e.g., "en", "es"). Defaults to the default locale',
       )
       .optional(),
-    where: z
-      .string()
-      .describe('Optional: JSON string for where clause to delete multiple documents')
+    where: whereSchema
+      .describe(
+        'Optional: where clause to delete multiple documents. Use field names with Payload operators, and/or arrays for grouping. Example: {"title":{"contains":"test"}}',
+      )
       .optional(),
   }),
 }).handler(async ({ authorizedMCP, collectionSlug, input, req }) => {
@@ -53,16 +66,6 @@ export const deleteCollectionTool = defineCollectionTool({
       }
     }
 
-    let whereClause: Record<string, unknown> = {}
-    if (where) {
-      try {
-        whereClause = JSON.parse(where) as Record<string, unknown>
-      } catch {
-        logger.warn(`Invalid where clause JSON: ${where}`)
-        return { content: [{ type: 'text', text: 'Error: Invalid JSON in where clause' }] }
-      }
-    }
-
     const deleteOptions: Record<string, unknown> = {
       collection: collectionSlug,
       depth,
@@ -75,7 +78,7 @@ export const deleteCollectionTool = defineCollectionTool({
     if (id) {
       deleteOptions.id = id
     } else {
-      deleteOptions.where = whereClause
+      deleteOptions.where = where
     }
 
     const result = await payload.delete(deleteOptions as Parameters<typeof payload.delete>[0])

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

@@ -0,0 +1,135 @@
+import type { PopulateType, SelectType } from 'payload'
+
+import { z } from 'zod'
+
+import { defaultAccess } from '../../../defaultAccess.js'
+import { defineCollectionTool } from '../../../defineTool.js'
+import { getLogger } from '../../../utils/getLogger.js'
+import {
+  getCollectionVirtualFieldNames,
+  stripVirtualFields,
+} from '../../../utils/getVirtualFieldNames.js'
+import { localAPIDefaults } from '../../../utils/localAPIDefaults.js'
+import { transformPointDataToPayload } from '../../../utils/transformPointDataToPayload.js'
+import { formatCollectionError } from './formatCollectionError.js'
+
+const DEFAULT_DESCRIPTION =
+  'Duplicate a document in any collection by passing the collection slug and source document ID.'
+
+export const duplicateDocumentTool = defineCollectionTool({
+  access: (args) =>
+    defaultAccess(args) && Boolean(args.permissions?.collections?.[args.collectionSlug]?.create),
+  annotations: {
+    destructiveHint: false,
+    idempotentHint: false,
+    openWorldHint: false,
+    readOnlyHint: false,
+    title: 'Duplicate Document',
+  },
+  description: DEFAULT_DESCRIPTION,
+  input: z.object({
+    id: z.union([z.string(), z.number()]).describe('The ID of the document to duplicate'),
+    data: z
+      .record(z.string(), z.unknown())
+      .describe('Optional: fields to override on the duplicated document')
+      .optional(),
+    depth: z
+      .number()
+      .int()
+      .min(0)
+      .max(10)
+      .describe('How many levels deep to populate relationships in response')
+      .optional()
+      .default(0),
+    draft: z
+      .boolean()
+      .describe('Whether to create the duplicate as a draft')
+      .optional()
+      .default(false),
+    fallbackLocale: z
+      .string()
+      .describe('Optional: fallback locale code to use when requested locale is not available')
+      .optional(),
+    locale: z
+      .string()
+      .describe(
+        'Optional: locale code to duplicate in (e.g., "en", "es"). Defaults to the default locale',
+      )
+      .optional(),
+    populate: z
+      .record(z.string(), z.unknown())
+      .describe(
+        'Optional: control which fields to include from populated relationship or upload documents.',
+      )
+      .optional(),
+    select: z
+      .record(z.string(), z.unknown())
+      .describe(
+        'Optional: define exactly which fields you\'d like to return in the response, e.g., {"title": true}',
+      )
+      .optional(),
+    selectedLocales: z
+      .array(z.string())
+      .describe('Optional: localized field locales to include in the duplicated document')
+      .optional(),
+    showHiddenFields: z
+      .boolean()
+      .describe('Optional: include hidden fields in the duplicated document response')
+      .optional(),
+  }),
+}).handler(async ({ authorizedMCP, collectionSlug, input, req }) => {
+  const payload = req.payload
+  const logger = getLogger({ payload })
+  const {
+    id,
+    data,
+    depth,
+    draft,
+    fallbackLocale,
+    locale,
+    populate,
+    select,
+    selectedLocales,
+    showHiddenFields,
+  } = input
+
+  logger.info(`Duplicating document in collection: ${collectionSlug} with ID: ${id}`)
+
+  try {
+    const virtualFieldNames = getCollectionVirtualFieldNames(payload.config, collectionSlug)
+    const inputData = data ? stripVirtualFields(data, virtualFieldNames) : undefined
+    const parsedData = inputData ? transformPointDataToPayload(inputData) : undefined
+
+    const result = await payload.duplicate({
+      id,
+      collection: collectionSlug,
+      depth,
+      draft,
+      req,
+      ...localAPIDefaults(authorizedMCP),
+      ...(parsedData ? { data: parsedData } : {}),
+      ...(locale ? { locale } : {}),
+      ...(fallbackLocale ? { fallbackLocale } : {}),
+      ...(populate ? { populate: populate as PopulateType } : {}),
+      ...(select ? { select: select as SelectType } : {}),
+      ...(selectedLocales ? { selectedLocales } : {}),
+      ...(showHiddenFields !== undefined ? { showHiddenFields } : {}),
+    })
+
+    logger.info(`Successfully duplicated document in ${collectionSlug} from ID: ${id}`)
+
+    return {
+      content: [
+        {
+          type: 'text',
+          text: `Document duplicated successfully in collection "${collectionSlug}"!\nDuplicated document:\n\`\`\`json\n${JSON.stringify(result)}\n\`\`\``,
+        },
+      ],
+      doc: result as Record<string, unknown>,
+    }
+  } catch (error) {
+    const errorMessage = error instanceof Error ? error.message : 'Unknown error'
+    logger.error(`Error duplicating document in ${collectionSlug}: ${errorMessage}`)
+    return formatCollectionError({ action: 'duplicating', collectionSlug, error, req })
+  }
+})