Pro Extended (PE)

Extends Pro Theme and Cornerstone page builder with an MCP Server, developer tools, and CLI commands — enabling AI agents to read, create, and manage Cornerstone layouts programmatically.

---

What is this?

Pro Extended connects your WordPress site (running Pro Theme / Cornerstone) to AI assistants like Claude, ChatGPT, Gemini, and others via the Model Context Protocol (MCP).

In practice, this means you can ask your AI assistant to:

• 📄 Create pages with full Cornerstone layouts
• 🎨 Read and modify existing layouts, headers, footers, and global blocks
• 🔍 Inspect element schemas, colors, fonts, and site configuration
• 💾 Backup and restore layouts with zero risk of data loss

No coding experience required — if you can install a WordPress plugin and follow a few configuration steps, you're ready to go.

---

Quick Start

Requirements

• WordPress 6.5+
• Pro Theme 6.x+ (or a child theme of Pro)
• PHP 8.1+

Installation

Option A — Upload via WordPress Admin (easiest)

1. Download the latest release as a .zip file.
2. In your WordPress admin, go to Plugins → Add New Plugin → Upload Plugin.
3. Select the downloaded .zip file and click Install Now.
4. After installation, click Activate Plugin.

That's it — no terminal, no extra steps. The plugin includes a built-in autoloader.

Option B — Git Clone (for developers)

# Clone into your plugins directory
cd wp-content/plugins/
git clone https://github.com/renandadalte/wpdev-pro-extended.git

# Activate via WP-CLI
wp plugin activate wpdev-pro-extended

Connecting an MCP Client

To allow your AI assistant to interact with your WordPress site, you need two things:

1. An Application Password — Go to your WordPress admin → Users → Your Profile → scroll down to Application Passwords. Enter a name (e.g., "MCP") and click Add New Application Password. Copy the generated password.

2. A Base64-encoded credential string — The MCP server uses HTTP Basic Authentication. You need to encode your username:password pair in Base64.

   How to generate your Base64 string:

   # macOS / Linux:
   echo -n "your_wp_username:xxxx xxxx xxxx xxxx xxxx xxxx" | base64

   # Windows (PowerShell):
   [Convert]::ToBase64String([Text.Encoding]::UTF8.GetBytes("your_wp_username:xxxx xxxx xxxx xxxx xxxx xxxx"))

   Or use any online Base64 encoder — just encode the string your_wp_username:your_application_password (with the colon separator).

3. Add the server to your IDE's MCP configuration:

   Antigravity (Google Gemini)

   Edit ~/.gemini/antigravity/mcp_config.json:

   {
     "mcpServers": {
       "pro-extended": {
         "serverUrl": "https://your-site.com/wp-json/pro-extended/v1/mcp",
         "headers": {
           "Authorization": "Basic YOUR_BASE64_STRING_HERE"
         }
       }
     }
   }

   Note: Antigravity uses serverUrl (camelCase) instead of url.

   Cursor

   Edit .cursor/mcp.json in your project root (or global settings):

   {
     "mcpServers": {
       "pro-extended": {
         "url": "https://your-site.com/wp-json/pro-extended/v1/mcp",
         "headers": {
           "Authorization": "Basic YOUR_BASE64_STRING_HERE"
         }
       }
     }
   }

   Claude Desktop

   Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

   {
     "mcpServers": {
       "pro-extended": {
         "url": "https://your-site.com/wp-json/pro-extended/v1/mcp",
         "headers": {
           "Authorization": "Basic YOUR_BASE64_STRING_HERE"
         }
       }
     }
   }

   VS Code (GitHub Copilot / Other MCP Clients)

   Edit .vscode/mcp.json in your project root:

   {
     "servers": {
       "pro-extended": {
         "url": "https://your-site.com/wp-json/pro-extended/v1/mcp",
         "headers": {
           "Authorization": "Basic YOUR_BASE64_STRING_HERE"
         }
       }
     }
   }

   Note: VS Code uses servers instead of mcpServers as the root key.

Important

Replace YOUR_BASE64_STRING_HERE with the Base64-encoded string you generated in step 2. Do not paste your username and password directly — it must be the Base64-encoded version.

4. Restart your IDE. Your AI agent can now list elements, read layouts, create pages, and more.

WP-CLI Usage

wp pe mcp test                                          # Verify MCP server
wp pe mcp tools                                         # List all 14 tools
wp pe mcp call get_site_info --user=1                   # Call any tool
wp pe layout list                                       # List all layouts
wp pe layout export 42 --output=homepage.json           # Export layout to JSON
wp pe layout backup 42                                  # Create backup
wp pe layout restore 42                                 # Restore from backup

---

Capabilities

MCP Tools (14)

Tool	Type	Description
list_elements	Read	List all Cornerstone element types with groups and valid children
get_element_schema	Read	Get full schema for a specific element type (properties, defaults, options)
list_layouts	Read	List all layouts (pages, headers, footers, global blocks, etc.)
get_layout	Read	Get complete layout JSON with metadata and checksum
validate_layout	Read	Validate layout structure against element schema and hierarchy rules
list_colors	Read	Get the Cornerstone global color palette
list_fonts	Read	Get registered font definitions and configuration
get_site_info	Read	Get WordPress, theme, Cornerstone versions and breakpoint config
create_page	Write	Create a new page with optional Cornerstone layout data
deploy_layout	Write	Write layout data to a post (auto-backup + validation)
backup_layout	Write	Create a timestamped backup (up to 10 per post)
restore_layout	Write	Restore from a backup
clear_cache	Write	Clear Cornerstone TSS cache (per-post or global)
update_layout	Write	Apply patch operations (add/remove/update elements)

MCP Resources (3)

URI	Description
pe://schema/elements	Full element definitions (cached)
pe://schema/hierarchy	Valid parent-child relationship map
pe://colors/palette	Current color palette

WP-CLI Commands

Command	Description
wp pe layout list	List all Cornerstone layouts
wp pe layout export <id>	Export layout to JSON file
wp pe layout import <file>	Import layout from JSON file
wp pe layout backup <id>	Create layout backup
wp pe layout restore <id>	Restore layout from backup
wp pe mcp test	Verify MCP server is operational
wp pe mcp tools	List registered MCP tools
wp pe mcp call <tool>	Call a tool directly

---

Architecture

Plugin Structure

wpdev-pro-extended/
├── wpdev-pro-extended.php       # Bootstrap, Pro Theme dependency guard, PSR-4 autoloader
└── src/
    ├── Plugin.php               # Service container (lazy-loaded)
    ├── Layouts/
    │   └── LayoutService.php    # Read/write/backup/restore for 3 storage formats
    ├── Elements/
    │   ├── SchemaExtractor.php  # Wraps cornerstone('Elements') with transient cache
    │   ├── HierarchyValidator.php  # Layout validation engine
    │   └── ValidationResult.php
    ├── Mcp/
    │   ├── Server.php           # JSON-RPC 2.0 router
    │   ├── Transport/
    │   │   └── StreamableHttp.php  # REST API endpoint (POST)
    │   ├── Tools/               # 14 tool implementations
    │   │   ├── ToolInterface.php
    │   │   ├── ListElements.php
    │   │   ├── GetElementSchema.php
    │   │   ├── ...
    │   │   └── UpdateLayout.php
    │   └── Resources/           # 3 resource implementations
    │       ├── ResourceInterface.php
    │       ├── ElementSchemaResource.php
    │       ├── HierarchyResource.php
    │       └── ColorPaletteResource.php
    └── Commands/
        ├── LayoutCommand.php    # wp pe layout *
        └── McpCommand.php       # wp pe mcp *

MCP Protocol

The server implements MCP 2025-03-26 via Streamable HTTP transport:

• Endpoint: POST /wp-json/pro-extended/v1/mcp
• Protocol: JSON-RPC 2.0
• Authentication: WordPress Application Passwords (Basic Auth)
• Capability checks: Per-tool (edit_posts for reads, manage_options for writes)

Cornerstone Data Handling

The plugin handles all three Cornerstone storage formats:

Post Type	Storage	Format
page, post	_cornerstone_data meta	Inline tree (nested _modules)
cs_header, cs_footer, cs_layout_*	post_content	Inline tree with regions
cs_global_block	post_content	Flat map (keyed by _id)

Critical safety patterns applied:

• wp_slash(wp_json_encode($data)) before update_post_meta() — prevents WordPress from corrupting JSON escaping
• $wpdb for raw backups — preserves exact byte-level encoding
• _bp_data validation — ensures breakpoint arrays are sequential (5-element, null-padded) to prevent TypeError: t[i] is not iterable in Cornerstone's React app

Security

• All endpoints require WordPress authentication (Application Passwords)
• Read tools require edit_posts capability
• Write tools require manage_options capability
• Input validation on all tool parameters
• Layout structure validation before writes
• Auto-backup before destructive operations
• Zero external dependencies — portable, no supply chain risk

---

Roadmap

✅ v1.0.0-alpha (Current)

• MCP Server with Streamable HTTP transport
• 14 tools (8 read + 6 write) for element/layout management
• 3 MCP resources for schema and palette data
• WP-CLI commands for layout management and MCP testing
• Layout backup/restore system
• Hierarchy and breakpoint data validation

🔜 v1.1 — Design Tokens & Settings Sync

• Design Token System: Centralized token registry, CSS custom property output, admin UI
• Settings Sync: ACF-style JSON export/import for version-controlled settings
• MCP rate limiting: Transient-based request throttling

🔮 v1.2 — Extended Features

• Element Defaults Manager: Admin UI for setting default values for Cornerstone elements
• Color Audit & Replace: CLI tool to find and replace hardcoded colors with global palette references
• Layout Versioning: Git-friendly JSON export with diff support

---

Support

If you find this project useful, consider supporting its development:

---

Contributing

1. Fork the repository
2. Create your feature branch (git checkout -b feature/my-feature)
3. Commit your changes (git commit -m 'feat: add my feature')
4. Push to the branch (git push origin feature/my-feature)
5. Open a Pull Request

Please follow Conventional Commits for commit messages.

---

License

This project is licensed under the GPL-2.0-or-later license.