内容
<div align="center">
# MarreiraMCP 构建工具
**统一的MCP服务器，用于Bricks Builder和Elementor — 智能创建和编辑页面，安全且可逆转。**
[](marreira-mcp-builders/CHANGELOG.md)
[](https://wordpress.org/)
[](https://www.php.net/)
[](#许可证)
[](https://modelcontextprotocol.io/)
</div>
---
## 什么是 MarreiraMCP 构建工具
**MarreiraMCP 构建工具**是一款WordPress插件，它直接将智能代理（Claude、Cursor和其他MCP客户端）连接到 **Bricks Builder** 或 **Elementor**。与其手动拖拽元素，不如让智能代理使用 **原生格式** 创建和调整页面，这是每个构建工具的视觉编辑器所使用的格式。
MCP服务器完全用 **PHP** 编写（无Node.js依赖），并通过隐藏的REST路由暴露，该路由受到令牌保护。一个站点一次只能使用 **一个活动构建工具**（在 onboarding过程中选择）；可以在任何时候在控制面板中切换。
> **取代** 两个以前的插件，现在已经冻结：
> **MarreiraMCP Bricks** （0.5.2）和 **MarreiraMCP Elementor** （0.1.1）。
> 这是官方统一的基础 - 参见后面的 [血统](#血统) 部分。
---
## 亮点
| | |
|---|---|
| 🔀 **一个插件，两个构建工具** | Bricks 或 Elementor — 每次一个，控制面板中可切换，无需重新安装。 |
| 🤖 **原生智能创建** | 智能创建部分、容器、标题、按钮 — 以真实格式，而不是粘贴的HTML。 |
| 🔁 **确保往返** | 智能创建的页面在视觉编辑器中打开；编辑器中的页面可以由智能优化。 |
| 📦 **`run_batch`** | 将N个更改分组为 **单个请求** — 避免主机/WAF阻止。 |
| 🔑 **多令牌与范围** | 令牌具有粒度能力；到期和IP允许列表是独立的。 |
| 🛡️ **默认安全** | HMAC-SHA256，IP限制，管理员重新验证，审计日志，Code_Guard防RCE。 |
| 🖥️ **WordPress CLI** | 插件、主题、核心、文件、代码片段、数据库、执行 — 出厂时关闭，双重锁定。 |
| ⚡ **可配置的智能模式** | `premium` （完整）或 `economy` （精简，限制较小）。 |
---
## 要求
- WordPress **6.4+**
- PHP **8.0+**
- **Bricks Builder** 或 **Elementor** 处于活动状态（两者之一）
- 网站上的 **HTTPS** （必填）
- 一个 **MCP客户端** 来消费服务器（例如：Claude Desktop，Cursor）
---
## 快速安装
1. 将 `marreira-mcp-builders/` 文件夹复制到 `wp-content/plugins/` （或通过WordPress控制面板安装 `.zip` 文件）。
2. 在 **插件** 中激活。
3. 在管理菜单中访问 **MarreiraMCP 构建工具**。
4. 按照 **onboarding向导** 进行操作：
- 选择 **活动构建工具** （Bricks 或 Elementor — 必须安装并激活）。
- 选择 **智能层级** （`premium` 或 `economy`）。
- 生成 **第一个令牌** 并复制它（仅显示一次）。
5. 配置您的MCP客户端：
```http
POST https://您的网站/wp-json/marreira-mcp/v1/mcp
Authorization: Bearer <您的令牌>
Content-Type: application/json
```
---
## 端点
所有路由都使用 `marreira-mcp/v1` 命名空间，并且 **隐藏** 在公共索引 `/wp-json/` 中（`show_in_index => false` + 索引过滤器）。
| 路由 | 方法 | 认证 | 描述 |
|---|---|---|---|
| `/mcp` | POST | Bearer令牌 | MCP服务器 — JSON-RPC 2.0 (`initialize` / `tools/list` / `tools/call`) |
| `/skill` | GET | 公共 | 提供 `SKILL.md` （精简版 `economy` 模式） |
| `/describe` | GET | Bearer令牌 | 活动构建工具、分层、令牌能力和工具目录 |
| `/cli/*` | GET/POST | Bearer令牌 + 能力 | 通用WordPress CLI（出厂时关闭） |
---
## 架构
```
┌──────────────┐ JSON-RPC 2.0 / HTTPS ┌───────────────────────────────────────┐
│ 智能客户端 │ ─── Authorization: Bearer ▶ │ WordPress + MarreiraMCP 构建工具 │
│ (MCP客户端) │ │ （隐藏REST路由 /mcp） │
└──────────────┘ ◀── JSON结果 ────────────── └──────────────────┬────────────────────┘
│
┌─────────────────────────────────────────┴──────────────────────┐
│ MCP核心（构建工具无关） │
│ Tool_Registry · Auth · Audit · CLI · run_batch · get_map │
└─────────────────────────────────────────┬──────────────────────┘
│ 构建工具管理器加载活动驱动程序
┌──────────────────────────┴──────────────────────────┐
│ │
┌────────▼────────────┐ ┌──────────────────▼──────┐
│ Bricks驱动程序 │ │ Elementor驱动程序 │
│ includes/builders/ │ │ includes/builders/ │
│ bricks/ │ │ elementor/ │
└─────────────────────┘ └─────────────────────────┘
```
MCP核心与构建工具无关。具体逻辑在驱动程序中，位于 `includes/builders/<slug>/`。驱动程序实现 `Builder_Driver` 接口，并向共享的 `Tool_Registry` 提供工具。
---
## 智能模式（层级）
在onboarding过程中配置，并在以后在设置中可更改：
- **`premium`** — 完整响应和地图；智能可以按需拉取整个树。
- **`economy`** — `/skill` 端点提供精简版文档；较小响应限制；智能建议使用 `get_map` 、分页列表和 `run_batch` 以节省上下文。
`GET /describe` 端点报告当前层级和令牌能力。
---
## `run_batch` — 一个请求，N个更改
许多快速连续的远程POST请求可能被主机和WAF解释为入侵模式并断开连接。 `run_batch` 通过将所有操作组合成 **单个请求** 来解决这个问题：
```json
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "run_batch",
"arguments": {
"commands": [
{
"tool": "create_bricks_page",
"arguments": { "title": "首页", "elements": [] }
},
{
"tool": "regenerate_css",
"arguments": {}
}
],
"stop_on_error": true,
"dry_run": false
}
}
}
```
- **`commands`** — 有序的 `{ tool, arguments }` 列表，按顺序执行。
- **`stop_on_error`** （默认为 `false` ）— 在第一个错误时停止，不应用后续命令。
- **`dry_run`** （默认为 `false` ）— 验证而不保存（当有元素树时使用 `validate_tree` ）。
- 响应：`results[]` 带有每个命令的单独状态 + `ok`/`failed` 摘要。
> 嵌入式SKILL（ `/skill` ）指导代理使用 `run_batch` 进行所有写入序列，并仅为临时读取预留单独的POST。
---
## 通用WordPress CLI
该插件包括一个通过REST访问的WordPress CLI，位于 `/wp-json/marreira-mcp/v1/cli/*`。
**出厂时禁用** （`enable_general_cli=0`）。要使用，请在设置中启用并确保令牌具有相应的能力。
| 区域 | 所需能力 | 操作 |
|---|---|---|
| 插件 | `plugins` | 列出、安装、激活、停用、更新、删除 |
| 主题 | `themes` | 列出、安装、激活、删除 |
| WordPress核心 | `core` | 查看版本、更新 |
| 活动主题文件 | `files` | 读取、写入（带有路径遍历保护） |
| PHP代码片段 | `snippets` | CRUD + lint（`php -l`） |
| 内容 | `content` | 文章、术语、评论、媒体、用户 |
| 数据库（读取） | `db` | 列出表格、模式、样本 |
| 数据库（查询） | `db_query` | SELECT与允许列表 — **双重锁定** |
| 执行/PHP | `exec` | 执行PHP — **双重锁定** ，需要 `allow_php_exec=1` |
> **双重锁定**：高风险操作（`db_query` 、 `exec` 、 `allow_file_write` ）需要设置标志开启 **和** 令牌中的对应能力。两者缺一不可则拒绝请求。
**自我保护** — CLI绝不会：
- 停用或删除插件本身；
- 删除活动主题；
- 通过网络公开令牌管理。
---
## 本地WP-CLI
使用服务器上的命令行管理插件：
```bash
# 信息和工具
wp mmcb describe # 活动构建工具、分层、能力、工具目录
wp mmcb tools # 列出活动构建工具的所有工具
wp mmcb builder # 显示/更改活动构建工具
# 执行工具
wp mmcb call <tool> [args] # 直接执行工具
wp mmcb batch <文件> # 从JSON文件执行run_batch
# 令牌管理
wp mmcb token create --abilities=builder,read [--expires=30d] [--label="Claude Desktop"]
wp mmcb token list
wp mmcb token revoke <id>
wp mmcb token delete <id>
```
---
## 安全
| 机制 | 详情 |
|---|---|
| 令牌哈希 | HMAC-SHA256 — 纯文本从未存储或记录 |
| 按令牌划分的能力 | 粒度范围；路由检查对应能力 |
| 过期时间 | 可配置令牌（例如：`30d`、`90d`、不限） |
| IP限制 | 20次失败尝试 → 5分钟阻止 |
| IP允许列表 | 令牌允许的CIDR列表 |
| 管理员重新验证 | 令牌绑定的用户在每次请求时需要继续是管理员 |
| `MMCB_TRUST_PROXY` | 从`X-Forwarded-For`读取IP的常量，用于反向代理 |
| 审计日志 | 每次请求记录；PII掩码；可配置保留天数 |
| Code_Guard（防RCE） | 拒绝执行任意代码的元素/配置 |
| 自我保护 | CLI不会取消自己的插件或删除活动主题 |
| `hash_equals` | 令牌的时序安全比较（无时序攻击） |
---
## 往返兼容性
所有构建工具编写都遵循 **读取-修改-写入** 标准：服务器读取当前状态，修改必要部分并保存，保留ID和未知字段。绝不盲目覆盖树。这确保：
- 智能创建的页面在视觉编辑器中打开并正常编辑。
- 编辑器中的页面可以由智能优化而不会损坏。
- 功能元素（表单、短代码、查询循环）被保留在编辑现有页面时。
---
## 血统
该插件统一并取代了两个以前的插件：
| 插件 | 最新版本 | 状态 |
|---|---|---|
| MarreiraMCP Bricks | 0.5.2 | **冻结** — 不再更新 |
| MarreiraMCP Elementor | 0.1.1 | **冻结** — 不再更新 |
| **MarreiraMCP 构建工具** | **1.0.0** | **活跃 — 官方继承者** |
如果您曾经使用过这两个插件之一，请停用它并安装这个插件。继承的往返兼容性在此插件中保留。
---
## 许可证
在 **GPL-2.0-or-later** 下许可。您可以自由使用、复制、修改和分发 — 包括在商业项目中 — 同时保留原始作者的署名（**Paulo Marreira / Marreira Digital** ）。
---
<div align="center">
由 **[Paulo Marreira](https://marreiradigital.com.br)** · MarreiraDigital制作
</div>
