Elementor Ultra

Elementor Ultra MCP

AI 代理的 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	套件管理器；lockfile 已提交。
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

執行伺服器 bin（尚未接線工具）

在 pnpm build 之後，伺服器 bin 位於 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 工具設定檔。

實際的傳輸綁定 + 工具註冊表由 WP-T01 在 packages/server/src/server.ts 中加入。 bin（index.ts）會延遲 import() ./server.js，並印出 "server core not yet wired"，直到 該模組存在 — 因此 bin 能在這個脚手架中獨立編譯並啟動。

---

本機 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）。全新 clone 後 你必須自行放置它們：

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 掛載為外掛。該目錄的內容 （bootstrap、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 maps，傳輸是深層的 .js 匯入。CI 會防止 lockfile 中出現 2.x 依賴 （WP-F07）。