@berthojoris/mcp-mysql-server 1.7.0 → 1.8.0

package/DOCUMENTATIONS.md

@@ -8,26 +8,27 @@ This file contains detailed documentation for all features of the MySQL MCP Serv
 
 1. [DDL Operations](#🏗️-ddl-operations)
 2. [Data Export Tools](#📤-data-export-tools)
-3. [Data Import Tools](#📥-data-import-tools) - NEW!
-4. [Database Backup & Restore](#💾-database-backup--restore) - NEW!
-5. [Transaction Management](#💰-transaction-management)
-6. [Stored Procedures](#🔧-stored-procedures)
-7. [Views Management](#👁️-views-management)
-8. [Triggers Management](#⚡-triggers-management)
-9. [Functions Management](#🔢-functions-management)
-10. [Index Management](#📇-index-management)
-11. [Constraint Management](#🔗-constraint-management)
-12. [Table Maintenance](#🔧-table-maintenance)
-13. [Process & Server Management](#📊-process--server-management)
-14. [Usage Examples](#📋-usage-examples)
-15. [Query Logging & Automatic SQL Display](#📝-query-logging--automatic-sql-display)
-16. [Security Features](#🔒-security-features)
-17. [Query Result Caching](#💾-query-result-caching)
-18. [Query Optimization Hints](#🎯-query-optimization-hints)
-19. [Bulk Operations](#🚀-bulk-operations)
-20. [Troubleshooting](#🛠️-troubleshooting)
-21. [License](#📄-license)
-22. [Roadmap](#🗺️-roadmap)
+3. [Data Import Tools](#📥-data-import-tools)
+4. [Database Backup & Restore](#💾-database-backup--restore)
+5. [Data Migration Tools](#🔄-data-migration-tools) - NEW!
+6. [Transaction Management](#💰-transaction-management)
+7. [Stored Procedures](#🔧-stored-procedures)
+8. [Views Management](#👁️-views-management)
+9. [Triggers Management](#⚡-triggers-management)
+10. [Functions Management](#🔢-functions-management)
+11. [Index Management](#📇-index-management)
+12. [Constraint Management](#🔗-constraint-management)
+13. [Table Maintenance](#🔧-table-maintenance)
+14. [Process & Server Management](#📊-process--server-management)
+15. [Usage Examples](#📋-usage-examples)
+16. [Query Logging & Automatic SQL Display](#📝-query-logging--automatic-sql-display)
+17. [Security Features](#🔒-security-features)
+18. [Query Result Caching](#💾-query-result-caching)
+19. [Query Optimization Hints](#🎯-query-optimization-hints)
+20. [Bulk Operations](#🚀-bulk-operations)
+21. [Troubleshooting](#🛠️-troubleshooting)
+22. [License](#📄-license)
+23. [Roadmap](#🗺️-roadmap)
 
 ---
 
@@ -481,6 +482,294 @@ Get a complete overview of all database objects:
 
 ---
 
+## 🔄 Data Migration Tools
+
+The MySQL MCP Server provides powerful data migration utilities for copying, moving, and synchronizing data between tables.
+
+### Data Migration Tools Overview
+
+| Tool | Description | Permission |
+|------|-------------|------------|
+| `copy_table_data` | Copy data from one table to another | `create` |
+| `move_table_data` | Move data (copy + delete from source) | `create`, `delete` |
+| `clone_table` | Clone table structure with optional data | `ddl` |
+| `compare_table_structure` | Compare structure of two tables | `list` |
+| `sync_table_data` | Synchronize data between tables | `update` |
+
+### Copy Table Data
+
+Copy data from one table to another with optional column mapping and filtering.
+
+```json
+{
+  "tool": "copy_table_data",
+  "arguments": {
+    "source_table": "users",
+    "target_table": "users_backup",
+    "batch_size": 1000
+  }
+}
+```
+
+**With Column Mapping:**
+```json
+{
+  "tool": "copy_table_data",
+  "arguments": {
+    "source_table": "old_customers",
+    "target_table": "customers",
+    "column_mapping": {
+      "customer_name": "name",
+      "customer_email": "email",
+      "customer_phone": "phone"
+    }
+  }
+}
+```
+
+**With Filters:**
+```json
+{
+  "tool": "copy_table_data",
+  "arguments": {
+    "source_table": "orders",
+    "target_table": "archived_orders",
+    "filters": [
+      { "field": "status", "operator": "eq", "value": "completed" },
+      { "field": "created_at", "operator": "lt", "value": "2024-01-01" }
+    ]
+  }
+}
+```
+
+**Response:**
+```json
+{
+  "status": "success",
+  "data": {
+    "message": "Data copied successfully",
+    "rows_copied": 5000,
+    "source_table": "orders",
+    "target_table": "archived_orders"
+  }
+}
+```
+
+### Move Table Data
+
+Move data from one table to another (copies data then deletes from source).
+
+```json
+{
+  "tool": "move_table_data",
+  "arguments": {
+    "source_table": "active_sessions",
+    "target_table": "expired_sessions",
+    "filters": [
+      { "field": "expires_at", "operator": "lt", "value": "2024-01-01" }
+    ]
+  }
+}
+```
+
+**Response:**
+```json
+{
+  "status": "success",
+  "data": {
+    "message": "Data moved successfully",
+    "rows_moved": 1500,
+    "source_table": "active_sessions",
+    "target_table": "expired_sessions"
+  }
+}
+```
+
+### Clone Table
+
+Clone a table structure with or without data.
+
+```json
+{
+  "tool": "clone_table",
+  "arguments": {
+    "source_table": "products",
+    "new_table_name": "products_staging",
+    "include_data": false,
+    "include_indexes": true
+  }
+}
+```
+
+**Clone with Data:**
+```json
+{
+  "tool": "clone_table",
+  "arguments": {
+    "source_table": "users",
+    "new_table_name": "users_test",
+    "include_data": true
+  }
+}
+```
+
+**Response:**
+```json
+{
+  "status": "success",
+  "data": {
+    "message": "Table cloned successfully",
+    "source_table": "products",
+    "new_table": "products_staging",
+    "include_data": false,
+    "include_indexes": true
+  }
+}
+```
+
+### Compare Table Structure
+
+Compare the structure of two tables to identify differences.
+
+```json
+{
+  "tool": "compare_table_structure",
+  "arguments": {
+    "table1": "users",
+    "table2": "users_backup"
+  }
+}
+```
+
+**Response:**
+```json
+{
+  "status": "success",
+  "data": {
+    "table1": "users",
+    "table2": "users_backup",
+    "identical": false,
+    "differences": {
+      "columns_only_in_table1": ["last_login", "avatar_url"],
+      "columns_only_in_table2": [],
+      "column_type_differences": [
+        {
+          "column": "email",
+          "table1_type": "VARCHAR(255)",
+          "table2_type": "VARCHAR(100)"
+        }
+      ],
+      "index_differences": {
+        "only_in_table1": ["idx_last_login"],
+        "only_in_table2": []
+      }
+    }
+  }
+}
+```
+
+### Sync Table Data
+
+Synchronize data between two tables based on a key column. Supports three modes:
+- **insert_only**: Only insert new records that don't exist in target
+- **update_only**: Only update existing records in target
+- **upsert**: Both insert new and update existing records (default)
+
+```json
+{
+  "tool": "sync_table_data",
+  "arguments": {
+    "source_table": "products_master",
+    "target_table": "products_replica",
+    "key_column": "product_id",
+    "sync_mode": "upsert"
+  }
+}
+```
+
+**Sync Specific Columns:**
+```json
+{
+  "tool": "sync_table_data",
+  "arguments": {
+    "source_table": "inventory_main",
+    "target_table": "inventory_cache",
+    "key_column": "sku",
+    "columns_to_sync": ["quantity", "price", "updated_at"],
+    "sync_mode": "update_only"
+  }
+}
+```
+
+**Response:**
+```json
+{
+  "status": "success",
+  "data": {
+    "message": "Sync completed successfully",
+    "source_table": "products_master",
+    "target_table": "products_replica",
+    "rows_inserted": 150,
+    "rows_updated": 3200,
+    "sync_mode": "upsert"
+  }
+}
+```
+
+### Migration Best Practices
+
+1. **Backup before migration** - Always backup target tables before large migrations
+2. **Use filters** - Migrate data in chunks using filters to avoid timeouts
+3. **Test with small batches** - Test migration logic with small datasets first
+4. **Verify data integrity** - Use `compare_table_structure` before migration
+5. **Monitor performance** - Adjust `batch_size` based on table size and server capacity
+
+### Common Migration Patterns
+
+**Pattern 1: Archive Old Data**
+```json
+// Move old orders to archive table
+{
+  "tool": "move_table_data",
+  "arguments": {
+    "source_table": "orders",
+    "target_table": "orders_archive",
+    "filters": [
+      { "field": "created_at", "operator": "lt", "value": "2023-01-01" }
+    ]
+  }
+}
+```
+
+**Pattern 2: Create Staging Table**
+```json
+// Clone structure for staging
+{
+  "tool": "clone_table",
+  "arguments": {
+    "source_table": "products",
+    "new_table_name": "products_staging",
+    "include_data": false
+  }
+}
+```
+
+**Pattern 3: Replicate Data Across Tables**
+```json
+// Keep replica in sync with master
+{
+  "tool": "sync_table_data",
+  "arguments": {
+    "source_table": "users_master",
+    "target_table": "users_read_replica",
+    "key_column": "id",
+    "sync_mode": "upsert"
+  }
+}
+```
+
+---
+
 ## 💰 Transaction Management
 
 The MySQL MCP Server provides full ACID transaction support, allowing you to group multiple database operations into atomic units.
@@ -2093,12 +2382,12 @@ MIT License - see [LICENSE](LICENSE) file for details.
 - ✅ **Process Management** - Server processes, status, and query analysis - **COMPLETED!**
 
 ### Enterprise Features
-- [x] **Database backup and restore tools** - **COMPLETED!**
-- [x] **Data export/import utilities** (CSV, JSON, SQL dumps) - **COMPLETED!**
+- ✅ **Database backup and restore tools** - **COMPLETED!**
+- ✅ **Data export/import utilities** (CSV, JSON, SQL dumps) - **COMPLETED!**
+- ✅ **Data migration utilities** - **COMPLETED!**
 - [ ] **Performance monitoring and metrics**
 - [ ] **Connection pool monitoring**
 - [ ] **Audit logging and compliance**
-- [ ] **Data migration utilities**
 - [ ] **Schema versioning and migrations**
 
 ### Database Adapters
@@ -2117,9 +2406,9 @@ MIT License - see [LICENSE](LICENSE) file for details.
 - [ ] **Database health checks** - Comprehensive system health monitoring
 
 #### **Phase 2: Data Management** 📊
-- [x] **Database backup and restore tools** - Essential for production data safety - **COMPLETED!**
-- [ ] **Data migration utilities** - Move data between databases and environments
-- [x] **Enhanced export/import** - Support for JSON, SQL dump formats - **COMPLETED!**
+- ✅ **Database backup and restore tools** - Essential for production data safety - **COMPLETED!**
+- ✅ **Data migration utilities** - Move data between databases and environments - **COMPLETED!**
+- ✅ **Enhanced export/import** - Support for JSON, SQL dump formats - **COMPLETED!**
 - [ ] **Query history & analytics** - Track and analyze database usage patterns
 
 #### **Phase 3: Enterprise Features** 🏢
@@ -2149,9 +2438,9 @@ MIT License - see [LICENSE](LICENSE) file for details.
 | Query Optimization | Medium | Medium | 9 | ✅ COMPLETED |
 | Database Backup/Restore | High | High | 10 | ✅ COMPLETED |
 | Data Export/Import (JSON, SQL) | High | Medium | 11 | ✅ COMPLETED |
-| Performance Monitoring | High | Medium | 12 | Pending |
-| Data Migration | High | High | 13 | Pending |
-| PostgreSQL Adapter | High | High | 13 | Pending |
+| Data Migration | High | High | 12 | ✅ COMPLETED |
+| Performance Monitoring | High | Medium | 13 | Pending |
+| PostgreSQL Adapter | High | High | 14 | Pending |
 | Audit Logging | Medium | Low | 14 | Pending |
 | Schema Versioning | Medium | Medium | 15 | Pending |
 

package/README.md

@@ -11,7 +11,7 @@ A fully-featured **Model Context Protocol (MCP)** server for MySQL database inte
 
 - ✅ **Full MCP Protocol Support** - Works with Claude Desktop, Cline, Windsurf, and any MCP-compatible AI agent
 - 🔐 **Secure by Default** - Parameterized queries, SQL injection protection, permission-based access control
-- 🛠️ **95 Powerful Tools** - Complete database operations (CRUD, DDL, queries, schema inspection, transactions, stored procedures, bulk operations, backup/restore, import/export)
+- 🛠️ **100 Powerful Tools** - Complete database operations (CRUD, DDL, queries, schema inspection, transactions, stored procedures, bulk operations, backup/restore, import/export, data migration)
 - 🎛️ **Dynamic Per-Project Permissions** - Each AI agent can have different access levels
 - 🗃️ **DDL Support** - Create, alter, and drop tables (when explicitly enabled)
 - 💎 **Transaction Support** - Full ACID transaction management (BEGIN, COMMIT, ROLLBACK)
@@ -347,123 +347,9 @@ You can have different databases with different permissions in the same AI agent
 
 ---
 
-## 🚫 Permission Error Handling
-
-The MySQL MCP Server provides clear, user-friendly error messages when operations are attempted without proper permissions. This helps users understand exactly what permissions are needed and how to enable them.
-
-### Error Message Format
-
-When a tool is called without the required permission, you'll receive a detailed error message like:
-
-```
-❌ Permission denied: Cannot use tool 'create_table'. This tool requires 'ddl' permission.
-
-Current permissions: list,read,utility
-To enable this tool, add 'ddl' to your permissions configuration.
-
-Example configuration:
-"args": ["mysql://user:pass@host:3306/db", "list,read,utility,ddl"]
-
-Tool description: Create new tables with columns and indexes
-```
-
-### Common Permission Error Examples
-
-#### Creating Tables Without DDL Permission
-
-**User prompt:** *"Create a new table called 'products'"*
-
-**Error response when DDL not enabled:**
-```
-❌ Permission denied: Cannot use tool 'create_table'. This tool requires 'ddl' permission.
-
-Current permissions: list,read,utility
-To enable this tool, add 'ddl' to your permissions configuration.
-
-Example configuration:
-"args": ["mysql://user:pass@host:3306/db", "list,read,utility,ddl"]
-
-Tool description: Create new tables with columns and indexes
-```
-
-#### Inserting Data Without Create Permission
-
-**User prompt:** *"Add a new user to the users table"*
-
-**Error response when CREATE not enabled:**
-```
-❌ Permission denied: Cannot use tool 'create_record'. This tool requires 'create' permission.
-
-Current permissions: list,read,utility
-To enable this tool, add 'create' to your permissions configuration.
-
-Example configuration:
-"args": ["mysql://user:pass@host:3306/db", "list,read,utility,create"]
-
-Tool description: Insert new records with automatic SQL generation
-```
-
-#### Updating Data Without Update Permission
-
-**User prompt:** *"Update the email for user ID 123"*
-
-**Error response when UPDATE not enabled:**
-```
-❌ Permission denied: Cannot use tool 'update_record'. This tool requires 'update' permission.
-
-Current permissions: list,read,utility
-To enable this tool, add 'update' to your permissions configuration.
-
-Example configuration:
-"args": ["mysql://user:pass@host:3306/db", "list,read,utility,update"]
-
-Tool description: Update existing records based on conditions
-```
-
-### Permission Error Benefits
-
-1. **🎯 Clear Guidance** - Exact permission needed and how to add it
-2. **📋 Current State** - Shows what permissions are currently active
-3. **💡 Example Configuration** - Ready-to-use configuration example
-4. **📖 Tool Context** - Explains what the tool does
-5. **🔐 Security** - Prevents unauthorized operations while being helpful
-
-### Troubleshooting Permission Errors
-
-If you encounter permission errors:
-
-1. **Check your configuration** - Verify the permissions string in your MCP configuration
-2. **Add required permission** - Add the missing permission to your configuration
-3. **Restart your AI agent** - Changes require a restart to take effect
-4. **Test with a simple operation** - Verify the permission is working
-
-**Example fix for DDL operations:**
-
-Before (DDL disabled):
-```json
-{
-  "args": [
-    "mysql://user:pass@localhost:3306/db",
-    "list,read,utility"
-  ]
-}
-```
-
-After (DDL enabled):
-```json
-{
-  "args": [
-    "mysql://user:pass@localhost:3306/db",
-    "list,read,utility,ddl"
-  ]
-}
-```
-
----
-
 ## 🛠️ Available Tools
 
-The MCP server provides **95 powerful tools**:
+The MCP server provides **100 powerful tools**:
 
 ### Database Discovery (4 tools)
 
@@ -645,7 +531,7 @@ The MCP server provides **95 powerful tools**:
 | `get_create_table_statement` | Get CREATE TABLE statement for a table | `list` permission |
 | `get_database_schema` | Get complete database schema (tables, views, procedures, functions, triggers) | `list` permission |
 
-### Data Import/Export (5 tools) - NEW!
+### Data Import/Export (5 tools)
 
 | Tool | Description | Requires |
 |------|-------------|----------|
@@ -655,6 +541,16 @@ The MCP server provides **95 powerful tools**:
 | `import_from_csv` | Import data from CSV string into a table | `create` permission |
 | `import_from_json` | Import data from JSON array into a table | `create` permission |
 
+### Data Migration (5 tools) - NEW!
+
+| Tool | Description | Requires |
+|------|-------------|----------|
+| `copy_table_data` | Copy data from one table to another with optional column mapping | `create` permission |
+| `move_table_data` | Move data (copy + delete from source) | `create`, `delete` permission |
+| `clone_table` | Clone table structure with optional data | `ddl` permission |
+| `compare_table_structure` | Compare structure of two tables and identify differences | `list` permission |
+| `sync_table_data` | Synchronize data between tables (insert_only, update_only, upsert) | `update` permission |
+
 ---
 
 ## 📚 Detailed Documentation
@@ -665,6 +561,7 @@ For comprehensive documentation on all features, please see **[DOCUMENTATIONS.md
 - 📤 **Data Export Tools** - Export data to CSV, JSON, and SQL formats
 - 📥 **Data Import Tools** - Import data from CSV and JSON sources
 - 💾 **Database Backup & Restore** - Full backup/restore with SQL dumps
+- 🔄 **Data Migration Tools** - Copy, move, clone, compare, and sync table data
 - 💎 **Transaction Management** - ACID transactions with BEGIN, COMMIT, ROLLBACK
 - 🔧 **Stored Procedures** - Create and execute stored procedures with IN/OUT/INOUT parameters
 - 📋 **Usage Examples** - Real-world examples for all tools

package/dist/config/featureConfig.js

@@ -141,6 +141,12 @@ exports.toolCategoryMap = {
     exportTableToSql: ToolCategory.UTILITY,
     importFromCSV: ToolCategory.CREATE,
     importFromJSON: ToolCategory.CREATE,
+    // Data migration tools
+    copyTableData: ToolCategory.CREATE,
+    moveTableData: ToolCategory.DELETE,
+    cloneTable: ToolCategory.DDL,
+    compareTableStructure: ToolCategory.LIST,
+    syncTableData: ToolCategory.UPDATE,
 };
 /**
  * Class to manage feature configuration based on runtime or environment variables

package/dist/index.d.ts

@@ -19,6 +19,7 @@ export declare class MySQLMCP {
     private maintenanceTools;
     private processTools;
     private backupRestoreTools;
+    private migrationTools;
     private security;
     private featureConfig;
     constructor(permissionsConfig?: string);
@@ -400,6 +401,68 @@ export declare class MySQLMCP {
         error?: string;
         queryLog?: string;
     }>;
+    copyTableData(params: {
+        source_table: string;
+        target_table: string;
+        column_mapping?: Record<string, string>;
+        filters?: any[];
+        batch_size?: number;
+        database?: string;
+    }): Promise<{
+        status: string;
+        data?: any;
+        error?: string;
+        queryLog?: string;
+    }>;
+    moveTableData(params: {
+        source_table: string;
+        target_table: string;
+        column_mapping?: Record<string, string>;
+        filters?: any[];
+        batch_size?: number;
+        database?: string;
+    }): Promise<{
+        status: string;
+        data?: any;
+        error?: string;
+        queryLog?: string;
+    }>;
+    cloneTable(params: {
+        source_table: string;
+        new_table_name: string;
+        include_data?: boolean;
+        include_indexes?: boolean;
+        database?: string;
+    }): Promise<{
+        status: string;
+        data?: any;
+        error?: string;
+        queryLog?: string;
+    }>;
+    compareTableStructure(params: {
+        table1: string;
+        table2: string;
+        database?: string;
+    }): Promise<{
+        status: string;
+        data?: any;
+        error?: string;
+        queryLog?: string;
+    }>;
+    syncTableData(params: {
+        source_table: string;
+        target_table: string;
+        key_column: string;
+        columns_to_sync?: string[];
+        sync_mode?: "insert_only" | "update_only" | "upsert";
+        batch_size?: number;
+        database?: string;
+    }): Promise<{
+        status: string;
+        data?: any;
+        error?: string;
+        queryLog?: string;
+    }>;
     getFeatureStatus(): {
         status: string;
         data: {

package/dist/index.js

@@ -20,6 +20,7 @@ const constraintTools_1 = require("./tools/constraintTools");
 const maintenanceTools_1 = require("./tools/maintenanceTools");
 const processTools_1 = require("./tools/processTools");
 const backupRestoreTools_1 = require("./tools/backupRestoreTools");
+const migrationTools_1 = require("./tools/migrationTools");
 const securityLayer_1 = __importDefault(require("./security/securityLayer"));
 const connection_1 = __importDefault(require("./db/connection"));
 const featureConfig_1 = require("./config/featureConfig");
@@ -47,6 +48,7 @@ class MySQLMCP {
         this.maintenanceTools = new maintenanceTools_1.MaintenanceTools(this.security);
         this.processTools = new processTools_1.ProcessTools(this.security);
         this.backupRestoreTools = new backupRestoreTools_1.BackupRestoreTools(this.security);
+        this.migrationTools = new migrationTools_1.MigrationTools(this.security);
     }
     // Helper method to check if tool is enabled
     checkToolEnabled(toolName) {
@@ -359,6 +361,42 @@ class MySQLMCP {
         }
         return await this.backupRestoreTools.getDatabaseSchema(params);
     }
+    // Data Migration Tools
+    async copyTableData(params) {
+        const check = this.checkToolEnabled("copyTableData");
+        if (!check.enabled) {
+            return { status: "error", error: check.error };
+        }
+        return await this.migrationTools.copyTableData(params);
+    }
+    async moveTableData(params) {
+        const check = this.checkToolEnabled("moveTableData");
+        if (!check.enabled) {
+            return { status: "error", error: check.error };
+        }
+        return await this.migrationTools.moveTableData(params);
+    }
+    async cloneTable(params) {
+        const check = this.checkToolEnabled("cloneTable");
+        if (!check.enabled) {
+            return { status: "error", error: check.error };
+        }
+        return await this.migrationTools.cloneTable(params);
+    }
+    async compareTableStructure(params) {
+        const check = this.checkToolEnabled("compareTableStructure");
+        if (!check.enabled) {
+            return { status: "error", error: check.error };
+        }
+        return await this.migrationTools.compareTableStructure(params);
+    }
+    async syncTableData(params) {
+        const check = this.checkToolEnabled("syncTableData");
+        if (!check.enabled) {
+            return { status: "error", error: check.error };
+        }
+        return await this.migrationTools.syncTableData(params);
+    }
     // Get feature configuration status
     getFeatureStatus() {
         return {