Elementor Ultra

Elementor Ultra MCP

面向代理的 Elementor 控制面。 一个模型上下文协议（Model Context Protocol）服务器 + 配套的 WordPress 插件，让 AI 代理能够像工程师交付软件一样读取、构建、重构和管理真实的 Elementor 站点——以 Editor 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 接口进行的。

快速开始（与代理配合使用）

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. 让您的代理列出页面、试运行树、构建页面。每次变更在保存前都会由 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）开发 WP 站点所需。
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 基本认证）。
MCP_TRANSPORT	否	stdio（默认）或 http（Streamable HTTP）。
ULTRA_TOOLS	否	lean（默认）或 full 工具配置。

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

---

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

开发站点使用 @wordpress/env 并通过本地插件 zip（而非 wp.org slug，后者会拉取最新版本且根本不提供 Pro）精确固定 Elementor 4.1.1 + Elementor Pro 4.1.0。

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

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

.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 提供。

---

单仓库布局

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。切勿添加任何 @modelcontextprotocol/* 2.x 包——在 1.x 中，inputSchema/outputSchema 是 ZodRawShape 映射，传输是深层的 .js 导入。CI 会防止锁文件中出现 2.x 依赖（WP-F07）。