D5MCP

# D5 MCP A working MVP for building Divi / Elegant Themes WordPress pages from AI prompts through the Model Context Protocol (MCP). This package contains two parts: 1. `mcp-server/` — a TypeScript MCP server that exposes prompt-driven Divi page-building tools. 2. `wordpress-plugin/divi-ai-bridge/` — a WordPress plugin that exposes secure REST endpoints for creating/updating Divi Builder pages. The MVP creates **draft pages by default** in **native Divi 5 serialized block format** (`wp:divi/*` blocks), with legacy Divi 4 shortcodes available via `format: "divi4"`. You review the page in WordPress/Divi before publishing. --- ## What this MVP can do - Check connection to your WordPress site. - Read basic site context. - Generate a structured page plan from a prompt. - Render validated page-plan JSON into native Divi 5 serialized blocks (default) or legacy Divi 4 shortcodes. - Create or update a WordPress page as a Divi Builder draft. - Publish only when you explicitly call the publishing tool. Approved section types: - `hero_luxury_split` - `hero_centered_minimal` - `logo_cloud` - `services_3_cards` - `services_grid_6` - `about_image_text` - `process_steps` - `testimonials` - `faq_accordion` - `lead_capture_form` - `cta_banner` - `footer_minimal` --- ## Important limitation This is a production-minded MVP, not an official Elegant Themes product. It uses WordPress REST endpoints plus Divi 5's serialized block storage format (`<!-- wp:divi/section {...} -->`), the same format the Divi 5 Visual Builder saves. Generated blocks use only verified block types and attribute paths (`divi/section`, `divi/row`, `divi/column`, `divi/text`); buttons, cards, FAQs, and CTAs are rendered as styled HTML inside `divi/text` modules for reliability, and can be swapped for native Button / Accordion / Contact Form modules in the Visual Builder. Known Divi 5 caveat: pages created programmatically (rather than through the Visual Builder) render correctly on the frontend, but the Visual Builder may not list every block in its Layers panel for editing. If full VB editability matters more than native D5 storage, pass `format: "divi4"` — legacy shortcode pages are converted by Divi 5's official migrator the first time you open them in the builder. After installation, always test on a staging site first. --- ## Requirements - WordPress site with HTTPS. - Divi theme or Divi Builder installed and active. - Node.js 20+ on your local computer or server. - A WordPress user with permission to edit pages. - WordPress Application Password for that user. - An MCP-compatible client, such as Claude Desktop, Cursor, Windsurf, or another client that can run stdio MCP servers. --- ## Part 1 — Install the WordPress bridge plugin ### Option A: Upload with FTP or hosting file manager 1. Open your WordPress files. 2. Go to: ```text wp-content/plugins/ ``` 3. Upload this folder: ```text wordpress-plugin/divi-ai-bridge ``` The final path should be: ```text wp-content/plugins/divi-ai-bridge/divi-ai-bridge.php ``` 4. Log in to WordPress admin. 5. Go to **Plugins**. 6. Activate **Divi AI Bridge**. ### Option B: Upload as ZIP 1. Compress the folder `wordpress-plugin/divi-ai-bridge` into `divi-ai-bridge.zip`. 2. In WordPress admin, go to **Plugins → Add New → Upload Plugin**. 3. Upload and activate it. --- ## Part 2 — Create a WordPress Application Password 1. In WordPress admin, create a dedicated user, for example: ```text Username: divi_ai_editor Role: Editor ``` 2. Go to **Users → Profile** for that user. 3. Find **Application Passwords**. 4. Create a password named: ```text Divi Elegant MCP ``` 5. Copy it immediately. WordPress shows it only once. Use HTTPS only. Application Passwords use Basic Auth, so they must not be sent over plain HTTP. --- ## Part 3 — Install the MCP server From the package root: ```bash cd mcp-server npm install cp .env.example .env ``` Edit `.env`: ```env WP_BASE_URL=https://yourwebsite.com WP_USERNAME=divi_ai_editor WP_APP_PASSWORD=xxxx xxxx xxxx xxxx xxxx xxxx DEFAULT_PAGE_STATUS=draft ``` Build the server: ```bash npm run build ``` Test locally: ```bash npm run dev ``` The server uses stdio, so it will appear to “wait” for MCP messages. That is normal. --- ## Part 4 — Test the WordPress plugin manually Replace the values below: ```bash curl --user "divi_ai_editor:YOUR_APPLICATION_PASSWORD" \ https://yourwebsite.com/wp-json/divi-ai/v1/health ``` Expected response: ```json { "ok": true, "plugin": "Divi AI Bridge", "version": "0.1.0", "user": "divi_ai_editor", "can_edit_pages": true } ``` Then test site context: ```bash curl --user "divi_ai_editor:YOUR_APPLICATION_PASSWORD" \ https://yourwebsite.com/wp-json/divi-ai/v1/site ``` --- ## Part 5 — Add the MCP server to your AI client ### Claude Desktop example Open your Claude Desktop MCP config file. macOS: ```text ~/Library/Application Support/Claude/claude_desktop_config.json ``` Windows: ```text %APPDATA%\Claude\claude_desktop_config.json ``` Add: ```json { "mcpServers": { "divi-elegant": { "command": "node", "args": ["/ABSOLUTE/PATH/TO/divi-elegant-mcp/mcp-server/dist/index.js"], "env": { "WP_BASE_URL": "https://yourwebsite.com", "WP_USERNAME": "divi_ai_editor", "WP_APP_PASSWORD": "xxxx xxxx xxxx xxxx xxxx xxxx", "DEFAULT_PAGE_STATUS": "draft" } } } } ``` Restart Claude Desktop. ### Cursor / Windsurf style example Use the same command and args: ```json { "divi-elegant": { "command": "node", "args": ["/ABSOLUTE/PATH/TO/divi-elegant-mcp/mcp-server/dist/index.js"], "env": { "WP_BASE_URL": "https://yourwebsite.com", "WP_USERNAME": "divi_ai_editor", "WP_APP_PASSWORD": "xxxx xxxx xxxx xxxx xxxx xxxx" } } } ``` The exact config screen differs by client, but the command is the same. --- ## Tools exposed by the MCP server ### `health_check` Checks that the plugin is installed and authentication works. ### `get_site_context` Returns site name, URL, active theme, and REST URLs. ### `list_approved_divi_sections` Returns the allowed section library. ### `generate_page_plan` Creates a structured page plan without writing to WordPress. Example prompt: ```text Use the Divi Elegant MCP to generate a page plan for a luxury dental clinic homepage. Audience: families and professionals in Amman. Offer: cosmetic dentistry, implants, orthodontics. Tone: elegant and reassuring. ``` ### `render_divi_layout` Converts a validated page plan into a Divi layout (Divi 5 blocks by default, shortcodes with `format: "divi4"`) without writing to WordPress. ### `create_divi_draft_page` Creates or updates a WordPress draft page from a page plan. ### `build_elegant_divi_page_from_prompt` One-step MVP: generate page plan, render Divi layout, and create a draft page. Example prompt: ```text Use Divi Elegant MCP to build an elegant Divi draft homepage for a boutique recruitment agency in Dubai. Audience: CEOs and HR leaders. Offer: executive search, HR advisory, compensation consulting. Tone: premium, warm, confident. Slug: home. Brand theme: black, warm beige, gold accent, Playfair Display headings, Inter body. Do not publish. ``` ### `publish_page_after_approval` Publishes a page by ID. Use only after manual review and explicit approval. --- ## Recommended workflow 1. Ask the AI to call `health_check`. 2. Ask it to call `get_site_context`. 3. Ask it to generate a page plan. 4. Review the plan. 5. Ask it to create a Divi draft page. 6. Open the preview/edit link in WordPress. 7. Review in Divi Visual Builder. 8. Publish manually or call `publish_page_after_approval`. --- ## Example brand theme ```json { "brandName": "HR180 Business Solutions", "style": "elegant, minimal, premium consulting", "colors": { "primary": "#111111", "secondary": "#F6F1EA", "accent": "#C7A76C", "text": "#202020", "muted": "#747474", "white": "#FFFFFF" }, "fonts": { "heading": "Playfair Display", "body": "Inter" }, "spacing": { "sectionDesktop": "96px", "sectionTablet": "72px", "sectionMobile": "52px" }, "buttons": { "radius": "999px", "style": "outlined" } } ``` --- ## Security checklist - Use a dedicated WordPress user, not your main admin account. - Give the user the minimum role needed. Start with Editor. - Use HTTPS only. - Keep the Application Password in `.env` or the MCP client env config only. - Do not commit `.env` to GitHub. - Create pages as drafts by default. - Review every page before publishing. - Keep plugin and MCP server logs. - Rotate the Application Password regularly. - Disable or delete the Application Password when not needed. - Test on staging before using production. --- ## Troubleshooting ### 401 or 403 from WordPress Check: - `WP_USERNAME` is the WordPress login username, not display name. - Application Password is copied correctly. - The site is HTTPS. - The WordPress user can edit pages. - A security plugin is not blocking REST API Basic Auth. ### Plugin endpoint not found Check: - The plugin is active. - Permalinks are working. - Try visiting: ```text https://yourwebsite.com/wp-json/divi-ai/v1/health ``` ### Page created but Divi does not open it correctly Check: - Divi theme or Divi Builder is active. - Open the page editor and enable Divi Builder manually once. - Save the page. - Test with a simple generated page first. ### Layout looks too plain This MVP prioritizes safe generation. Improve it by expanding `mcp-server/src/divi/sectionLibrary.ts` with richer Divi modules, custom CSS classes, and your saved design system. --- ## How to extend this into a full production product Next improvements: 1. Add media upload support. 2. Add menu creation and homepage assignment. 3. Add full website generation: Home, About, Services, Blog, Contact. 4. Add saved brand profiles by client. 5. Add a richer section library. 6. Add custom CSS generation with a strict allowlist. 7. Add rollback/version history. 8. Add Divi Cloud or saved layout integration if your Elegant Themes account/workflow supports it. 9. Add QA tools: check broken buttons, missing CTAs, mobile spacing, SEO title length, duplicate slugs. 10. Add staging/production separation. --- ## File map ```text divi-elegant-mcp/ README.md examples/ homepage-plan.json mcp-server/ package.json tsconfig.json .env.example src/ index.ts wordpress/client.ts schemas/theme.ts schemas/page.ts divi/blocks.ts divi/sectionLibrary5.ts divi/shortcodes.ts divi/sectionLibrary.ts divi/layoutBuilder.ts prompts/elegant-homepage.md wordpress-plugin/ divi-ai-bridge/ divi-ai-bridge.php ``` --- ## Remote deployment (Docker / VPS) The server runs in two modes: - **stdio** (default): launched locally by Claude Desktop/Cursor. Uses `WP_*` env vars. - **Streamable HTTP** (when `PORT` is set): remote endpoint `POST /mcp/<key>` for use as a Claude custom connector from anywhere. ### Multi-tenant keys - `MCP_AUTH_TOKEN` — admin key; requests to `/mcp/<MCP_AUTH_TOKEN>` use the `WP_*` env credentials. - `USERS_FILE` (`data/users.json`) — JSON map of per-user keys to their own WordPress site credentials. Each user installs the `divi-ai-bridge` plugin on their site, creates an Application Password, and gets their own key/URL. See `data/users.json.example`. The file is re-read on every request, so you can add users without restarting. ### Deploy with Docker Compose ```bash git clone https://github.com/moeadas/D5MCP.git && cd D5MCP cp .env.example .env # fill MCP_AUTH_TOKEN (openssl rand -hex 32) + WP_* creds cp data/users.json.example data/users.json # optional: add per-user sites docker compose up -d --build curl http://localhost:3111/ # {"ok":true,...} ``` Endpoint: `http://<server>:3111/mcp/<key>`. Put it behind HTTPS (reverse proxy, Cloudflare Tunnel, or your panel's proxy) before using it as a Claude custom connector — claude.ai requires HTTPS. ### Security notes - Keys are long random strings in the URL path; treat them like passwords. - Use Editor-level WordPress users, never admins. - `data/users.json` holds credentials — keep it out of git (already ignored) and readable only by the container (mounted read-only).