Elementor Ultra

Elementor Ultra MCP

Elementor용 에이전트 제어 표면. AI 에이전트가 실제 Elementor 사이트를 엔지니어가 소프트웨어를 배포하듯 읽고, 구축하고, 리팩터링하고, 관리할 수 있게 해주는 Model Context Protocol 서버 + 동반 WordPress 플러그인 — Editor V4 원자적 요소 우선, V3 클래식 폴백 — 모든 쓰기 작업에 대해 권위 있는 서버 측 검증, diff, 백업 및 롤백을 제공합니다.

• packages/server — TypeScript MCP 서버: 91개 도구 (elementor.page.*, widget, design, templates, media, nav, pro.*, HTML→Elementor 변환), stdio + HTTP 전송, 경량/전체 도구 프로필.
• plugin/elementor-ultra-mcp — 권위 있는 REST 시임을 노출하는 WordPress 플러그인 (/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	실행 중	개발 WP 사이트의 @wordpress/env (wp-env)에 필요합니다.
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)는 해당 모듈이 존재할 때까지 ./server.js을 지연 import()하고 "server core not yet wired" 를 출력합니다 — 따라서 바이너리는 이 스캐폴드에서 단독으로 컴파일 및 부팅됩니다.

---

로컬 WordPress 개발 사이트 (wp-env)

개발 사이트는 @wordpress/env을 사용하며 Elementor 4.1.1 + Elementor Pro 4.1.0을 로컬 플러그인 zip을 통해 정확히 고정합니다 (wp.org 슬러그가 아닌 — wp.org는 최신 버전을 가져오며 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에서 제공됩니다.

---

모노레포 구조

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 고정 (LOCKED)

packages/server는 **@modelcontextprotocol/sdk ^1.29**을 고정하며 zod을 필수 피어로 요구합니다. @modelcontextprotocol/* 2.x 패키지를 추가하지 마세요 — 1.x에서 inputSchema/outputSchema은 ZodRawShape 맵이며 전송은 깊은 .js 임포트입니다. CI는 잠금 파일에 2.x 의존성이 나타나는 것을 방지합니다 (WP-F07).