有效载荷CMS MCP服务器
概述
这是一个模型上下文协议（MCP）服务器，它使人工智能助手和工具能够直接与您的Payload CMS实例进行交互。它提供了一套安全、经过身份验证的工具，用于通过REST API执行创建、搜索和更新您Payload集合中对象等常见操作。
服务器自动处理身份验证，包括在需要时进行JWT令牌管理和基于浏览器的登录流程。它设计为轻量级、可配置，并且易于集成到开发工作流中（例如，与VS Code和Kilocode集成）。
特点/功能
- 创建对象向任意集合添加新文档，支持单个对象或批量添加。
- 搜索对象使用过滤器查询集合（类似MongoDB的方式）
where条款）、分页、排序、本地化以及相关字段的填充。 - 更新对象通过ID修改现有文档，支持部分更新。
- 认证处理自动刷新JWT令牌、存储凭据以及交互式浏览器登录，实现无缝认证。
- 本地化支持与Payload的i18n（国际化）功能配合使用；在工具调用中指定语言环境。
- 错误处理全面处理验证、认证、API及连接问题的异常。
- 可配置的通过环境变量覆盖有效载荷主机、超时设置、SSL 配置和日志记录。
工具模式（或工具架构）
以下列出了可用的工具及其输入模式（JSON Schema 格式）。这些定义了每个工具调用的参数。
创建对象
描述在指定的集合中创建一个或多个新对象。
{
"type": "object",
"properties": {
"collection_name": {
"type": "string",
"description": "Name of the collection to create object in"
},
"data": {
"oneOf": [
{
"type": "object",
"description": "Object data to create"
},
{
"type": "array",
"items": {
"type": "object"
},
"description": "Array of objects to create"
}
],
"description": "Object data or array of objects to create"
},
"locale": {
"type": "string",
"description": "Locale code for the operation (e.g., 'en', 'es'). If not provided and localization is enabled, only the ONE default locale will be used"
}
},
"required": ["collection_name", "data"]
}搜索对象
描述在集合中搜索对象。
{
"type": "object",
"properties": {
"collection_name": {
"type": "string",
"description": "Name of the collection to search in"
},
"query": {
"type": "object",
"description": "Search query parameters (MongoDB-like where clause)"
},
"limit": {
"type": "integer",
"description": "Maximum number of results to return"
},
"page": {
"type": "integer",
"description": "Page number for pagination"
},
"sort": {
"type": "string",
"description": "Sort field and direction"
},
"locale": {
"type": "string",
"description": "Locale code for the operation (e.g., 'en', 'es'). If not provided and localization is enabled, only the ONE default locale will be used"
}
},
"required": ["collection_name"]
}更新对象
描述通过ID更新对象。
{
"type": "object",
"properties": {
"collection_name": {
"type": "string",
"description": "Name of the collection containing the object"
},
"object_id": {
"type": "string",
"description": "ID of the object to update"
},
"data": {
"type": "object",
"description": "Updated object data"
},
"locale": {
"type": "string",
"description": "Locale code for the operation (e.g., 'en', 'es'). If not provided and localization is enabled, only the ONE default locale will be used"
}
},
"required": ["collection_name", "object_id", "data"]
}先决条件
在设置和使用此MCP服务器之前，请确保以下事项：
- Python 3.8及以上版本该服务器是用Python构建的，需要3.8或更高版本。
- 运行 Payload CMS 实例：
- 您的 Payload CMS 必须已启动并运行。 - 默认假设：可访问于 http://localhost:3000/api。 - 当首次调用工具时（例如，从您的MCP客户端发起调用），Payload实例必须已经可访问。 - 如果您的有效载荷托管在其他位置（例如，远程服务器），请通过环境变量配置基础URL（参见配置部分）。
- MCP兼容客户端：
- 一个像Kilocode这样的MCP客户端，可以在VS Code、Cursor或类似的AI开发工具中使用，这些工具支持MCP服务器。 - 确保您的客户端能够执行外部命令（例如，运行服务器二进制文件）。
注除了拥有一个正常运行的实例外，无需进行额外的数据库设置或有效载荷（Payload）配置。服务器不会为您启动或管理有效载荷——请单独处理这部分。
安装
- 克隆仓库：
git clone https://github.com/your-org/payload-mcp.git
cd payload-mcp- 安装依赖项：
安装所需的Python包。这包括MCP协议支持、HTTP客户端以及配置库。
pip install -r requirements.txt或者，安装完整包（建议用于全局使用）：
pip install .这使得 payload-mcp-server 在您的 PATH 中可用的命令。
- 设置环境：
复制示例环境文件并进行自定义：
cp .env.example .env编辑 .env 按需添加（见下文配置）。添加 .env 到你的 .gitignore 如果尚未设置（默认情况下是已设置的）。
配置
服务器使用 Pydantic 来确保从环境变量加载的配置类型安全。大多数用户可以依赖默认设置，但也可以通过（某种方式）进行自定义 .env 对于非本地设置。
关键环境变量
来自 .env.example：
- 有效载荷内容管理系统（CMS）连接：
- PAYLOAD_MCP_PAYLOAD__BASE_URL基础API URL（默认： http://localhost:3000/api)。 为远程主机设置覆盖，例如。， https://your-site.com/api. - PAYLOAD_MCP_PAYLOAD__AUTH_TOKEN可选的JWT令牌，用于预认证访问。如果省略，则在首次需要时将使用浏览器登录。 - PAYLOAD_MCP_PAYLOAD__TIMEOUT请求超时时间（以秒为单位）（默认：30）。 - PAYLOAD_MCP_PAYLOAD__VERIFY_SSL启用SSL验证（默认：本地开发时为false；设置为 true （用于HTTPS生产环境）。 - PAYLOAD_MCP_PAYLOAD__BYPASS_PROXY为本地主机设置旁路代理（默认：true）。
- 服务器设置：
- PAYLOAD_MCP_LOG_LEVEL日志详细程度（默认： INFO; 选项： DEBUG， WARNING， ERROR， CRITICAL）。
示例 .env 用于远程有效载荷：
PAYLOAD_MCP_PAYLOAD__BASE_URL=https://myapp.com/api
PAYLOAD_MCP_PAYLOAD__AUTH_TOKEN=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
PAYLOAD_MCP_PAYLOAD__VERIFY_SSL=true
PAYLOAD_MCP_LOG_LEVEL=DEBUG配置更改后重新加载服务器。
运行服务器
- 启动MCP服务器：
安装后，请运行：
payload-mcp-server或者直接从源头获取：
python -m payload_mcp.server- 服务器初始化，加载配置，并测试基本连接性（记录任何问题但继续运行）。 - 它在标准输入（stdio）上监听MCP协议通信。 - 日志将显示连接状态以及任何身份验证提示。
- 背景/制作：
- 对于持续运行的情况，使用诸如……之类的工具 nohup， screen或者 systemd。 - 示例： nohup payload-mcp-server > server.log 2>&1 &
服务器确实 不是 要求在启动时运行Payload——仅在调用工具时。然而，请确保在使用工具之前，Payload是可访问的。
与MCP客户端集成
- 添加到客户端 （例如，使用Kilocode的VS Code）：
- 打开你的MCP客户端设置（例如，在VS Code中：按Ctrl+Shift+P > 选择“Kilocode: 编辑MCP配置”）。 - 在您的MCP设置文件中添加一个新的服务器配置（通常 mcp.json 或类似情况）。 - 使用以下示例配置，并替换 `` 以及此项目根目录的实际路径：
{
"mcpServers": {
"payload-mcp": {
"command": "python",
"args": ["-m", "payload_mcp.server"],
"cwd": ""
}
}
}- 保存设置并重启/重新加载您的MCP客户端。 - 当需要时，客户端会自动启动服务器并列出可用的工具（例如。， create_object， search_objects， update_object)。
- 验证集成：
- 在您的MCP客户端中，查询可用工具。您应该会看到列出的Payload CMS工具。 - 测试一个简单的工具调用，比如搜索一个集合，以确保身份验证和连接功能正常工作。 - 如果触发了浏览器身份验证，请按照提示登录到您的Payload实例。
使用示例
一旦集成，您就可以在AI助手提示中使用这些工具。示例：
- 创建一个对象：
Use the create_object tool to add a new user to the 'users' collection with name: "John Doe" and email: "john@example.com".- 搜索对象：
Search the 'posts' collection for items where title contains "Payload" and limit to 5 results.- 更新一个对象：
Update the user with ID "123" in the 'users' collection to set email to "john@newemail.com".这些工具支持高级参数，如区域设置、人口统计以及复杂查询——有关详细信息，请参阅上面的工具模式。
故障排除
- 连接错误确保有效载荷（Payload）正在运行，并且可以通过配置的URL访问。检查日志以获取详细信息。
- 认证问题提供一个有效的JWT令牌
.env或者允许浏览器登录。请验证您的Payload用户是否拥有必要的权限。 - 未找到工具添加服务器配置后，重启MCP客户端。
- 日志设定/套装
PAYLOAD_MCP_LOG_LEVEL=DEBUG用于详细输出。 - Windows/PowerShell命令使用标准语法；使用
python.exe如果python含义模糊。
做出贡献
- 克隆该仓库并创建一个拉取请求。
- 如果添加新功能，请安装开发依赖项。
- 遵循PEP 8风格，并在适用的地方添加测试。
许可证
MIT 许可证。详见 许可证 如需详情，请添加（如需）。
如需支持，请查阅 Payload CMS 的文档或提交一个问题。