Initial commit: MCP Hub Community Edition v3.0.0
Community edition generated from private repo via sync pipeline. Includes 9 plugins (WordPress, WooCommerce, WP Advanced, Gitea, n8n, Supabase, OpenPanel, Appwrite, Directus) with ~587 tools. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
airano
676
docs/troubleshooting.md
Normal file
676
docs/troubleshooting.md
Normal file
@@ -0,0 +1,676 @@
|
||||
# 🔧 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]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
---
|
||||
Reference in New Issue
Block a user