Elementor Ultra

Elementor Ultra MCP

A superfície de controle do agente para Elementor. Um servidor Model Context Protocol + plugin WordPress complementar que permite que agentes de IA leiam, construam, refatorem e governem sites Elementor reais da maneira como engenheiros entregam software — elementos atômicos do Editor V4 primeiro, fallback clássico V3 — com validação autoritativa no lado do servidor, diffs, backups e rollback em cada gravação.

• packages/server — Servidor MCP TypeScript: 91 ferramentas (elementor.page.*, widget, design, templates, media, nav, pro.*, conversor HTML→Elementor), transportes stdio + HTTP, perfis de ferramentas enxuto/completo.
• plugin/elementor-ultra-mcp — Plugin WordPress expondo a camada REST autoritativa (/wp-json/elementor-ultra/v1/*): cada gravação passa pelo próprio Document::save() do Elementor com snapshots de backup, concorrência otimista (base_hash), replay de idempotência (op_id), o validador autoritativo e priming de CSS obrigatório.
• packages/shared — a superfície de contrato congelada: registro de rotas REST, taxonomia de erros, espelhos JSON-schema, fixtures douradas. Byte-idêntico ao spec/contracts/schemas (protegido por CI).
• spec/ — o registro completo de engenharia: contratos, vereditos de spikes e pacotes de trabalho sobre os quais o sistema foi construído.

Emparelha com elementor-jsx — o compilador JSX→Elementor cujos deploys usam a camada REST deste plugin.

Início rápido (use com um agente)

1. Instale o plugin complementar no seu site WordPress (zip das Releases; requer Elementor ≥ 4.1) e crie uma senha de aplicativo.
2. Conecte o servidor ao seu cliente 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. Peça ao seu agente para listar páginas, simular uma árvore, construir uma página. Cada mutação é validada pelos próprios parsers do Elementor no lado do servidor antes de qualquer salvamento; árvores inválidas são rejeitadas atomicamente com um código de erro taxonômico.

Licenciamento

• Pacotes TypeScript (packages/*): MIT © 2026 Algorismus
• Plugin WordPress (plugin/elementor-ultra-mcp): GPL-2.0-or-later (convenção do WordPress)

Não afiliado ou endossado pela Elementor Ltd — "Elementor" é sua marca registrada; esta é uma integração independente que visa seu formato de página.

---

Pré-requisitos

Ferramenta	Versão	Notas
Node.js	≥ 20 LTS	.nvmrc fixa 20. engine-strict=true é imposto.
pnpm	9.x	O gerenciador de pacotes; o lockfile está commitado.
Docker	em execução	Necessário para @wordpress/env (wp-env) para o site WP de desenvolvimento.
PHP	≥ 7.4 (no container)	Fornecido pelo container Docker wp-env — nenhum PHP no host necessário.
Composer	(no container)	A configuração Composer/PHPCS do plugin é fornecida pelo WP-P01.

Você não precisa de PHP ou Composer no host; as ferramentas PHP são executadas dentro do container wp-env.

---

Instalação e build

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

Executando o bin do servidor (sem ferramentas conectadas ainda)

Após pnpm build, o bin do servidor existe em packages/server/dist/index.js. Com nenhuma env definida, ele imprime uma mensagem clara e sai de forma limpa (código de saída 0):

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

Quando configurado, ele lê as seguintes variáveis de ambiente:

Variável	Obrigatório	Significado
WP_URL	sim	URL base do site WordPress alvo.
WP_USER	sim	Nome de usuário do WordPress (dono da senha de aplicativo).
WP_APP_PASSWORD	sim	Senha de aplicativo do WordPress (auth básica HTTP).
MCP_TRANSPORT	não	stdio (padrão) ou http (Streamable HTTP).
ULTRA_TOOLS	não	lean (padrão) ou full perfil de ferramentas.

A ligação real de transporte + registro de ferramentas são adicionados pelo WP-T01 em packages/server/src/server.ts. O bin (index.ts) carrega import() de ./server.js de forma preguiçosa e imprime "server core not yet wired" até que esse módulo exista — então o bin compila e inicia de forma autônoma neste scaffold.

---

Site WordPress de desenvolvimento local (wp-env)

O site de desenvolvimento usa @wordpress/env e fixa Elementor 4.1.1 + Elementor Pro 4.1.0 exatamente via zips locais de plugins (não o slug do wp.org, que puxa a versão mais recente e não hospeda o Pro de forma alguma).

Onde os zips dos plugins ficam (e onde o Pro deve ser colocado)

.wp-env.json referencia dois zips locais em .wp-env-plugins/ (um diretório gitignored):

.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)

Esses zips não são commitados (são binários licenciados e estão no gitignore). Após um clone limpo, você mesmo deve colocá-los:

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

Os nomes exatos acima devem corresponder aos caminhos em .wp-env.json.

Iniciar / parar

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 também monta ./plugin/elementor-ultra-mcp como plugin. O conteúdo desse diretório (o bootstrap, composer.json, phpcs.xml.dist, readme.txt e includes/) é criado pelo WP-P01; uma vez que existam, o plugin complementar pode ser ativado no site wp-env. A própria configuração Composer/PHPCS do plugin também é fornecida pelo WP-P01.

---

Estrutura do 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)

Fixação do SDK MCP (BLOQUEADO)

packages/server fixa @modelcontextprotocol/sdk ^1.29 com zod como peer obrigatório. Nunca adicione nenhum pacote 2.x do @modelcontextprotocol/* — em 1.x, inputSchema/outputSchema são mapas ZodRawShape e os transportes são imports profundos de .js. CI protege contra uma dependência 2.x aparecendo no lockfile (WP-F07).