AI导哈

CMS数据操作工具

Payload CMS MCP Server是一个轻量级的模型上下文协议服务器，提供创建、搜索和更新Payload CMS集合中对象的安全认证工具，支持自动JWT令牌管理和本地化功能。

  • by ohnicholas93
  • Python
  • 本地部署
  • 9 星标
  • 更新于
在 GitHub 查看 ohnicholas93/payload-mcp-server

使用说明

有效载荷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服务器之前，请确保以下事项：

  1. Python 3.8及以上版本该服务器是用Python构建的，需要3.8或更高版本。
  2. 运行 Payload CMS 实例：
    • 您的 Payload CMS 必须已启动并运行。
    • 默认假设：可访问于 http://localhost:3000/api。
    • 当首次调用工具时（例如，从您的MCP客户端发起调用），Payload实例必须已经可访问。
    • 如果您的有效载荷托管在其他位置（例如，远程服务器），请通过环境变量配置基础URL（参见配置部分）。
  3. MCP兼容客户端：
    • 一个像Kilocode这样的MCP客户端，可以在VS Code、Cursor或类似的AI开发工具中使用，这些工具支持MCP服务器。
    • 确保您的客户端能够执行外部命令（例如，运行服务器二进制文件）。

注除了拥有一个正常运行的实例外，无需进行额外的数据库设置或有效载荷（Payload）配置。服务器不会为您启动或管理有效载荷——请单独处理这部分。

安装

  1. 克隆仓库：

    git clone https://github.com/your-org/payload-mcp.git
cd payload-mcp

  2. 安装依赖项： 安装所需的Python包。这包括MCP协议支持、HTTP客户端以及配置库。

    pip install -r requirements.txt

    或者，安装完整包（建议用于全局使用）：

    pip install .

    这使得 payload-mcp-server 在您的 PATH 中可用的命令。

  3. 设置环境： 复制示例环境文件并进行自定义：

    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

配置更改后重新加载服务器。

运行服务器

  1. 启动MCP服务器： 安装后，请运行：

    payload-mcp-server

    或者直接从源头获取：

    python -m payload_mcp.server
    • 服务器初始化，加载配置，并测试基本连接性（记录任何问题但继续运行）。
    • 它在标准输入（stdio）上监听MCP协议通信。
    • 日志将显示连接状态以及任何身份验证提示。

  2. 背景/制作：

    • 对于持续运行的情况，使用诸如……之类的工具 nohup， screen或者 systemd。
    • 示例： nohup payload-mcp-server > server.log 2>&1 &

服务器确实 不是 要求在启动时运行Payload——仅在调用工具时。然而，请确保在使用工具之前，Payload是可访问的。

与MCP客户端集成

  1. 添加到客户端 （例如，使用Kilocode的VS Code）：

    • 打开你的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)。

  2. 验证集成：

    • 在您的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 的文档或提交一个问题。

相关 MCP