@payloadcms/plugin-mcp 0.0.1-alpha.0

package/src/mcp/tools/job/run.ts

@@ -0,0 +1,189 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
+import type { PayloadRequest } from 'payload'
+
+import { toolSchemas } from '../schemas.js'
+
+// Reusable function for running jobs
+export const runJob = async (
+  req: PayloadRequest,
+  verboseLogs: boolean,
+  jobSlug: string,
+  input: Record<string, any>,
+  queue?: string,
+  priority?: number,
+  delay?: number,
+) => {
+  const payload = req.payload
+
+  if (verboseLogs) {
+    payload.logger.info(`[payload-mcp] Running job: ${jobSlug}`)
+  }
+
+  try {
+    // Actually run the job using Payload's job queue
+    const jobQueueOptions: Record<string, unknown> = {
+      input,
+      task: jobSlug,
+    }
+
+    if (queue && queue !== 'default') {
+      jobQueueOptions.queue = queue
+      if (verboseLogs) {
+        payload.logger.info(`[payload-mcp] Using custom queue: ${queue}`)
+      }
+    }
+
+    if (priority && priority > 0) {
+      jobQueueOptions.priority = priority
+      if (verboseLogs) {
+        payload.logger.info(`[payload-mcp] Setting job priority: ${priority}`)
+      }
+    }
+
+    if (delay && delay > 0) {
+      jobQueueOptions.waitUntil = new Date(Date.now() + delay)
+      if (verboseLogs) {
+        payload.logger.info(`[payload-mcp] Setting job delay: ${delay}ms`)
+      }
+    }
+
+    if (verboseLogs) {
+      payload.logger.info(
+        `[payload-mcp] Queuing job with options: ${JSON.stringify(jobQueueOptions)}`,
+      )
+    }
+
+    const job = await payload.jobs.queue(
+      jobQueueOptions as Parameters<typeof payload.jobs.queue>[0],
+    )
+
+    const jobId = (job as { id?: string })?.id || 'unknown'
+
+    if (verboseLogs) {
+      payload.logger.info(`[payload-mcp] Job created successfully: ${jobId}`)
+    }
+
+    return {
+      content: [
+        {
+          type: 'text' as const,
+          text: `# Job Queued Successfully: ${jobSlug}
+
+## Job Details
+- **Job ID**: ${jobId}
+- **Job Slug**: ${jobSlug}
+- **Queue**: ${queue || 'default'}
+- **Priority**: ${priority || 'default'}
+- **Delay**: ${delay ? `${delay}ms` : 'none'}
+- **Status**: Queued and Running
+
+## Input Data
+\`\`\`json
+${JSON.stringify(input, null, 2)}
+\`\`\`
+
+## Job Status
+The job has been successfully queued and will be processed according to the queue settings.
+
+## Monitoring the Job
+You can monitor the job status using:
+
+\`\`\`typescript
+// Check job status
+const jobStatus = await payload.jobs.status('${jobId}')
+console.log('Job status:', jobStatus)
+
+// Wait for completion
+const result = await payload.jobs.wait('${jobId}')
+console.log('Job result:', result)
+\`\`\`
+
+✅ Job successfully queued with ID: ${jobId}`,
+        },
+      ],
+    }
+  } catch (error) {
+    const errorMsg = (error as Error).message
+    payload.logger.error(`[payload-mcp] Error running job "${jobSlug}": ${errorMsg}`)
+
+    return {
+      content: [
+        {
+          type: 'text' as const,
+          text: `❌ Error running job "${jobSlug}": ${errorMsg}
+
+## Common Issues:
+1. **Job not found**: The job "${jobSlug}" may not be registered in your Payload configuration
+2. **Invalid input format**: Ensure the input matches the job's input schema
+3. **Queue not configured**: The queue "${queue || 'default'}" may not be properly set up
+4. **Permission issues**: Ensure proper access rights for job execution
+5. **Job handler error**: The job implementation may have errors
+
+## Input Data Provided:
+\`\`\`json
+${JSON.stringify(input, null, 2)}
+\`\`\`
+
+## Next Steps:
+1. **Verify job exists**: Check that the job "${jobSlug}" is properly registered
+2. **Check input format**: Ensure the input data matches the expected schema
+3. **Review job configuration**: Verify the job is properly configured in your Payload setup
+4. **Check permissions**: Ensure you have the necessary permissions to run jobs
+5. **Review error logs**: Check the server logs for more detailed error information
+
+## Troubleshooting:
+- **Job not found**: Verify the job slug and check your jobs configuration
+- **Schema mismatch**: Ensure input data matches the job's input schema
+- **Queue issues**: Check that the specified queue is properly configured
+- **Permission errors**: Verify user permissions for job execution`,
+        },
+      ],
+    }
+  }
+}
+
+export const runJobTool = (server: McpServer, req: PayloadRequest, verboseLogs: boolean) => {
+  const tool = async (
+    jobSlug: string,
+    input: Record<string, any>,
+    queue?: string,
+    priority?: number,
+    delay?: number,
+  ) => {
+    if (verboseLogs) {
+      req.payload.logger.info(`[payload-mcp] Run Job Tool called with: ${jobSlug}`)
+    }
+
+    try {
+      const result = await runJob(req, verboseLogs, jobSlug, input, queue, priority, delay)
+
+      if (verboseLogs) {
+        req.payload.logger.info(`[payload-mcp] Run Job Tool completed successfully`)
+      }
+
+      return result
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : 'Unknown error'
+      req.payload.logger.error(`[payload-mcp] Error in Run Job Tool: ${errorMessage}`)
+
+      return {
+        content: [
+          {
+            type: 'text' as const,
+            text: `❌ **Error in Run Job Tool**: ${errorMessage}`,
+          },
+        ],
+      }
+    }
+  }
+
+  server.tool(
+    'runJob',
+    'Runs a Payload job with specified input data and queue options',
+    toolSchemas.runJob.parameters.shape,
+    async (args) => {
+      const { delay, input, jobSlug, priority, queue } = args
+      return await tool(jobSlug, input, queue, priority, delay)
+    },
+  )
+}

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

@@ -0,0 +1,319 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
+import type { PayloadRequest } from 'payload'
+
+import { existsSync, readFileSync, writeFileSync } from 'fs'
+import { join } from 'path'
+
+import type { JobConfigUpdate, SchemaField, TaskSequenceItem } from '../../../types.js'
+
+import { validatePayloadFile } from '../../helpers/fileValidation.js'
+import { toolSchemas } from '../schemas.js'
+
+// Reusable function for updating jobs
+export const updateJob = async (
+  req: PayloadRequest,
+  verboseLogs: boolean,
+  jobsDir: string,
+  jobSlug: string,
+  updateType: string,
+  inputSchema?: SchemaField[],
+  outputSchema?: SchemaField[],
+  taskSequence?: TaskSequenceItem[],
+  configUpdate?: JobConfigUpdate,
+  handlerCode?: string,
+) => {
+  const payload = req.payload
+
+  if (verboseLogs) {
+    payload.logger.info(`[payload-mcp] Updating job: ${jobSlug} (${updateType})`)
+  }
+
+  try {
+    const camelCaseJobSlug = toCamelCase(jobSlug)
+
+    // Find the job file - check both tasks and workflows
+    let filePath: null | string = null
+    let jobType: 'task' | 'workflow' | null = null
+
+    const taskPath = join(jobsDir, 'tasks', `${camelCaseJobSlug}.ts`)
+    const workflowPath = join(jobsDir, 'workflows', `${camelCaseJobSlug}.ts`)
+
+    if (existsSync(taskPath)) {
+      filePath = taskPath
+      jobType = 'task'
+      if (verboseLogs) {
+        payload.logger.info(`[payload-mcp] Found task file: ${taskPath}`)
+      }
+    } else if (existsSync(workflowPath)) {
+      filePath = workflowPath
+      jobType = 'workflow'
+      if (verboseLogs) {
+        payload.logger.info(`[payload-mcp] Found workflow file: ${workflowPath}`)
+      }
+    } else {
+      throw new Error(`No task or workflow file found for job slug: ${jobSlug}`)
+    }
+
+    // Read the current file content
+    let content = readFileSync(filePath, 'utf8')
+    const originalContent = content
+
+    if (verboseLogs) {
+      payload.logger.info(`[payload-mcp] Applying update type: ${updateType}`)
+    }
+
+    // Apply updates based on type
+    switch (updateType) {
+      case 'change_config':
+        if (!configUpdate) {
+          throw new Error('config must be provided for change_config')
+        }
+
+        content = updateConfig(content, jobSlug, configUpdate)
+        if (verboseLogs) {
+          payload.logger.info(`[payload-mcp] Configuration updated successfully`)
+        }
+        break
+
+      case 'modify_schema':
+        if (!inputSchema && !outputSchema) {
+          throw new Error('Either inputSchema or outputSchema must be provided for modify_schema')
+        }
+
+        content = updateSchema(content, camelCaseJobSlug, inputSchema, outputSchema)
+        if (verboseLogs) {
+          payload.logger.info(`[payload-mcp] Schema updated successfully`)
+        }
+        break
+
+      case 'replace_handler':
+        if (!handlerCode) {
+          throw new Error('handlerCode must be provided for replace_handler')
+        }
+
+        content = updateHandler(content, handlerCode, jobType)
+        if (verboseLogs) {
+          payload.logger.info(`[payload-mcp] Handler code replaced successfully`)
+        }
+        break
+
+      case 'update_tasks':
+        if (!taskSequence) {
+          throw new Error('taskSequence must be provided for update_tasks')
+        }
+
+        if (jobType !== 'workflow') {
+          throw new Error('update_tasks is only supported for workflow jobs')
+        }
+
+        content = updateWorkflowTasks(content, taskSequence)
+        if (verboseLogs) {
+          payload.logger.info(`[payload-mcp] Workflow tasks updated successfully`)
+        }
+        break
+    }
+
+    // Only write if content changed
+    if (content !== originalContent) {
+      if (verboseLogs) {
+        payload.logger.info(`[payload-mcp] Writing updated content to file`)
+      }
+
+      // Write the updated content
+      writeFileSync(filePath, content)
+
+      // Validate the updated file
+      const fileName = `${camelCaseJobSlug}.ts`
+      const validationType = jobType === 'task' ? 'task' : 'workflow'
+
+      try {
+        const validationResult = await validatePayloadFile(fileName, validationType)
+
+        if (!validationResult.success) {
+          if (verboseLogs) {
+            payload.logger.warn(`[payload-mcp] Validation warning: ${validationResult.error}`)
+          }
+
+          return {
+            content: [
+              {
+                type: 'text' as const,
+                text: `⚠️ **Warning**: Job updated but validation failed:\n\n${validationResult.error}\n\nPlease review the generated code for any syntax errors.`,
+              },
+            ],
+          }
+        }
+
+        if (verboseLogs) {
+          payload.logger.info(`[payload-mcp] File validation successful`)
+        }
+      } catch (validationError) {
+        if (verboseLogs) {
+          payload.logger.warn(`[payload-mcp] Validation error: ${validationError}`)
+        }
+
+        return {
+          content: [
+            {
+              type: 'text' as const,
+              text: `⚠️ **Warning**: Job updated but validation could not be completed:\n\n${validationError}\n\nPlease review the generated code manually.`,
+            },
+          ],
+        }
+      }
+
+      return {
+        content: [
+          {
+            type: 'text' as const,
+            text: `✅ **Job updated successfully!**\n\n**Job**: \`${jobSlug}\`\n**Type**: \`${jobType}\`\n**Update**: \`${updateType}\`\n**File**: \`${fileName}\`\n\n**Next steps**:\n1. Restart your development server to load the updated job\n2. Test the updated functionality\n3. Verify the changes meet your requirements`,
+          },
+        ],
+      }
+    } else {
+      if (verboseLogs) {
+        payload.logger.info(`[payload-mcp] No changes detected, file not modified`)
+      }
+
+      return {
+        content: [
+          {
+            type: 'text' as const,
+            text: `ℹ️ **No changes made**: The job file was not modified as no changes were detected.\n\n**Job**: \`${jobSlug}\`\n**Type**: \`${jobType}\`\n**Update**: \`${updateType}\``,
+          },
+        ],
+      }
+    }
+  } catch (error) {
+    const errorMessage = (error as Error).message
+    payload.logger.error(`[payload-mcp] Error updating job: ${errorMessage}`)
+
+    return {
+      content: [
+        {
+          type: 'text' as const,
+          text: `❌ **Error updating job**: ${errorMessage}`,
+        },
+      ],
+    }
+  }
+}
+
+// Helper function to convert to camel case
+function toCamelCase(str: string): string {
+  return str
+    .replace(/[-_\s]+(.)?/g, (_, chr) => (chr ? chr.toUpperCase() : ''))
+    .replace(/^(.)/, (_, chr) => chr.toLowerCase())
+}
+
+// Helper functions for different update types
+function updateSchema(
+  content: string,
+  camelCaseJobSlug: string,
+  inputSchema?: SchemaField[],
+  outputSchema?: SchemaField[],
+): string {
+  // TODO: Implementation for schema updates
+  // This would modify the inputSchema and outputSchema in the job file
+  return content
+}
+
+function updateWorkflowTasks(content: string, taskSequence: TaskSequenceItem[]): string {
+  // TODO: Implementation for updating workflow tasks
+  // This would modify the steps array in the workflow
+  return content
+}
+
+function updateConfig(content: string, jobSlug: string, configUpdate: JobConfigUpdate): string {
+  // TODO: Implementation for updating job configuration
+  // This would modify various config properties
+  return content
+}
+
+function updateHandler(content: string, handlerCode: string, jobType: 'task' | 'workflow'): string {
+  // TODO: Implementation for replacing handler code
+  // This would replace the handler function in the job file
+  return content
+}
+
+export const updateJobTool = (
+  server: McpServer,
+  req: PayloadRequest,
+  verboseLogs: boolean,
+  jobsDir: string,
+) => {
+  const tool = async (
+    jobSlug: string,
+    updateType: string,
+    inputSchema?: SchemaField[],
+    outputSchema?: SchemaField[],
+    taskSequence?: TaskSequenceItem[],
+    configUpdate?: JobConfigUpdate,
+    handlerCode?: string,
+  ) => {
+    if (verboseLogs) {
+      req.payload.logger.info(
+        `[payload-mcp] Update Job Tool called with: ${jobSlug}, ${updateType}`,
+      )
+    }
+
+    try {
+      const result = await updateJob(
+        req,
+        verboseLogs,
+        jobsDir,
+        jobSlug,
+        updateType,
+        inputSchema,
+        outputSchema,
+        taskSequence,
+        configUpdate,
+        handlerCode,
+      )
+
+      if (verboseLogs) {
+        req.payload.logger.info(`[payload-mcp] Update Job Tool completed successfully`)
+      }
+
+      return result
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : 'Unknown error'
+      req.payload.logger.error(`[payload-mcp] Error in Update Job Tool: ${errorMessage}`)
+
+      return {
+        content: [
+          {
+            type: 'text' as const,
+            text: `❌ **Error in Update Job Tool**: ${errorMessage}`,
+          },
+        ],
+      }
+    }
+  }
+
+  server.tool(
+    'updateJob',
+    'Updates an existing Payload job with new configuration, schema, or handler code',
+    toolSchemas.updateJob.parameters.shape,
+    async (args) => {
+      const {
+        configUpdate,
+        handlerCode,
+        inputSchema,
+        jobSlug,
+        outputSchema,
+        taskSequence,
+        updateType,
+      } = args
+      return await tool(
+        jobSlug,
+        updateType,
+        inputSchema as unknown as SchemaField[],
+        outputSchema as unknown as SchemaField[],
+        taskSequence,
+        configUpdate,
+        handlerCode,
+      )
+    },
+  )
+}

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

@@ -0,0 +1,121 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
+import type { JSONSchema4 } from 'json-schema'
+import type { PayloadRequest, TypedUser } from 'payload'
+
+import type { PluginMCPServerConfig } from '../../../types.js'
+
+import { toCamelCase } from '../../../utils/camelCase.js'
+import { convertCollectionSchemaToZod } from '../../../utils/convertCollectionSchemaToZod.js'
+import { toolSchemas } from '../schemas.js'
+export const createResourceTool = (
+  server: McpServer,
+  req: PayloadRequest,
+  user: TypedUser,
+  verboseLogs: boolean,
+  collectionSlug: string,
+  collections: PluginMCPServerConfig['collections'],
+  schema: JSONSchema4,
+) => {
+  const tool = async (
+    data: string,
+  ): Promise<{
+    content: Array<{
+      text: string
+      type: 'text'
+    }>
+  }> => {
+    const payload = req.payload
+
+    if (verboseLogs) {
+      payload.logger.info(`[payload-mcp] Creating resource in collection: ${collectionSlug}`)
+    }
+
+    try {
+      // Parse the data JSON
+      let parsedData: Record<string, unknown>
+      try {
+        parsedData = JSON.parse(data)
+        if (verboseLogs) {
+          payload.logger.info(
+            `[payload-mcp] Parsed data for ${collectionSlug}: ${JSON.stringify(parsedData)}`,
+          )
+        }
+      } catch (_parseError) {
+        payload.logger.error(`[payload-mcp] Invalid JSON data provided: ${data}`)
+        return {
+          content: [{ type: 'text' as const, text: 'Error: Invalid JSON data provided' }],
+        }
+      }
+
+      // Create the resource
+      const result = await payload.create({
+        collection: collectionSlug,
+        // TODO: Move the override to a `beforeChange` hook and extend the payloadAPI context req to include MCP request info.
+        data: collections?.[collectionSlug]?.override?.(parsedData, req) || parsedData,
+        user,
+      })
+
+      if (verboseLogs) {
+        payload.logger.info(
+          `[payload-mcp] Successfully created resource in ${collectionSlug} with ID: ${result.id}`,
+        )
+      }
+
+      const response = {
+        content: [
+          {
+            type: 'text' as const,
+            text: `Resource created successfully in collection "${collectionSlug}"!
+Created resource:
+\`\`\`json
+${JSON.stringify(result, null, 2)}
+\`\`\``,
+          },
+        ],
+      }
+
+      return (collections?.[collectionSlug]?.overrideResponse?.(response, result, req) ||
+        response) as {
+        content: Array<{
+          text: string
+          type: 'text'
+        }>
+      }
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : 'Unknown error'
+      payload.logger.error(
+        `[payload-mcp] Error creating resource in ${collectionSlug}: ${errorMessage}`,
+      )
+
+      const response = {
+        content: [
+          {
+            type: 'text' as const,
+            text: `Error creating resource in collection "${collectionSlug}": ${errorMessage}`,
+          },
+        ],
+      }
+
+      return (collections?.[collectionSlug]?.overrideResponse?.(response, {}, req) || response) as {
+        content: Array<{
+          text: string
+          type: 'text'
+        }>
+      }
+    }
+  }
+
+  if (collections?.[collectionSlug]?.enabled) {
+    const convertedFields = convertCollectionSchemaToZod(schema)
+
+    server.tool(
+      `create${collectionSlug.charAt(0).toUpperCase() + toCamelCase(collectionSlug).slice(1)}`,
+      `${toolSchemas.createResource.description.trim()}\n\n${collections?.[collectionSlug]?.description || ''}`,
+      convertedFields.shape,
+      async (params: Record<string, unknown>) => {
+        const data = JSON.stringify(params)
+        return await tool(data)
+      },
+    )
+  }
+}