elementor-ultra-mcp

Elementor Ultra MCP

Elementor 的 Agent 控制界面。 一个模型上下文协议服务和配套的 WordPress 插件，让 AI Agent 能像工程师交付软件一样，读取、构建、重构和管理真实的 Elementor 网站 — 优先使用编辑器 V4 原子元素，回退到 V3 经典元素 — 每次写入都经过权威的服务端验证，并提供差异对比、备份和回滚。

• packages/server — TypeScript MCP 服务：91 个工具（elementor.page.*、 widget、design、templates、media、nav、pro.*、HTML→Elementor 转换）， 支持 stdio 和 HTTP 传输，以及精简／完整工具配置。
• plugin/elementor-ultra-mcp — WordPress 插件，提供权威 REST 接口 （/wp-json/elementor-ultra/v1/*）：每次写入都通过 Elementor 自身的 Document::save() 执行，并提供备份快照、乐观并发控制（base_hash）、 幂等性（op_id）重放、权威验证器，以及强制 CSS 预热。
• packages/shared — 冻结的契约界面：REST 路由注册表、错误分类、 JSON Schema 镜像和黄金测试夹具。与 spec/contracts/schemas 字节级一致（由 CI 强制检查）。
• spec/ — 完整的工程记录：系统构建所依据的契约、技术验证结论和工作包。

与 elementor-jsx 配合使用 — 这是一个 JSX→Elementor 编译器，其部署通过此插件的 REST 接口完成。

快速入门（与 Agent 配合使用）

1. 在 WordPress 网站上安装配套插件（从 Releases 下载 zip；需要 Elementor ≥ 4.1），并创建应用程序密码。
2. 将服务接入 MCP 客户端（.mcp.json）：

{
  "mcpServers": {
    "elementor-ultra": {
      "command": "node",
      "args": ["/path/to/elementor-ultra-mcp/packages/server/dist/index.js"],
      "env": {
        "WP_URL": "https://your-site.com",
        "WP_USER": "admin",
        "WP_APP_PASSWORD": "xxxx xxxx xxxx xxxx xxxx xxxx",
        "ULTRA_TOOLS": "full",
      },
    },
  },
}

3. 让 Agent 列出页面、对树结构进行试运行或构建页面。每次修改都会先由 Elementor 自身的解析器在服务端验证，再进行保存；无效的树结构会被原子性地拒绝，并返回分类错误代码。

许可

• TypeScript 包（packages/*）：MIT © 2026 Algorismus
• WordPress 插件（plugin/elementor-ultra-mcp）：GPL-2.0-or-later（WordPress 惯例）

本项目与 Elementor Ltd 无关联，也未获其背书 — “Elementor” 是其商标；本项目是面向其页面格式的独立集成。

---

前置条件

工具	版本	说明
Node.js	≥ 20 LTS	.nvmrc 固定为 20。强制启用 engine-strict=true。
pnpm	9.x	包管理器；锁文件已提交。
Docker	运行中	@wordpress/env（wp-env）开发用 WordPress 网站所需。
PHP	≥ 7.4 （容器内）	由 wp-env Docker 容器提供 — 主机无需安装 PHP。
Composer	（容器内）	插件的 Composer/PHPCS 配置由 WP-P01 提供。

主机上无需安装 PHP 或 Composer；PHP 工具在 wp-env 容器内运行。

---

安装与构建

pnpm install        # installs all workspace deps; writes/uses pnpm-lock.yaml
pnpm build          # turbo: compiles packages/shared + packages/server (strict TS)
pnpm lint           # eslint (typescript-eslint, recommended-type-checked) across the workspace
pnpm format:check   # prettier --check
pnpm test:unit      # turbo: vitest run in each package

运行服务器二进制文件（尚未接入工具）

运行 pnpm build 后，服务器二进制文件位于 packages/server/dist/index.js。未设置任何环境变量时，它会输出清晰的提示并正常退出（退出代码为 0）：

node packages/server/dist/index.js
# -> elementor-ultra-mcp: missing required environment variable(s): WP_URL, WP_USER, WP_APP_PASSWORD. ...

配置完成后，它会读取以下环境变量：

变量	必需	含义
WP_URL	是	目标 WordPress 站点的基础 URL。
WP_USER	是	WordPress 用户名（应用程序密码所有者）。
WP_APP_PASSWORD	是	WordPress 应用程序密码（HTTP Basic 身份验证）。
MCP_TRANSPORT	否	stdio（默认）或 http（Streamable HTTP）。
ULTRA_TOOLS	否	lean（默认）或 full 工具配置。

实际的传输绑定和工具注册表由 packages/server/src/server.ts 中的 WP-T01 添加。 二进制文件（index.ts）会延迟 import() ./server.js；在该模块存在之前，它会输出 "server core not yet wired"——因此，该二进制文件可在此脚手架上独立编译并启动。

---

本地 WordPress 开发站点（wp-env）

开发站点使用 @wordpress/env，并通过本地插件 zip 包将版本精确固定为 Elementor 4.1.1 + Elementor Pro 4.1.0（而不是 wp.org slug；它会拉取最新版本，而且根本不托管 Pro）。

插件 zip 包的位置（以及 Pro 必须放置的位置）

.wp-env.json 引用了 .wp-env-plugins/ 下的两个本地 zip 包（这是一个被 gitignore 忽略的目录）：

.wp-env-plugins/
├─ elementor.4.1.1.zip        # Elementor free 4.1.1
└─ elementor-pro.4.1.0.zip    # Elementor Pro 4.1.0  (licensed; not on wp.org)

这些 zip 包不会提交到仓库（它们是受许可保护的二进制文件，并且会被 gitignore 忽略）。全新克隆仓库后，必须自行放置这些文件：

mkdir -p .wp-env-plugins
cp /path/to/elementor.4.1.1.zip      .wp-env-plugins/elementor.4.1.1.zip
cp /path/to/elementor-pro.4.1.0.zip  .wp-env-plugins/elementor-pro.4.1.0.zip

上述确切文件名必须与 .wp-env.json 中的路径匹配。

启动 / 停止

pnpm wp-env:start   # boots WordPress + Elementor 4.1.1 + Pro 4.1.0; mounts the companion plugin
pnpm wp-env:stop

.wp-env.json 还会将 ./plugin/elementor-ultra-mcp 挂载为插件。该目录的内容（引导文件、composer.json、phpcs.xml.dist、readme.txt 和 includes/）由 WP-P01 创建；这些文件提交后，即可在 wp-env 站点中启用配套插件。该插件自己的 Composer/PHPCS 配置也由 WP-P01 提供。

---

Monorepo 布局

elementor-ultra-mcp/
├─ packages/
│  ├─ server/      # TS MCP server (bin: elementor-ultra-mcp)
│  └─ shared/      # shared types + JSON Schemas + fixtures
├─ plugin/
│  └─ elementor-ultra-mcp/   # companion WP plugin (PHP) — populated by WP-P01
├─ spec/           # frozen architecture + contracts + work packages
├─ .wp-env.json    # pins Elementor 4.1.1 + Pro 4.1.0 (local zips) + mounts the plugin
└─ (root tooling: pnpm-workspace.yaml, turbo.json, tsconfig.base.json, eslint, prettier)

MCP SDK 固定版本（锁定）

packages/server 固定使用 @modelcontextprotocol/sdk ^1.29，并将 zod 作为必需的 peer 依赖。切勿添加任何 @modelcontextprotocol/* 2.x 包——在 1.x 中，inputSchema/outputSchema 是 ZodRawShape 映射，而传输模块使用深层 .js 导入。CI 会防止 lockfile 中出现 2.x 依赖（WP-F07）。