mcp-wordpress 2.10.0 → 2.10.2

package/docs/TROUBLESHOOTING.md

@@ -27,12 +27,12 @@ npm run test:performance
 
 ### Common Issue Categories
 
-| Issue Type | Symptoms | Quick Fix |
-|------------|----------|-----------|
-| **[Connection](#-connection-issues)** | Can't reach WordPress | Check URL and network |
-| **[Authentication](#-authentication-issues)** | Login failures | Verify credentials |
-| **[Tools](#️-tool-issues)** | Commands not working | Check permissions |
-| **[Performance](#-performance-issues)** | Slow responses | Enable caching |
+| Issue Type                                     | Symptoms                | Quick Fix               |
+| ---------------------------------------------- | ----------------------- | ----------------------- |
+| **[Connection](#-connection-issues)**          | Can't reach WordPress   | Check URL and network   |
+| **[Authentication](#-authentication-issues)**  | Login failures          | Verify credentials      |
+| **[Tools](#️-tool-issues)**                    | Commands not working    | Check permissions       |
+| **[Performance](#-performance-issues)**        | Slow responses          | Enable caching          |
 | **[Claude Desktop](#️-claude-desktop-issues)** | Not appearing in Claude | Restart and reconfigure |
 
 ## 🌐 Connection Issues
@@ -40,11 +40,13 @@ npm run test:performance
 ### Issue: "Cannot connect to WordPress"
 
 **Symptoms:**
+
 - Connection timeout errors
 - "Site not reachable" messages
 - Network-related failures
 
 **Diagnosis:**
+
 ```bash
 # Test WordPress REST API manually
 curl -i https://your-site.com/wp-json/wp/v2/
@@ -56,30 +58,33 @@ curl -i https://your-site.com/wp-json/wp/v2/
 **Solutions:**
 
 1. **Verify WordPress URL Format**
+
    ```bash
    # ✅ Correct formats
    https://yoursite.com
    https://www.yoursite.com
    https://blog.yoursite.com
-   
+
    # ❌ Incorrect formats
    yoursite.com          # Missing protocol
    https://yoursite.com/ # Trailing slash
    ```
 
 2. **Check WordPress REST API**
+
    - Go to **Settings** → **Permalinks** in WordPress admin
    - Click "Save Changes" to refresh rewrite rules
    - Verify REST API is not disabled by plugins
 
 3. **Network and Firewall**
+
    ```bash
    # Test connectivity
    ping yoursite.com
-   
+
    # Test HTTPS
    curl -I https://yoursite.com
-   
+
    # Test specific port if needed
    telnet yoursite.com 443
    ```
@@ -94,10 +99,12 @@ curl -i https://your-site.com/wp-json/wp/v2/
 ### Issue: "SSL Certificate Error"
 
 **Symptoms:**
+
 - SSL verification failures
 - Certificate warnings
 
 **Solutions:**
+
 ```bash
 # For development only - disable SSL verification
 export NODE_TLS_REJECT_UNAUTHORIZED=0
@@ -111,11 +118,13 @@ export NODE_TLS_REJECT_UNAUTHORIZED=0
 ### Issue: "Authentication failed"
 
 **Symptoms:**
+
 - 401 Unauthorized errors
 - "Invalid credentials" messages
 - Login repeatedly fails
 
 **Diagnosis:**
+
 ```bash
 # Test authentication manually
 curl -u "username:app-password" https://your-site.com/wp-json/wp/v2/users/me
@@ -127,10 +136,11 @@ curl -u "username:app-password" https://your-site.com/wp-json/wp/v2/users/me
 **Solutions:**
 
 1. **Application Password Format**
+
    ```bash
    # ✅ Correct format (with spaces)
    WORDPRESS_APP_PASSWORD="AbCd EfGh IjKl MnOp QrSt UvWx"
-   
+
    # ❌ Incorrect formats
    WORDPRESS_APP_PASSWORD=AbCdEfGhIjKlMnOpQrStUvWx  # No spaces
    WORDPRESS_APP_PASSWORD='AbCd EfGh...'             # Single quotes
@@ -138,12 +148,14 @@ curl -u "username:app-password" https://your-site.com/wp-json/wp/v2/users/me
    ```
 
 2. **Regenerate Application Password**
+
    - WordPress Admin → Users → Profile
    - Delete old application password
    - Create new one: "MCP WordPress Server"
    - Copy the exact password shown (with spaces)
 
 3. **Check WordPress User Permissions**
+
    ```text
    # Minimum role requirements:
    - Read operations: Subscriber
@@ -162,12 +174,14 @@ curl -u "username:app-password" https://your-site.com/wp-json/wp/v2/users/me
 ### Issue: "Permission denied for operation"
 
 **Symptoms:**
+
 - Some tools work, others fail
 - "Insufficient permissions" errors
 
 **Solutions:**
 
 1. **Check User Role Requirements**
+
    ```bash
    # Test user capabilities
    curl -u "username:app-password" \
@@ -175,25 +189,23 @@ curl -u "username:app-password" https://your-site.com/wp-json/wp/v2/users/me
      jq '.capabilities'
    ```
 
-2. **Role-Based Access Matrix**
-   | Operation | Subscriber | Author | Editor | Admin |
-   |-----------|------------|--------|--------|-------|
-   | Read posts | ✅ | ✅ | ✅ | ✅ |
-   | Create posts | ❌ | ✅ | ✅ | ✅ |
-   | Edit others' posts | ❌ | ❌ | ✅ | ✅ |
-   | Manage users | ❌ | ❌ | ❌ | ✅ |
-   | Site settings | ❌ | ❌ | ❌ | ✅ |
+2. **Role-Based Access Matrix** | Operation | Subscriber | Author | Editor | Admin |
+   |-----------|------------|--------|--------|-------| | Read posts | ✅ | ✅ | ✅ | ✅ | | Create posts | ❌ | ✅ | ✅
+   | ✅ | | Edit others' posts | ❌ | ❌ | ✅ | ✅ | | Manage users | ❌ | ❌ | ❌ | ✅ | | Site settings | ❌ | ❌ | ❌
+   | ✅ |
 
 ## 🛠️ Tool Issues
 
 ### Issue: "Tool not found" or "Command failed"
 
 **Symptoms:**
+
 - Specific WordPress tools don't work
 - "Unknown tool" errors
 - Tools missing from Claude
 
 **Diagnosis:**
+
 ```bash
 # List available tools
 npm run test:tools
@@ -206,6 +218,7 @@ DEBUG=true npm run dev
 **Solutions:**
 
 1. **Verify Tool Registration**
+
    ```bash
    # Check all tools are loaded
    npm run status | grep "tools available"
@@ -213,6 +226,7 @@ DEBUG=true npm run dev
    ```
 
 2. **Test Individual Tool Categories**
+
    ```text
    # In Claude, test each category:
    "List my WordPress posts"          # Posts tools
@@ -222,11 +236,12 @@ DEBUG=true npm run dev
    ```
 
 3. **Check Multi-Site Configuration**
+
    ```bash
    # If using multi-site, always specify site parameter
    # ✅ Correct
    wp_list_posts --site="main-site"
-   
+
    # ❌ Incorrect (will fail with multiple sites)
    wp_list_posts
    ```
@@ -234,16 +249,18 @@ DEBUG=true npm run dev
 ### Issue: "Invalid parameters" errors
 
 **Symptoms:**
+
 - Tools reject valid-looking parameters
 - Type validation errors
 
 **Solutions:**
 
 1. **Check Parameter Types**
+
    ```text
    # ✅ Correct parameter types
    wp_create_post --title="My Post" --content="Content here"
-   
+
    # ❌ Incorrect (missing quotes for strings)
    wp_create_post --title=My Post --content=Content here
    ```
@@ -260,11 +277,13 @@ DEBUG=true npm run dev
 ### Issue: Slow response times
 
 **Symptoms:**
+
 - Tools take a long time to respond
 - Timeout errors
 - Claude appears to hang
 
 **Diagnosis:**
+
 ```bash
 # Check performance metrics
 npm run test:performance
@@ -279,26 +298,29 @@ npm run cache:stats
 **Solutions:**
 
 1. **Enable Caching**
+
    ```bash
    # Ensure caching is enabled (default)
    # Remove this line if present:
    # DISABLE_CACHE=true
-   
+
    # Check cache performance
    npm run cache:stats
    ```
 
 2. **WordPress Optimization**
+
    - Install caching plugin (W3 Total Cache, WP Rocket)
    - Optimize database and images
    - Use CDN for media files
    - Upgrade hosting if necessary
 
 3. **Network Optimization**
+
    ```bash
    # Test network latency
    ping your-site.com
-   
+
    # Test WordPress response time
    time curl -s https://your-site.com/wp-json/wp/v2/ > /dev/null
    ```
@@ -306,6 +328,7 @@ npm run cache:stats
 ### Issue: Memory or CPU high usage
 
 **Symptoms:**
+
 - System becomes slow
 - High resource usage
 - Crashes or restarts
@@ -313,20 +336,22 @@ npm run cache:stats
 **Solutions:**
 
 1. **Monitor Resource Usage**
+
    ```bash
    # Check memory usage
    npm run test:performance | grep memory
-   
+
    # Monitor during operation
    top -p $(pgrep node)
    ```
 
 2. **Optimize Configuration**
+
    ```bash
    # Reduce cache size if memory is limited
    # Edit configuration:
    CACHE_MAX_SIZE=100  # Reduce from default 1000
-   
+
    # Disable performance monitoring in production
    DISABLE_PERFORMANCE_MONITORING=true
    ```
@@ -336,6 +361,7 @@ npm run cache:stats
 ### Issue: "WordPress tools not appearing in Claude"
 
 **Symptoms:**
+
 - Claude doesn't recognize WordPress commands
 - No WordPress functionality available
 - "I don't have access to WordPress" responses
@@ -343,19 +369,22 @@ npm run cache:stats
 **Solutions:**
 
 1. **Restart Claude Desktop**
+
    ```bash
    # Always restart Claude Desktop after configuration changes
    # This ensures MCP server connections are refreshed
    ```
 
 2. **Check Configuration File**
-   
+
    **For DXT Extension:**
+
    - Verify extension is enabled in Claude Desktop
    - Check configuration in Extensions settings
    - Reinstall DXT if necessary
 
    **For NPX/NPM Method:**
+
    ```json
    // Verify Claude Desktop config file format
    {
@@ -374,18 +403,21 @@ npm run cache:stats
    ```
 
 3. **Verify Configuration File Location**
-   
+
    **macOS:**
+
    ```bash
    ~/Library/Application Support/Claude/claude_desktop_config.json
    ```
-   
+
    **Windows:**
+
    ```bash
    %APPDATA%\Claude\claude_desktop_config.json
    ```
-   
+
    **Linux:**
+
    ```bash
    ~/.config/claude_desktop_config.json
    ```
@@ -393,39 +425,43 @@ npm run cache:stats
 ### Issue: "Server connection failed"
 
 **Symptoms:**
+
 - Claude shows "MCP server connection failed"
 - Server appears to start but then disconnects
 
 **Solutions:**
 
 1. **Check Server Logs**
+
    ```bash
    # Run server manually to see errors
    DEBUG=true npx -y mcp-wordpress
-   
+
    # Look for specific error messages
    # Common issues: missing dependencies, port conflicts
    ```
 
 2. **JSON-RPC Protocol Issues**
+
    ```bash
    # Recent fix for DXT: JSON parsing errors
    # Update to latest version
    curl -L -o mcp-wordpress.dxt \
      https://github.com/docdyhr/mcp-wordpress/releases/latest/download/\
      mcp-wordpress.dxt
-   
+
    # Reinstall DXT extension
    ```
 
 3. **Environment Issues**
+
    ```bash
    # Test Node.js version
    node --version  # Should be 16+
-   
+
    # Test npm access
    npm --version
-   
+
    # Clear npm cache if needed
    npm cache clean --force
    ```
@@ -435,16 +471,18 @@ npm run cache:stats
 ### Issue: Container won't start
 
 **Symptoms:**
+
 - Docker container exits immediately
 - "Configuration missing" errors
 
 **Solutions:**
 
 1. **Check Environment Variables**
+
    ```bash
    # Verify all required variables are set
    docker run --rm docdyhr/mcp-wordpress:latest env | grep WORDPRESS
-   
+
    # Should show:
    # WORDPRESS_SITE_URL=...
    # WORDPRESS_USERNAME=...
@@ -452,10 +490,11 @@ npm run cache:stats
    ```
 
 2. **Check Container Logs**
+
    ```bash
    # View container logs
    docker logs mcp-wordpress
-   
+
    # Follow logs in real-time
    docker logs -f mcp-wordpress
    ```
@@ -471,11 +510,13 @@ npm run cache:stats
 ### Enable Debug Mode
 
 1. **Environment Variable**
+
    ```bash
    DEBUG=true npm run dev
    ```
 
 2. **For Claude Desktop DXT**
+
    - Enable "Debug Mode" in extension settings
    - Check Claude Desktop console for detailed logs
 
@@ -522,8 +563,9 @@ tail -f /path/to/wordpress/wp-content/debug.log
 
 When reporting issues, include this information:
 
-```markdown
+````markdown
 ### Environment
+
 - **Installation Method**: DXT/NPX/NPM/Docker
 - **Version**: [Check with npm list mcp-wordpress]
 - **Node.js Version**: [node --version]
@@ -531,27 +573,33 @@ When reporting issues, include this information:
 - **Claude Desktop Version**: [If applicable]
 
 ### WordPress Details
+
 - **WordPress Version**: [Check in WP admin]
 - **User Role**: [Administrator/Editor/etc.]
 - **Authentication Method**: [app-password/jwt/basic]
 - **REST API URL**: [https://site.com/wp-json/wp/v2/]
 
 ### Issue Description
+
 - **What you were trying to do**:
 - **What happened instead**:
 - **Error messages** (exact text):
 - **Steps to reproduce**:
 
 ### Debug Information
+
 ```bash
 # Output of diagnostic commands
 npm run health
 npm run status
 DEBUG=true [command that failed]
 ```
+````
 
 ### Configuration
+
 [Include relevant configuration, redacting sensitive information]
+
 ```text
 
 ## 🆘 Getting Help
@@ -576,4 +624,5 @@ For enterprise users or complex integrations:
 
 ---
 
-**Still having issues?** [Open a GitHub issue](https://github.com/docdyhr/mcp-wordpress/issues/new) with the debugging information above, and we'll help you resolve it!
+**Still having issues?** [Open a GitHub issue](https://github.com/docdyhr/mcp-wordpress/issues/new) with the debugging information above, and we'll help you resolve it!
+```