@payloadcms/plugin-mcp 0.0.1-alpha.0

package/src/mcp/helpers/fileValidation.ts

@@ -0,0 +1,417 @@
+import type { CollectionConfig } from 'payload'
+
+import { existsSync } from 'fs'
+import { join } from 'path'
+
+export type ValidationType = 'collection' | 'task' | 'workflow'
+
+export interface ValidationResult<T = unknown> {
+  config?: T
+  error?: string
+  success: boolean
+}
+
+// Custom task config interface that matches what we're creating
+export interface TaskConfig {
+  handler: (args: {
+    input: Record<string, unknown>
+    job: Record<string, unknown>
+    tasks: Record<string, unknown>
+  }) => Record<string, unknown>
+  inputSchema?: Array<{
+    label?: string
+    name: string
+    options?: Array<{ label: string; value: string }>
+    required?: boolean
+    type: string
+  }>
+  label?: string
+  outputSchema?: Array<{
+    label?: string
+    name: string
+    options?: Array<{ label: string; value: string }>
+    required?: boolean
+    type: string
+  }>
+  retries?: number
+  slug: string
+}
+
+// Custom workflow config interface that matches what we're creating
+export interface WorkflowConfig {
+  handler: (args: {
+    input: Record<string, unknown>
+    job: Record<string, unknown>
+    tasks: Record<string, unknown>
+  }) => void
+  inputSchema?: Array<{
+    label?: string
+    name: string
+    options?: Array<{ label: string; value: string }>
+    required?: boolean
+    type: string
+  }>
+  label?: string
+  queue?: string
+  retries?: number
+  slug: string
+}
+
+/**
+ * Generic validation function for Payload configuration files
+ * @param fileName - The name of the file (e.g., 'Users.ts', 'my-task.ts')
+ * @param type - The type of validation to perform ('collection', 'task', or 'workflow')
+ * @returns Object containing success status and any error messages
+ */
+export const validatePayloadFile = async <T = CollectionConfig | TaskConfig | WorkflowConfig>(
+  fileName: string,
+  type: ValidationType,
+): Promise<ValidationResult<T>> => {
+  try {
+    const basePath = type === 'collection' ? 'collections' : type === 'task' ? 'tasks' : 'workflows'
+    const fullPath = join(process.cwd(), 'src', basePath)
+    const filePath = join(fullPath, fileName)
+
+    // Check if file exists
+    if (!existsSync(filePath)) {
+      return {
+        error: `${type} file does not exist: ${fileName}`,
+        success: false,
+      }
+    }
+
+    // Clear require cache to ensure fresh import
+    delete require.cache[filePath]
+
+    // Use relative path for webpack compatibility
+    const moduleName = fileName.replace('.ts', '')
+    const relativePath = `../${basePath}/${moduleName}`
+
+    // Dynamic import with relative path
+    const importedModule = await import(/* webpackIgnore: true */ relativePath)
+
+    // Get the configuration based on type
+    let config: T | undefined
+
+    if (type === 'collection') {
+      config = getCollectionConfig(importedModule, moduleName) as T
+    } else if (type === 'task') {
+      config = getTaskConfig(importedModule) as T
+    } else if (type === 'workflow') {
+      config = getWorkflowConfig(importedModule) as T
+    }
+
+    if (!config) {
+      return {
+        error: `${type} file does not export a valid ${type} config`,
+        success: false,
+      }
+    }
+
+    // Validate the configuration
+    let validationResult: ValidationResult<unknown>
+    if (type === 'collection') {
+      validationResult = validateCollectionConfig(config as unknown as CollectionConfig)
+    } else if (type === 'task') {
+      validationResult = validateTaskConfig(config as unknown as TaskConfig)
+    } else if (type === 'workflow') {
+      validationResult = validateWorkflowConfig(config as unknown as WorkflowConfig)
+    } else {
+      return {
+        error: `Unknown validation type: ${type}`,
+        success: false,
+      }
+    }
+
+    if (!validationResult.success) {
+      return validationResult as ValidationResult<T>
+    }
+
+    return {
+      config,
+      success: true,
+    }
+  } catch (error) {
+    const errorMessage = error instanceof Error ? error.message : 'Unknown error during validation'
+    return {
+      error: `Failed to validate ${type} file: ${errorMessage}`,
+      success: false,
+    }
+  }
+}
+
+/**
+ * Extract collection configuration from module exports
+ */
+function getCollectionConfig(
+  importedModule: Record<string, unknown>,
+  moduleName: string,
+): CollectionConfig | undefined {
+  if (importedModule.default) {
+    return importedModule.default as CollectionConfig
+  }
+
+  if (importedModule[moduleName]) {
+    return importedModule[moduleName] as CollectionConfig
+  }
+
+  return undefined
+}
+
+/**
+ * Extract task configuration from module exports
+ */
+function getTaskConfig(importedModule: Record<string, unknown>): TaskConfig | undefined {
+  // First check for default export
+  if (importedModule.default) {
+    return importedModule.default as TaskConfig
+  }
+
+  // Look for named exports ending with "Task"
+  const exportNames = Object.keys(importedModule)
+  const taskExport = exportNames.find((name) => name.endsWith('Task'))
+
+  if (taskExport) {
+    return importedModule[taskExport] as TaskConfig
+  }
+
+  return undefined
+}
+
+/**
+ * Extract workflow configuration from module exports
+ */
+function getWorkflowConfig(importedModule: Record<string, unknown>): undefined | WorkflowConfig {
+  // First check for default export
+  if (importedModule.default) {
+    return importedModule.default as WorkflowConfig
+  }
+
+  // Look for named exports ending with "Workflow"
+  const exportNames = Object.keys(importedModule)
+  const workflowExport = exportNames.find((name) => name.endsWith('Workflow'))
+
+  if (workflowExport) {
+    return importedModule[workflowExport] as WorkflowConfig
+  }
+
+  return undefined
+}
+
+/**
+ * Validate collection configuration structure
+ */
+function validateCollectionConfig(config: CollectionConfig): ValidationResult<CollectionConfig> {
+  if (!config || typeof config !== 'object') {
+    return {
+      error: 'Collection config is not a valid object',
+      success: false,
+    }
+  }
+
+  if (!config.slug || typeof config.slug !== 'string') {
+    return {
+      error: 'Collection config must have a valid slug property',
+      success: false,
+    }
+  }
+
+  // Validate each field has required properties
+  if (config.fields) {
+    for (let i = 0; i < config.fields.length; i++) {
+      const field = config.fields[i] as Record<string, unknown>
+      if (!field || typeof field !== 'object') {
+        return {
+          error: `Field at index ${i} is not a valid object`,
+          success: false,
+        }
+      }
+
+      // Check if field has type property
+      if ('type' in field && field.type && typeof field.type !== 'string') {
+        return {
+          error: `Field at index ${i} has invalid type property`,
+          success: false,
+        }
+      }
+    }
+  }
+
+  return { config, success: true }
+}
+
+/**
+ * Validate task configuration structure
+ */
+function validateTaskConfig(config: TaskConfig): ValidationResult<TaskConfig> {
+  if (!config || typeof config !== 'object') {
+    return {
+      error: 'Task config is not a valid object',
+      success: false,
+    }
+  }
+
+  if (!config.slug || typeof config.slug !== 'string') {
+    return {
+      error: 'Task config must have a valid slug property',
+      success: false,
+    }
+  }
+
+  if (!config.handler || typeof config.handler !== 'function') {
+    return {
+      error: 'Task config must have a valid handler function',
+      success: false,
+    }
+  }
+
+  // Validate optional properties
+  if (config.retries !== undefined && (typeof config.retries !== 'number' || config.retries < 0)) {
+    return {
+      error: 'Task config retries must be a non-negative number',
+      success: false,
+    }
+  }
+
+  // Validate schemas if present
+  if (config.inputSchema && Array.isArray(config.inputSchema)) {
+    for (let i = 0; i < config.inputSchema.length; i++) {
+      const field = config.inputSchema[i]
+      if (!field || typeof field !== 'object') {
+        return {
+          error: `Input schema field at index ${i} is not a valid object`,
+          success: false,
+        }
+      }
+
+      if (!field.name || typeof field.name !== 'string') {
+        return {
+          error: `Input schema field at index ${i} must have a valid name property`,
+          success: false,
+        }
+      }
+
+      if (!field.type || typeof field.type !== 'string') {
+        return {
+          error: `Input schema field at index ${i} must have a valid type property`,
+          success: false,
+        }
+      }
+    }
+  }
+
+  if (config.outputSchema && Array.isArray(config.outputSchema)) {
+    for (let i = 0; i < config.outputSchema.length; i++) {
+      const field = config.outputSchema[i]
+      if (!field || typeof field !== 'object') {
+        return {
+          error: `Output schema field at index ${i} is not a valid object`,
+          success: false,
+        }
+      }
+
+      if (!field.name || typeof field.name !== 'string') {
+        return {
+          error: `Output schema field at index ${i} must have a valid name property`,
+          success: false,
+        }
+      }
+
+      if (!field.type || typeof field.type !== 'string') {
+        return {
+          error: `Output schema field at index ${i} must have a valid type property`,
+          success: false,
+        }
+      }
+    }
+  }
+
+  return { config, success: true }
+}
+
+/**
+ * Validate workflow configuration structure
+ */
+function validateWorkflowConfig(config: WorkflowConfig): ValidationResult<WorkflowConfig> {
+  if (!config || typeof config !== 'object') {
+    return {
+      error: 'Workflow config is not a valid object',
+      success: false,
+    }
+  }
+
+  if (!config.slug || typeof config.slug !== 'string') {
+    return {
+      error: 'Workflow config must have a valid slug property',
+      success: false,
+    }
+  }
+
+  if (!config.handler || typeof config.handler !== 'function') {
+    return {
+      error: 'Workflow config must have a valid handler function',
+      success: false,
+    }
+  }
+
+  // Validate optional properties
+  if (config.queue && typeof config.queue !== 'string') {
+    return {
+      error: 'Workflow config queue must be a string',
+      success: false,
+    }
+  }
+
+  if (config.retries !== undefined && (typeof config.retries !== 'number' || config.retries < 0)) {
+    return {
+      error: 'Workflow config retries must be a non-negative number',
+      success: false,
+    }
+  }
+
+  // Validate schema if present
+  if (config.inputSchema && Array.isArray(config.inputSchema)) {
+    for (let i = 0; i < config.inputSchema.length; i++) {
+      const field = config.inputSchema[i]
+      if (!field || typeof field !== 'object') {
+        return {
+          error: `Input schema field at index ${i} is not a valid object`,
+          success: false,
+        }
+      }
+
+      if (!field.name || typeof field.name !== 'string') {
+        return {
+          error: `Input schema field at index ${i} must have a valid name property`,
+          success: false,
+        }
+      }
+
+      if (!field.type || typeof field.type !== 'string') {
+        return {
+          error: `Input schema field at index ${i} must have a valid type property`,
+          success: false,
+        }
+      }
+    }
+  }
+
+  return { config, success: true }
+}
+
+// Convenience functions for backward compatibility
+export const validateCollectionFile = async (
+  fileName: string,
+): Promise<ValidationResult<CollectionConfig>> => {
+  return validatePayloadFile<CollectionConfig>(fileName, 'collection')
+}
+
+export const validateTaskFile = async (fileName: string): Promise<ValidationResult<TaskConfig>> => {
+  return validatePayloadFile<TaskConfig>(fileName, 'task')
+}
+
+export const validateWorkflowFile = async (
+  fileName: string,
+): Promise<ValidationResult<WorkflowConfig>> => {
+  return validatePayloadFile<WorkflowConfig>(fileName, 'workflow')
+}

package/src/mcp/helpers/validation.ts

@@ -0,0 +1,32 @@
+/**
+ * Validates collection-specific data for resource creation
+ */
+export function validateCollectionData(
+  collection: string,
+  data: Record<string, unknown>,
+  availableCollections: string[],
+): null | string {
+  // Check if collection exists
+  if (!availableCollections.includes(collection)) {
+    return `Unknown collection: ${collection}. Available collections: ${availableCollections.join(', ')}`
+  }
+
+  if (!data || typeof data !== 'object' || Object.keys(data).length === 0) {
+    return `Collection "${collection}" requires data to be provided`
+  }
+
+  return null
+}
+
+/**
+ * Checks if a collection slug is valid
+ */
+export function validateCollectionSlug(
+  collection: string,
+  collections: Partial<Record<string, true>>,
+) {
+  const collectionSlugs = Object.keys(collections)
+  if (!collectionSlugs.includes(collection)) {
+    return `Collection "${collection}" is not valid`
+  }
+}

package/src/mcp/registerTool.ts

@@ -0,0 +1,22 @@
+export const registerTool = (
+  isEnabled: boolean | undefined,
+  toolType: string,
+  registrationFn: () => void,
+  payload: { logger: { info: (message: string) => void } },
+  useVerboseLogs: boolean,
+) => {
+  if (isEnabled) {
+    try {
+      registrationFn()
+      if (useVerboseLogs) {
+        payload.logger.info(`[payload-mcp] ✅ Tool: ${toolType} Registered.`)
+      }
+    } catch (error) {
+      // Log the error and re-throw
+      payload.logger.info(`[payload-mcp] ❌ Tool: ${toolType} Failed to register.`)
+      throw error
+    }
+  } else if (useVerboseLogs) {
+    payload.logger.info(`[payload-mcp] ⏭️ Tool: ${toolType} Skipped.`)
+  }
+}

package/src/mcp/tools/auth/auth.ts

@@ -0,0 +1,69 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
+import type { PayloadRequest } from 'payload'
+
+import { toolSchemas } from '../schemas.js'
+
+export const authTool = (server: McpServer, req: PayloadRequest, verboseLogs: boolean) => {
+  const tool = async (headers?: string) => {
+    const payload = req.payload
+
+    if (verboseLogs) {
+      payload.logger.info('[payload-mcp] Checking authentication status')
+    }
+
+    try {
+      // Parse custom headers if provided, otherwise use empty headers
+      let authHeaders = new Headers()
+
+      if (headers) {
+        try {
+          const parsedHeaders = JSON.parse(headers)
+          authHeaders = new Headers(parsedHeaders)
+          if (verboseLogs) {
+            payload.logger.info(`[payload-mcp] Using custom headers: ${headers}`)
+          }
+        } catch (_ignore) {
+          payload.logger.warn(`[payload-mcp] Invalid headers JSON: ${headers}, using empty headers`)
+        }
+      }
+
+      const result = await payload.auth({
+        headers: authHeaders,
+      })
+
+      if (verboseLogs) {
+        payload.logger.info('[payload-mcp] Authentication check completed successfully')
+      }
+
+      return {
+        content: [
+          {
+            type: 'text' as const,
+            text: `# Authentication Status\n\n\`\`\`json\n${JSON.stringify(result, null, 2)}\n\`\`\``,
+          },
+        ],
+      }
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : 'Unknown error'
+      payload.logger.error(`[payload-mcp] Error checking authentication: ${errorMessage}`)
+
+      return {
+        content: [
+          {
+            type: 'text' as const,
+            text: `❌ **Error checking authentication**: ${errorMessage}`,
+          },
+        ],
+      }
+    }
+  }
+
+  server.tool(
+    'auth',
+    toolSchemas.auth.description,
+    toolSchemas.auth.parameters.shape,
+    async ({ headers }) => {
+      return await tool(headers)
+    },
+  )
+}

package/src/mcp/tools/auth/forgotPassword.ts

@@ -0,0 +1,68 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
+import type { PayloadRequest } from 'payload'
+
+import { toolSchemas } from '../schemas.js'
+
+export const forgotPasswordTool = (
+  server: McpServer,
+  req: PayloadRequest,
+  verboseLogs: boolean,
+) => {
+  const tool = async (collection: string, email: string, disableEmail: boolean = false) => {
+    const payload = req.payload
+
+    if (verboseLogs) {
+      payload.logger.info(
+        `[payload-mcp] Sending password reset email for user: ${email} in collection: ${collection}`,
+      )
+    }
+
+    try {
+      const result = await payload.forgotPassword({
+        collection,
+        data: {
+          email,
+        },
+        disableEmail,
+      })
+
+      if (verboseLogs) {
+        payload.logger.info(
+          `[payload-mcp] Password reset email sent successfully for user: ${email}`,
+        )
+      }
+
+      return {
+        content: [
+          {
+            type: 'text' as const,
+            text: `# Password Reset Email Sent\n\n**User:** ${email}\n**Collection:** ${collection}\n**Email Disabled:** ${disableEmail}\n\n\`\`\`json\n${JSON.stringify(result, null, 2)}\n\`\`\``,
+          },
+        ],
+      }
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : 'Unknown error'
+      payload.logger.error(
+        `[payload-mcp] Error sending password reset email for user ${email}: ${errorMessage}`,
+      )
+
+      return {
+        content: [
+          {
+            type: 'text' as const,
+            text: `❌ **Error sending password reset email for user "${email}"**: ${errorMessage}`,
+          },
+        ],
+      }
+    }
+  }
+
+  server.tool(
+    'forgotPassword',
+    toolSchemas.forgotPassword.description,
+    toolSchemas.forgotPassword.parameters.shape,
+    async ({ collection, disableEmail, email }) => {
+      return await tool(collection, email, disableEmail)
+    },
+  )
+}

package/src/mcp/tools/auth/login.ts

@@ -0,0 +1,70 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
+import type { PayloadRequest } from 'payload'
+
+import { toolSchemas } from '../schemas.js'
+
+export const loginTool = (server: McpServer, req: PayloadRequest, verboseLogs: boolean) => {
+  const tool = async (
+    collection: string,
+    email: string,
+    password: string,
+    depth: number = 0,
+    overrideAccess: boolean = false,
+    showHiddenFields: boolean = false,
+  ) => {
+    const payload = req.payload
+
+    if (verboseLogs) {
+      payload.logger.info(
+        `[payload-mcp] Attempting login for user: ${email} in collection: ${collection}`,
+      )
+    }
+
+    try {
+      const result = await payload.login({
+        collection,
+        data: {
+          email,
+          password,
+        },
+        depth,
+        overrideAccess,
+        showHiddenFields,
+      })
+
+      if (verboseLogs) {
+        payload.logger.info(`[payload-mcp] Login successful for user: ${email}`)
+      }
+
+      return {
+        content: [
+          {
+            type: 'text' as const,
+            text: `# Login Successful\n\n**User:** ${email}\n**Collection:** ${collection}\n\n\`\`\`json\n${JSON.stringify(result, null, 2)}\n\`\`\``,
+          },
+        ],
+      }
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : 'Unknown error'
+      payload.logger.error(`[payload-mcp] Login failed for user ${email}: ${errorMessage}`)
+
+      return {
+        content: [
+          {
+            type: 'text' as const,
+            text: `❌ **Login failed for user "${email}"**: ${errorMessage}`,
+          },
+        ],
+      }
+    }
+  }
+
+  server.tool(
+    'login',
+    toolSchemas.login.description,
+    toolSchemas.login.parameters.shape,
+    async ({ collection, depth, email, overrideAccess, password, showHiddenFields }) => {
+      return await tool(collection, email, password, depth, overrideAccess, showHiddenFields)
+    },
+  )
+}