mcphub/plugins/wordpress_advanced

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:

# 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

# 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

# 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

# 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

# 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

# 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)

# 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)

# 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)

# 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:

# 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:

# 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)

# All features in one plugin
WORDPRESS_SITE1_CONTAINER=coolify-wp1

# All 117 tools visible to everyone

After (Phase D - Split Plugins)

# 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
• Documentation: docs/
• Main README: ../../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