负载-mcp服务器

Name: 负载-mcp服务器
Author: ohnicholas93

作者：ohnicholas939 星标更新：2025-10-08

安装使用来源：spider==github.com

项目介绍

Payload CMS MCP 服务器

概述

这是一个模型上下文协议（MCP）服务器，它使AI助手和工具能够直接与您的Payload CMS实例进行交互。它提供了一组安全、经过身份验证的工具，用于通过REST API执行常见的操作，如在Payload集合中创建、搜索和更新对象。

该服务器自动处理身份验证，包括JWT令牌管理和浏览器登录流程（如有需要）。它设计得轻量级、可配置且易于集成到开发工作流中（例如，与VS Code和Kilocode一起使用）。

功能

创建对象：向任何集合添加新文档，支持单个对象或批量对象。
搜索对象：使用过滤器查询集合（类似于MongoDB的where子句），分页、排序、本地化以及相关字段的填充。
更新对象：通过ID修改现有文档，并支持部分更新。
身份验证处理：自动刷新JWT令牌，存储凭证以及交互式浏览器登录以实现无缝认证。
本地化支持：与Payload的i18n功能配合使用；在工具调用中指定区域设置。
错误处理：针对验证、认证、API和连接问题的全面异常处理。
可配置性：通过环境变量覆盖Payload主机、超时、SSL和日志记录设置。

工具模式

以下列出了可用工具及其输入模式（JSON Schema格式）。这些定义了每个工具调用的参数。

create_object

描述：在一个指定的集合中创建一个或多个新对象。

{
  "type": "object",
  "properties": {
    "collection_name": {
      "type": "string",
      "description": "要创建对象的集合名称"
    },
    "data": {
      "oneOf": [
        {
          "type": "object",
          "description": "要创建的对象数据"
        },
        {
          "type": "array",
          "items": {
            "type": "object"
          },
          "description": "要创建的对象数组"
        }
      ],
      "description": "要创建的对象数据或对象数组"
    },
    "locale": {
      "type": "string",
      "description": "操作的语言代码（例如，'en'，'es'）。如果未提供并且启用了本地化，则仅使用默认语言"
    }
  },
  "required": ["collection_name", "data"]
}

search_objects

描述：搜索集合中的对象。

{
  "type": "object",
  "properties": {
    "collection_name": {
      "type":  "string",
      "description": "要搜索的集合名称"
    },
    "query": {
      "type": "object",
      "description": "搜索查询参数（类似于MongoDB的where子句）"
    },
    "limit": {
      "type": "integer",
      "description": "返回结果的最大数量"
    },
    "page": {
      "type": "integer",
      "description": "分页的页码"
    },
    "sort": {
      "type": "string",
      "description": "排序字段和方向"
    },
    "locale": {
      "type": "string",
      "description": "操作的语言代码（例如，'en'，'es'）。如果未提供并且启用了本地化，则仅使用默认语言"
    }
  },
  "required": ["collection_name"]
}

update_object

描述：通过ID更新对象。

{
  "type": "object",
  "properties": {
    "collection_name": {
      "type": "string",
      "description": "包含对象的集合名称"
    },
    "object_id": {
      "type": "string",
      "description": "要更新的对象ID"
    },
    "data": {
      "type": "object",
      "description": "更新后的对象数据"
    },
    "locale": {
      "type": "string",
      "description": "操作的语言代码（例如，'en'，'es'）。如果未提供并且启用了本地化，则仅使用默认语言"
    }
  },
  "required": ["collection_name", "object_id", "data"]
}

先决条件

在设置并使用此MCP服务器之前，请确保满足以下条件：

Python 3.8+：服务器使用Python构建，需要版本3.8或更高版本。
运行中的Payload CMS实例：
- 您的Payload CMS必须正在运行。
- 默认假设：可通过http://localhost:3000/api访问。
- 在首次调用工具（例如，从您的MCP客户端）时，Payload实例必须已经可访问。
- 如果您的Payload托管在其他地方（例如远程服务器），则通过环境变量配置基础URL（参见配置部分）。
兼容MCP的客户端：
- 类似于Kilocode在VS Code中的MCP客户端，Cursor或其他支持MCP服务器的AI开发工具。
- 确保您的客户端可以执行外部命令（例如，运行服务器二进制文件）。

注意：除了拥有一个正常工作的实例外，不需要额外的数据库设置或Payload配置。服务器不会为您启动或管理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：

Payload 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；生产HTTPS设置为true）。
- PAYLOAD_MCP_PAYLOAD__BYPASS_PROXY：绕过本地主机代理（默认：true）。
服务器设置：
- PAYLOAD_MCP_LOG_LEVEL：日志详细程度（默认：INFO；选项：DEBUG，WARNING，ERROR，CRITICAL）。

示例.env用于远程Payload：

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
```
- 服务器初始化，加载配置，并测试基本连接（记录任何问题但继续运行）。
- 它监听标准输入输出以进行MCP协议通信。
- 日志将显示连接状态和任何认证提示。
后台/生产：
- 对于持久运行，使用nohup、screen或systemd等工具。
- 示例：nohup payload-mcp-server > server.log 2>&1 &

服务器在启动时不需要Payload正在运行——只需在调用工具时即可。但是，请确保在使用工具前Payload是可访问的。

与MCP客户端集成

添加到客户端（例如，VS Code与Kilocode）：
- 打开您的MCP客户端设置（例如，在VS Code中：Ctrl+Shift+P > "Kilocode: 编辑MCP配置"）。
- 将新的服务器配置添加到您的MCP设置文件中（通常是mcp.json或类似文件）。
- 使用以下示例配置，将<swap to root directory of the mcp server>替换为此项目根目录的实际路径：
```
{
  "mcpServers": {
    "payload-mcp": {
      "command": "python",
      "args": ["-m", "payload_mcp.server"],
      "cwd": "<swap to root directory of the mcp server>"
    }
  }
}
```
- 保存设置并重启/重新加载您的MCP客户端。
- 客户端将在需要时自动启动服务器，并列出可用工具（例如，create_object，search_objects，update_object）。
验证集成：
- 在您的MCP客户端中查询可用工具。您应该看到Payload CMS工具列表。
- 测试简单的工具调用，如搜索集合，以确保认证和连接正常工作。
- 如果触发浏览器认证，请按照提示登录到您的Payload实例。

使用示例

一旦集成，您可以在AI助手提示中使用这些工具。示例如下：

创建对象：

使用create_object工具将具有姓名："John Doe"和电子邮件："john@example.com"的新用户添加到'users'集合中。

搜索对象：

在'posts'集合中搜索标题包含"Payload"的项目，并限制结果为5条。

更新对象：

更新'users'集合中ID为"123"的用户的电子邮件为"john@newemail.com"。

这些工具支持高级参数，如区域设置、填充和复杂查询——请参阅上述工具模式以获取完整详情。

故障排除

连接错误：确保Payload正在运行并且可以在配置的URL上访问。检查日志以获取详细信息。
认证问题：在.env中提供有效的JWT令牌或允许浏览器登录。验证您的Payload用户具有必要的权限。
工具未找到：在添加服务器配置后重启MCP客户端。
日志：设置PAYLOAD_MCP_LOG_LEVEL=DEBUG以获得详细的输出。
Windows/PowerShell：命令使用标准语法；如果python有歧义，请使用python.exe。

贡献

分叉仓库并创建拉取请求。
如果添加功能，请安装开发依赖项。
遵循PEP 8风格并在适用的情况下添加测试。

许可证

MIT许可证。详情见LICENSE（如有必要添加）。

如有支持需求，请查阅Payload CMS文档或提交问题。