Awinel/payload-plugin-mcp-granular

# Payload MCP 细粒度 Plugin 一个用于 [Payload](https://github.com/payloadcms/payload) 的插件，派生自官方的 [`@payloadcms/plugin-mcp`](https://github.com/payloadcms/payload/tree/main/packages/plugin-mcp) 包，并为 collection 的 `find`、`create` 和 `update` 操作添加了字段级别的颗粒度控制。 ## 它添加了什么 - 向后兼容官方的 `enabled: true` 和 `enabled: { ... }` MCP 配置 - 针对集合的全新 `granularity` 配置 - API key 的 UI 界面，允许管理员为每个 MCP key 选择可以 `find`、`create` 和 `update` 的顶层字段 - MCP 工具 schema 经过过滤，仅保留当前 API key 允许的字段 - Runtime 字段访问包装器，确保在 MCP 流量中，写入时会丢弃不允许的字段，读取时会忽略这些字段 ## 前置要求 - Payload `^3.80.0` - 一个已经在使用或准备使用 Payload MCP 插件模型的项目 ## 安装说明 ``` pnpm add payload-plugin-mcp-granular ``` ## 快速开始 ``` import { buildConfig } from 'payload' import { mcpPlugin } from 'payload-plugin-mcp-granular' export default buildConfig({ collections: [ { slug: 'students', fields: [ { name: 'name', type: 'text' }, { name: 'email', type: 'email' }, { name: 'notes', type: 'textarea' }, ], }, ], plugins: [ mcpPlugin({ collections: { students: { enabled: { find: true, update: true, }, granularity: { find: true, update: true, }, }, }, }), ], }) ``` 使用上述配置，每个 MCP API key 的管理 UI 将暴露出 `students` 的 `find` / `update` 开关，一旦启用，它将显示诸如 `name`、`email` 和 `notes` 等字段的复选框。 ## 颗粒度配置 您可以通过两种方式启用细粒度字段控制。 将其应用于所有已启用的基于字段的操作： ``` collections: { students: { enabled: { find: true, create: true, update: true, delete: true, }, granularity: true, }, } ``` 或者针对特定操作进行应用： ``` collections: { students: { enabled: { find: true, update: true, }, granularity: { find: true, update: true, }, }, } ``` ## API Key 权限的工作原理 与官方插件一样，依然有两层访问控制： 1. 在您的 Payload 配置中启用集合和操作。 2. 在管理面板中创建一个 MCP API key，并允许该 key 执行特定的操作。 当为集合操作启用了 `granularity` 时： - 为该集合开启 `find`、`create` 或 `update` 会显示第二组字段复选框 - 每个复选框代表集合中的一个顶层字段 - 在 `create` / `update` 的 MCP 工具 schema 中，仅暴露选中的字段 - 在 Runtime 期间，MCP 流量仅允许操作选中的字段 ## 行为说明 - 目前仅支持对集合进行颗粒度控制 - 在 v1 版本中，颗粒度控制仅限于顶层字段 - `delete` 依然维持在集合级别 - Globals 保持上游插件的行为 - 如果为某个 key 启用了某项操作，但未选择任何字段，则该颗粒化 MCP 工具将被视为对该 key 禁用 - 非 MCP 流量不受影响 ## 行为示例 如果您进行了如下配置： ``` collections: { students: { enabled: { find: true, update: true, }, granularity: { find: true, update: true, }, }, } ``` 并且在 API key UI 中您允许： - `students.update = true` - `students.updateFields.name = true` - `students.find = true` - `students.findFields.name = true` 那么： - MCP 客户端可以更新 `name` 字段 - MCP 客户端无法更新 `email`、`notes` 或其他顶层字段 - `findStudents` 的响应仅暴露 `name` 以及正常的系统元数据（例如 `id`） ## 本地开发 构建该包： ``` pnpm install pnpm build ``` 创建一个 tarball 以便在另一个 Payload 应用中进行测试： ``` npm pack ``` ## 相关链接 - 官方插件源码：[payloadcms/payload/packages/plugin-mcp](https://github.com/payloadcms/payload/tree/main/packages/plugin-mcp) - 官方插件文档：[Payload MCP Plugin Docs](https://payloadcms.com/docs/plugins/mcp)

标签：API管理, CMS插件, MCP, MITM代理, Payload CMS, Streamlit, Syscall, Web开发, 自动化攻击, 访问控制