Payload MCP

Payload MCP

⚠️ 正在开发中
此仓库仍在积极开发中，功能尚未完善。API、配置和 CLI 命令可能会随时更改。使用风险自负！

Payload MCP 是一款强大的 Payload CMS 模型上下文协议（MCP）服务，可帮助 AI 助手开发、管理和扩展 Payload CMS 项目。

概述

Payload MCP（模型上下文协议）是一款专用服务，可将 AI 助手连接到 Payload CMS 开发工作流。它提供一系列工具，可用于生成代码、验证组件、搭建项目脚手架以及执行专用查询，AI Agent 可通过标准化的模型上下文协议访问所有这些工具。

此项目实现了一个可在本地运行的 MCP 服务，为 AI 助手提供专为 Payload CMS 开发定制的功能，让以下工作更加轻松：

• 为集合、字段、访问控制等生成样板代码
• 验证 Payload CMS 组件
• 搭建新的 Payload CMS 项目脚手架
• 查询和分析现有代码库

功能

• 代码生成：按照正确的结构和最佳实践，创建集合、字段、配置文件、访问控制规则、钩子、端点、插件、区块、迁移和组件
• 验证：验证 Payload CMS 组件，确保它们遵循最佳实践且能正常运行
• 脚手架搭建：使用合适的文件结构和依赖项设置新的 Payload CMS 项目
• 专用查询：获取关于 Payload CMS 代码库的建议和见解
• 符合 MCP 规范：适用于任何支持模型上下文协议的 AI 助手
• 本地优先：完全在本地计算机上运行，保护隐私和安全

开始使用

前提条件

• Node.js（v16 或更高版本）
• npm 或 Bun（推荐）

安装

1. 安装软件包：

   npm install -g @ngyngcphu/payload-mcp
   

2. 通过在 mcp.json 中添加以下内容来配置 MCP 客户端（例如 Cursor）：

   {
     "mcpServers": {
       "@ngyngcphu/payload-mcp": {
         "command": "npx",
         "args": ["@ngyngcphu/payload-mcp"]
       }
     }
   }
   

3. MCP 客户端需要时，服务会自动启动。默认端口为 3001。

手动启动（可选）

如果要手动启动服务：

npx @ngyngcphu/payload-mcp

工具参考

Payload MCP 提供四类工具：

生成器工具

为 Payload CMS 组件生成样板代码：

工具	描述
collection	生成包含字段、钩子和访问控制的 Payload 集合
field	为集合生成字段配置
config	生成 Payload 配置文件
access-control	生成访问控制函数
hook	为集合生成前置/后置钩子
endpoint	生成自定义 API 端点
plugin	生成 Payload 插件
block	为 Payload 区块字段类型生成区块
migration	生成数据库迁移
component	为管理面板生成 React 组件

查询工具

用于查询和分析 Payload CMS 代码库的工具：

工具	描述
validate_query	验证并格式化 Payload 查询
get_query_suggestions	根据集合获取 Payload 查询建议
format_response	格式化 Payload 查询的响应

脚手架工具

用于搭建新的 Payload CMS 项目脚手架的工具：

工具	描述
create_project	按照推荐结构创建新的 Payload CMS 项目
add_feature	为现有 Payload CMS 项目添加功能
setup_authentication	为 Payload CMS 项目配置身份验证
setup_deployment	为各种平台配置部署设置

验证工具

用于验证 Payload CMS 组件的工具：

工具	描述
validate_collection	验证集合配置
validate_field	验证字段配置
validate_access_control	验证访问控制规则
validate_hook	验证钩子实现

示例用法

生成集合

// Example: Generate a simple blog post collection
const options = {
  name: "Post",
  slug: "posts",
  fields: [
    { name: "title", type: "text", required: true },
    { name: "content", type: "richText" },
    { name: "status", type: "select", options: ["draft", "published"] }
  ],
  timestamps: true,
  auth: false
};

// The AI would use the generate_template tool with these options
// Result would be a complete collection configuration file

验证查询

// Example: Validate a query for the posts collection
const query = {
  where: {
    status: {
      equals: "published"
    },
    createdAt: {
      greater_than: "2023-01-01"
    }
  },
  sort: "-createdAt",
  limit: 10
};

// The AI would use the validate_query tool with this query
// Result would indicate if the query is valid and properly formatted

搭建新项目

// Example: Create a new Payload CMS project for a blog
const options = {
  name: "My Blog",
  collections: ["posts", "categories", "authors"],
  authentication: true,
  admin: {
    customization: true
  },
  database: "mongodb"
};

// The AI would use the create_project tool with these options
// Result would be instructions for setting up a complete project

配置

可通过修改以下文件来配置 Payload MCP：

• package.json：更新 name、version 和其他元数据
• index.ts：根据需要更改默认端口（3001）
• server/index.ts：配置服务器选项，例如 MCP 服务名称

示例工作流

使用 Payload MCP 的典型工作流如下：

1. 启动 MCP 服务：

   npm start
   

2. 连接 AI 助手： 将 AI 助手配置为使用 http://localhost:3001/ 上的 MCP 服务

3. 请求生成： 请 AI 助手为你的 Payload CMS 项目生成一个新集合

4. 审查并集成： 审查生成的代码，并将其集成到你的 Payload CMS 项目中

5. 验证： 使用验证工具确保实现正确

6. 迭代： 在 AI 助手和 MCP 工具的帮助下继续开发

提示与最佳实践

• 从搭建开始：对于新项目，使用搭建工具来设置结构良好的项目
• 经常验证：使用验证工具在开发过程中尽早发现问题
• 组合使用工具：大多数复杂任务都需要多个工具，例如先生成集合，再进行验证
• 审查生成的代码：集成到项目之前，务必审查生成的代码
• 保持服务运行：在开发期间保持 MCP 服务运行，以便 AI 助手访问
• 使用 Git：经常提交更改，以便在需要时轻松跟踪和还原更改

未来计划

• 为更多 Payload CMS 组件类型添加生成器
• 与主流 IDE 集成
• 支持 GraphQL 查询生成和验证
• 针对大型 Payload CMS 项目进行性能优化

贡献

欢迎贡献！请随时提交 Pull Request。

支持

如果遇到问题或有疑问，请在 GitHub 仓库中提交 issue。