技术文档摘要

🚀 Payload CMS 3.0 MCP 服务器

<div align="center"> <p align="center"> <img src="https://www.payloadcmsmcp.info/logopayload.png" alt="Payload CMS Logo" width="120" height="120" style="border-radius: 10px; padding: 5px; background-color: white; box-shadow: 0 3px 10px rgba(0, 0, 0, 0.25);" /> </p> <p align="center"> <img src="https://img.shields.io/badge/Model%20Context%20Protocol-Enabled-6366F1?style=for-the-badge" alt="MCP 启用" /> <img src="https://img.shields.io/badge/Payload%20CMS%203.0-集成-3B82F6?style=for-the-badge" alt="Payload CMS" /> <img src="https://img.shields.io/badge/License-MIT-10B981?style=for-the-badge" alt="许可证" /> <img src="https://img.shields.io/badge/Railway-部署-0B0D0E?style=for-the-badge" alt="Railway 部署" /> </p> <h3>专为 Payload CMS 3.0 设计的 MCP 服务器</h3> <p>验证代码、生成模板并遵循最佳实践构建项目</p> </div> <hr>

📋 概述

Payload CMS 3.0 MCP 服务器是一个专门设计用于增强 Payload CMS 开发体验的 Model Context Protocol 服务器。它通过提供代码验证、模板生成和项目搭建功能来帮助开发者构建更好的 Payload CMS 应用程序，这些功能都遵循最佳实践。

<hr>

✨ 特性

<div align="center"> <table> <tr> <td align="center"> <h3>📚</h3> <b>代码验证</b> <p>验证集合、字段、全局变量和配置文件中的 Payload CMS 代码，并提供详细的语法错误反馈和最佳实践。</p> </td> <td align="center"> <h3>🔍</h3> <b>代码生成</b> <p>生成集合、字段、全局变量、访问控制、钩子、端点、插件、块和迁移的代码模板。</p> </td> <td align="center"> <h3>🚀</h3> <b>项目搭建</b> <p>使用经过验证的选项搭建整个 Payload CMS 项目，以确保一致性和遵循最佳实践。</p> </td> </tr> </table> </div> <hr>

🔧 Payload CMS 3.0 能力

验证工具

• validate - 验证集合、字段、全局变量和配置文件的代码
• query - 查询验证规则和最佳实践
• mcp_query - 执行类似于 SQL 的查询以获取 Payload CMS 结构信息

代码生成

• generate_template - 生成各种组件的代码模板
• generate_collection - 创建完整的集合定义
• generate_field - 生成具有适当类型的字段定义

项目设置

• scaffold_project - 创建整个 Payload CMS 项目结构
• validate_scaffold_options - 确保项目搭建选项遵循最佳实践（由 scaffold_project 内部使用）

<hr>

📝 工具详细参考

验证工具

validate

验证 Payload CMS 代码的语法和最佳实践。

参数：

• code (字符串)：要验证的代码
• fileType (枚举)：文件类型 - "collection"、"field"、"global" 或 "config"

示例提示：

你能验证这段 Payload CMS 集合代码吗？

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

query

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

参数：

• query (字符串)：查询字符串
• fileType (可选枚举)：文件类型 - "collection"、"field"、"global" 或 "config"

示例提示：

在 Payload CMS 集合中实现访问控制的最佳实践是什么？

mcp_query

执行类似于 SQL 的查询以获取 Payload CMS 结构信息。

参数：

• sql (字符串)：类似于 SQL 的查询字符串

示例提示：

你能执行这个查询来查找所有有效的字段类型吗？
SELECT field_types FROM payload_schema WHERE version = '3.0'

代码生成

generate_template

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

参数：

• templateType (枚举)：模板类型 - "collection"、"field"、"global"、"config"、"access-control"、"hook"、"endpoint"、"plugin"、"block"、"migration"
• options (记录)：模板配置选项

示例提示：

生成一个 Payload CMS 钩子模板，当文档创建时记录日志。

generate_collection

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

参数：

• slug (字符串)：集合别名
• fields (可选数组)：字段对象数组
• auth (可选布尔值)：是否为认证集合
• timestamps (可选布尔值)：是否包含时间戳
• admin (可选对象)：管理面板配置
• hooks (可选布尔值)：是否包含钩子
• access (可选布尔值)：是否包含访问控制
• versions (可选布尔值)：是否启用版本控制

示例提示：

生成一个包含标题、内容、作者和发布日期字段的博客 Payload CMS 集合。包含时间戳和版本控制。

generate_field

生成 Payload CMS 字段定义。

参数：

• name (字符串)：字段名称
• type (字符串)：字段类型
• required (可选布尔值)：字段是否必填
• unique (可选布尔值)：字段是否唯一
• localized (可选布尔值)：字段是否本地化
• access (可选布尔值)：是否包含访问控制
• admin (可选对象)：管理面板配置
• validation (可选布尔值)：是否包含验证
• defaultValue (可选任意类型)：字段默认值

示例提示：

生成一个带有验证要求的 Payload CMS 图像字段，需要替代文本并在管理面板中有描述。

项目设置

scaffold_project

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

参数：

• projectName (字符串)：项目名称
• description (可选字符串)：项目描述
• serverUrl (可选字符串)：服务器 URL
• database (可选枚举)：数据库类型 - "mongodb" 或 "postgres"
• auth (可选布尔值)：是否包含认证
• admin (可选对象)：管理面板配置
• collections (可选数组)：集合对象数组
• globals (可选数组)：全局对象数组
• blocks (可选数组)：块对象数组
• plugins (可选数组)：插件字符串数组
• typescript (可选布尔值)：是否使用 TypeScript

示例提示：

搭建一个名为 "blog-platform" 的 Payload CMS 项目，使用 MongoDB、认证以及用于帖子、类别和用户的集合。包含一个全局设置。

<hr>

🚀 快速开始

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 服务器部分
3. 添加一个新的 MCP 服务器
4. 将其命名为 "Payload CMS 3.0 MCP"
5. 将传输类型设置为 "命令"
6. 将命令设置为：railway run --service=YOUR_SERVICE_ID
7. 保存配置

3. 使用 MCP 服务器

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

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

4. 示例工作流程

使用 Payload CMS MCP 服务器的一个典型工作流程：

1. 生成一个具有特定字段的集合模板
2. 验证生成的代码以遵循最佳实践
3. 查询特定的验证规则以改进代码
4. 生成额外的组件，如钩子或端点
5. 当准备好时，搭建完整的项目结构

5. 完整的工作流程示例

以下是如何在对话中使用 MCP 服务器的完整示例：

用户：我需要创建一个用于产品目录的 Payload CMS 集合。

AI：我会帮你创建一个产品目录集合。让我为你生成一个模板。

[使用 generate_collection 工具]

这是你的产品目录集合模板：

```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,
        },
        {
          1. 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 初始化。

<hr>

📋 搭建示例及详细提示

项目搭建示例

当你使用 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

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

搭建一个用于博客平台的 Payload CMS 项目，包括以下内容：
- 项目名称：blog-platform
- 数据库：MongoDB
- 认证：是
- 集合：Posts, Categories, Authors, Media
- 全局变量：SiteSettings
- TypeScript：是

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

搭建一个全面的用于电子商务平台的 Payload CMS 项目，具体规格如下：

项目详情：
- 名称：luxury-watches-store
- 描述：“一个奢侈品手表电子商务平台”
- 数据库：PostgreSQL
- TypeScript：是

所需集合：
1. Products 集合，包含：
   - 名称（文本，必填）
   - 描述（富文本）
   - 价格（数字，必填）
   - SKU（文本，唯一）
   - 品牌（与 Brands 集合的关系）
   - 类别（与 Categories 的关系，多个）
   - 功能（文本字段数组）
   - 规格（键值对数组）
   - 图像（带有替代文本的媒体上传数组）
   - 库存量（数字）
   - 状态（选择：可用、缺货、停产）

2. Categories 集合，包含：
   - 名称（文本，必填）
   - 描述（富文本）
   - 父类别（自我关系）
   - 图像（媒体上传）

3. Brands 集合，包含：
   - 名称（文本，必填）
   - 标识（媒体上传）
   - 描述（富文本）
   - 成立年份（数字）
   - 原产国（文本）

4. Orders 集合，包含：
   - 订单号（文本，生成）
   - 客户（与 Users 的关系）
   - 产品（与 Products 的关系数组，带数量）
   - 状态（选择：待处理、处理中、已发货、已送达、取消）
   - 收货地址（字段组）
   - 账单地址（字段组）
   - 支付方式（选择）
   - 总金额（数字，计算）
   - 备注（文本）

5. Users 集合（启用认证），包含：
   - 邮箱（电子邮件，必填）
   - 名称（文本，必填）
   - 收货地址（地址组数组）
   - 订单历史（与 Orders 的关系）
   - 喜欢列表（与 Products 的关系）
   - 角色（选择：客户、管理员）

全局变量：
1. SiteSettings，包含：
   - 网站名称
   - 标识
   - 联系信息
   - 社交媒体链接
   - SEO 默认值

2. ShippingMethods，包含：
   - 运输选项数组及其价格

包含访问控制：
- 管理员可以管理产品、类别和品牌
- 客户可以访问自己的订单和个人资料
- 公众可以阅读产品和类别

添加钩子：
- 当订单被下单时更新库存
- 生成订单号
- 在订单状态更改时发送电子邮件通知

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

生成一个包含标题、内容、作者和发布日期字段的博客帖子 Payload CMS 集合。

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

生成一个用于房地产物业列表的 Payload CMS 集合，具体规格如下：

集合名称：Properties
管理面板配置：
- 使用“标题”作为显示字段
- 在管理面板下分组为“列表”
- 默认列：标题、价格、位置、状态、创建日期

字段：
1. 标题（文本，必填）
2. 别名（文本，唯一，从标题生成）
3. 描述（富文本，具有基本格式选项）
4. 价格（数字，必填）
5. 位置（字段组）包含：
   - 地址（文本）
   - 城市（文本，必填）
   - 州/省（文本，必填）
   - 邮政编码（文本）
   -