@payloadcms/plugin-mcp 3.85.0 → 4.0.0-canary.0

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

@@ -0,0 +1,205 @@
+import type { SelectType } from 'payload'
+
+import { z } from 'zod'
+
+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 { prepareCollectionSchema } from '../../../utils/schemaConversion/prepareCollectionSchema.js'
+import { transformPointDataToPayload } from '../../../utils/transformPointDataToPayload.js'
+
+const DEFAULT_DESCRIPTION = 'Update documents in a collection by ID or where clause.'
+
+export const updateCollectionTool = defineCollectionTool({
+  description: DEFAULT_DESCRIPTION,
+  input: ({ collectionSchema }) => {
+    const partialSchema = prepareCollectionSchema(collectionSchema)
+
+    // Collection updates do not require all required fields to be passed => delete .required.
+    //
+    // Local API equivalent: packages/payload/src/collections/operations/local/update.ts#BaseOptions#data:
+    // data: DeepPartial<RequiredDataFromCollectionSlug<TSlug>>
+    delete partialSchema.required
+
+    return z.object({
+      id: z.union([z.string(), z.number()]).describe('The ID of the document to update').optional(),
+      data: z
+        .fromJSONSchema(partialSchema as unknown as z.core.JSONSchema.JSONSchema)
+        .describe('The fields to update'),
+      depth: z
+        .number()
+        .describe('How many levels deep to populate relationships')
+        .optional()
+        .default(0),
+      draft: z
+        .boolean()
+        .describe('Whether to update 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(),
+      filePath: z.string().describe('File path for file uploads').optional(),
+      locale: z
+        .string()
+        .describe(
+          'Optional: locale code to update the document in (e.g., "en", "es"). Defaults to the default locale',
+        )
+        .optional(),
+      overrideLock: z
+        .boolean()
+        .describe('Whether to override document locks')
+        .optional()
+        .default(true),
+      overwriteExistingFiles: z
+        .boolean()
+        .describe('Whether to overwrite existing files')
+        .optional()
+        .default(false),
+      select: z
+        .string()
+        .describe(
+          'Optional: define exactly which fields you\'d like to return in the response (JSON), e.g., \'{"title": "My Post"}\'',
+        )
+        .optional(),
+      where: z
+        .string()
+        .describe('JSON string for where clause to update multiple documents')
+        .optional(),
+    })
+  },
+}).handler(async ({ authorizedMCP, collectionSlug, input, req }) => {
+  const payload = req.payload
+  const logger = getLogger({ payload })
+
+  const {
+    id,
+    data,
+    depth,
+    draft,
+    fallbackLocale,
+    filePath,
+    locale,
+    overrideLock,
+    overwriteExistingFiles,
+    select,
+    where,
+  } = input
+
+  logger.info(
+    `Updating document in collection: ${collectionSlug}${id ? ` with ID: ${id}` : ' with where clause'}, draft: ${draft}${locale ? `, locale: ${locale}` : ''}`,
+  )
+
+  try {
+    if (!id && !where) {
+      return {
+        content: [{ type: 'text', text: 'Error: Either id or where clause must be provided' }],
+      }
+    }
+
+    let parsedData = transformPointDataToPayload(data as Record<string, unknown>)
+    const virtualFieldNames = getCollectionVirtualFieldNames(payload.config, collectionSlug)
+    parsedData = stripVirtualFields(parsedData, virtualFieldNames)
+
+    let whereClause: Record<string, unknown> = {}
+    if (where) {
+      try {
+        whereClause = JSON.parse(where) as Record<string, unknown>
+      } catch {
+        logger.error(`Invalid where clause JSON: ${where}`)
+        return { content: [{ type: 'text', text: 'Error: Invalid JSON in where clause' }] }
+      }
+    }
+
+    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 (id) {
+      const updateOptions = {
+        id,
+        collection: collectionSlug,
+        data: parsedData,
+        depth,
+        draft,
+        overrideLock,
+        req,
+        ...localAPIDefaults(authorizedMCP),
+        ...(filePath ? { filePath } : {}),
+        ...(overwriteExistingFiles ? { overwriteExistingFiles } : {}),
+        ...(locale ? { locale } : {}),
+        ...(fallbackLocale ? { fallbackLocale } : {}),
+        ...(selectClause ? { select: selectClause } : {}),
+      }
+
+      const result = await payload.update(updateOptions as any)
+
+      return {
+        content: [
+          {
+            type: 'text',
+            text: `Document updated successfully in collection "${collectionSlug}"!\nUpdated document:\n\`\`\`json\n${JSON.stringify(result)}\n\`\`\``,
+          },
+        ],
+        doc: result as Record<string, unknown>,
+      }
+    }
+
+    const updateOptions = {
+      collection: collectionSlug,
+      data: parsedData,
+      depth,
+      draft,
+      overrideLock,
+      req,
+      ...localAPIDefaults(authorizedMCP),
+      where: whereClause,
+      ...(filePath ? { filePath } : {}),
+      ...(overwriteExistingFiles ? { overwriteExistingFiles } : {}),
+      ...(locale ? { locale } : {}),
+      ...(fallbackLocale ? { fallbackLocale } : {}),
+      ...(selectClause ? { select: selectClause } : {}),
+    }
+
+    const result = await payload.update(updateOptions as any)
+
+    const bulkResult = result as { docs?: unknown[]; errors?: unknown[] }
+    const docs = bulkResult.docs || []
+    const errors = bulkResult.errors || []
+
+    let responseText = `Multiple documents updated in collection "${collectionSlug}"!\nUpdated: ${docs.length} documents\nErrors: ${errors.length}\n---`
+    if (docs.length > 0) {
+      responseText += `\n\nUpdated documents:\n\`\`\`json\n${JSON.stringify(docs)}\n\`\`\``
+    }
+    if (errors.length > 0) {
+      responseText += `\n\nErrors:\n\`\`\`json\n${JSON.stringify(errors)}\n\`\`\``
+    }
+
+    return {
+      content: [{ type: 'text', text: responseText }],
+      doc: { docs, errors } as unknown as Record<string, unknown>,
+    }
+  } catch (error) {
+    const errorMessage = error instanceof Error ? error.message : 'Unknown error'
+    logger.error(`Error updating document in ${collectionSlug}: ${errorMessage}`)
+    return {
+      content: [
+        {
+          type: 'text',
+          text: `Error updating document in collection "${collectionSlug}": ${errorMessage}`,
+        },
+      ],
+    }
+  }
+})

package/src/mcp/builtin/globals/findTool.ts

@@ -0,0 +1,96 @@
+import type { SelectType } from 'payload'
+
+import { z } from 'zod'
+
+import { defineGlobalTool } from '../../../defineTool.js'
+import { getLogger } from '../../../utils/getLogger.js'
+import { localAPIDefaults } from '../../../utils/localAPIDefaults.js'
+
+const DEFAULT_DESCRIPTION = 'Find a Payload global singleton configuration.'
+
+export const findGlobalTool = defineGlobalTool({
+  description: DEFAULT_DESCRIPTION,
+  input: z.object({
+    depth: z
+      .number()
+      .int()
+      .min(0)
+      .max(10)
+      .describe('Depth of population for relationships')
+      .optional()
+      .default(0),
+    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 retrieve data in (e.g., "en", "es"). Use "all" to retrieve all locales for localized fields',
+      )
+      .optional(),
+    select: z
+      .string()
+      .describe(
+        "Optional: define exactly which fields you'd like to return in the response (JSON), e.g., '{\"title\": true}'",
+      )
+      .optional(),
+  }),
+}).handler(async ({ authorizedMCP, globalSlug, input, req }) => {
+  const payload = req.payload
+  const logger = getLogger({ payload })
+
+  const { depth, fallbackLocale, locale, select } = input
+
+  logger.info(
+    `Reading global: ${globalSlug}, depth: ${depth}${locale ? `, locale: ${locale}` : ''}`,
+  )
+
+  try {
+    const findOptions: Parameters<typeof payload.findGlobal>[0] = {
+      slug: globalSlug,
+      depth,
+      ...localAPIDefaults(authorizedMCP),
+    }
+
+    let selectClause: SelectType | undefined
+    if (select) {
+      try {
+        selectClause = JSON.parse(select) as SelectType
+      } catch {
+        logger.warn(`Invalid select clause JSON for global: ${select}`)
+        return { content: [{ type: 'text', text: 'Error: Invalid JSON in select clause' }] }
+      }
+    }
+
+    if (locale) {
+      findOptions.locale = locale
+    }
+    if (fallbackLocale) {
+      findOptions.fallbackLocale = fallbackLocale
+    }
+    if (selectClause) {
+      findOptions.select = selectClause
+    }
+
+    const result = await payload.findGlobal(findOptions)
+
+    return {
+      content: [
+        {
+          type: 'text',
+          text: `Global "${globalSlug}":\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 reading global ${globalSlug}: ${errorMessage}`)
+    return {
+      content: [
+        { type: 'text', text: `❌ **Error reading global "${globalSlug}":** ${errorMessage}` },
+      ],
+    }
+  }
+})

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

@@ -0,0 +1,118 @@
+import type { SelectType } from 'payload'
+
+import { z } from 'zod'
+
+import { defineGlobalTool } from '../../../defineTool.js'
+import { getLogger } from '../../../utils/getLogger.js'
+import {
+  getGlobalVirtualFieldNames,
+  stripVirtualFields,
+} from '../../../utils/getVirtualFieldNames.js'
+import { localAPIDefaults } from '../../../utils/localAPIDefaults.js'
+import { prepareCollectionSchema } from '../../../utils/schemaConversion/prepareCollectionSchema.js'
+
+const DEFAULT_DESCRIPTION = 'Update a Payload global singleton configuration.'
+
+export const updateGlobalTool = defineGlobalTool({
+  description: DEFAULT_DESCRIPTION,
+  input: ({ globalSchema }) => {
+    const partialSchema = prepareCollectionSchema(globalSchema)
+    // Global updates do not require all required fields to be passed => delete .required.
+    //
+    // Local API equivalent: packages/payload/src/global/operations/local/update.ts#BaseOptions#data:
+    // data: DeepPartial<Omit<DataFromGlobalSlug<TSlug>, 'id'>>
+    delete partialSchema.required
+
+    return z.object({
+      data: z
+        .fromJSONSchema(partialSchema as unknown as z.core.JSONSchema.JSONSchema)
+        .describe('The fields to update'),
+      depth: z
+        .number()
+        .describe('Optional: Depth of relationships to populate')
+        .optional()
+        .default(0),
+      draft: z
+        .boolean()
+        .describe('Optional: Whether to save as draft (default: false)')
+        .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 update data in (e.g., "en", "es"). Use "all" to update all locales for localized fields',
+        )
+        .optional(),
+      select: z
+        .string()
+        .describe(
+          'Optional: define exactly which fields you\'d like to return in the response (JSON), e.g., \'{"siteName": "My Site"}\'',
+        )
+        .optional(),
+    })
+  },
+}).handler(async ({ authorizedMCP, globalSlug, input, req }) => {
+  const payload = req.payload
+  const logger = getLogger({ payload })
+
+  const { data, depth, draft, fallbackLocale, locale, select } = input
+
+  logger.info(
+    `Updating global: ${globalSlug}, draft: ${draft}${locale ? `, locale: ${locale}` : ''}`,
+  )
+
+  try {
+    const virtualFieldNames = getGlobalVirtualFieldNames(payload.config, globalSlug)
+    const parsedData = stripVirtualFields(data as Record<string, unknown>, virtualFieldNames)
+
+    let selectClause: SelectType | undefined
+    if (select) {
+      try {
+        selectClause = JSON.parse(select) as SelectType
+      } catch {
+        logger.warn(`Invalid select clause JSON for global: ${select}`)
+        return { content: [{ type: 'text', text: 'Error: Invalid JSON in select clause' }] }
+      }
+    }
+
+    const updateOptions: Parameters<typeof payload.updateGlobal>[0] = {
+      slug: globalSlug,
+      data: parsedData,
+      depth,
+      draft,
+      ...localAPIDefaults(authorizedMCP),
+    }
+
+    if (locale) {
+      updateOptions.locale = locale
+    }
+    if (fallbackLocale) {
+      updateOptions.fallbackLocale = fallbackLocale
+    }
+    if (selectClause) {
+      updateOptions.select = selectClause
+    }
+
+    const result = await payload.updateGlobal(updateOptions)
+
+    return {
+      content: [
+        {
+          type: 'text',
+          text: `Global "${globalSlug}" updated successfully!\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 updating global ${globalSlug}: ${errorMessage}`)
+    return {
+      content: [{ type: 'text', text: `Error updating global "${globalSlug}": ${errorMessage}` }],
+    }
+  }
+})

package/src/mcp/builtinTools.ts

@@ -0,0 +1,84 @@
+import type { CollectionTool, GlobalTool } from '../types.js'
+
+import {
+  authCollectionTool,
+  forgotPasswordCollectionTool,
+  loginCollectionTool,
+  resetPasswordCollectionTool,
+  unlockCollectionTool,
+  verifyCollectionTool,
+} from './builtin/collections/authTools.js'
+import { createCollectionTool } from './builtin/collections/createTool.js'
+import { deleteCollectionTool } from './builtin/collections/deleteTool.js'
+import { findCollectionTool } from './builtin/collections/findTool.js'
+import { updateCollectionTool } from './builtin/collections/updateTool.js'
+import { findGlobalTool } from './builtin/globals/findTool.js'
+import { updateGlobalTool } from './builtin/globals/updateTool.js'
+
+/**
+ * The static built-in collection CRUD tools. Keys here are the source of truth
+ * for `MCPCollectionBuiltinName` — adding/removing an entry updates the type
+ * automatically.
+ */
+export const COLLECTION_BUILTINS: Record<MCPCollectionBuiltinName, CollectionTool> = {
+  create: createCollectionTool,
+  delete: deleteCollectionTool,
+  find: findCollectionTool,
+  update: updateCollectionTool,
+}
+
+/**
+ * The static auth tools surfaced under auth-enabled collections. Each entry
+ * carries the admin-UI label alongside the tool. Keys are the source of truth
+ * for `MCPCollectionAuthToolName`.
+ */
+export const COLLECTION_AUTH_BUILTINS: Record<
+  MCPCollectionAuthToolName,
+  { label: string; tool: CollectionTool }
+> = {
+  auth: { label: 'Check Auth Status', tool: authCollectionTool },
+  forgotPassword: { label: 'Forgot Password', tool: forgotPasswordCollectionTool },
+  login: { label: 'User Login', tool: loginCollectionTool },
+  resetPassword: { label: 'Reset Password', tool: resetPasswordCollectionTool },
+  unlock: { label: 'Unlock Account', tool: unlockCollectionTool },
+  verify: { label: 'Email Verification', tool: verifyCollectionTool },
+}
+
+/**
+ * The static built-in global tools. Keys are the source of truth for
+ * `MCPGlobalBuiltinName`.
+ */
+export const GLOBAL_BUILTINS: Record<MCPGlobalBuiltinName, GlobalTool> = {
+  find: findGlobalTool,
+  update: updateGlobalTool,
+}
+
+export type MCPCollectionBuiltinName = 'create' | 'delete' | 'find' | 'update'
+
+export type MCPCollectionAuthToolName =
+  | 'auth'
+  | 'forgotPassword'
+  | 'login'
+  | 'resetPassword'
+  | 'unlock'
+  | 'verify'
+
+export type MCPGlobalBuiltinName = 'find' | 'update'
+
+/**
+ * Pre-typed `Object.entries` for each registry. The cast from `string` to the
+ * literal key union lives here once so consumers can iterate without their own
+ * cast — TypeScript's `Object.entries` always widens keys to `string`, which
+ * defeats the narrow type lookups on `MCPCollectionToolsMap`.
+ */
+export const COLLECTION_BUILTIN_ENTRIES = Object.entries(COLLECTION_BUILTINS) as Array<
+  [MCPCollectionBuiltinName, CollectionTool]
+>
+
+export const COLLECTION_AUTH_BUILTIN_ENTRIES = Object.entries(COLLECTION_AUTH_BUILTINS) as Array<
+  [MCPCollectionAuthToolName, { label: string; tool: CollectionTool }]
+>
+
+export const GLOBAL_BUILTIN_ENTRIES = Object.entries(GLOBAL_BUILTINS) as Array<
+  [MCPGlobalBuiltinName, GlobalTool]
+>