🚀 有效载荷CMS 3.0 MCP服务器
A specialized MCP server for Payload CMS 3.0
Validate code, generate templates, and scaffold projects following best practices
📋 概述
Payload CMS 3.0 MCP服务器是一个专门的模型上下文协议服务器，旨在增强您的Payload CMS开发体验。它通过提供遵循最佳实践的代码验证、模板生成和项目脚手架功能，帮助开发人员构建更好的Payload CMS应用程序。
✨ 特性
📚
Code Validation
Validate Payload CMS code for collections, fields, globals, and config files with detailed feedback on syntax errors and best practices.
🔍
Code Generation
Generate code templates for collections, fields, globals, access control, hooks, endpoints, plugins, blocks, and migrations.
🚀
Project Scaffolding
Scaffold entire Payload CMS projects with validated options for consistency and adherence to best practices.
🔧 有效载荷CMS 3.0功能
验证工具
validate-验证集合、字段、全局变量和配置的代码query-查询验证规则和最佳实践mcp_query-对Payload CMS结构执行类似SQL的查询
代码生成
generate_template-为各种组件生成代码模板generate_collection-创建完整的集合定义generate_field-使用正确的键入生成字段定义
项目设置
scaffold_project-创建整个Payload CMS项目结构validate_scaffold_options-确保脚手架选项遵循最佳实践（脚手架项目内部使用）
📝 详细工具参考
验证工具
validate
验证Payload CMS代码的语法和最佳实践。
参数：
code（string）：要验证的代码fileType（枚举）：文件类型-“集合”、“字段”、“全局”或“配置”
示例提示：
Can you validate this Payload CMS collection code?
export const Posts = { slug: 'posts', fields: [ { name: 'title', type: 'text', required: true, }, { name: 'content', type: 'richText', } ], admin: { useAsTitle: 'title', } }
#### `query`
查询有效载荷CMS的验证规则和最佳实践。
**参数：**
- `query` （string）：查询字符串
- `fileType` （可选枚举）：文件类型-“集合”、“字段”、“全局”或“配置”
**示例提示：**
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` （枚举）：模板类型-“集合”、“字段”、“全局”、“配置”、“访问控制”、“钩子”、“端点”、“插件”、“块”、“迁移”
- `options` （记录）：模板的配置选项
**示例提示：**
Generate a template for a Payload CMS hook that logs when a document is created.
#### `generate_collection`
生成完整的Payload CMS收集定义。
**参数：**
- `slug` （字符串）：收集段塞
- `fields` （可选数组）：字段对象数组
- `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`
生成有效载荷CMS字段定义。
**参数：**
- `name` （string）：字段名称
- `type` （string）：字段类型
- `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`
构建完整的有效载荷CMS项目结构。
**参数：**
- `projectName` （string）：项目名称
- `description` （可选字符串）：项目描述
- `serverUrl` （可选字符串）：服务器URL
- `database` （可选枚举）：数据库类型-“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.先决条件
在开始之前，请确保您已经：
- Node.js 18+（有效负载CMS 3.0所需）
- 活跃的铁路账户
- 铁路API令牌（在 [铁路.app/account/tokes](https://railway.app/account/tokens))
- 基本熟悉Payload CMS 3.0概念
### 2.配置光标
要与Cursor IDE一起使用，请执行以下操作：
1. 打开光标设置
1. 转到MCP服务器部分
1. 添加新的MCP服务器
1. 将其命名为“有效载荷CMS 3.0 MCP”
1. 将传输类型设置为“命令”
1. 将命令设置为： `railway run --service=YOUR_SERVICE_ID`
1. 保存配置
### 3.使用MCP服务器
配置后，您可以在AI提示中使用这些工具：
- **代码验证：** “验证此有效载荷CMS收集代码”
- **模板生成：** “为媒体收藏生成模板”
- **查询规则：** “查询访问控制的验证规则”
- **类似SQL的查询：** “执行查询以查找集合的字段类型”
### 4.工作流程示例
Payload CMS MCP服务器的典型工作流程：
1. 生成包含特定字段的集合模板
1. 验证生成的代码是否符合最佳实践
1. 查询特定验证规则以改进代码
1. 生成其他组件，如钩子或端点
1. 准备就绪后搭建完整的项目结构
### 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:
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中访问控制的最佳实践：
- 始终为创建、读取、更新和删除操作定义显式访问控制函数
- 对管理员用户使用基于角色的访问控制
- 对敏感数据实施现场级访问控制
- 对广泛权限使用集合级访问控制
- 考虑在访问控制的同时使用钩子来处理复杂的逻辑
用户：现在我需要用这个产品集合和一个类别集合来构建一个完整的项目。
艾：我会为你搭建一个完整的项目。
\[使用脚手架_工程工具\]
我已经生成了一个完整的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许可证获得许可-有关详细信息，请参阅许可证文件。
🌍 关于MATMAX全球
MATMAX WORLDWIDE
Creating technology that helps humans be more human.
我们相信技术是好的——在尊重人性的同时改善我们生活的工具。
加入我们，建设一个技术服务于健康、联系和目的的未来。我们可以共同创造数字体验，让我们所有人发挥出最好的一面。
访问 matmax.world 了解更多关于我们以人为本的技术愿景。
🖥️ 本地运行
您可以使用npm在本地运行Payload CMS MCP服务器：
](https://www.npmjs.org/package/payload-cms-mcp) ](https://npmjs.org/package/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- 安装依赖项：
npm install- 在本地运行服务器：
npm run dev或者：
npm run local您的MCP服务器现在将在本地运行，并可用于开发和测试，而不需要Railway API令牌。
🚀 部署选项
部署到铁路（推荐）
部署MCP服务器最简单的方法是使用Railway的一键部署：
点击按钮后：
- 选择“从GitHub仓库部署”
- 搜索“Matmax Worldwide/payloadcmsmcp”
- 点击“立即部署”
快速光标IDE设置
部署后：
- 安装铁路CLI：
npm install -g @railway/cli - 登录铁路：
railway login - 链接到您的项目：
railway link - 在光标设置>MCP服务器中，将命令设置为：
railway run