mcp-wpbakery

# MCP WPBakery [](https://github.com/dvos301/mcp-wpbakery/actions/workflows/ci.yml) 允许 AI 代理（Claude Code）读取 WordPress 站点的实时 **WPBakery（js_composer）元素注册表**（`vc_map`）并在页面上构建/编辑 **原生、可完全编辑的 WPBakery 元素**，而非原始 HTML 补丁。 打开它编写的任意页面，在 WPBakery 编辑器中，每一行、列和元素都可编辑，就像人类拖拽它们一样。 --- ## 🚀 快速开始（v0.7.0+）：直接连接，无需本地安装 WordPress 插件 **本身就是一个远程 MCP 服务器**。三个步骤： 1. **安装插件** — 下载 [`mcp-wpbakery.zip`](https://github.com/dvos301/mcp-wpbakery/raw/main/dist/mcp-wpbakery.zip) （始终在 `main` 分支上更新；也可在每个 [发布版本](https://github.com/dvos301/mcp-wpbakery/releases/latest)中找到）并通过 **WP 管理后台 → 插件 → 新增 → 上传插件 → 激活**上传。 更新时？WordPress 提供 *"用上传的文件替换当前文件"* — 令牌和设置保持不变。 2. **生成令牌** — wp-admin → **MCP WPBakery → 选项 A** → *生成令牌* （需要管理员 + HTTPS；显示一次）。本地开发站点 （LocalWP `.local`，Valet `.test`，`localhost` 或 `WP_ENVIRONMENT_TYPE=local`）可豁免 HTTPS 要求 — 其流量从未离开机器。 3. **运行给出的命令** 在运行 Claude Code 的计算机上： ```bash claude mcp add --transport http wpbakery-<站点> \ https://<站点>/wp-json/mcp-wpbakery/v1/mcp \ --header "Authorization: Bearer wpbmcp_..." ``` 下一次 Claude Code 会话中，所有 **40 个 `wpbakery_*` 工具**都可用，并且 [构建规则](WPBAKERY_BUILD_RULES.md)被自动注入为会话 指令。无需 Python，无需 `install.sh`，无需应用密码。 **安全性：**令牌在存储时进行 SHA-256 哈希，显示一次，颁发仅限 HTTPS（本地开发环境除外 — 见上文），调用受速率限制 （120/分钟/令牌）并进行审计日志记录（REST 代理记录实际方法和路由）。在同一管理员页面上撤销任何令牌。 --- ## 📦 我需要哪个下载文件？ | 您想要... | 获取此文件 | |---|---| | 在 WP 站点上安装/更新插件 | [`dist/mcp-wpbakery.zip` （直接下载）](https://github.com/dvos301/mcp-wpbakery/raw/main/dist/mcp-wpbakery.zip) 或 [最新发布版本](https://github.com/dvos301/mcp-wpbakery/releases/latest) | | 运行本地中心/开发 | `git clone https://github.com/dvos301/mcp-wpbakery` + `./install.sh` | > **不要**将 GitHub 的绿色 **代码 → 下载 ZIP** 上传到 WordPress — 这是整个源代码仓库（`server/`、`clients/`、`wp-plugin/` 等），WordPress 拒绝它，提示 *"未找到有效插件"*。 --- ## 🖥 选项 B：本地中心（多站点/SSH） 原始架构仍然有效，且当您 **从一个配置文件夹驱动多个站点** 或站点仅可通过 **SSH + WP-CLI** 访问时，这是正确选择： ``` Claude Code ─MCP(stdio)→ Python 中心 ─REST（应用密码）或 SSH+WP-CLI→ WP 插件 ``` 设置（完整的演练在 [ONBOARDING.md](ONBOARDING.md) 中）： ```bash git clone https://github.com/dvos301/mcp-wpbakery cd mcp-wpbakery && ./install.sh # 安装依赖 + 注册 MCP 服务器 ``` 每个站点的配置在 `clients/<slug>.json` 中（`base_url` + 任意 `wp_rest_user`/`wp_rest_app_password` 或 `server_ip`/`ssh_user`/`wp_app_slug`）。 管理员页面的 **选项 B** 生成应用密码 + 可粘贴的代理提示。机密也可以存储在环境变量中：`WPBAKERY_<SLUG>_USER` / `WPBAKERY_<SLUG>_APP_PW`. SSH 部署是自动化的：`python server/deploy.py <slug> --check`，然后 `python server/deploy.py <slug>`（使用 `~/.ssh/cloudways_ed25519`）。 --- ## 📐 构建规则（强制 - 自动注入到每个会话中） [`WPBAKERY_BUILD_RULES.md`](WPBAKERY_BUILD_RULES.md) 是 *如何* 构建页面的不可更改 契约：粒度原生元素，禁止的"将整个部分塞进一个文本块中"反模式，元素选择映射，属性编码和自我审计门。 您永远不会手动连接它 — **两种** 连接模式都注入它： - **直接（选项 A）：** `pack.py` 将文件包含在插件 zip 中，MCP `initialize` 响应将其作为会话指令提供。 - **本地中心（选项 B）：** `server/mcp_wpbakery/server.py` 在启动时读取存储库根文件，并将其附加到服务器指令中。 编辑存储库根文件 → 重新构建 zip（选项 A）或重新启动会话 （选项 B）。代理指南 [`CLAUDE.md`](CLAUDE.md) 也指向它。 --- ## 🧱 元素工作室 — 可重用的自定义元素，这些元素在插件之外持久存在（v0.8.0+） 取代元素构建插件（元素工作室等）：代理可以创作 **可重用的自定义 WPBakery 元素** — 每个字段都是真正的 `vc_map` 参数，因此客户可以在构建器中像任何原生元素一样编辑它们。 定义 **不** 存储在此插件中。它们被写入一个 独立的、自动生成的库插件 — **`wp-content/plugins/custom-wpbakery-elements/`** — 它拥有这些元素： - 删除 MCP WPBakery 桥 → 每个自定义元素 **保持渲染和可编辑**。库对桥有零依赖。 - 每个元素都是库的 `elements/` 文件夹中的一个 JSON 文件（参数 + HTML 模板 + 作用域 CSS）— 可手动编辑，可 Git， 可移植到其他站点，复制文件夹即可。 - 模板使用 `{{param}}` （转义），`{{{param}}}` （富 HTML）， `{{#if p}}…{{/if}}`，`{{#each group}}…{{/each}}` 用于可重复行，和 `{{content}}` 用于包含元素。元素 CSS 每次页面打印一次。 - 工作室工具：`wpbakery_create_custom_element`，`wpbakery_update_custom_element`， `wpbakery_list_custom_elements`，`wpbakery_get_custom_element`， `wpbakery_delete_custom_element`（拒绝删除仍在内容中使用的元素）。创建/更新/删除需要 `install_plugins` 能力。 ## 🧰 MCP 工具（40） **构建工具**（两种模式下具有一致性；中心工具接受 `client` 斜杠，远程工具不接受 — 连接标识站点）： | 工具 | 目的 | |------|---------| | `wpbakery_ping` | 连接性 + WP/WPBakery 版本。**先调用此工具。** | | `wpbakery_list_elements` | 实时 `vc_map` 注册表（核心 + 主题 + 插件）。 | | `wpbakery_element_schema` | 元素的完整参数模式。 | | `wpbakery_list_pages` | 标记为 WPBakery 使用的页面/帖子。 | | `wpbakery_get_page` / `wpbakery_get_structure` | 原始内容 + 解析树（+ CSS）。 | | `wpbakery_build_element` | 构建一个已验证的可编辑元素（无数据库写入）。 | | `wpbakery_validate` | 在写入前根据 `vc_map` 验证内容。 | | `wpbakery_update_page` | 真正的写入：验证 → 修订版备份 → 写入 → CSS 重新生成 → **在同一响应中呈现预览摘要** （v0.9.0；`preview=false` 跳过）。 | | `wpbakery_set_page_css` / `wpbakery_append_page_css` | 页面范围的 CSS 迭代。 | | `wpbakery_render_preview` | 真实的 前端渲染：令牌化预览 URL，未渲染的短代码检测，和 **DOM 骨架摘要** （主题的真实包装器类 — 针对这些样式，而无需获取完整的页面 HTML；`include_html=true` 获取原始摘录）。 | | `wpbakery_create_page` / `wpbakery_set_status` | 草稿优先的页面生命周期。 | | `wpbakery_set_post_meta` | 任意帖子元数据（Rank Math robots 等）。 | | `wpbakery_replace_in_content` | 具有预期计数的外科手术查找/替换。 | | `wpbakery_purge_cache` | 对象 + 页面缓存破坏，用于页面。 | **全站**（远程端点，v0.7.0+）： | 工具 | 目的 | |------|---------| | `wpbakery_find_pages` | 按标题/斜杠/内容搜索，或将 URL 解析为其帖子。 | | `wpbakery_find_in_pages` | 全站文本搜索，细致到保存匹配的短代码元素。 | | `wpbakery_page_links` | 页面上的所有链接与锚点（HTML + 编码的 vc 链接属性）。 | | `wpbakery_inbound_links` | 链接到页面的对象，带有锚点频率摘要（包括菜单）。 | | `wpbakery_link_map` | 全站内部链接图，热门目标，孤立页面。 | | `wpbakery_site_status` | WP/PHP/主题/插件版本，待处理更新，调试 + 缓存状态。 | | `wpbakery_read_error_log` | 读取 debug.log / PHP 错误日志。 | | `wpbakery_get_seo_meta` / `wpbakery_set_seo_meta` | Rank Math / Yoast 标题，描述，聚焦关键词。 | | `wpbakery_clone_page` | 复制页面（内容 + 元数据 + 页面 CSS）为草稿。 | | `wpbakery_rest_request` / `wpbakery_list_rest_routes` | 完整的核心 + 插件 REST 接口，具有权限检查。 | | `wpbakery_create/update/get/delete/list_custom_element(s)` | 元素工作室：创作可重用的自定义元素到独立的库插件（见上文）。 | **站点知识**（v0.9.0 — 站点记住，因此无需会话重新支付发现税）： | 工具 | 目的 | |------|---------| | `wpbakery_get_site_knowledge` | 主题 + 品牌令牌（从 `us_theme_options`/主题修改 + logo 自动提取）+ 已知损坏的元素 + 来自先前会话的注释。摘要自动注入到每个会话的 `initialize` 指令中。 | | `wpbakery_add_site_note` | 为所有未来会话保存关于此站点的经验教训。 | | `wpbakery_flag_broken_element` | 记录“此元素在此处无法渲染 — 改用 X”。Impreza/us-core 站点预先植入了 `vc_btn`/`vc_icon`/`vc_single_image` 陷阱。 | | `wpbakery_set_brand_tokens` | 覆盖/扩展品牌令牌（`manage_options`）。 | ## 典型的代理工作流程 1. `wpbakery_ping` → 2. `wpbakery_list_elements` → 3. `wpbakery_element_schema` → 4. `wpbakery_get_page` → 5. `wpbakery_build_element` → 6. `wpbakery_validate` → 7. `wpbakery_update_page`（草稿）→ 8. `wpbakery_render_preview`（修复任何 `unrendered_shortcodes`）→ 9. `wpbakery_set_status(publish)`。 ## 为什么需要配套插件 `vc_map` 仅在 PHP/WordPress 运行时存在，并且生成 *可编辑* 元素意味着发出与每个元素的注册模式匹配的短代码 **和** 保持 `_wpb_shortcodes_custom_css` 帖子元数据同步。两者都必须在 WP 上下文中运行 — 泛型 WordPress REST 工具无法完成这两项。插件还 会在每次写入前保存修订版，并在写入后清除缓存。 ## 开发 ```bash python server/pack.py # 重建 dist/mcp-wpbakery.zip（包括构建规则） ``` CI（GitHub Actions）检查每个插件 PHP 文件的 lint，运行在 PHP 7.2 和 8.2 上，编译 Python 服务器，重新构建 zip 并验证每次推送的 zip 内容。 ## 状态 **v0.7.0** — 混合型：插件兼作远程 MCP 服务器（令牌身份验证， 速率限制，审计日志，29 个工具，构建规则注入），而本地中心 和 REST/SSH 传输保持不变。早期里程碑：针对 WPBakery 8.7.x + Impreza/us-core（实时 `vc_map` 读取， 验证的原生构建，稳定的解析 → 序列化往返，修订版支持的 写入，并具有 CSS 再生）进行端到端验证。