🚀 Payload CMS 3.0 MCP Server

🚀 Payload CMS 3.0 MCP 服务

---

📋 概览

Payload CMS 3.0 MCP 服务是一款专用的模型上下文协议服务，旨在提升您的 Payload CMS 开发体验。它通过提供代码验证、模板生成和项目搭建功能，帮助开发者构建更出色的 Payload CMS 应用，并遵循最佳实践。

---

✨ 功能

---

🔧 Payload CMS 3.0 功能

验证工具

• validate - 验证集合、字段、全局配置和配置的代码
• query - 查询验证规则和最佳实践
• mcp_query - 对 Payload CMS 结构执行类似 SQL 的查询

代码生成

• generate_template - 为各种组件生成代码模板
• generate_collection - 创建完整的集合定义
• generate_field - 生成类型设置正确的字段定义

项目设置

• scaffold_project - 创建完整的 Payload CMS 项目结构
• validate_scaffold_options - 确保搭建选项符合最佳实践（由 scaffold_project 在内部使用）

---

📝 工具详细参考

验证工具

validate

验证 Payload CMS 代码是否符合语法要求和最佳实践。

参数：

• code（string）：要验证的代码
• fileType（enum）：文件类型——"collection"、"field"、"global" 或 "config"

提示词示例：

Can you validate this Payload CMS collection code?

```typescript
export const Posts = {
  slug: 'posts',
  fields: [
    {
      name: 'title',
      type: 'text',
      required: true,
    },
    {
      name: 'content',
      type: 'richText',
    }
  ],
  admin: {
    useAsTitle: 'title',
  }
}

query

查询 Payload CMS 的验证规则和最佳实践。

参数：

• query（string）：查询字符串
• fileType（可选 enum）：文件类型——"collection"、"field"、"global" 或 "config"

提示词示例：

What are the best practices for implementing access control in Payload CMS collections?

mcp_query

对 Payload CMS 结构执行类似 SQL 的查询。

参数：

• sql（string）：类似 SQL 的查询字符串

提示词示例：

Can you execute this query to find all valid field types in Payload CMS?
SELECT field_types FROM payload_schema WHERE version = '3.0'

代码生成

generate_template

为各种 Payload CMS 组件生成代码模板。

参数：

• templateType（enum）：模板类型——"collection"、"field"、"global"、"config"、"access-control"、"hook"、"endpoint"、"plugin"、"block"、"migration"
• options（record）：模板的配置选项

提示词示例：

Generate a template for a Payload CMS hook that logs when a document is created.

generate_collection

生成完整的 Payload CMS 集合定义。

参数：

• slug（string）：集合 slug
• fields（可选 array）：字段对象数组
• auth（可选 boolean）：是否为 auth 集合
• timestamps（可选 boolean）：是否包含时间戳
• admin（可选 object）：管理面板配置
• hooks（可选 boolean）：是否包含钩子
• access（可选 boolean）：是否包含访问控制
• versions（可选 boolean）：是否启用版本控制

提示词示例：

Generate a Payload CMS collection for a blog with title, content, author, and published date fields. Include timestamps and versioning.

generate_field

生成 Payload CMS 字段定义。

参数：

• name（string）：字段名称
• type（string）：字段类型
• required（可选 boolean）：字段是否必填
• unique（可选 boolean）：字段是否应为唯一
• localized（可选 boolean）：字段是否应本地化
• access（可选 boolean）：是否包含访问控制
• admin（可选 object）：管理面板配置
• validation（可选 boolean）：是否包含验证
• defaultValue（可选 any）：字段的默认值

提示词示例：

Generate a Payload CMS image field with validation that requires alt text and has a description in the admin panel.

项目设置

scaffold_project

搭建完整的 Payload CMS 项目结构。

参数：

• projectName（string）：项目名称
• description（可选 string）：项目描述
• serverUrl（可选 string）：服务 URL
• database（可选 enum）：数据库类型——“mongodb”或“postgres”
• auth（可选 boolean）：是否包含身份验证
• admin（可选 object）：管理面板配置
• collections（可选 array）：集合对象数组
• globals（可选 array）：全局对象数组
• blocks（可选 array）：区块对象数组
• plugins（可选 array）：插件字符串数组
• typescript（可选 boolean）：是否使用 TypeScript

提示词示例：

Scaffold a Payload CMS project called "blog-platform" with MongoDB, authentication, and collections for posts, categories, and users. Include a global for site settings.

---

🚀 入门指南

1. 先决条件

开始之前，请确保你具备以下条件：

• Node.js 18+（Payload CMS 3.0 的必需版本）
• 有效的 Railway 账户
• Railway API 令牌（在 railway.app/account/tokens 创建）
• 对 Payload CMS 3.0 概念有基本了解

2. 配置 Cursor

要与 Cursor IDE 配合使用：

1. 打开 Cursor 设置
2. 前往 MCP Servers 部分
3. 添加新的 MCP 服务
4. 将其命名为“Payload CMS 3.0 MCP”
5. 将 Transport Type 设置为“Command”
6. 将 Command 设置为：railway run --service=YOUR_SERVICE_ID
7. 保存配置

3. 使用 MCP 服务

配置完成后，你可以在 AI 提示词中使用这些工具：

• 代码验证：“验证这段 Payload CMS 集合代码”
• 模板生成：“为媒体集合生成模板”
• 查询规则：“查询访问控制的验证规则”
• 类似 SQL 的查询：“执行查询，查找集合的字段类型”

4. 示例工作流

使用 Payload CMS MCP 服务的典型工作流：

1. 生成包含指定字段的集合模板
2. 验证生成的代码是否符合最佳实践
3. 查询特定验证规则以改进代码
4. 生成钩子或端点等其他组件
5. 准备就绪后，搭建完整的项目结构

5. 完整工作流示例

以下是一个在对话中使用 MCP 服务的完整示例：

User: I need to create a Payload CMS collection for a product catalog.

AI: I'll help you create a product catalog collection. Let me generate a template for you.

[Uses generate_collection tool]

Here's a collection template for your product catalog:

```typescript
import { CollectionConfig } from 'payload/types';

export const Products: CollectionConfig = {
  slug: 'products',
  admin: {
    useAsTitle: 'name',
    defaultColumns: ['name', 'price', 'category', 'inStock'],
    group: 'Shop',
  },
  access: {
    read: () => true,
  },
  fields: [
    {
      name: 'name',
      type: 'text',
      required: true,
    },
    {
      name: 'description',
      type: 'richText',
    },
    {
      name: 'price',
      type: 'number',
      required: true,
    },
    {
      name: 'category',
      type: 'relationship',
      relationTo: 'categories',
      required: true,
    },
    {
      name: 'images',
      type: 'array',
      fields: [
        {
          name: 'image',
          type: 'upload',
          relationTo: 'media',
          required: true,
        },
        {
          name: 'altText',
          type: 'text',
          required: true,
        }
      ]
    },
    {
      name: 'inStock',
      type: 'checkbox',
      defaultValue: true,
    },
  ],
  timestamps: true,
}

用户：你能验证这段代码，确保它符合最佳实践吗？

AI：我来为你验证这段代码。

[使用 validate 工具]

验证结果显示，你的代码有效且符合最佳实践。以下是一些建议：

1. 考虑为类别关系字段添加 maxDepth，以防止查询过深
2. 你可能需要为创建、更新和删除操作添加访问控制
3. 考虑在产品更新时添加库存管理钩子

用户：Payload CMS 中访问控制的最佳实践是什么？

AI：我来查询访问控制的验证规则。

[使用 query 工具]

以下是 Payload CMS 中访问控制的最佳实践：

1. 始终为创建、读取、更新和删除操作定义明确的访问控制函数
2. 对管理员用户使用基于角色的访问控制
3. 对敏感数据实施字段级访问控制
4. 对广泛权限使用集合级访问控制
5. 对于复杂逻辑，考虑将钩子与访问控制结合使用

用户：现在我需要使用这个产品集合和一个类别集合搭建一个完整项目。

AI：我来为你搭建一个完整项目。

[使用 scaffold_project 工具]

我已生成完整的 Payload CMS 项目结构，其中包括：

• 按照你的要求创建的产品集合
• 包含名称和描述字段的类别集合
• 用于产品图片的媒体集合
• 管理员用户身份验证
• TypeScript 配置
• MongoDB 数据库设置
• 所有必要的文件和配置

该项目已准备就绪，可通过 npm install 和 npm run dev 进行初始化。

---

📋 搭建项目示例与详细提示词

项目搭建示例

使用 MCP 服务搭建项目时，你会收到完整的项目结构。以下是搭建出的电商项目可能呈现的样子：

e-commerce-platform/
├── .env
├── .eslintrc.js
├── .gitignore
├── README.md
├── package.json
├── tsconfig.json
├── src/
│   ├── payload.config.ts
│   ├── server.ts
│   ├── collections/
│   │   ├── Products.ts
│   │   ├── Categories.ts
│   │   ├── Orders.ts
│   │   ├── Customers.ts
│   │   ├── Media.ts
│   │   └── Users.ts
│   ├── globals/
│   │   ├── Settings.ts
│   │   └── Footer.ts
│   ├── blocks/
│   │   ├── Hero.ts
│   │   ├── ProductGrid.ts
│   │   └── CallToAction.ts
│   ├── fields/
│   │   ├── richText/
│   │   ├── metaImage.ts
│   │   └── slug.ts
│   ├── hooks/
│   │   ├── beforeChange.ts
│   │   └── afterChange.ts
│   ├── access/
│   │   ├── isAdmin.ts
│   │   └── isAdminOrSelf.ts
│   └── utilities/
│       ├── formatSlug.ts
│       └── sendEmail.ts

搭建项目提示词示例（基础）

Scaffold a Payload CMS project for a blog platform with the following:
- Project name: blog-platform
- Database: MongoDB
- Authentication: Yes
- Collections: Posts, Categories, Authors, Media
- Globals: SiteSettings
- TypeScript: Yes

搭建项目提示词示例（详细）

Scaffold a comprehensive Payload CMS project for an e-commerce platform with the following specifications:

Project details:
- Name: luxury-watches-store
- Description: "An e-commerce platform for luxury watches"
- Database: PostgreSQL
- TypeScript: Yes

Collections needed:
1. Products collection with:
   - Name (text, required)
   - Description (rich text)
   - Price (number, required)
   - SKU (text, unique)
   - Brand (relationship to Brands collection)
   - Categories (relationship to Categories, multiple)
   - Features (array of text fields)
   - Specifications (array of key-value pairs)
   - Images (array of media uploads with alt text)
   - Stock quantity (number)
   - Status (select: available, out of stock, discontinued)

2. Categories collection with:
   - Name (text, required)
   - Description (rich text)
   - Parent category (self-relationship)
   - Image (media upload)

3. Brands collection with:
   - Name (text, required)
   - Logo (media upload)
   - Description (rich text)
   - Founded year (number)
   - Country of origin (text)

4. Orders collection with:
   - Order number (text, generated)
   - Customer (relationship to Users)
   - Products (array of relationships to Products with quantity)
   - Status (select: pending, processing, shipped, delivered, cancelled)
   - Shipping address (group of fields)
   - Billing address (group of fields)
   - Payment method (select)
   - Total amount (number, calculated)
   - Notes (text)

5. Users collection (auth enabled) with:
   - Email (email, required)
   - Name (text, required)
   - Shipping addresses (array of address groups)
   - Order history (relationship to Orders)
   - Wishlist (relationship to Products)
   - Role (select: customer, admin)

Globals:
1. SiteSettings with:
   - Site name
   - Logo
   - Contact information
   - Social media links
   - SEO defaults

2. ShippingMethods with:
   - Array of shipping options with prices

Include access control for:
- Admin-only access to manage products, categories, brands
- Customer access to their own orders and profile
- Public read access to products and categories

Add hooks for:
- Updating stock when orders are placed
- Generating order numbers
- Sending email notifications on order status changes

创建集合提示词示例（基础）

Generate a Payload CMS collection for blog posts with title, content, author, and published date fields.

创建集合提示词示例（详细）

Generate a Payload CMS collection for a real estate property listing with the following specifications:

Collection name: Properties
Admin configuration:
- Use "title" as the display field
- Group under "Listings" in the admin panel
- Default columns: title, price, location, status, createdAt

Fields:
1. Title (text, required)
2. Slug (text, unique, generated from title)
3. Description (rich text with basic formatting options)
4. Price (number, required)
5. Location (group) with:
   - Address (text)
   - City (text, required)
   - State/Province (text, required)
   - Postal code (text)
   - Country (select from predefined list)
   - Coordinates (point) for map display
6. Property details (group) with:
   - Property type (select: house, apartment, condo, land, commercial)
   - Bedrooms (number)
   - Bathrooms (number)
   - Square footage (number)
   - Lot size (number)
   - Year built (number)
   - Parking spaces (number)
7. Features (array of checkboxes) including:
   - Air conditioning
   - Swimming pool
   - Garden
   - Garage
   - Fireplace
   - Security system
   - Elevator
   - Furnished
8. Images (array of media uploads with alt text and caption)
9. Documents (array of file uploads for floor plans, certificates, etc.)
10. Status (select: available, under contract, sold, off market)
11. Featured (checkbox to highlight on homepage)
12. Agent (relationship to Users collection, required)
13. Related properties (relationship to self, multiple)

Access control:
- Public read access
- Agent can create and edit their own listings
- Admin can manage all listings

Hooks:
- Before change: Format slug from title
- After change: Notify agent of status changes

Versioning: Enabled
Timestamps: Enabled

提示词详细程度

MCP 服务可以处理详细程度各异的提示词：

最低详细程度（由 AI 补全缺失内容）

Generate a collection for blog posts.

中等详细程度（具体要求）

Generate a collection for blog posts with title, content, featured image, categories, and author fields. Make title and content required.

高详细程度（完整规范）

Generate a collection for blog posts with:
- Slug: posts
- Fields:
  - Title (text, required)
  - Content (rich text with custom formatting options)
  - Featured image (upload with alt text)
  - Categories (relationship to categories collection, multiple)
  - Author (relationship to users collection)
  - Status (select: draft, published, archived)
  - Published date (date)
  - SEO (group with title, description, and keywords)
- Admin configuration:
  - Use title as display field
  - Group under "Content"
  - Default columns: title, author, status, publishedDate
- Access control for different user roles
- Hooks for slug generation and notification
- Enable versioning and timestamps

编写有效提示词的技巧

1. 明确说明需求：提供的细节越多，输出就越贴合需求。

2. 说明关系：清楚指出各个集合之间的关系。

3. 说明验证需求：提及字段的任何验证规则或约束。

4. 描述管理界面偏好：说明你希望集合在管理面板中的呈现方式。

5. 提及钩子和访问控制：如果需要特定的业务逻辑或安全规则，请将其写入提示词。

6. 使用特定领域术语：使用与你的行业或应用场景相关的术语来描述项目。

---

📄 许可证

本项目采用 MIT License 授权，详情请参阅 LICENSE 文件。

---

🌍 关于 MATMAX WORLDWIDE

我们相信科技可以造福社会——创造提升生活品质、同时尊重人性的工具。

加入我们，共同构建一个让科技服务于健康、联结与目标的未来。携手共进，我们可以创造展现每个人最佳一面的数字体验。

访问 matmax.world，进一步了解我们以人为本的技术愿景。

---

## 🖥️ 在本地运行

你可以使用 npm 在本地运行 Payload CMS MCP Server：

选项 1：从 npm 安装

# Install globally
npm install -g payload-cms-mcp

# Run the server
payload-cms-mcp

选项 2：克隆仓库

1. 克隆仓库：

git clone https://github.com/Matmax-Worldwide/payloadcmsmcp.git
cd payloadcmsmcp

2. 安装依赖项：

npm install

3. 在本地运行服务：

npm run dev

或者：

npm run local

现在，你的 MCP 服务将在本地运行，可用于开发和测试，无需 Railway API 令牌。

🚀 部署选项

部署到 Railway（推荐）

部署 MCP 服务最简单的方式是使用 Railway 的一键部署：

点击按钮后：

1. 选择“Deploy from GitHub repo”
2. 搜索“Matmax-Worldwide/payloadcmsmcp”
3. 点击“Deploy Now”

快速配置 Cursor IDE

部署后：

1. 安装 Railway CLI：npm install -g @railway/cli
2. 登录 Railway：railway login
3. 链接到你的项目：railway link
4. 在 Cursor Settings > MCP Servers 中，将 Command 设置为：railway run