@respira/wordpress-mcp-server 2.0.3 → 2.0.5

package/README.md

@@ -1,68 +1,123 @@
-# Respira WordPress MCP Server
+<p align="center">
+  <a href="https://respira.press">
+    <img src="https://respira.press/hero/respira-press-cover.jpg" alt="Respira for WordPress" width="100%">
+  </a>
+</p>
 
-MCP (Model Context Protocol) server for connecting AI coding assistants to WordPress sites.
+<h1 align="center">Respira WordPress MCP Server</h1>
 
-**Important:** This MCP server requires a Respira API key. Get your API key by:
-1. Installing the [Respira WordPress plugin](https://respira.press) on your WordPress site
-2. Going to **Respira → API Keys** in WordPress admin
-3. Generating a new API key
+<p align="center">
+  <strong>The only WordPress MCP with page builder support.</strong><br>
+  Edit Divi, Elementor, Bricks + 7 more builders with AI. Duplicate-before-edit safety. SEO analysis. 60+ tools.
+</p>
 
-## Installation
+<p align="center">
+  <a href="https://www.npmjs.com/package/@respira/wordpress-mcp-server"><img src="https://img.shields.io/npm/v/@respira/wordpress-mcp-server.svg?style=flat-square&color=blue" alt="npm version"></a>
+  <a href="https://www.npmjs.com/package/@respira/wordpress-mcp-server"><img src="https://img.shields.io/npm/dm/@respira/wordpress-mcp-server.svg?style=flat-square" alt="npm downloads"></a>
+  <a href="https://github.com/webmyc/respira-wordpress"><img src="https://img.shields.io/github/stars/webmyc/respira-wordpress?style=flat-square" alt="GitHub stars"></a>
+  <a href="https://respira.press"><img src="https://img.shields.io/badge/website-respira.press-purple?style=flat-square" alt="Website"></a>
+</p>
 
-Install the MCP server from npm:
+<p align="center">
+  <a href="https://respira.press">Website</a> •
+  <a href="https://respira.press/docs">Documentation</a> •
+  <a href="https://respira.press/support">Support</a> •
+  <a href="https://github.com/webmyc/respira-wordpress">GitHub</a>
+</p>
 
-```bash
-npm install -g @respira/wordpress-mcp-server
-```
+---
 
-Or use it directly with npx (no installation needed):
+## Why Respira?
 
-```bash
-npx -y @respira/wordpress-mcp-server
-```
+Most WordPress MCP servers only work with Gutenberg. **Respira is the only MCP that supports real page builders** — the tools that power 50%+ of WordPress sites.
+
+### Feature Comparison
+
+| Feature | Respira | mcp-wordpress | wordpress-mcp |
+|---------|---------|---------------|---------------|
+| **Divi Builder** (200+ modules) | ✅ | ❌ | ❌ |
+| **Elementor** (widgets, templates) | ✅ | ❌ | ❌ |
+| **Bricks Builder** | ✅ | ❌ | ❌ |
+| **Oxygen Builder** | ✅ | ❌ | ❌ |
+| **WPBakery / Visual Composer** | ✅ | ❌ | ❌ |
+| **Beaver Builder** | ✅ | ❌ | ❌ |
+| **Thrive Architect** | ✅ | ❌ | ❌ |
+| **Brizy** | ✅ | ❌ | ❌ |
+| Gutenberg (Block Editor) | ✅ | ✅ | ✅ |
+| Duplicate-before-edit safety | ✅ | ❌ | ❌ |
+| SEO analysis tools | ✅ | ❌ | ❌ |
+| Performance / Core Web Vitals | ✅ | ❌ | ❌ |
+| AI Engine Optimization (AEO) | ✅ | ❌ | ❌ |
+| Menu management (full CRUD) | ✅ | ❌ | Limited |
+| Media upload & management | ✅ | ✅ | ✅ |
+| WPML multilingual support | ✅ | ❌ | ❌ |
+| Multi-site switching | ✅ | ❌ | ❌ |
+| Plugin management | ✅ | ❌ | ❌ |
+| **Total tools** | **60+** | ~15 | ~20 |
+
+### What Makes Respira Different
+
+1. **Page Builder Intelligence** — AI understands Divi sections, Elementor widgets, Bricks elements. Not just raw HTML.
+
+2. **Duplicate-Before-Edit Safety** — Respira creates a duplicate before editing any live page. Review changes in WordPress admin before they go live. Your production site is never touched until you approve.
+
+3. **SEO & Performance Analysis** — Built-in tools for comprehensive SEO audits, Core Web Vitals, and AI Engine Optimization (AEO) for ChatGPT/Perplexity visibility.
+
+4. **Module-Level Precision** — Update a specific Divi module or Elementor widget by its admin label or path, without touching the rest of the page.
+
+---
+
+## Quick Start (2 Minutes)
 
-**Note:** When using npx, you don't need to install the package globally. It will automatically download and run the latest version.
+### Step 1: Install the WordPress Plugin
 
-## Configuration
+1. Download from [respira.press](https://respira.press)
+2. Upload to WordPress: **Plugins → Add New → Upload Plugin**
+3. Activate and go to **Respira → API Keys**
+4. Generate your API key (starts with `respira_`)
 
-### Option 1: Configuration File (Recommended)
+### Step 2: Configure Your AI Assistant
 
-Create a configuration file at `~/.respira/config.json`:
+<details>
+<summary><b>Cursor</b></summary>
+
+Create or edit `.cursor/mcp.json` in your project:
 
 ```json
 {
-  "sites": [
-    {
-      "id": "my-site",
-      "name": "My WordPress Site",
-      "url": "https://mysite.com",
-      "apiKey": "respira_your-api-key-here",
-      "default": true
+  "mcpServers": {
+    "respira-wordpress": {
+      "command": "npx",
+      "args": ["-y", "@respira/wordpress-mcp-server"]
     }
-  ],
-  "preferences": {
-    "autoDuplicate": true,
-    "securityChecks": true
   }
 }
 ```
 
-### Option 2: Environment Variables
+</details>
 
-Create a `.env` file:
+<details>
+<summary><b>Claude Code</b></summary>
 
-```bash
-WP_SITE_URL=https://your-wordpress-site.com
-WP_API_KEY=respira_your-api-key-here
-```
+Add to your Claude Code config (`~/.claude.json` or project settings):
 
-## Usage
+```json
+{
+  "mcpServers": {
+    "respira-wordpress": {
+      "command": "npx",
+      "args": ["-y", "@respira/wordpress-mcp-server"]
+    }
+  }
+}
+```
 
-### With Cursor
+</details>
 
-**Option 1: Using npm (Recommended)**
+<details>
+<summary><b>Windsurf</b></summary>
 
-Add to your Cursor settings (`.cursor/mcp.json`):
+Add to your Windsurf MCP configuration:
 
 ```json
 {
@@ -75,144 +130,286 @@ Add to your Cursor settings (`.cursor/mcp.json`):
 }
 ```
 
-**Option 2: Using global installation**
+</details>
+
+<details>
+<summary><b>Claude Desktop</b></summary>
 
-If you installed globally with `npm install -g`, use:
+Add to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):
 
 ```json
 {
   "mcpServers": {
     "respira-wordpress": {
-      "command": "respira-wordpress-mcp"
+      "command": "npx",
+      "args": ["-y", "@respira/wordpress-mcp-server"]
     }
   }
 }
 ```
 
+</details>
+
+### Step 3: Create Config File
+
+Create `~/.respira/config.json`:
+
+```json
+{
+  "sites": [
+    {
+      "id": "my-site",
+      "name": "My WordPress Site",
+      "url": "https://yoursite.com",
+      "apiKey": "respira_your-api-key-here",
+      "default": true
+    }
+  ]
+}
+```
 
-### With Claude Desktop
+**That's it!** Restart your AI assistant and start editing.
 
-Add to your Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):
+---
 
-**Using npm (Recommended):**
+## Page Builder Support
+
+### Divi Builder
+- 200+ module types supported
+- Section, row, and module-level editing
+- Update by admin label: `"Find the module labeled 'Hero CTA' and change the button text"`
+- Preserves all Divi styling and settings
+
+### Elementor
+- Widget-level precision editing
+- Template and section support
+- CSS cache regeneration after updates
+- Compatible with Elementor Pro
+
+### Other Builders
+- **Bricks** — Elements and containers
+- **Oxygen** — Components and templates
+- **WPBakery** — Shortcode-based editing
+- **Beaver Builder** — Modules and rows
+- **Thrive Architect** — Elements and templates
+- **Brizy** — Blocks and elements
+- **Visual Composer** — Elements and grids
+
+---
+
+## Safe Editing Workflow
+
+Respira never edits your live pages directly:
+
+1. AI requests a page update
+2. Respira **creates a duplicate** of the page
+3. AI edits the duplicate
+4. You **review changes** in WordPress admin
+5. One-click to approve and replace the original
+
+Go to **Respira → Approve Edits** to review pending changes.
+
+---
+
+## Available Tools (60+)
+
+### Content Management
+| Tool | Description |
+|------|-------------|
+| `wordpress_list_pages` | List all pages |
+| `wordpress_read_page` | Get page content with builder data |
+| `wordpress_update_page` | Update page (auto-creates duplicate) |
+| `wordpress_create_page_duplicate` | Manually create safe duplicate |
+| `wordpress_list_posts` | List all posts |
+| `wordpress_read_post` | Get post content |
+| `wordpress_update_post` | Update post content |
+
+### Page Builders
+| Tool | Description |
+|------|-------------|
+| `wordpress_get_builder_info` | Get available modules/widgets for detected builder |
+| `wordpress_extract_builder_content` | Extract structured content (sections, rows, modules) |
+| `wordpress_inject_builder_content` | Inject structured builder content |
+| `wordpress_update_module` | Update specific module by admin_label or path |
+
+### Media Management
+| Tool | Description |
+|------|-------------|
+| `wordpress_list_media` | List all media files |
+| `wordpress_upload_media` | Upload images, videos, documents |
+| `wordpress_update_media` | Update alt text, title, caption |
+| `wordpress_delete_media` | Delete media files |
+
+### Menu Management
+| Tool | Description |
+|------|-------------|
+| `wordpress_list_menus` | List all navigation menus |
+| `wordpress_get_menu` | Get menu with all items |
+| `wordpress_create_menu` | Create new menu |
+| `wordpress_update_menu` | Update menu structure |
+| `wordpress_list_menu_locations` | List theme menu locations |
+| `wordpress_assign_menu_location` | Assign menu to location |
+| `wordpress_create_menu_item` | Add menu item |
+| `wordpress_update_menu_item` | Update menu item |
+
+### SEO & Performance
+| Tool | Description |
+|------|-------------|
+| `wordpress_analyze_seo` | Comprehensive SEO analysis with recommendations |
+| `wordpress_check_seo_issues` | Quick SEO issue checker |
+| `wordpress_analyze_performance` | Performance metrics and bottlenecks |
+| `wordpress_get_core_web_vitals` | LCP, FID, CLS scores |
+| `wordpress_analyze_aeo` | AI search engine optimization (ChatGPT, Perplexity) |
+| `wordpress_check_structured_data` | Schema markup validation |
+| `wordpress_analyze_images` | Image optimization opportunities |
+| `wordpress_analyze_readability` | Content readability scores |
+
+### Users & Comments
+| Tool | Description |
+|------|-------------|
+| `wordpress_list_users` | List all users |
+| `wordpress_create_user` | Create new user |
+| `wordpress_update_user` | Update user details |
+| `wordpress_list_comments` | List comments |
+| `wordpress_create_comment` | Create comment |
+| `wordpress_update_comment` | Update/moderate comment |
+
+### Taxonomies & Terms
+| Tool | Description |
+|------|-------------|
+| `wordpress_list_taxonomies` | List all taxonomies |
+| `wordpress_list_terms` | List terms in taxonomy |
+| `wordpress_create_term` | Create category/tag/term |
+| `wordpress_update_term` | Update term |
+
+### Custom Post Types
+| Tool | Description |
+|------|-------------|
+| `wordpress_list_post_types` | List registered CPTs |
+| `wordpress_list_custom_posts` | List CPT entries |
+| `wordpress_create_custom_post` | Create CPT entry |
+| `wordpress_update_custom_post` | Update CPT entry |
+
+### Plugin Management (Experimental)
+| Tool | Description |
+|------|-------------|
+| `wordpress_list_plugins` | List installed plugins |
+| `wordpress_install_plugin` | Install from WordPress.org |
+| `wordpress_activate_plugin` | Activate plugin |
+| `wordpress_deactivate_plugin` | Deactivate plugin |
+| `wordpress_update_plugin` | Update to latest version |
+
+### Site Context
+| Tool | Description |
+|------|-------------|
+| `wordpress_get_site_context` | Get site info, theme, plugins, builders |
+| `wordpress_get_theme_docs` | Get theme documentation |
+| `wordpress_switch_site` | Switch to different site (multi-site) |
+
+---
+
+## Multi-Site Support
+
+Manage multiple WordPress sites from one config:
+
+```json
+{
+  "sites": [
+    {
+      "id": "production",
+      "name": "Production Site",
+      "url": "https://mysite.com",
+      "apiKey": "respira_prod_key",
+      "default": true
+    },
+    {
+      "id": "staging",
+      "name": "Staging Site",
+      "url": "https://staging.mysite.com",
+      "apiKey": "respira_staging_key"
+    }
+  ]
+}
+```
+
+Switch sites with: `wordpress_switch_site`
+
+---
+
+## WPML Multilingual Support
+
+Full support for WPML multilingual sites:
+- Menu translations
+- Page/post language detection
+- Translation links
+- Language-aware content queries
+
+---
+
+## Windows Troubleshooting
+
+If you see `'npx' is not recognized`:
+
+### Option 1: Use Full Path (Recommended)
 
 ```json
 {
   "mcpServers": {
     "respira-wordpress": {
-      "command": "npx",
+      "command": "C:\\Program Files\\nodejs\\npx.cmd",
       "args": ["-y", "@respira/wordpress-mcp-server"]
     }
   }
 }
 ```
 
+### Option 2: Install Globally
 
-## Available Tools
+```bash
+npm install -g @respira/wordpress-mcp-server
+```
 
-### Content Management
-- `wordpress_get_site_context` - Get comprehensive site information
-- `wordpress_get_theme_docs` - Get theme documentation
-- `wordpress_get_builder_info` - Get page builder information
-- `wordpress_list_pages` - List all pages
-- `wordpress_read_page` - Get page content
-- `wordpress_create_page_duplicate` - Duplicate a page for safe editing
-- `wordpress_update_page` - Update page content
-- `wordpress_delete_page` - Delete a page
-- `wordpress_list_posts` - List all posts
-- `wordpress_read_post` - Get post content
-- `wordpress_create_post_duplicate` - Duplicate a post
-- `wordpress_list_media` - List media files
-- `wordpress_upload_media` - Upload media files (images, documents, videos) - supports base64, URLs, or file paths
-- `wordpress_get_media` - Get single media item details
-- `wordpress_update_media` - Update media metadata (title, alt text, caption)
-- `wordpress_delete_media` - Delete a media file
-- `wordpress_extract_builder_content` - Extract page builder content
-- `wordpress_inject_builder_content` - Inject page builder content
-- `wordpress_validate_security` - Validate content for security issues
-- `wordpress_switch_site` - Switch between multiple WordPress sites
-
-### User Management
-- `wordpress_list_users` - List all users with optional filtering
-- `wordpress_get_user` - Get user details by ID
-- `wordpress_create_user` - Create a new user
-- `wordpress_update_user` - Update user information
-- `wordpress_delete_user` - Delete a user
-
-### Comments
-- `wordpress_list_comments` - List all comments with optional filtering
-- `wordpress_get_comment` - Get comment details by ID
-- `wordpress_create_comment` - Create a new comment
-- `wordpress_update_comment` - Update a comment
-- `wordpress_delete_comment` - Delete a comment
-
-### Taxonomies
-- `wordpress_list_taxonomies` - List all registered taxonomies
-- `wordpress_get_taxonomy` - Get taxonomy details
-- `wordpress_list_terms` - List terms in a taxonomy
-- `wordpress_get_term` - Get term details
-- `wordpress_create_term` - Create a new term
-- `wordpress_update_term` - Update a term
-- `wordpress_delete_term` - Delete a term
+Then use:
 
-### Custom Post Types
-- `wordpress_list_post_types` - List all registered post types
-- `wordpress_get_post_type` - Get post type details
-- `wordpress_list_custom_posts` - List posts of a custom post type
-- `wordpress_get_custom_post` - Get custom post details
-- `wordpress_create_custom_post` - Create a new custom post
-- `wordpress_update_custom_post` - Update a custom post
-- `wordpress_delete_custom_post` - Delete a custom post
-
-### WordPress Options
-- `wordpress_list_options` - List WordPress options (with optional search filter)
-- `wordpress_get_option` - Get option value by name
-- `wordpress_update_option` - Update an option value
-- `wordpress_delete_option` - Delete an option
-
-### Page Speed Analysis
-- `wordpress_analyze_performance` - Analyze page performance metrics (load time, optimization opportunities)
-- `wordpress_get_core_web_vitals` - Get Core Web Vitals scores (LCP, FID, CLS)
-- `wordpress_analyze_images` - Analyze image optimization opportunities
-
-### SEO Analysis
-- `wordpress_analyze_seo` - Comprehensive SEO analysis (meta tags, headings, alt text, linking)
-- `wordpress_check_seo_issues` - Check for common SEO issues and get recommendations
-- `wordpress_analyze_readability` - Analyze content readability (Flesch Reading Ease, sentence structure)
-
-### AI Engine Optimization (AEO)
-- `wordpress_analyze_aeo` - Analyze content for AI search engines (Perplexity, ChatGPT)
-- `wordpress_check_structured_data` - Check schema markup and structured data (JSON-LD, microdata)
-
-### Plugin Management (EXPERIMENTAL)
-- `wordpress_list_plugins` - List all installed plugins with status and version
-- `wordpress_install_plugin` - Install a plugin from WordPress.org or ZIP URL
-- `wordpress_activate_plugin` - Activate a plugin
-- `wordpress_deactivate_plugin` - Deactivate a plugin
-- `wordpress_update_plugin` - Update a plugin to the latest version
-- `wordpress_delete_plugin` - Permanently delete a plugin
-
-**Note**: Plugin management tools are EXPERIMENTAL and require the feature to be enabled in Respira settings (disabled by default for security). Use with caution and always have backups.
-
-## Development
+```json
+{
+  "mcpServers": {
+    "respira-wordpress": {
+      "command": "respira-wordpress-mcp"
+    }
+  }
+}
+```
+
+---
+
+## Environment Variables
+
+Instead of config file, use `.env`:
 
 ```bash
-# Watch mode
-npm run watch
+WP_SITE_URL=https://your-site.com
+WP_API_KEY=respira_your-api-key
+```
 
-# Build
-npm run build
+---
 
-# Run
-npm run start
+## Need Help?
 
-# Lint
-npm run lint
+- [Documentation](https://respira.press/docs)
+- [Support](https://respira.press/support)
+- [Report Issues](https://github.com/webmyc/respira-wordpress/issues)
+- [Contact](mailto:support@respira.press)
 
-# Format
-npm run format
-```
+---
 
 ## License
 
-MIT
+MIT © [Respira](https://respira.press)
+
+---
+
+<p align="center">
+  <strong>Built for the WordPress community</strong><br>
+  <a href="https://respira.press">respira.press</a>
+</p>

package/dist/server.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAUH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,kBAAkB,CAAC;AAE5D,qBAAa,sBAAsB;IACjC,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,WAAW,CAAgC;IACnD,OAAO,CAAC,KAAK,CAA2C;gBAE5C,WAAW,EAAE,mBAAmB,EAAE;IA2B9C,OAAO,CAAC,aAAa;IA8ErB,OAAO,CAAC,QAAQ;YAwyCF,cAAc;IA2QtB,GAAG;CAKV"}
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAUH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,kBAAkB,CAAC;AAE5D,qBAAa,sBAAsB;IACjC,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,WAAW,CAAgC;IACnD,OAAO,CAAC,KAAK,CAA2C;gBAE5C,WAAW,EAAE,mBAAmB,EAAE;IA2B9C,OAAO,CAAC,aAAa;IAsGrB,OAAO,CAAC,QAAQ;YAyiDF,cAAc;IAkTtB,GAAG;CAKV"}