@respira/wordpress-mcp-server 2.0.2 → 2.0.4

package/README.md

@@ -1,68 +1,93 @@
-# 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>Vibe code your WordPress site with AI.</strong><br>
+  Connect Cursor, Claude Code, Windsurf, and other AI coding assistants directly to WordPress.
+</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):
+## ✨ What is Respira?
 
-```bash
-npx -y @respira/wordpress-mcp-server
-```
+Respira lets you **edit WordPress sites using AI coding assistants** like Cursor, Claude Code, and Windsurf. No SSH access needed. Works with any hosting provider.
+
+**Supported Page Builders:**
+- Divi • Elementor • Gutenberg • Beaver Builder • Bricks
+- Oxygen • WPBakery • Visual Composer • Brizy • Thrive
+
+---
 
-**Note:** When using npx, you don't need to install the package globally. It will automatically download and run the latest version.
+## 🎬 Quick Start (2 Minutes)
 
-## Configuration
+### Step 1: Install the WordPress Plugin
 
-### Option 1: Configuration File (Recommended)
+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_`)
 
-Create a configuration file at `~/.respira/config.json`:
+### Step 2: Configure Your AI Assistant
+
+<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 +100,256 @@ Add to your Cursor settings (`.cursor/mcp.json`):
 }
 ```
 
-**Option 2: Using global installation**
+</details>
 
-If you installed globally with `npm install -g`, use:
+<details>
+<summary><b>🖥️ Claude Desktop</b></summary>
+
+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>
 
-### With Claude Desktop
+### Step 3: Create Config File
 
-Add to your Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):
+Create `~/.respira/config.json`:
 
-**Using npm (Recommended):**
+```json
+{
+  "sites": [
+    {
+      "id": "my-site",
+      "name": "My WordPress Site",
+      "url": "https://yoursite.com",
+      "apiKey": "respira_your-api-key-here",
+      "default": true
+    }
+  ]
+}
+```
+
+**That's it!** Restart your AI assistant and start vibe coding! 🎉
+
+---
+
+## 🪟 Windows Users: Troubleshooting
+
+If you see `'npx' is not recognized as an internal or external command`:
+
+### Option 1: Use Full Path (Recommended)
+
+Find your Node.js installation path and use the full path in your config:
 
 ```json
 {
   "mcpServers": {
     "respira-wordpress": {
-      "command": "npx",
+      "command": "C:\\Program Files\\nodejs\\npx.cmd",
       "args": ["-y", "@respira/wordpress-mcp-server"]
     }
   }
 }
 ```
 
+### Option 2: Add Node.js to PATH
+
+1. Press `Win + R`, type `sysdm.cpl`, press Enter
+2. Click **Advanced** tab → **Environment Variables**
+3. Under **System variables**, find **Path** and click **Edit**
+4. Click **New** and add: `C:\Program Files\nodejs\`
+5. Click **OK** on all dialogs
+6. **Restart your AI assistant completely**
 
-## Available Tools
+### Option 3: Install Globally First
+
+```bash
+npm install -g @respira/wordpress-mcp-server
+```
+
+Then use this config:
+
+```json
+{
+  "mcpServers": {
+    "respira-wordpress": {
+      "command": "respira-wordpress-mcp"
+    }
+  }
+}
+```
+
+---
+
+## 🛠️ Available Tools (60+)
 
 ### 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
+| Tool | Description |
+|------|-------------|
+| `wordpress_list_pages` | List all pages |
+| `wordpress_read_page` | Get page content with builder data |
+| `wordpress_update_page` | Update page content |
+| `wordpress_create_page_duplicate` | Safely duplicate before editing |
+| `wordpress_list_posts` | List all posts |
+| `wordpress_read_post` | Get post content |
+| `wordpress_update_post` | Update post content |
+
+### 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 |
+| `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 |
+
+### Page Builders
+| Tool | Description |
+|------|-------------|
+| `wordpress_get_builder_info` | Get available modules/widgets |
+| `wordpress_extract_builder_content` | Extract structured content |
+| `wordpress_inject_builder_content` | Inject builder content |
+| `wordpress_update_module` | Update specific module |
+
+### SEO & Performance
+| Tool | Description |
+|------|-------------|
+| `wordpress_analyze_seo` | Comprehensive SEO analysis |
+| `wordpress_analyze_performance` | Performance metrics |
+| `wordpress_get_core_web_vitals` | LCP, FID, CLS scores |
+| `wordpress_analyze_aeo` | AI search engine optimization |
+
+### Users, Comments, Taxonomies
+| Tool | Description |
+|------|-------------|
+| `wordpress_list_users` | List all users |
+| `wordpress_create_user` | Create new user |
+| `wordpress_list_comments` | List comments |
+| `wordpress_list_taxonomies` | List taxonomies |
+| `wordpress_list_terms` | List category/tag terms |
 
 ### 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
+| Tool | Description |
+|------|-------------|
+| `wordpress_list_post_types` | List registered CPTs |
+| `wordpress_list_custom_posts` | List CPT entries |
+| `wordpress_create_custom_post` | Create CPT entry |
 
-```bash
-# Watch mode
-npm run watch
+### Plugin Management (Experimental)
+| Tool | Description |
+|------|-------------|
+| `wordpress_list_plugins` | List installed plugins |
+| `wordpress_install_plugin` | Install from WordPress.org |
+| `wordpress_activate_plugin` | Activate plugin |
+| `wordpress_update_plugin` | Update to latest version |
+
+---
+
+## 🔒 Safe Editing with Duplicates
+
+Respira automatically creates duplicates before editing live pages. This means:
+
+1. **Your live site stays untouched** until you approve changes
+2. **Preview changes** before they go live
+3. **Easy rollback** if something goes wrong
+
+Approve changes in WordPress admin: **Respira → Approve Edits**
+
+---
+
+## 🌍 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
 
-# Build
-npm run build
+---
 
-# Run
-npm run start
+## 📦 Alternative Installation
 
-# Lint
-npm run lint
+### Global Installation
 
-# Format
-npm run format
+```bash
+npm install -g @respira/wordpress-mcp-server
+```
+
+### Environment Variables
+
+Instead of config file, use `.env`:
+
+```bash
+WP_SITE_URL=https://your-site.com
+WP_API_KEY=respira_your-api-key
 ```
 
-## License
+---
+
+## 🆘 Need Help?
+
+- 📖 [Documentation](https://respira.press/docs)
+- 💬 [Support](https://respira.press/support)
+- 🐛 [Report Issues](https://github.com/webmyc/respira-wordpress/issues)
+- 📧 [Contact](mailto:support@respira.press)
+
+---
+
+## 📄 License
+
+MIT © [Respira](https://respira.press)
+
+---
 
-MIT
+<p align="center">
+  <strong>Built with ❤️ 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"}