🚀 Payload CMS 3.0 MCP 服务器
📋 概述
Payload CMS 3.0 MCP 服务器是一款专用的模型上下文协议 (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 （字符串）：要验证的代码fileType （枚举）：文件类型 - “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 （字符串）：查询字符串fileType （可选枚举）：文件类型 - “collection”、“field”、“global”或“config”
示例提示：
What are the best practices for implementing access control in Payload CMS collections?
mcp_query
针对 Payload CMS 结构执行类似 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 （枚举）：模板类型 - “collection”、“field”、“global”、“config”、“access-control”、“hook”、“endpoint”、“plugin”、“block”、“migration”options （记录）：模板的配置选项
示例提示：
Generate a template for a Payload CMS hook that logs when a document is created.
generate_collection
生成完整的 Payload CMS 集合定义。
参数：
slug （字符串）：集合slugfields （可选数组）：字段对象数组auth （可选布尔值）：这是否是一个身份验证集合timestamps （可选布尔值）：是否包含时间戳admin （可选对象）：管理面板配置hooks （可选布尔值）：是否包含钩子access （可选布尔值）：是否包含访问控制versions （可选布尔值）：是否启用版本控制
示例提示：
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 （字符串）：字段名称type （字符串）：字段类型required （可选布尔值）：该字段是否为必填项unique （可选布尔值）：该字段是否应唯一localized （可选布尔值）：该字段是否应该本地化access （可选布尔值）：是否包含访问控制admin （可选对象）：管理面板配置validation （可选布尔值）：是否包含验证defaultValue （可选）：字段的默认值
示例提示：
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 （字符串）：项目名称description （可选字符串）：项目描述serverUrl （可选字符串）：服务器 URLdatabase （可选枚举）：数据库类型 - “mongodb”或“postgres”auth （可选布尔值）：是否包含身份验证admin （可选对象）：管理面板配置collections （可选数组）：集合对象数组globals （可选数组）：全局对象数组blocks （可选数组）：块对象数组plugins （可选数组）：插件字符串数组typescript （可选布尔值）：是否使用 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. 先决条件
在开始之前，请确保您已：
2. 配置游标
与 Cursor IDE 一起使用：
- 打开游标设置
- 前往 MCP 服务器部分
- 添加新的 MCP 服务器
- 将其命名为“Payload CMS 3.0 MCP”
- 将传输类型设置为“命令”
- 将命令设置为：
railway run --service=YOUR_SERVICE_ID - 保存配置
3. 使用 MCP 服务器
配置完成后，您可以在 AI 提示中使用这些工具：
- 代码验证： “验证此 Payload CMS 收集代码”
- 模板生成： “为媒体集合生成模板”
- 查询规则： “访问控制的查询验证规则”
- 类似 SQL 的查询： “执行查询以查找集合的字段类型”
4.示例工作流程
Payload CMS MCP 服务器的典型工作流程：
- 生成具有特定字段的集合模板
- 验证生成的代码是否符合最佳实践
- 查询特定的验证规则来改进代码
- 生成附加组件，例如钩子或端点
- 准备就绪后搭建完整的项目结构
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：我会为你验证代码。
[使用验证工具]
验证结果表明您的代码有效且遵循最佳实践。以下是一些建议：
- 考虑向类别关系字段添加 maxDepth 以防止深度查询
- 您可能希望为创建、更新和删除操作添加访问控制
- 考虑在产品更新时添加库存管理挂钩
用户：Payload CMS 中访问控制的最佳实践是什么？
AI：让我查询一下访问控制的验证规则。
[使用查询工具]
以下是 Payload CMS 中访问控制的最佳实践：
- 始终为创建、读取、更新和删除操作定义明确的访问控制函数
- 对管理员用户使用基于角色的访问控制
- 对敏感数据实施字段级访问控制
- 使用集合级访问控制来获得广泛的权限
- 考虑使用钩子和访问控制来实现复杂的逻辑
用户：现在我需要用这个产品集合和类别集合来构建一个完整的项目。
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
有效提示的技巧
- 具体说明要求：您提供的细节越多，输出就越有针对性。
- 指定关系：清楚地表明集合之间的关系。
- 包括验证需求：提及字段的任何验证规则或约束。
- 描述管理员 UI 首选项：指定您希望集合在管理面板中显示的方式。
- 提及钩子和访问控制：如果您需要特定的业务逻辑或安全规则，请将它们包含在您的提示中。
- 使用特定领域的术语：使用与您的行业或用例相关的术语描述您的项目。
📄 许可证
该项目根据 MIT 许可证获得许可 - 有关详细信息，请参阅 LICENSE 文件。
🌍 关于 MATMAX WORLDWIDE
我们相信科技可以带来好处——科技工具可以在尊重人性的同时改善我们的生活。
加入我们，共创未来，让科技服务于健康、连接和目标。携手共创数字体验，激发每个人的潜能。
访问matmax.world了解有关我们以人为本的技术愿景的更多信息。
🖥️ 本地运行
您可以使用 npm 在本地运行 Payload CMS MCP 服务器：
选项 1：从 npm 安装
# Install globally
npm install -g payload-cms-mcp
# Run the server
payload-cms-mcp
选项 2：克隆存储库
- 克隆存储库：
git clone https://github.com/Matmax-Worldwide/payloadcmsmcp.git
cd payloadcmsmcp
- 安装依赖项：
- 在本地运行服务器：
或者：
您的 MCP 服务器现在将在本地运行，并且可以进行开发和测试，而无需 Railway API 令牌。
🚀 部署选项
部署到 Railway（推荐）
部署 MCP 服务器最简单的方法是使用 Railway 的一键部署：
点击按钮后：
- 选择“从 GitHub 仓库部署”
- 搜索“Matmax-Worldwide/payloadcmsmcp”
- 点击“立即部署”
快速光标 IDE 设置
部署后：
- 安装 Railway CLI：
npm install -g @railway/cli - 登录铁路：
railway login - 项目链接：
railway link - 在“光标设置”>“MCP 服务器”中，将“命令”设置为：
railway run