@payloadcms/plugin-mcp 0.0.1-alpha.0

package/src/types.ts

@@ -0,0 +1,405 @@
+import type { CollectionConfig, CollectionSlug, PayloadRequest } from 'payload'
+import type { z } from 'zod'
+
+import { type ResourceTemplate } from '@modelcontextprotocol/sdk/server/mcp.js'
+
+export type PluginMCPServerConfig = {
+  /**
+   * Set the collections that should be available as resources via MCP.
+   */
+  collections?: Partial<
+    Record<
+      CollectionSlug,
+      {
+        /**
+         * Set the description of the collection. This is used by MCP clients to determine when to use the collecton as a resource.
+         */
+        description: string
+        /**
+         * Set the enabled capabilities of the collection. Admins can then allow or disallow the use of the capability by MCP clients.
+         */
+        enabled:
+          | {
+              create?: boolean
+              delete?: boolean
+              find?: boolean
+              update?: boolean
+            }
+          | boolean
+
+        /**
+         * Override the data generated by the MCP client. This allows you to modify the data that is sent to the MCP client. This is useful for adding additional data to the response, data normalization, or verifying data.
+         */
+        override?: (
+          original: Record<string, unknown>,
+          req: PayloadRequest,
+        ) => Record<string, unknown>
+
+        /**
+         * Override the response generated by the MCP client. This allows you to modify the response that is sent to the MCP client. This is useful for adding additional data to the response, data normalization, or verifying data.
+         */
+        overrideResponse?: (
+          response: {
+            content: Array<{
+              text: string
+              type: string
+            }>
+          },
+          doc: Record<string, unknown>,
+          req: PayloadRequest,
+        ) => {
+          content: Array<{
+            text: string
+            type: string
+          }>
+        }
+      }
+    >
+  >
+  /**
+   * Disable the MCP plugin.
+   */
+  disabled?: boolean
+  /**
+   * Experimental features
+   * **These features are for experimental purposes -- They are Disabled in Production by Default**
+   */
+  experimental?: {
+    /**
+     * These are MCP tools that can be used by a client to modify Payload.
+     */
+    tools: {
+      /**
+       * **Experimental** -- Auth MCP tools allow a client to change authentication priviliages for users. This is for developing ideas that help Admins with authentication tasks.
+       */
+      auth?: {
+        /**
+         * Enable the auth MCP tools. This allows Admins to enable or disable the auth capabilities.
+         * @default false
+         */
+        enabled: boolean
+      }
+      /**
+       * **Experimental** -- Collection MCP tools allow for the creation, modification, and deletion of Payload collections. This is for developing ideas that help Developers with collection tasks.
+       */
+      collections?: {
+        /**
+         * Set the directory path to the collections directory. This can be a directory outside of your default directory, or another Payload project.
+         */
+        collectionsDirPath: string
+        /**
+         * Enable the collection MCP tools. This allows Admins to enable or disable the Collection modification capabilities.
+         * @default false
+         */
+        enabled: boolean
+      }
+      /**
+       * **Experimental** -- Config MCP tools allow for the modification of a Payload Config. This is for developing ideas that help Developers with config tasks.
+       */
+      config?: {
+        /**
+         * Set the directory path to the config directory. This can be a directory outside of your default directory, or another Payload project.
+         */
+        configFilePath: string
+        /**
+         * Enable the config MCP tools. This allows Admins to enable or disable the Payload Config modification capabilities.
+         * @default false
+         */
+        enabled: boolean
+      }
+      /**
+       * **Experimental** -- Jobs MCP tools allow for the modification of Payload jobs. This is for developing ideas that help Developers with job tasks.
+       */
+      jobs?: {
+        /**
+         * Enable the jobs MCP tools. This allows Admins to enable or disable the Job modification capabilities.
+         * @default false
+         */
+        enabled: boolean
+        /**
+         * Set the directory path to the jobs directory. This can be a directory outside of your default directory, or another Payload project.
+         */
+        jobsDirPath: string
+      }
+    }
+  }
+  /**
+   * MCP Server options.
+   */
+  mcp?: {
+    handlerOptions?: MCPHandlerOptions
+    /**
+     * Add custom MCP Prompts.
+     */
+    prompts?: {
+      /**
+       * Set the args schema of the prompt. This is the args schema that will be passed to the prompt. This is used by MCP clients to determine the arguments that will be passed to the prompt.
+       */
+      argsSchema: z.ZodRawShape
+      /**
+       * Set the description of the prompt. This is used by MCP clients to determine when to use the prompt.
+       */
+      description: string
+      /**
+       * Set the handler of the prompt. This is the function that will be called when the prompt is used.
+       */
+      handler: (...args: any) => any
+      /**
+       * Set the function name of the prompt.
+       */
+      name: string
+      /**
+       * Set the title of the prompt. LLMs will interperate the title to determine when to use the prompt.
+       */
+      title: string
+    }[]
+
+    /**
+     * Add custom MCP Resource.
+     */
+    resources?: {
+      /**
+       * Set the description of the resource. This is used by MCP clients to determine when to use the resource.
+       * example: 'Data is a resource that contains special data.'
+       */
+      description: string
+      /**
+       * Set the handler of the resource. This is the function that will be called when the resource is used.
+       */
+      handler: (...args: any) => any
+      /**
+       * Set the mime type of the resource.
+       * example: 'text/plain'
+       */
+      mimeType: string
+      /**
+       * Set the function name of the resource.
+       * example: 'data'
+       */
+      name: string
+      /**
+       * Set the title of the resource. LLMs will interperate the title to determine when to use the resource.
+       * example: 'Data'
+       */
+      title: string
+      /**
+       * Set the uri of the resource.
+       * example: 'data://app'
+       */
+      uri: ResourceTemplate | string
+    }[]
+    serverOptions?: MCPServerOptions
+    /**
+     * Add custom MCP Tools.
+     */
+    tools?: {
+      /**
+       * Set the description of the tool. This is used by MCP clients to determine when to use the tool.
+       */
+      description: string
+      /**
+       * Set the handler of the tool. This is the function that will be called when the tool is used.
+       */
+      handler: (args: Record<string, unknown>) => Promise<{
+        content: Array<{
+          text: string
+          type: 'text'
+        }>
+      }>
+      /**
+       * Set the name of the tool. This is the name that will be used to identify the tool. LLMs will interperate the name to determine when to use the tool.
+       */
+      name: string
+      /**
+       * Set the parameters of the tool. This is the parameters that will be passed to the tool.
+       */
+      parameters: z.ZodRawShape
+    }[]
+  }
+  overrideApiKeyCollection?: (collection: CollectionConfig) => CollectionConfig
+}
+
+/**
+ * MCP Handler options.
+ */
+export type MCPHandlerOptions = {
+  /**
+   * Set the base path of the MCP handler. This is the path that will be used to access the MCP handler.
+   * @default /api
+   */
+  basePath?: string
+  /**
+   * Set the maximum duration of the MCP handler. This is the maximum duration that the MCP handler will run for.
+   * @default 60
+   */
+  maxDuration?: number
+  /**
+   * Set the Redis URL for the MCP handler. This is the URL that will be used to access the Redis server.
+   * @default process.env.REDIS_URL
+   * INFO: Disabled until developer clarity is reached for server side streaming and we have an auth pattern for all SSE patterns
+   */
+  // redisUrl?: string
+  /**
+   * Set verbose logging.
+   * @default false
+   */
+  verboseLogs?: boolean
+}
+
+/**
+ * MCP Server options.
+ */
+export type MCPServerOptions = {
+  /**
+   * Set the server info of the MCP server.
+   */
+  serverInfo?: {
+    /**
+     * Set the name of the MCP server.
+     * @default 'Payload MCP Server'
+     */
+    name: string
+    /**
+     * Set the version of the MCP server.
+     * @default '1.0.0'
+     */
+    version: string
+  }
+}
+
+export type ToolSettings = {
+  auth?: {
+    auth?: boolean
+    forgotPassword?: boolean
+    login?: boolean
+    resetPassword?: boolean
+    unlock?: boolean
+    verify?: boolean
+  }
+  collections?: {
+    create?: boolean
+    delete?: boolean
+    find?: boolean
+    update?: boolean
+  }
+  config?: {
+    find?: boolean
+    update?: boolean
+  }
+  custom?: Record<string, boolean>
+  jobs?: {
+    create?: boolean
+    run?: boolean
+    update?: boolean
+  }
+} & Record<string, unknown>
+
+export type FieldDefinition = {
+  description?: string
+  name: string
+  options?: { label: string; value: string }[]
+  position?: 'main' | 'sidebar'
+  required?: boolean
+  type: string
+}
+
+export type FieldModification = {
+  changes: {
+    description?: string
+    options?: { label: string; value: string }[]
+    position?: 'main' | 'sidebar'
+    required?: boolean
+    type?: string
+  }
+  fieldName: string
+}
+
+export type CollectionConfigUpdates = {
+  access?: {
+    create?: string
+    delete?: string
+    read?: string
+    update?: string
+  }
+  description?: string
+  slug?: string
+  timestamps?: boolean
+  versioning?: boolean
+}
+
+export type AdminConfig = {
+  avatar?: string
+  css?: string
+  dateFormat?: string
+  inactivityRoute?: string
+  livePreview?: {
+    breakpoints?: Array<{
+      height: number
+      label: string
+      name: string
+      width: number
+    }>
+  }
+  logoutRoute?: string
+  meta?: {
+    favicon?: string
+    ogImage?: string
+    titleSuffix?: string
+  }
+  user?: string
+}
+
+export type DatabaseConfig = {
+  connectOptions?: string
+  type?: 'mongodb' | 'postgres'
+  url?: string
+}
+
+export type PluginUpdates = {
+  add?: string[]
+  remove?: string[]
+}
+
+export type GeneralConfig = {
+  cookiePrefix?: string
+  cors?: string
+  csrf?: string
+  graphQL?: {
+    disable?: boolean
+    schemaOutputFile?: string
+  }
+  rateLimit?: {
+    max?: number
+    skip?: string
+    window?: number
+  }
+  secret?: string
+  serverURL?: string
+  typescript?: {
+    declare?: boolean
+    outputFile?: string
+  }
+}
+
+export interface SchemaField {
+  description?: string
+  name: string
+  options?: string[]
+  required?: boolean
+  type: string
+}
+
+export interface TaskSequenceItem {
+  description?: string
+  retries?: number
+  taskId: string
+  taskSlug: string
+  timeout?: number
+}
+
+export interface JobConfigUpdate {
+  description?: string
+  queue?: string
+  retries?: number
+  timeout?: number
+}

package/src/utils/camelCase.ts

@@ -0,0 +1,12 @@
+/**
+ * Converts a string to camel case by replacing dashes, underscores, and spaces
+ * with camel case formatting.
+ *
+ * @param str - The string to convert to camel case
+ * @returns The camel cased string
+ */
+export const toCamelCase = (str: string): string => {
+  return str
+    .replace(/[-_\s]+(.)?/g, (_, chr) => (chr ? chr.toUpperCase() : ''))
+    .replace(/^(.)/, (_, chr) => chr.toLowerCase())
+}

package/src/utils/convertCollectionSchemaToZod.ts

@@ -0,0 +1,35 @@
+import type { JSONSchema4 } from 'json-schema'
+
+import { jsonSchemaToZod } from 'json-schema-to-zod'
+import * as ts from 'typescript'
+import { z } from 'zod'
+
+export const convertCollectionSchemaToZod = (schema: JSONSchema4) => {
+  // Remove properties that should not be included in the Zod schema
+  delete schema?.properties?.createdAt
+  delete schema?.properties?.updatedAt
+
+  const zodSchemaAsString = jsonSchemaToZod(schema)
+
+  // Transpile TypeScript to JavaScript
+  const transpileResult = ts.transpileModule(zodSchemaAsString, {
+    compilerOptions: {
+      module: ts.ModuleKind.CommonJS,
+      removeComments: true,
+      strict: false,
+      target: ts.ScriptTarget.ES2018,
+    },
+  })
+
+  /**
+   * This Function evaluation is safe because:
+   * 1. The input schema comes from Payload's collection configuration, which is controlled by the application developer
+   * 2. The jsonSchemaToZod library converts JSON Schema to Zod schema definitions, producing only type validation code
+   * 3. The transpiled output contains only Zod schema definitions (z.string(), z.number(), etc.) - no executable logic
+   * 4. The resulting Zod schema is used only for parameter validation in MCP tools, not for data processing
+   * 5. No user input or external data is involved in the schema generation process
+   */
+  // eslint-disable-next-line @typescript-eslint/no-implied-eval
+  const zodSchema = new Function('z', `return ${transpileResult.outputText}`)(z)
+  return zodSchema
+}