elementor-mcp-agent 0.1.0

package/ARCHITECTURE.md

@@ -0,0 +1,60 @@
+# Architecture
+
+## Layers
+
+```
+┌─────────────────────────────────────────────────────────┐
+│  MCP stdio (Claude Desktop / Code / any MCP client)     │
+└────────────────────────────────────────────────────┬────┘
+                                                    │
+                                          ┌─────────▼────────┐
+                                          │  server.ts       │
+                                          │  (MCP entry)     │
+                                          └─────────┬────────┘
+                                                    │
+              ┌─────────────────────────────────────┼──────────────────────────────┐
+              │                                     │                              │
+       ┌──────▼──────┐                      ┌───────▼─────┐                ┌───────▼──────┐
+       │  tools/     │                      │  resources/ │                │  config.ts   │
+       │             │                      │  (docs)     │                │  (sites pool)│
+       └──────┬──────┘                      └─────────────┘                └──────────────┘
+              │
+   ┌──────────┼──────────────┐
+   │          │              │
+┌──▼───┐ ┌────▼─────┐ ┌──────▼────────┐
+│ api/ │ │ elementor│ │ throttle/     │
+│ wp-  │ │ data-    │ │ token-bucket  │
+│ rest │ │ parser   │ │ (per-site)    │
+└──────┘ │ safety   │ └───────────────┘
+         └──────────┘
+```
+
+## Design decisions
+
+- **Stdio transport** — same as every other MCP. No HTTP server, no auth surface. The MCP client (Claude Desktop, Claude Code, etc.) spawns the binary, talks JSON-RPC over its stdin/stdout.
+- **Per-site config, not per-call** — the LLM doesn't get to inject credentials. Sites are configured once in the env via JSON; tools take a `site_id` to pick one.
+- **Zod everywhere** — every tool's input is validated with Zod before the handler runs. Same Zod schema is converted to JSON Schema Draft 7 for the MCP `tools/list` response.
+- **Logs to stderr only** — stdio transport is sacred. A single `console.log` would corrupt the JSON-RPC stream. `pino.destination(2)` enforces stderr.
+- **Token bucket per site** — 60 req/min default. Each site has its own bucket so one slow site doesn't block another.
+- **Confirmation tokens for destructive ops** — 8-byte random hex, TTL 60s, single-use, intent-locked. Stored in-memory only (no disk). Surface area for accidental destruction is minimised.
+- **Backup before edit** — `_elementor_data` is fragile. Every edit creates a timestamped postmeta backup first.
+
+## Why not WP-CLI as primary transport?
+
+WP-CLI is more powerful than the REST API (can do anything WordPress can do), but:
+
+1. Requires SSH access — many managed hosts don't expose it.
+2. Slower per-call (SSH handshake overhead).
+3. Output is text — needs parsing each time.
+
+So: REST API is the primary surface. WP-CLI is reserved for the v0.2 escape hatch.
+
+## Why not include Elementor Pro version check?
+
+Elementor Pro is paid and updates through Elementor's own server (not wordpress.org). Reliably detecting "is there a newer version?" requires either:
+
+1. Hitting Elementor's licence server (not public).
+2. Scraping `elementor.com/changelog/` (fragile).
+3. Reading the Pro update transient on each site (works, in roadmap).
+
+For v0.1 we surface the **installed** Pro version per site (good enough to spot fleet-wide drift) but don't compare against a "latest" until we wire option 3 properly.

package/LICENSE

@@ -0,0 +1,15 @@
+MIT License
+
+Copyright (c) 2026 MogaCode SARL-AU
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND.

package/README.md

@@ -0,0 +1,189 @@
+# elementor-mcp-agent
+
+[![npm version](https://img.shields.io/npm/v/elementor-mcp-agent.svg)](https://www.npmjs.com/package/elementor-mcp-agent)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)
+
+> **Agency-grade MCP server for WordPress Elementor.** Multi-site management, safe Elementor data editing with backup + dry-run + CSS-flush, template export/import across sites, version tracking, and a curated Elementor docs corpus exposed as MCP resources.
+
+Built for agencies running many client sites on Elementor / Elementor Pro who want Claude (or any MCP client) to drive the toil — without breaking pages.
+
+---
+
+## Why this exists
+
+There are ~25 WordPress MCP servers on GitHub today. None target the **agency** use case:
+
+- **Multi-site** — list, ping, and act on a pool of sites in one prompt.
+- **Elementor-aware** — understands `_elementor_data` structure, not just generic WP REST.
+- **Defensive editing** — auto-backup before any change, dry-run + confirmation token for destructive ops, CSS regeneration on save.
+- **Cross-site template sync** — export from staging, import on every client site in one shot.
+- **Version oversight** — see who's running which Elementor / Elementor Pro version across the whole fleet.
+
+This MCP starts with these four pillars and grows from there.
+
+---
+
+## ⚠️ Status: early days
+
+v0.1.0 is shipped end-to-end (CI green, 14 tests passing, npm + MCP Registry listed) but the tool surface is intentionally focused. Expect rapid iteration. Don't run destructive operations on production without testing on staging first.
+
+---
+
+## Install
+
+```bash
+npx -y elementor-mcp-agent
+```
+
+Or globally:
+
+```bash
+npm install -g elementor-mcp-agent
+```
+
+## Configure
+
+The server needs to know about your sites. The simplest path: an env var with a JSON array.
+
+```bash
+export ELEMENTOR_MCP_SITES='[
+  {
+    "id": "client-acme",
+    "url": "https://acme.example.com",
+    "username": "admin",
+    "application_password": "xxxx xxxx xxxx xxxx xxxx xxxx"
+  },
+  {
+    "id": "client-beta",
+    "url": "https://beta.example.com",
+    "username": "admin",
+    "application_password": "yyyy yyyy yyyy yyyy yyyy yyyy"
+  }
+]'
+```
+
+Generate the **WordPress Application Password** at:
+`https://{your-site}/wp-admin/profile.php#application-passwords-section`
+
+(`Application Passwords` is a built-in WordPress 5.6+ feature. No plugin required.)
+
+Or use a config file:
+
+```bash
+export ELEMENTOR_MCP_CONFIG_PATH="/path/to/sites.json"
+```
+
+With `sites.json`:
+```json
+{
+  "sites": [
+    { "id": "...", "url": "...", "username": "...", "application_password": "..." }
+  ],
+  "default_site_id": "client-acme",
+  "rate_limit_per_minute": 60,
+  "confirmation_ttl_seconds": 60
+}
+```
+
+### Configure Claude Desktop
+
+`~/Library/Application Support/Claude/claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "elementor": {
+      "command": "npx",
+      "args": ["-y", "elementor-mcp-agent"],
+      "env": {
+        "ELEMENTOR_MCP_SITES": "[{\"id\":\"acme\",\"url\":\"https://acme.com\",\"username\":\"admin\",\"application_password\":\"xxxx...\"}]"
+      }
+    }
+  }
+}
+```
+
+### Configure Claude Code
+
+```bash
+claude mcp add elementor \
+  -e ELEMENTOR_MCP_SITES='[{"id":"acme","url":"https://acme.com","username":"admin","application_password":"xxxx..."}]' \
+  -- npx -y elementor-mcp-agent
+```
+
+---
+
+## Tools (v0.1)
+
+| Tool | What it does |
+|---|---|
+| `list_sites` | Lists every site in the pool (id, url, username, has_ssh). |
+| `ping_site` | Verifies auth + reports WP / Elementor / Elementor Pro versions. |
+| `list_elementor_pages` | Lists pages built with Elementor on a given site. |
+| `read_page_elementor` | Returns a structured summary of a page's `_elementor_data` (widget counts by type, depth). Full tree with `verbose=true`. |
+| `elementor_find_replace` | Find/replace plain text in every widget on a page. **Two-call destructive flow**: dry-run returns a count + token; second call with token applies after auto-backup. |
+| `list_elementor_templates` | Lists library templates (sections, pages, popups, headers, footers). |
+| `export_elementor_template` | Exports a template as portable JSON. |
+| `import_elementor_template` | Imports a portable JSON template into a target site. |
+| `check_elementor_versions` | Fleet-wide Elementor version audit. Flags outdated installs against wordpress.org latest. |
+
+## Resources
+
+The server exposes a hand-curated set of Elementor reference docs as MCP `resources`, so the LLM can look up hook names, widget structure, and safe editing patterns without leaving its context:
+
+- `elementor-docs://hooks-actions.md` — common action hooks + filters
+- `elementor-docs://widget-structure.md` — `_elementor_data` schema + common widget types
+- `elementor-docs://safe-editing.md` — backup, dry-run, CSS flush patterns
+
+---
+
+## Safety patterns
+
+Every destructive operation follows the same dance:
+
+1. **First call** (no `confirmation` arg) → dry-run. Returns `match_count` + `confirmation_token` (TTL 60s, configurable).
+2. **Second call** (same args + token) → applies after backing up the page's `_elementor_data` to a timestamped postmeta key.
+3. **CSS flush** is triggered automatically (REST `/elementor/v1/css?action=regenerate`, falls back to re-save).
+
+The backup is **never deleted** — purge old `_elementor_data_backup_*` postmeta keys yourself when no longer needed.
+
+---
+
+## Rate limiting
+
+Per-site token bucket, default **60 req/min** (matches what most managed WordPress hosts allow on `wp-json`). Override via `rate_limit_per_minute` in config.
+
+---
+
+## Roadmap
+
+**v0.2**
+- [ ] `widget_swap` — replace one widget by another with field mapping
+- [ ] `restore_elementor_backup` — restore a page from a timestamped backup
+- [ ] `bulk_find_replace` — apply find/replace across all pages of a site
+- [ ] WP-CLI runner via SSH for ops the REST API can't do
+
+**v0.3**
+- [ ] Cross-site template push (`push_template_to_all`)
+- [ ] Fleet health: outdated plugins, broken links, PageSpeed snapshot
+- [ ] Visual diff (screenshot before/after)
+- [ ] Elementor Pro version detection from Pro server (currently free-only)
+
+**v1.0**
+- [ ] Mature widget mutation API (typed setters per widget type)
+- [ ] Automated docs ingestion from developer.elementor.com
+- [ ] Per-tool happy-path tests against a real Elementor install
+
+---
+
+## Architecture
+
+See [ARCHITECTURE.md](./ARCHITECTURE.md) for the full design rationale.
+
+Short version: stdio MCP, Zod-validated tools, token-bucket throttling, confirmation tokens for destructive ops, pino logs to stderr (never stdout), tsup bundle, vitest tests.
+
+---
+
+## License
+
+[MIT](./LICENSE) — © 2026 [MogaCode](https://mogacode.ma).

package/dist/server.d.ts

@@ -0,0 +1,2 @@
+
+export {  }