mcphub/plugins/wordpress_advanced/README.md

# WordPress Advanced Plugin

> **Advanced WordPress management features requiring elevated permissions**

## Overview

The WordPress Advanced plugin provides 22 powerful tools for advanced WordPress management, separated from the core WordPress plugin for better security and tool visibility.

### Why Separated?

**Phase D (WordPress Advanced Split)** separates advanced management features into their own plugin for:

1. **Better Security** 🔒
   - Separate API keys for basic vs advanced operations
   - Advanced operations require explicit permission
   - Reduces risk of accidental database modifications

2. **Better Tool Visibility** 👁️
   - Basic users see only 95 WordPress tools (not 117)
   - Advanced users explicitly enable advanced features
   - Cleaner tool list for most users

3. **Granular Access Control** 🎯
   - Per-project API keys can grant access to:
     - WordPress Core only (95 tools)
     - WordPress Advanced only (22 tools)
     - Both (117 tools total)

## Features

### 22 Advanced Tools

#### Database Operations (7 tools)
- `wp_db_export` - Export WordPress database to SQL file
- `wp_db_import` - Import SQL file to WordPress database
- `wp_db_size` - Get database size and table information
- `wp_db_tables` - List all database tables with sizes
- `wp_db_search` - Search database for specific content
- `wp_db_query` - Execute read-only SQL queries
- `wp_db_repair` - Repair and optimize database tables

#### Bulk Operations (8 tools)
- `bulk_update_posts` - Update multiple posts in parallel (max 100)
- `bulk_delete_posts` - Delete multiple posts in parallel (max 100)
- `bulk_update_products` - Update multiple products in parallel (max 100)
- `bulk_delete_products` - Delete multiple products in parallel (max 100)
- `bulk_delete_media` - Delete multiple media files in parallel (max 100)
- `bulk_assign_categories` - Assign categories to multiple posts
- `bulk_assign_tags` - Assign tags to multiple posts
- `bulk_trash_posts` - Move multiple posts to trash

#### System Operations (7 tools)
- `system_info` - Get WordPress system information (PHP, MySQL, server)
- `system_phpinfo` - Get detailed PHP configuration
- `system_disk_usage` - Get disk usage for WordPress installation
- `system_clear_all_caches` - Clear all WordPress caches
- `cron_list` - List all WordPress cron jobs
- `cron_run` - Run specific cron job immediately
- `error_log` - Get WordPress error log

## Requirements

### Core Requirements
- WordPress site with REST API enabled
- WordPress application password
- **Docker container name** (for WP-CLI access) - REQUIRED!

### WP-CLI Access
All WordPress Advanced features require WP-CLI access through Docker:

```bash
# The MCP server must have access to:
/var/run/docker.sock  # Docker socket

# And the WordPress container must be accessible:
docker exec <container_name> wp --version
```

## Configuration

### Environment Variables

```bash
# WordPress Advanced Site 1
WORDPRESS_ADVANCED_SITE1_URL=https://example.com
WORDPRESS_ADVANCED_SITE1_USERNAME=admin
WORDPRESS_ADVANCED_SITE1_APP_PASSWORD=xxxx xxxx xxxx xxxx xxxx xxxx
WORDPRESS_ADVANCED_SITE1_ALIAS=myblog           # Optional: friendly name
WORDPRESS_ADVANCED_SITE1_CONTAINER=coolify-wp1  # REQUIRED: Docker container name
```

### Finding Container Name

```bash
# List all WordPress containers:
docker ps --filter "name=wordpress" --format "{{.Names}}"

# Test WP-CLI access:
docker exec <container_name> wp --info
```

## Usage Examples

### Database Operations

```python
# Export database
result = await mcp.call_tool("wordpress_advanced_wp_db_export", {
    "site": "myblog",
    "output_file": "/backup/db-backup.sql"
})

# Get database size
result = await mcp.call_tool("wordpress_advanced_wp_db_size", {
    "site": "myblog"
})

# Search database
result = await mcp.call_tool("wordpress_advanced_wp_db_search", {
    "site": "myblog",
    "search_term": "old-domain.com",
    "tables": ["wp_posts", "wp_options"]
})

# Execute read-only query
result = await mcp.call_tool("wordpress_advanced_wp_db_query", {
    "site": "myblog",
    "query": "SELECT COUNT(*) as total FROM wp_posts WHERE post_status='publish'"
})
```

### Bulk Operations

```python
# Bulk update posts
result = await mcp.call_tool("wordpress_advanced_bulk_update_posts", {
    "site": "myblog",
    "post_ids": [1, 2, 3, 4, 5],
    "updates": {
        "status": "draft",
        "author": 2
    }
})

# Bulk delete products
result = await mcp.call_tool("wordpress_advanced_bulk_delete_products", {
    "site": "mystore",
    "product_ids": [100, 101, 102],
    "force": False  # Move to trash instead of permanent delete
})

# Bulk assign categories
result = await mcp.call_tool("wordpress_advanced_bulk_assign_categories", {
    "site": "myblog",
    "post_ids": [10, 11, 12],
    "category_ids": [5, 6]
})
```

### System Operations

```python
# Get system information
result = await mcp.call_tool("wordpress_advanced_system_info", {
    "site": "myblog"
})

# Clear all caches
result = await mcp.call_tool("wordpress_advanced_system_clear_all_caches", {
    "site": "myblog"
})

# List cron jobs
result = await mcp.call_tool("wordpress_advanced_cron_list", {
    "site": "myblog"
})

# Get error log
result = await mcp.call_tool("wordpress_advanced_error_log", {
    "site": "myblog",
    "lines": 100
})
```

## Tool Count

```
WordPress Core Plugin:        95 tools  ✅ (basic features)
WordPress Advanced Plugin:    22 tools  🔒 (advanced features)
─────────────────────────────────────────────────
Total (if both enabled):     117 tools
```

## API Key Configuration

### Option 1: WordPress Core Only (Basic Users)
```bash
# Create API key with wordpress scope only
# User gets: 95 WordPress tools
# User does NOT see: WordPress Advanced tools
```

### Option 2: WordPress Advanced Only (Power Users)
```bash
# Create API key with wordpress_advanced scope only
# User gets: 22 WordPress Advanced tools
# User does NOT see: WordPress Core tools
```

### Option 3: Both Plugins (Admin Users)
```bash
# Create API key with both scopes
# User gets: 117 total tools (95 + 22)
```

## Security Considerations

### Database Operations
- **wp_db_export**: Exports contain sensitive data - secure storage required
- **wp_db_import**: Can overwrite entire database - use with extreme caution
- **wp_db_query**: Read-only enforced - write queries are rejected
- **wp_db_search**: May expose sensitive information in results

### Bulk Operations
- **Parallel Execution**: Max 10 concurrent operations (controlled by semaphore)
- **Batch Limits**: Maximum 100 items per bulk operation
- **Error Handling**: Returns success/failure status for each item
- **Reversibility**: Most operations support trash (soft delete) before permanent deletion

### System Operations
- **system_clear_all_caches**: May cause temporary performance impact
- **cron_run**: Can trigger resource-intensive operations
- **error_log**: May contain sensitive information (paths, credentials)

## Troubleshooting

### "WP-CLI not available" Error

**Cause**: Container not configured or Docker socket not mounted

**Solution**:
```bash
# 1. Check container name
docker ps | grep wordpress

# 2. Test WP-CLI access
docker exec <container_name> wp --info

# 3. Verify Docker socket in docker-compose.yaml
volumes:
  - /var/run/docker.sock:/var/run/docker.sock:ro
```

### "Database handler not available" Error

**Cause**: WP-CLI not configured (container name missing)

**Solution**:
```bash
# Ensure CONTAINER is set in environment variables
WORDPRESS_ADVANCED_SITE1_CONTAINER=your-container-name
```

### "Bulk operation failed" Error

**Cause**: Too many items or invalid IDs

**Solution**:
- Reduce batch size (max 100 items)
- Verify all IDs exist
- Check error details in response for specific failures

## Architecture

```
plugins/wordpress_advanced/
├── __init__.py                  # Plugin exports
├── plugin.py                    # WordPressAdvancedPlugin class
├── README.md                    # This file
│
├── schemas/                     # Pydantic validation models
│   ├── __init__.py
│   ├── database.py             # Database operation schemas
│   ├── bulk.py                 # Bulk operation schemas
│   └── system.py               # System operation schemas
│
└── handlers/                    # Tool implementations
    ├── __init__.py
    ├── database.py             # Database operations (7 tools)
    ├── bulk.py                 # Bulk operations (8 tools)
    └── system.py               # System operations (7 tools)
```

## Migration from WordPress Core

If you previously used WordPress Phase 5 features (database, bulk, system operations):

### Before (Phase 5 - Single Plugin)
```bash
# All features in one plugin
WORDPRESS_SITE1_CONTAINER=coolify-wp1

# All 117 tools visible to everyone
```

### After (Phase D - Split Plugins)
```bash
# Basic WordPress (95 tools)
WORDPRESS_SITE1_URL=...
WORDPRESS_SITE1_USERNAME=...
WORDPRESS_SITE1_APP_PASSWORD=...

# Advanced WordPress (22 tools) - separate configuration
WORDPRESS_ADVANCED_SITE1_URL=...
WORDPRESS_ADVANCED_SITE1_USERNAME=...
WORDPRESS_ADVANCED_SITE1_APP_PASSWORD=...
WORDPRESS_ADVANCED_SITE1_CONTAINER=coolify-wp1  # REQUIRED

# API Keys can now control access separately
```

### Tool Name Changes

Tool names now include `wordpress_advanced_` prefix:

| Before (Phase 5)      | After (Phase D)                       |
|-----------------------|---------------------------------------|
| `wp_db_export`        | `wordpress_advanced_wp_db_export`     |
| `bulk_update_posts`   | `wordpress_advanced_bulk_update_posts`|
| `system_info`         | `wordpress_advanced_system_info`      |

## Performance

### Bulk Operations
- **Parallel Execution**: Up to 10 concurrent operations
- **Semaphore Control**: Prevents server overload
- **Progress Tracking**: Per-item success/failure status
- **Recommended Batch Size**: 10-50 items for optimal performance

### Database Operations
- **Export**: Time depends on database size (1GB ≈ 30-60 seconds)
- **Import**: Slightly slower than export due to indexing
- **Search**: Full-text search across specified tables
- **Query**: Fast read-only queries with result limits

### System Operations
- **Cache Clear**: 1-5 seconds depending on cache size
- **Cron Jobs**: Immediate execution, duration depends on job
- **System Info**: Near-instant (<1 second)

## Best Practices

1. **Use Separate API Keys**: Create different keys for basic and advanced operations
2. **Batch Size**: Keep bulk operations under 50 items for optimal performance
3. **Database Backups**: Always backup before using wp_db_import
4. **Cron Jobs**: Test cron jobs in staging environment first
5. **Error Logs**: Regularly check error logs for security issues
6. **Disk Usage**: Monitor disk usage before large export operations

## Support

For issues, feature requests, or contributions:
- GitHub Issues: [mcphub/issues](https://github.com/airano-ir/mcphub/issues)
- Documentation: [docs/](../../docs/)
- Main README: [../../README.md](../../README.md)

## License

Same as main project license.

---

**Part of MCP Hub** - Phase D (WordPress Advanced Split)
**Version**: 1.0.0
**Last Updated**: 2025-11-18