mcp-wordpress 1.5.2 → 2.0.0

package/docs/TROUBLESHOOTING.md

@@ -0,0 +1,578 @@
+# Troubleshooting Guide
+
+Comprehensive troubleshooting guide for common issues with MCP WordPress Server.
+
+## 🔍 Quick Diagnosis
+
+### Health Check Commands
+
+Before diving into specific issues, run these diagnostic commands:
+
+```bash
+# Overall system health
+npm run health
+
+# Connection status
+npm run status
+
+# Test authentication
+npm run test:auth
+
+# Quick tool validation
+npm run test:tools
+
+# Performance check
+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 |
+| **[Claude Desktop](#️-claude-desktop-issues)** | Not appearing in Claude | Restart and reconfigure |
+
+## 🌐 Connection Issues
+
+### 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/
+
+# Should return HTTP 200 with JSON data
+# If not, WordPress REST API may be disabled
+```
+
+**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
+   ```
+
+4. **WordPress Configuration**
+   ```php
+   // In wp-config.php, ensure REST API is enabled
+   // Remove or comment out if present:
+   // add_filter('rest_enabled', '__return_false');
+   ```
+
+### Issue: "SSL Certificate Error"
+
+**Symptoms:**
+- SSL verification failures
+- Certificate warnings
+
+**Solutions:**
+```bash
+# For development only - disable SSL verification
+export NODE_TLS_REJECT_UNAUTHORIZED=0
+
+# Better solution: Fix SSL certificate
+# Contact your hosting provider or use Let's Encrypt
+```
+
+## 🔐 Authentication Issues
+
+### 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
+
+# Should return user information
+# If 401, credentials are wrong
+```
+
+**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
+   WORDPRESS_APP_PASSWORD="AbCd-EfGh-IjKl..."       # Hyphens instead of spaces
+   ```
+
+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
+   - Create/edit posts: Author
+   - Manage comments: Editor
+   - Site settings: Administrator
+   ```
+
+4. **Verify Application Passwords are Enabled**
+   ```php
+   // In functions.php or plugin
+   // Ensure this is NOT present:
+   // add_filter('wp_is_application_passwords_available', '__return_false');
+   ```
+
+### 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" \
+     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 | ❌ | ❌ | ❌ | ✅ |
+
+## 🛠️ 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
+
+# Test specific tool
+DEBUG=true npm run dev
+# Then try the failing tool
+```
+
+**Solutions:**
+
+1. **Verify Tool Registration**
+   ```bash
+   # Check all tools are loaded
+   npm run status | grep "tools available"
+   # Should show "59 tools available"
+   ```
+
+2. **Test Individual Tool Categories**
+   ```text
+   # In Claude, test each category:
+   "List my WordPress posts"          # Posts tools
+   "Show my WordPress users"          # User tools
+   "Check WordPress site settings"    # Site tools
+   "Show cache statistics"            # Cache tools
+   ```
+
+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
+   ```
+
+### 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
+   ```
+
+2. **Required vs Optional Parameters**
+   ```bash
+   # Check tool documentation
+   # Each tool specifies required parameters
+   # See docs/api/tools/[tool-name].md
+   ```
+
+## ⚡ Performance Issues
+
+### 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
+
+# Test with caching disabled
+DISABLE_CACHE=true npm run dev
+
+# Monitor cache statistics
+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
+   ```
+
+### Issue: Memory or CPU high usage
+
+**Symptoms:**
+- System becomes slow
+- High resource usage
+- Crashes or restarts
+
+**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
+   ```
+
+## 🖥️ Claude Desktop Issues
+
+### 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
+
+**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
+   {
+     "mcpServers": {
+       "mcp-wordpress": {
+         "command": "npx",
+         "args": ["-y", "mcp-wordpress"],
+         "env": {
+           "WORDPRESS_SITE_URL": "https://your-site.com",
+           "WORDPRESS_USERNAME": "your-username",
+           "WORDPRESS_APP_PASSWORD": "your-app-password"
+         }
+       }
+     }
+   }
+   ```
+
+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
+   ```
+
+### 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/raw/main/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
+   ```
+
+## 🐳 Docker Issues
+
+### 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=...
+   # WORDPRESS_APP_PASSWORD=...
+   ```
+
+2. **Check Container Logs**
+   ```bash
+   # View container logs
+   docker logs mcp-wordpress
+   
+   # Follow logs in real-time
+   docker logs -f mcp-wordpress
+   ```
+
+3. **Test Configuration**
+   ```bash
+   # Test with environment file
+   docker run --rm --env-file .env docdyhr/mcp-wordpress:latest npm run status
+   ```
+
+## 🔧 Advanced Debugging
+
+### 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
+
+3. **Comprehensive Debugging**
+   ```bash
+   # Maximum debug output
+   NODE_ENV=development DEBUG=true LOG_LEVEL=debug npm run dev
+   ```
+
+### Debug Specific Components
+
+```bash
+# Test individual components
+npm run test:auth          # Authentication only
+npm run test:tools         # Tool registration
+npm run test:integration   # WordPress API integration
+npm run test:cache         # Cache functionality
+npm run test:performance   # Performance monitoring
+```
+
+### Network Debugging
+
+```bash
+# Capture network traffic
+tcpdump -i any -w capture.pcap host your-site.com
+
+# Analyze with Wireshark or:
+tcpdump -r capture.pcap -A | grep -i wordpress
+```
+
+### WordPress Debug Mode
+
+```php
+// Add to wp-config.php for WordPress debugging
+define('WP_DEBUG', true);
+define('WP_DEBUG_LOG', true);
+define('WP_DEBUG_DISPLAY', false);
+
+// Check WordPress debug log
+tail -f /path/to/wordpress/wp-content/debug.log
+```
+
+## 📋 Issue Reporting Template
+
+When reporting issues, include this information:
+
+```markdown
+### Environment
+- **Installation Method**: DXT/NPX/NPM/Docker
+- **Version**: [Check with npm list mcp-wordpress]
+- **Node.js Version**: [node --version]
+- **Operating System**: [OS and version]
+- **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
+
+### Self-Help Resources
+
+1. **[Documentation Hub](README.md)** - Complete documentation
+2. **[API Reference](api/README.md)** - Tool documentation
+3. **[GitHub Issues](https://github.com/docdyhr/mcp-wordpress/issues)** - Known issues and solutions
+
+### Community Support
+
+1. **[GitHub Discussions](https://github.com/docdyhr/mcp-wordpress/discussions)** - Community Q&A
+2. **[Issue Tracker](https://github.com/docdyhr/mcp-wordpress/issues/new)** - Bug reports
+
+### Professional Support
+
+For enterprise users or complex integrations:
+- Priority support available
+- Custom configuration assistance
+- Integration consulting
+
+---
+
+**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!