使用说明
🚀 有效载荷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 ValidationValidate Payload CMS code for collections, fields, globals, and config files with detailed feedback on syntax errors and best practices. |
🔍Code GenerationGenerate code templates for collections, fields, globals, access control, hooks, endpoints, plugins, blocks, and migrations. |
🚀Project ScaffoldingScaffold 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?
```typescript
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(可选字符串):服务器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.先决条件
在开始之前,请确保您已经:
- Node.js 18+(有效负载CMS 3.0所需)
- 活跃的铁路账户
- 铁路API令牌(在 铁路.app/account/tokes)
- 基本熟悉Payload CMS 3.0概念
2.配置光标
要与Cursor IDE一起使用,请执行以下操作:
- 打开光标设置
- 转到MCP服务器部分
- 添加新的MCP服务器
- 将其命名为“有效载荷CMS 3.0 MCP”
- 将传输类型设置为“命令”
- 将命令设置为:
railway run --service=YOUR_SERVICE_ID - 保存配置
3.使用MCP服务器
配置后,您可以在AI提示中使用这些工具:
- 代码验证: “验证此有效载荷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中访问控制的最佳实践:
- 始终为创建、读取、更新和删除操作定义显式访问控制函数
- 对管理员用户使用基于角色的访问控制
- 对敏感数据实施现场级访问控制
- 对广泛权限使用集合级访问控制
- 考虑在访问控制的同时使用钩子来处理复杂的逻辑
用户:现在我需要用这个产品集合和一个类别集合来构建一个完整的项目。
艾:我会为你搭建一个完整的项目。
[使用脚手架_工程工具]
我已经生成了一个完整的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服务器:
选项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