MCP 服务器

Payload CMS MCP Server

通过自然语言命令管理 Payload CMS 项目，允许开发者使用对话式 AI 创建、配置和部署内容模型。

README

🚀 Payload CMS 3.0 MCP 服务器

<h3>一个专为 Payload CMS 3.0 设计的 MCP 服务器</h3> <p>验证代码、生成模板并按照最佳实践搭建项目</p> </div>

<hr>

📋 概述

Payload CMS 3.0 MCP 服务器是一个专门的模型上下文协议服务器，旨在增强您的 Payload CMS 开发体验。它通过提供代码验证、模板生成和项目脚手架功能（均遵循最佳实践），帮助开发者构建更好的 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 - 对 Payload CMS 结构执行类似 SQL 的查询

代码生成

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`

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

参数：

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

示例提示：

你能执行这个查询来查找 Payload CMS 中所有有效的字段类型吗？
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 (字符串)：集合 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 一起使用：

打开 Cursor 设置
转到 MCP 服务器部分
添加一个新的 MCP 服务器
将其命名为 "Payload CMS 3.0 MCP"
将传输类型设置为 "Command"
将命令设置为：railway run --service=YOUR_SERVICE_ID
保存配置

3. 使用 MCP 服务器

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

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

4. 示例工作流程

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

生成具有特定字段的集合模板
验证生成的代码是否符合最佳实践
查询特定的验证规则以改进代码
生成其他组件，如钩子或端点
在准备就绪时搭建一个完整的项目结构

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,
        },
        {
          name: 'altText',
          type: 'text',
          required: true,
        }
      ]
    },
    {
      name: 'inStock',
      type: 'checkbox',
      defaultValue: true,
    },
  ],
  timestamps: true,
}

用户：你能验证这段代码以确保它遵循最佳实践吗？

AI：我将为您验证代码。

[使用 validate 工具]

验证结果表明您的代码有效并遵循最佳实践。以下是一些建议：

考虑向您的类别关系字段添加 maxDepth 以防止深度查询
您可能需要为创建、更新和删除操作添加访问控制
考虑在产品更新时添加用于库存管理的钩子

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

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

[使用 query 工具]

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

始终为创建、读取、更新和删除操作定义显式访问控制函数
对管理员用户使用基于角色的访问控制
为敏感数据实施字段级别的访问控制
对广泛的权限使用集合级别的访问控制
考虑将钩子与访问控制一起使用以实现复杂的逻辑

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

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
- 身份验证：是
- 集合：文章、类别、作者、媒体
- 全局变量：SiteSettings
- TypeScript：是

示例脚手架项目提示（详细）

为一个电子商务平台搭建一个全面的 Payload CMS 项目，其中包含以下规范：

项目详情：
- 名称：luxury-watches-store
- 描述："一个豪华手表的电子商务平台"
- 数据库：PostgreSQL
- TypeScript：是

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

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

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

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

5. 用户集合（启用身份验证），包含：
   - 电子邮件（电子邮件，必填）
   - 姓名（文本，必填）
   - 运送地址（地址组数组）
   - 订单历史记录（与订单的关系）
   - 愿望清单（与产品的关系）
   - 角色（选择：客户、管理员）

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

2. ShippingMethods，包含：
   - 带有价格的运送选项数组

包括以下内容的访问控制：
- 仅管理员访问权限才能管理产品、类别、品牌
- 客户访问权限才能访问自己的订单和个人资料
- 公开读取产品和类别的权限

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

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

为一个博客文章生成一个 Payload CMS 集合，其中包含标题、内容、作者和发布日期字段。

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

为一个房地产房产列表生成一个 Payload CMS 集合，其中包含以下规范：

集合名称：Properties
管理配置：
- 使用 "title" 作为显示字段
- 在管理面板中的 "Listings" 下分组
- 默认列：title、price、location、status、createdAt

字段：
1. 标题（文本，必填）
2. Slug（文本，唯一，从标题生成）
3. 描述（具有基本格式选项的富文本）
4. 价格（数字，必填）
5. 位置（组），包含：
   - 地址（文本）
   - 城市（文本，必填）
   - 州/省（文本，必填）
   - 邮政编码（文本）
   - 国家/地区（从预定义列表中选择）
   - 坐标（点）用于地图显示
6. 房产详情（组），包含：
   - 房产类型（选择：房屋、公寓、公寓、土地、商业）
   - 卧室（数字）
   - 浴室（数字）
   - 建筑面积（数字）
   - 占地面积（数字）
   - 建造年份（数字）
   - 停车位（数字）
7. 功能（复选框数组），包括：
   - 空调
   - 游泳池
   - 花园
   - 车库
   - 壁炉
   - 安全系统
   - 电梯
   - 家具
8. 图像（带有替代文本和标题的媒体上传数组）
9. 文档（用于平面图、证书等的文件上传数组）
10. 状态（选择：可用、合同中、已售出、已下架）
11. 精选（复选框，用于在主页上突出显示）
12. 代理（与用户集合的关系，必填）
13. 相关房产（与自身的关系，多个）

访问控制：
- 公开读取权限
- 代理可以创建和编辑自己的列表
- 管理员可以管理所有列表

钩子：
- 更改前：从标题格式化 slug
- 更改后：通知代理状态更改

版本控制：已启用
时间戳：已启用

提示的详细程度

MCP 服务器可以处理具有不同详细程度的提示：

最小细节（AI 填补空白）

为一个博客文章生成一个集合。

中等细节（具体要求）

为一个博客文章生成一个集合，其中包含标题、内容、特色图像、类别和作者字段。使标题和内容成为必填项。

高度细节（完整规范）

为一个博客文章生成一个集合，其中包含：
- Slug：posts
- 字段：
  - 标题（文本，必填）
  - 内容（具有自定义格式选项的富文本）
  - 特色图像（带有替代文本的上传）
  - 类别（与类别集合的关系，多个）
  - 作者（与用户集合的关系）
  - 状态（选择：草稿、已发布、已存档）
  - 发布日期（日期）
  - SEO（包含标题、描述和关键字的组）
- 管理配置：
  - 使用标题作为显示字段
  - 在 "Content" 下分组
  - 默认列：title、author、status、publishedDate
- 不同用户角色的访问控制
- 用于 slug 生成和通知的钩子
- 启用版本控制和时间戳

有效提示的技巧

具体说明要求：您提供的细节越多，输出就越量身定制。
指定关系：清楚地表明集合如何相互关联。
包括验证需求：提及字段的任何验证规则或约束。
描述管理 UI 首选项：指定您希望集合在管理面板中如何显示。
提及钩子和访问控制：如果您需要特定的业务逻辑或安全规则，请将其包含在您的提示中。
使用特定领域的术语：使用与您的行业或用例相关的术语来描述您的项目。

<hr>

📄 许可证

该项目已获得 MIT 许可证的许可 - 有关详细信息，请参阅 LICENSE 文件。

<hr>

🌍 关于 MATMAX WORLDWIDE

<div align="center"> <h3>MATMAX WORLDWIDE</h3> <p>创造帮助人类更加人性化的技术。</p> </div>

我们相信有益的技术——在尊重我们人性的同时，增强我们生活质量的工具。

加入我们，共同建设一个技术服务于健康、连接和目标的未来。我们可以共同创造出能够激发我们所有人最佳状态的数字体验。

访问 matmax.world 以了解更多关于我们以人为本的技术愿景。

<hr>

🖥️ 在本地运行

您可以使用 npm 在本地运行 Payload CMS MCP 服务器：

选项 1：从 npm 安装

# 全局安装
npm install -g payload-cms-mcp

# 运行服务器
payload-cms-mcp

选项 2：克隆存储库

克隆存储库：

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

安装依赖项：

npm install

在本地运行服务器：

npm run dev

或者：

npm run local

您的 MCP 服务器现在将在本地运行，并且可以用于开发和测试，而无需 Railway API 令牌。

🚀 部署选项

部署到 Railway（推荐）

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

点击按钮后：

选择 "Deploy from GitHub repo"
搜索 "Matmax-Worldwide/payloadcmsmcp"
点击 "Deploy Now"

快速 Cursor IDE 设置

部署后：

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

Payload CMS MCP Server

README

🚀 Payload CMS 3.0 MCP 服务器

📋 概述

✨ 功能

🔧 Payload CMS 3.0 功能

验证工具

代码生成

项目设置

📝 详细工具参考

验证工具

validate

query

mcp_query

代码生成

generate_template

generate_collection

generate_field

项目设置

scaffold_project

🚀 入门指南

1. 前提条件

2. 配置 Cursor

3. 使用 MCP 服务器

4. 示例工作流程

5. 完整的工作流程示例

📋 脚手架示例 & 详细提示

项目脚手架示例

示例脚手架项目提示（基本）

示例脚手架项目提示（详细）

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

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

提示的详细程度

最小细节（AI 填补空白）

中等细节（具体要求）

高度细节（完整规范）

有效提示的技巧

📄 许可证

🌍 关于 MATMAX WORLDWIDE

🖥️ 在本地运行

选项 1：从 npm 安装

选项 2：克隆存储库

🚀 部署选项

部署到 Railway（推荐）

快速 Cursor IDE 设置

推荐服务器

`validate`

`query`

`mcp_query`

`generate_template`

`generate_collection`

`generate_field`

`scaffold_project`