Elementor Ultra

Elementor Ultra MCP

Bề mặt điều khiển tác nhân cho Elementor. Một máy chủ Model Context Protocol + plugin WordPress đồng hành cho phép các tác nhân AI đọc, xây dựng, tái cấu trúc và quản trị các trang Elementor thực tế theo cách các kỹ sư phát hành phần mềm — ưu tiên các phần tử nguyên tử Editor V4, dự phòng V3 cổ điển — với xác thực phía máy chủ có thẩm quyền, diff, sao lưu và khôi phục trên mỗi lần ghi.

• packages/server — Máy chủ MCP TypeScript: 91 công cụ (elementor.page.*, widget, design, templates, media, nav, pro.*, chuyển đổi HTML→Elementor), giao thức stdio + HTTP, hồ sơ công cụ gọn nhẹ/đầy đủ.
• plugin/elementor-ultra-mcp — Plugin WordPress hiển thị đường nối REST có thẩm quyền (/wp-json/elementor-ultra/v1/*): mọi thao tác ghi đều đi qua chính Document::save() của Elementor với ảnh chụp sao lưu, đồng thời lạc quan (base_hash), phát lại tính idempotency (op_id), trình xác thực có thẩm quyền và chuẩn bị CSS bắt buộc.
• packages/shared — bề mặt hợp đồng đã đóng băng: đăng ký tuyến REST, phân loại lỗi, bản sao JSON-schema, fixture vàng. Giống hệt byte với spec/contracts/schemas (được bảo vệ bởi CI).
• spec/ — hồ sơ kỹ thuật đầy đủ: hợp đồng, kết luận thử nghiệm và gói công việc mà hệ thống được xây dựng dựa trên.

Kết hợp với elementor-jsx — trình biên dịch JSX→Elementor có các bản triển khai chạy trên đường nối REST của plugin này.

Bắt đầu nhanh (sử dụng với tác nhân)

1. Cài plugin đồng hành trên trang WordPress của bạn (zip từ Releases; yêu cầu Elementor ≥ 4.1) và tạo mật khẩu ứng dụng.
2. Kết nối máy chủ vào ứng dụng khách MCP của bạn (.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. Yêu cầu tác nhân của bạn liệt kê các trang, chạy thử một cây, xây dựng một trang. Mọi thay đổi đều được xác thực bởi chính trình phân tích cú pháp của Elementor phía máy chủ trước khi lưu; các cây không hợp lệ bị từ chối một cách nguyên tử với mã lỗi phân loại.

Giấy phép

• Các gói TypeScript (packages/*): MIT © 2026 Algorismus
• Plugin WordPress (plugin/elementor-ultra-mcp): GPL-2.0-or-later (quy ước WordPress)

Không liên kết với hoặc được xác nhận bởi Elementor Ltd — "Elementor" là nhãn hiệu của họ; đây là một tích hợp độc lập nhắm vào định dạng trang của họ.

---

Điều kiện tiên quyết

Công cụ	Phiên bản	Ghi chú
Node.js	≥ 20 LTS	.nvmrc ghim 20. engine-strict=true được thực thi.
pnpm	9.x	Trình quản lý gói; tệp khóa được cam kết.
Docker	đang chạy	Bắt buộc bởi @wordpress/env (wp-env) cho trang WP phát triển.
PHP	≥ 7.4 (trong container)	Được cung cấp bởi container Docker wp-env — không cần PHP trên máy chủ.
Composer	(trong container)	Cấu hình Composer/PHPCS của plugin được cung cấp bởi WP-P01.

Bạn không cần PHP hoặc Composer trên máy chủ; công cụ PHP chạy bên trong container wp-env.

---

Cài đặt & xây dựng

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

Chạy tệp nhị phân máy chủ (chưa kết nối công cụ)

Sau pnpm build, tệp nhị phân máy chủ tồn tại tại packages/server/dist/index.js. Với không có biến môi trường được đặt, nó in một thông báo rõ ràng và thoát sạch sẽ (mã thoát 0):

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

Khi được cấu hình, nó đọc các biến môi trường sau:

Biến	Bắt buộc	Ý nghĩa
WP_URL	có	URL cơ sở của trang WordPress mục tiêu.
WP_USER	có	Tên người dùng WordPress (chủ sở hữu Mật khẩu Ứng dụng).
WP_APP_PASSWORD	có	Mật khẩu Ứng dụng WordPress (xác thực HTTP Basic).
MCP_TRANSPORT	không	stdio (mặc định) hoặc http (Streamable HTTP).
ULTRA_TOOLS	không	lean (mặc định) hoặc full hồ sơ công cụ.

Ràng buộc giao thức thực tế + đăng ký công cụ được thêm bởi WP-T01 trong packages/server/src/server.ts. Tệp nhị phân (index.ts) lười biếng import()s ./server.js và in "server core not yet wired" cho đến khi mô-đun đó tồn tại — vì vậy tệp nhị phân biên dịch và khởi động độc lập trên khung này.

---

Trang WordPress phát triển cục bộ (wp-env)

Trang phát triển sử dụng @wordpress/env và ghim Elementor 4.1.1 + Elementor Pro 4.1.0 chính xác qua các tệp zip plugin cục bộ (không phải slug wp.org, nơi kéo phiên bản mới nhất và không lưu trữ Pro chút nào).

Nơi các tệp zip plugin nằm (và nơi Pro phải được đặt)

.wp-env.json tham chiếu hai tệp zip cục bộ dưới .wp-env-plugins/ (một thư mục bị 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)

Các tệp zip này không được cam kết (chúng là các tệp nhị phân được cấp phép và bị gitignore). Sau khi clone mới, bạn phải tự đặt chúng:

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

Các tên tệp chính xác ở trên phải khớp với các đường dẫn trong .wp-env.json.

Bắt đầu / dừng

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 cũng gắn ./plugin/elementor-ultra-mcp như một plugin. Nội dung của thư mục đó (bootstrap, composer.json, phpcs.xml.dist, readme.txt, và includes/) được tạo bởi WP-P01; khi chúng xuất hiện, plugin đồng hành có thể kích hoạt trong trang wp-env. Cấu hình Composer/PHPCS riêng của plugin cũng được cung cấp bởi WP-P01.

---

Bố cục 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)

Ghim MCP SDK (ĐÃ KHÓA)

packages/server ghim @modelcontextprotocol/sdk ^1.29 với zod như một peer bắt buộc. Không bao giờ thêm bất kỳ gói @modelcontextprotocol/* 2.x nào — trong 1.x, inputSchema/outputSchema là bản đồ ZodRawShape và các giao thức là các import .js sâu. CI bảo vệ chống lại sự phụ thuộc 2.x xuất hiện trong tệp khóa (WP-F07).