READMEmain

Payload MCP

Name: payload-mcp
Author: Govcraft

A Model Context Protocol (MCP) server for Payload CMS 3.0 that auto-generates tools from Payload's TypeScript type definitions.

Features

Auto-generates MCP tools from Payload CMS 3.0 TypeScript definitions
Provides an HTTP endpoint for LLMs to generate up-to-date Payload code
Bridges the gap between LLM training cutoff and current Payload CMS API
Supports all major Payload CMS features:
- Collections
- Globals
- Fields
- Authentication
- Configuration

How It Works

Parse Type Definitions: Uses ts-morph to analyze Payload's .d.ts files
Generate Tools: Converts types into MCP tools with parameters and code-gen logic
Serve Endpoint: Provides an /api/v1/payload-mcp endpoint for LLMs to query
Generate Code: Returns properly formatted Payload CMS 3.0 code

Getting Started

Prerequisites

Node.js (v18 or higher)
pnpm (v8 or higher)

Installation

# Clone the repository
git clone https://github.com/yourusername/payload-mcp.git
cd payload-mcp

# Install dependencies
pnpm install

# Generate tools from Payload CMS type definitions
pnpm generate-tools

# Start the development server
pnpm dev

Usage

The MCP server exposes an endpoint at /api/v1/payload-mcp that accepts POST requests with the following structure:

{
  "model": "claude-3-opus-20240229",
  "tools": [
    {
      "name": "createCollection",
      "parameters": {
        "slug": "posts",
        "fields": [
          {
            "name": "title",
            "type": "text",
            "required": true
          }
        ],
        "admin": {
          "useAsTitle": "title"
        }
      }
    }
  ]
}

The server will respond with generated Payload CMS 3.0 code:

{
  "id": "uuid",
  "context": [
    {
      "id": "uuid",
      "data": {
        "code": "import { CollectionConfig } from 'payload/types';\n\nexport const postsCollection: CollectionConfig = {\n  slug: 'posts',\n  fields: [\n  {\n    \"name\": \"title\",\n    \"type\": \"text\",\n    \"required\": true\n  }\n],\n  // Add other properties as needed from params\n  ...{\n  \"admin\": {\n    \"useAsTitle\": \"title\"\n  }\n}\n};\n",
        "message": "Collection 'posts' created successfully"
      }
    }
  ],
  "tool_results": [
    {
      "tool_name": "createCollection",
      "output": {
        "code": "import { CollectionConfig } from 'payload/types';\n\nexport const postsCollection: CollectionConfig = {\n  slug: 'posts',\n  fields: [\n  {\n    \"name\": \"title\",\n    \"type\": \"text\",\n    \"required\": true\n  }\n],\n  // Add other properties as needed from params\n  ...{\n  \"admin\": {\n    \"useAsTitle\": \"title\"\n  }\n}\n};\n",
        "message": "Collection 'posts' created successfully"
      }
    }
  ]
}

Available Tools

The following tools are auto-generated from Payload CMS 3.0 type definitions:

createCollection: Creates a collection configuration
createGlobal: Creates a global configuration
createField: Creates a field configuration
createAuth: Creates authentication configuration
createConfig: Creates the main Payload CMS configuration

Development

Regenerating Tools

If you update Payload CMS or want to regenerate the tools:

# Update Payload
pnpm add payload@latest

# Regenerate tools
pnpm generate-tools

Logging

The server uses Winston for logging. By default, logs are written to the logs directory with the following files:

combined.log: All logs (info level and above)
error.log: Error logs only
exceptions.log: Uncaught exceptions
rejections.log: Unhandled promise rejections

The server uses npm logging levels (from highest to lowest priority):

error: 0,
warn: 1,
info: 2,
http: 3,
verbose: 4,
debug: 5,
silly: 6

By default, the log level is set to info, which means only logs with level info, warn, and error will be recorded. To see more detailed logs:

Set to verbose to see tool registration details
Set to debug for even more detailed debugging information
Set to silly for the most verbose output

You can change the log level by setting the LOG_LEVEL environment variable:

# Run with verbose logging (shows tool registration)
LOG_LEVEL=verbose pnpm start

# Run with debug logging (more detailed)
LOG_LEVEL=debug pnpm start

# Or set in .env file
# LOG_LEVEL=verbose

Testing

To test the auto-generated tools:

# Start the server
pnpm dev

# In another terminal, run the test script
node test-generated-tools.mjs

License

ISC

Sponsor

Govcraft is a one-person shop—no corporate backing, no investors, just me building useful tools. If this project helps you, sponsoring keeps the work going.

payload-mcp