elementor-ultra-mcp

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 — 権威ある REST 接続点（/wp-json/elementor-ultra/v1/*）を提供する WordPress プラグイン：すべての書き込みは Elementor 自身の Document::save() を通じて行われ、バックアップスナップショット、楽観的同時実行制御（base_hash）、 冪等性（op_id）による再実行、権威あるバリデーター、必須の CSS プライミングが適用されます。
• packages/shared — 凍結された契約サーフェス：REST ルートレジストリ、エラー分類、 JSON スキーマミラー、ゴールデンフィクスチャ。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」は同社の商標です。これは 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 を使用し、 ローカルのプラグイン ZIP ファイルで Elementor 4.1.1 と Elementor Pro 4.1.0 を正確に固定します（最新バージョンを取得し、Pro をまったくホストしていない wp.org のスラッグは使用しません）。

プラグイン ZIP ファイルの保存場所（および Pro の配置場所）

.wp-env.json は .wp-env-plugins/（gitignore 対象のディレクトリ）にある 2 つのローカル 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）。