mcphub/docs/troubleshooting.md

# 🔧 Troubleshooting Guide

---

## Table of Contents

1. [Common Errors](#common-errors)
2. [Connection Issues](#connection-issues)
3. [Authentication Problems](#authentication-problems)
4. [Rate Limiting Issues](#rate-limiting-issues)
5. [Docker Problems](#docker-problems)
6. [Performance Issues](#performance-issues)
7. [Tool Registration Issues](#tool-registration-issues)
8. [Logging and Debugging](#logging-and-debugging)
9. [Getting Help](#getting-help)

---

## Common Errors

### Error: "No module named 'fastmcp'"

**Cause**: Dependencies not installed or virtual environment not activated.

**Solution**:
```bash
# Activate virtual environment
source venv/bin/activate  # Linux/Mac
.\venv\Scripts\Activate.ps1  # Windows

# Install dependencies
pip install -r requirements.txt
```

### Error: "KeyError: 'WORDPRESS_SITE1_URL'"

**Cause**: Environment variables not configured.

**Solution**:
```bash
# Check if .env file exists
ls -la .env

# If not, create from template
cp .env.example .env

# Edit with your credentials
nano .env  # Linux/Mac
notepad .env  # Windows
```

### Error: "ModuleNotFoundError: No module named 'core'"

**Cause**: Running from wrong directory or Python path issue.

**Solution**:
```bash
# Make sure you're in project root
cd /path/to/mcphub

# Run the server directly
python server.py

# Or add to .env
echo "PYTHONPATH=." >> .env
```

---

## Connection Issues

### WordPress Site Not Accessible

**Symptoms**: `Connection timeout`, `Connection refused`, `Name or service not known`

**Diagnosis**:
```bash
# Test site accessibility
curl -I https://your-wordpress-site.com

# Check DNS resolution
nslocalhost your-wordpress-site.com

# Test with timeout
timeout 5 curl https://your-wordpress-site.com
```

**Solutions**:

1. **Check URL format**:
   ```bash
   # Correct
   WORDPRESS_SITE1_URL=https://example.com

   # Incorrect
   WORDPRESS_SITE1_URL=example.com  # Missing https://
   WORDPRESS_SITE1_URL=https://example.com/  # Extra trailing slash
   ```

2. **Verify HTTPS certificate**:
   ```bash
   curl -v https://your-site.com 2>&1 | grep SSL
   ```

3. **Check firewall rules**:
   - Ensure port 443 (HTTPS) is open
   - Check if IP is whitelisted (if using server firewall)

4. **Test from different network**:
   - Try from different IP address
   - Check if WordPress site blocks data center IPs

### WordPress REST API Not Available

**Symptoms**: `404 Not Found` on `/wp-json/`

**Diagnosis**:
```bash
curl https://your-site.com/wp-json/
```

**Solutions**:

1. **Check permalink settings**:
   - Go to: WordPress Admin → Settings → Permalinks
   - Select any option except "Plain"
   - Click "Save Changes"

2. **Check .htaccess**:
   ```apache
   # Must have these rules
   RewriteEngine On
   RewriteRule ^index\.php$ - [L]
   RewriteCond %{REQUEST_FILENAME} !-f
   RewriteCond %{REQUEST_FILENAME} !-d
   RewriteRule . /index.php [L]
   ```

3. **Check nginx configuration** (if using nginx):
   ```nginx
   location / {
       try_files $uri $uri/ /index.php?$args;
   }
   ```

---

## Authentication Problems

### Error: "Invalid username or password"

**Cause**: Application Password not configured correctly.

**Solution**:

1. **Verify Application Password is enabled**:
   - WordPress 5.6+ only
   - Go to: Users → Your Profile
   - Look for "Application Passwords" section

2. **Generate new Application Password**:
   ```
   Name: MCP Server
   Click: Add New Application Password
   Copy password (format: xxxx xxxx xxxx xxxx xxxx xxxx)
   ```

3. **Update .env file**:
   ```bash
   WORDPRESS_SITE1_APP_PASSWORD=xxxx xxxx xxxx xxxx xxxx xxxx
   ```

4. **Important notes**:
   - Include spaces in password
   - Password is one-time display only
   - Each application needs unique password

### Error: "Application Passwords not available"

**Cause**: WordPress version < 5.6 or disabled by plugin/filter.

**Solutions**:

1. **Update WordPress**:
   ```bash
   # Via WP-CLI
   wp core update
   ```

2. **Check if disabled by plugin/filter**:
   - Some security plugins disable Application Passwords
   - Check: Security Plugins → Settings → Application Passwords

3. **Enable via code** (add to `functions.php`):
   ```php
   // Remove filter that may disable it
   add_filter('wp_is_application_passwords_available', '__return_true');
   ```

### WooCommerce Authentication Failed

**Cause**: Invalid Consumer Key/Secret.

**Solution**:

1. **Regenerate API keys**:
   - WooCommerce → Settings → Advanced → REST API
   - Add Key
   - Permissions: Read/Write
   - Copy both Consumer Key and Consumer Secret

2. **Verify format in .env**:
   ```bash
   WORDPRESS_SITE1_WC_CONSUMER_KEY=ck_xxxxxxxxxxxxxxxxxxxx
   WORDPRESS_SITE1_WC_CONSUMER_SECRET=cs_xxxxxxxxxxxxxxxxxxxx
   ```

3. **Check permissions**:
   - User must have `manage_woocommerce` capability
   - Keys must be for admin user

---

## Rate Limiting Issues

### Error: "Rate limit exceeded"

**Symptoms**: HTTP 429, "Too many requests"

**Diagnosis**:
```bash
# Check rate limit stats
python -c "
from src.core.rate_limiter import RateLimiter
limiter = RateLimiter()
print(limiter.get_stats())
"
```

**Solutions**:

1. **Adjust rate limits** in `.env`:
   ```bash
   RATE_LIMIT_PER_MINUTE=120  # Increase from 60
   RATE_LIMIT_PER_HOUR=2000   # Increase from 1000
   RATE_LIMIT_PER_DAY=20000   # Increase from 10000
   ```

2. **Reset rate limiter**:
   ```bash
   # Via MCP tool
   reset_rate_limit()

   # Or restart server
   docker compose restart  # If using Docker
   ```

3. **Distribute requests**:
   - Add delays between bulk operations
   - Use batching for large operations

### Rate Limit Not Working

**Symptoms**: No rate limiting being applied.

**Solution**:

Check rate limiter initialization in logs:
```bash
grep "Rate limiter" logs/audit.log
```

Ensure rate limiter is enabled:
```python
# In .env
RATE_LIMITING_ENABLED=true
```

---

## Docker Problems

### Container Won't Start

**Symptoms**: `docker compose up` fails, container exits immediately.

**Diagnosis**:
```bash
# Check container logs
docker compose logs

# Check container exit code
docker compose ps -a
```

**Common Solutions**:

1. **Port already in use**:
   ```bash
   # Check what's using port 8000
   lsof -i :8000  # Linux/Mac
   netstat -ano | findstr :8000  # Windows

   # Change port in docker-compose.yml
   ports:
     - "8080:8000"  # Use 8080 instead
   ```

2. **Invalid environment variables**:
   ```bash
   # Validate .env file
   docker compose config
   ```

3. **Permission issues**:
   ```bash
   # Fix permissions
   sudo chown -R 1000:1000 logs/
   ```

### Container Running but Not Accessible

**Symptoms**: Container status shows "Up" but health check fails.

**Diagnosis**:
```bash
# Check container health
docker compose ps

# Test from inside container
docker compose exec mcp-server curl localhost:8000/health

# Check container network
docker compose exec mcp-server cat /etc/hosts
```

**Solutions**:

1. **Check binding address**:
   - Should bind to `0.0.0.0`, not `127.0.0.1`
   - Update `server.py` if needed

2. **Check firewall**:
   ```bash
   # Allow Docker network
   sudo ufw allow from 172.0.0.0/8
   ```

### High Memory Usage

**Symptoms**: Container using excessive RAM.

**Solutions**:

1. **Set memory limits** in `docker-compose.yml`:
   ```yaml
   services:
     mcp-server:
       deploy:
         resources:
           limits:
             memory: 512M
   ```

2. **Optimize logging**:
   ```bash
   # Reduce log level
   LOG_LEVEL=WARNING
   ```

3. **Clear cache**:
   ```bash
   docker system prune -a
   ```

---

## Performance Issues

### Slow Response Times

**Symptoms**: Tools taking > 5 seconds to respond.

**Diagnosis**:
```bash
# Check health metrics
python -c "
from core.health import HealthMonitor
monitor = HealthMonitor()
print(monitor.get_all_health())
"
```

**Solutions**:

1. **Check WordPress site performance**:
   ```bash
   # Test direct WordPress API
   time curl https://your-site.com/wp-json/wp/v2/posts
   ```

2. **Enable caching** on WordPress:
   - Install caching plugin (WP Super Cache, W3 Total Cache)
   - Enable object caching (Redis/Memcached)

3. **Optimize database**:
   ```bash
   # Use WP-CLI tool
   wordpress_wp_db_optimize(site="site1")
   ```

4. **Reduce payload size**:
   ```python
   # Request fewer items
   wordpress_list_posts(site="site1", per_page=10)  # Instead of 100
   ```

### High CPU Usage

**Symptoms**: Server using 100% CPU.

**Solutions**:

1. **Check for infinite loops** in logs:
   ```bash
   tail -f logs/audit.log | grep ERROR
   ```

2. **Limit concurrent requests**:
   ```bash
   # In .env
   MAX_CONCURRENT_REQUESTS=5
   ```

3. **Optimize queries**:
   - Use pagination
   - Filter results
   - Cache responses

---

## Tool Registration Issues

### Error: "Tool not found"

**Symptoms**: MCP reports tool doesn't exist.

**Diagnosis**:
```bash
# List all registered tools
python -c "
from server import mcp
tools = app.list_tools()
for tool in tools:
    print(tool['name'])
"
```

**Solutions**:

1. **Check site configuration**:
   ```bash
   # Ensure site is configured in .env
   grep "WORDPRESS_SITE1" .env
   ```

2. **Verify plugin loaded**:
   ```bash
   # Check logs for plugin initialization
   grep "plugin loaded" logs/audit.log
   ```

3. **Restart server**:
   ```bash
   # Tools are registered at startup
   docker compose restart
   ```

### Duplicate Tools

**Symptoms**: Same tool name registered multiple times.

**Cause**: Multiple plugins or sites with same alias.

**Solution**:

1. **Check for duplicate aliases**:
   ```bash
   grep "ALIAS" .env | sort
   ```

2. **Ensure unique aliases**:
   ```bash
   WORDPRESS_SITE1_ALIAS=mainsite
   WORDPRESS_SITE2_ALIAS=shop  # Not mainsite
   ```

---

## Logging and Debugging

### Enable Debug Logging

```bash
# In .env
LOG_LEVEL=DEBUG

# Restart server
docker compose restart
```

### View Real-time Logs

```bash
# Audit logs
tail -f logs/audit.log

# Application logs
docker compose logs -f

# Filter for errors
grep ERROR logs/audit.log

# Filter for specific site
grep "site1" logs/audit.log
```

### Common Log Patterns

**Successful request**:
```json
{
  "timestamp": "2025-11-11T10:30:00Z",
  "event_type": "tool_execution",
  "level": "INFO",
  "event": "wordpress_list_posts",
  "details": {
    "site": "site1",
    "status": "success"
  }
}
```

**Failed request**:
```json
{
  "timestamp": "2025-11-11T10:30:00Z",
  "event_type": "tool_execution",
  "level": "ERROR",
  "event": "wordpress_list_posts",
  "details": {
    "site": "site1",
    "error": "Connection timeout",
    "status": "failed"
  }
}
```

### Debugging Tips

1. **Test with curl**:
   ```bash
   # Test WordPress directly
   curl -u "admin:xxxx xxxx xxxx xxxx xxxx xxxx" \
     https://your-site.com/wp-json/wp/v2/posts
   ```

2. **Check environment loading**:
   ```python
   python -c "
   from dotenv import load_dotenv
   import os
   load_dotenv()
   print(os.getenv('WORDPRESS_SITE1_URL'))
   "
   ```

3. **Test individual components**:
   ```bash
   # Test WordPress plugin
   pytest tests/test_wordpress_plugin.py -v

   # Test rate limiter
   pytest tests/test_rate_limiter.py -v
   ```

---

## Getting Help

### Before Asking for Help

1. **Check logs**:
   ```bash
   tail -50 logs/audit.log
   ```

2. **Run health check**:
   ```bash
   python -c "
   from core.health import HealthMonitor
   monitor = HealthMonitor()
   print(monitor.check_all_projects())
   "
   ```

3. **Verify configuration**:
   ```bash
   # Mask sensitive data
   grep -v "PASSWORD\|KEY\|SECRET" .env
   ```

4. **Test connectivity**:
   ```bash
   curl -I https://your-wordpress-site.com
   ```

### What to Include in Bug Reports

1. **Environment information**:
   - Python version: `python --version`
   - Docker version: `docker --version`
   - OS: `uname -a` (Linux/Mac) or `systeminfo` (Windows)

2. **Error messages**:
   - Full error output
   - Stack trace if available
   - Relevant log entries

3. **Configuration** (mask sensitive data):
   - Relevant .env variables
   - docker-compose.yml modifications
   - WordPress/WooCommerce versions

4. **Steps to reproduce**:
   - Exact commands run
   - Expected vs actual behavior
   - Frequency (always, sometimes, once)

### Contact Information

**Email**: hello@mcphub.dev

**Subject format**: `[BUG] Brief description`

**Example**:
```
Subject: [BUG] wordpress_list_posts returns 403 error

Environment:
- Python 3.11.5
- Docker 24.0.6
- WordPress 6.4
- Ubuntu 22.04

Issue:
wordpress_list_posts(site="site1") returns 403 Forbidden

Steps to reproduce:
1. Configure WORDPRESS_SITE1_* in .env
2. Run python server.py
3. Call wordpress_list_posts(site="site1", per_page=10)
4. Receive 403 error

Logs:
[Include relevant log entries]

Configuration:
WORDPRESS_SITE1_URL=https://example.com
WORDPRESS_SITE1_USERNAME=admin
[Application password masked]
```

---

---