Ultimate Elementor MCP

# 🔄 Migration Guide - Moving to Ultimate Elementor MCP Guide for users migrating from the original WordPress Elementor MCP or Elementor MCP. --- ## 📋 **Table of Contents** - [Why Migrate?](#why-migrate) - [Migration from wp-elementor-mcp](#migration-from-wp-elementor-mcp) - [Migration from Elementor-MCP](#migration-from-elementor-mcp) - [Tool Name Changes](#tool-name-changes) - [Configuration Changes](#configuration-changes) - [Breaking Changes](#breaking-changes) - [Step-by-Step Migration](#step-by-step-migration) --- ## 🎯 **Why Migrate?** ### **Ultimate Elementor MCP Advantages** | Feature | Original MCPs | Ultimate MCP | |---------|---------------|--------------| | **Total Tools** | 7-34 tools | **60 tools** | | **Configuration Modes** | 1-4 modes | **4 modes** with better organization | | **Error Handling** | Basic | **Advanced** with recovery and suggestions | | **File Operations** | Limited or none | **8 comprehensive tools** | | **Security** | Basic | **Enterprise-grade** validation | | **Testing** | Minimal | **105 tests** with integration coverage | | **Documentation** | Basic | **Comprehensive** multi-guide system | | **TypeScript** | Partial | **100% TypeScript** coverage | | **Debugging** | Basic logging | **5 debugging tools** with statistics | ### **What You Get** ✅ **All tools** from both original MCPs ✅ **19 additional tools** for enhanced functionality ✅ **Better error messages** and recovery ✅ **Comprehensive documentation** ✅ **Production-ready** reliability ✅ **Easy setup** for all MCP clients --- ## 🔄 **Migration from wp-elementor-mcp** ### **Good News: 100% Compatible!** If you're using **wp-elementor-mcp-main**, the Ultimate Elementor MCP is a **drop-in replacement** with the same tools and more! ### **Configuration Changes** **Old (wp-elementor-mcp):** ```env ELEMENTOR_MINIMAL_MODE=true ELEMENTOR_MCP_MODE=advanced ELEMENTOR_ENABLE_ALL=true ``` **New (Ultimate MCP):** ```env MCP_MODE=full # Simpler, clearer # Or use the same old variables (they still work!): ELEMENTOR_MCP_MODE=advanced ELEMENTOR_ENABLE_ALL=true ``` ### **Tool Names: No Changes** All tool names remain the same: - ✅ `get_posts`, `create_page`, `update_elementor_data`, etc. - ✅ All 34 tools from wp-elementor-mcp work identically - ✅ **Plus 26 new tools!** ### **Environment Variables** **Old:** ```env WORDPRESS_URL=https://site.com ``` **New:** ```env WORDPRESS_BASE_URL=https://site.com # Or both work: WORDPRESS_URL=https://site.com ``` ### **MCP Client Configuration** **Old:** ```json { "mcpServers": { "wp-elementor-mcp": { "command": "npx", "args": ["wp-elementor-mcp"] } } } ``` **New:** ```json { "mcpServers": { "ultimate-elementor-mcp": { "command": "node", "args": ["/path/to/ultimate-elementor-mcp/dist/index.js"], "env": { "WORDPRESS_BASE_URL": "https://your-site.com", "WORDPRESS_USERNAME": "your-username", "WORDPRESS_APPLICATION_PASSWORD": "your-app-password", "MCP_MODE": "full" } } } } ``` **Benefits:** - ✅ No need for `npx` (faster startup) - ✅ Direct control over configuration - ✅ Better error messages - ✅ All 60 tools available --- ## 🔄 **Migration from Elementor-MCP** ### **Tool Name Mapping** The Elementor-MCP tools are **all included** with the same names: | Original Tool | Ultimate MCP Tool | Status | |--------------|-------------------|--------| | `create_page` | `create_page` | ✅ Same | | `get_page` | `get_page` | ✅ Enhanced | | `update_page` | `update_page` | ✅ Enhanced | | `delete_page` | `delete_page` | ✅ Same | | `download_page_to_file` | `export_elementor_data` | ⚠️ Name change | | `update_page_from_file` | `import_elementor_data` | ⚠️ Name change | | `get_page_id_by_slug` | Tool built into `get_pages` | ⚠️ Integrated | ### **Configuration Changes** **Old (Elementor-MCP):** ```env WORDPRESS_URL=https://site.com WP_USERNAME=admin WP_APPLICATION_PASSWORD=xxxxxxxxxxxxxxxxxxxx ``` **New (Ultimate MCP):** ```env WORDPRESS_BASE_URL=https://site.com WORDPRESS_USERNAME=admin WORDPRESS_APPLICATION_PASSWORD=xxxxxxxxxxxxxxxxxxxx MCP_MODE=full ``` ### **File Operations Changes** **Old:** ```javascript // Download page to file download_page_to_file({ pageId: 123, filePath: '/path/to/file.json', onlyElementorData: true }) ``` **New (More features!):** ```javascript // Export Elementor data export_elementor_data({ post_id: 123, file_path: '/path/to/file.json', include_metadata: true, compress: false }) ``` **Benefits:** - ✅ Metadata support - ✅ Compression option - ✅ Checksum generation - ✅ Better error handling --- ## 📝 **Tool Name Changes** ### **File Operations** | Old Name | New Name | Reason | |----------|----------|--------| | `download_page_to_file` | `export_elementor_data` | More descriptive | | `update_page_from_file` | `import_elementor_data` | Clearer intent | ### **New Capabilities Not in Original** **Enhanced WordPress Operations:** - `get_media` - List media files - `upload_media` - Upload new media - `get_users` - List users - `get_user` - Get user details - `get_categories` - List categories - `get_tags` - List tags - `list_all_content` - List all content with Elementor status **Enhanced Elementor Operations:** - `get_elementor_data_chunked` - Large page handling - `backup_elementor_data` - Quick backups - `clear_elementor_cache` - Cache management - `create_section`, `create_column`, `create_container` - Element creation - `create_heading`, `create_text`, `create_button`, etc. - Widget creation - `find_element_by_id` - Element search - `update_element_settings` - Setting updates - `delete_element`, `clone_element`, `move_element` - Element manipulation - `extract_page_structure` - Structure analysis - `get_templates`, `create_template`, etc. - Template management **File Operations:** - `backup_page_data` - Create versioned backups - `restore_page_data` - Restore from backups - `list_backups` - List available backups - `cleanup_old_backups` - Backup management - `get_file_info` - File information - `validate_file` - File integrity checking **Configuration & Debugging:** - `get_configuration` - Current config - `list_configuration_modes` - Available modes - `validate_configuration` - Config validation - `get_feature_descriptions` - Feature info - `test_wordpress_connection` - Connection testing - `get_error_statistics` - Error tracking - `set_log_level` - Logging control - `health_check` - System health --- ## ⚙️ **Configuration Changes** ### **Environment Variables** | Old Variable | New Variable | Notes | |--------------|--------------|-------| | `WORDPRESS_URL` | `WORDPRESS_BASE_URL` | More specific name | | `WP_USERNAME` | `WORDPRESS_USERNAME` | Consistent naming | | `WP_APPLICATION_PASSWORD` | `WORDPRESS_APPLICATION_PASSWORD` | Consistent naming | | N/A | `MCP_MODE` | New: Simpler mode selection | | `ELEMENTOR_MCP_MODE` | `ELEMENTOR_MCP_MODE` | Still supported | | `ELEMENTOR_MINIMAL_MODE` | `ELEMENTOR_MINIMAL_MODE` | Still supported | | `ELEMENTOR_ENABLE_ALL` | `ELEMENTOR_ENABLE_ALL` | Still supported | **Backwards Compatibility:** ✅ Old variable names still work! ✅ No breaking changes for existing configurations ✅ New names are optional but recommended --- ## 🚨 **Breaking Changes** ### **Minimal Breaking Changes** The Ultimate MCP is designed to be **backwards compatible**. However, there are a few changes: 1. **Installation Method** - Old: `npx wp-elementor-mcp` or `npx elementor-mcp` - New: `node /path/to/dist/index.js` - **Why**: More control, faster startup, better debugging 2. **File Operation Tool Names** - Old: `download_page_to_file` - New: `export_elementor_data` - **Why**: More descriptive and consistent naming 3. **Module System** - Old: CommonJS (`require`) - New: ES Modules (`import`) - **Impact**: Only affects custom extensions --- ## 📋 **Step-by-Step Migration** ### **For wp-elementor-mcp Users** #### **Step 1: Install Ultimate MCP** ```bash git clone https://github.com/mbrown1837/Ultimate-Elementor-MCP.git cd Ultimate-Elementor-MCP npm install npm run build ``` #### **Step 2: Copy Configuration** Copy your existing `.env` file or create a new one: ```bash cp ../wp-elementor-mcp/.env ./.env ``` Or update the new `.env`: ```env WORDPRESS_BASE_URL=https://your-site.com # Same as before WORDPRESS_USERNAME=your-username # Same as before WORDPRESS_APPLICATION_PASSWORD=xxxxxx # Same as before MCP_MODE=full # New: Set your preferred mode ``` #### **Step 3: Update MCP Client Config** **Replace** your old MCP server configuration: ```json { "mcpServers": { "ultimate-elementor-mcp": { "command": "node", "args": ["/absolute/path/to/ultimate-elementor-mcp/dist/index.js"], "env": { "WORDPRESS_BASE_URL": "https://your-site.com", "WORDPRESS_USERNAME": "your-username", "WORDPRESS_APPLICATION_PASSWORD": "xxxxxxxxxxxxxxxxxxxx", "MCP_MODE": "full" } } } } ``` #### **Step 4: Restart and Test** 1. Restart your MCP client 2. Test basic functionality: ``` List available MCP tools ``` 3. Verify you see all 60 tools (if using full mode) --- ### **For Elementor-MCP Users** #### **Step 1: Install Ultimate MCP** Same as above. #### **Step 2: Update Environment Variables** **Old `.env`:** ```env WORDPRESS_URL=https://site.com WP_USERNAME=admin WP_APPLICATION_PASSWORD=xxxxxx ``` **New `.env`:** ```env WORDPRESS_BASE_URL=https://site.com WORDPRESS_USERNAME=admin WORDPRESS_APPLICATION_PASSWORD=xxxxxx MCP_MODE=full ``` #### **Step 3: Update Tool Calls (If Scripted)** If you have scripts calling specific tools: **Old:** ```javascript await mcpClient.callTool('download_page_to_file', { pageId: 123, filePath: '/path/to/file.json', onlyElementorData: true }); ``` **New:** ```javascript await mcpClient.callTool('export_elementor_data', { post_id: 123, file_path: '/path/to/file.json', include_metadata: true }); ``` #### **Step 4: Update MCP Client Config** Same as wp-elementor-mcp section above. --- ## ✅ **Migration Checklist** ### **Pre-Migration** - [ ] Backup your current WordPress site - [ ] Export important page data - [ ] Document your current setup - [ ] Note which tools you use most ### **During Migration** - [ ] Install Ultimate Elementor MCP - [ ] Copy/update environment variables - [ ] Update MCP client configuration - [ ] Restart MCP client - [ ] Verify tools are available ### **Post-Migration** - [ ] Test basic WordPress operations - [ ] Test Elementor operations - [ ] Verify existing workflows still work - [ ] Explore new tools and features - [ ] Update any documentation/scripts ### **Optional Enhancements** - [ ] Switch to higher configuration mode (full) - [ ] Set up file operations directories - [ ] Enable debug mode for learning - [ ] Try new batch operation features - [ ] Set up automated backups --- ## 💡 **Migration Tips** ### **Tip 1: Start with Same Mode** If you used "standard" mode before, start with `MCP_MODE=standard` in Ultimate MCP, then upgrade to `full` later. ### **Tip 2: Test on Staging First** Migrate your staging site first, verify everything works, then migrate production. ### **Tip 3: Keep Old MCP Temporarily** Keep the old MCP configured alongside the new one with a different name: ```json { "mcpServers": { "old-mcp": { "command": "npx", "args": ["wp-elementor-mcp"] }, "ultimate-elementor-mcp": { "command": "node", "args": ["/path/to/ultimate-elementor-mcp/dist/index.js"], "env": { /* config */ } } } } ``` This allows you to compare and switch back if needed. ### **Tip 4: Leverage New Features** Explore the 26 new tools: - File operations for better data management - Debugging tools for troubleshooting - Configuration tools for runtime management - Enhanced WordPress operations ### **Tip 5: Update Documentation** If you have team documentation or workflows, update them to reference the new tool names and capabilities. --- ## 🔧 **Compatibility** ### **✅ Fully Compatible** - All WordPress CRUD operations - All Elementor data operations - All authentication methods - All configuration modes - Environment variable handling ### **⚠️ Minor Changes Required** - File operation tool names (only if you have scripts) - Installation method (npx → node) - MCP client configuration paths ### **🚫 Not Compatible** - None! The Ultimate MCP maintains full backwards compatibility --- ## 📞 **Need Help?** ### **Migration Support** If you encounter issues during migration: 1. **Check logs** with `DEBUG_MODE=true` 2. **Review this guide** for specific scenarios 3. **Test connection** with `test_wordpress_connection` tool 4. **Ask for help** in GitHub Issues ### **Common Migration Questions** **Q: Will my existing pages be affected?** A: No! The MCP only reads/writes when you ask it to. Your existing content is safe. **Q: Can I migrate back to the old MCP?** A: Yes! Just change your MCP client configuration. No data is lost. **Q: Do I need to reinstall WordPress or Elementor?** A: No! The Ultimate MCP works with your existing WordPress installation. **Q: Will my Application Password still work?** A: Yes! Same authentication method, same credentials. **Q: What about my exported data files?** A: They're compatible! The Ultimate MCP can read files from the original MCPs. --- ## 🎉 **Welcome to Ultimate Elementor MCP!** You've successfully migrated to the most comprehensive WordPress & Elementor management MCP available! ### **Next Steps** 1. 📖 Read the [User Guide](USER_GUIDE.md) 2. 💡 Check out [Examples](EXAMPLES.md) 3. 🔧 Explore the [Tools Reference](TOOLS_REFERENCE.md) 4. 🚀 Start building with 60 powerful tools! --- **🔧 Happy building with Ultimate Elementor MCP!** 🚀