@berthojoris/mcp-mysql-server 1.6.3 → 1.8.0

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
-- 🛠️ **85 Powerful Tools** - Complete database operations (CRUD, DDL, queries, schema inspection, transactions, stored procedures, bulk operations)
+- 🛠️ **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 **85 powerful tools**:
+The MCP server provides **100 powerful tools**:
 
 ### Database Discovery (4 tools)
 
@@ -635,6 +521,36 @@ The MCP server provides **85 powerful tools**:
 | `analyze_query` | Analyze query and get optimization suggestions |
 | `get_optimization_hints` | Get optimizer hints for SPEED, MEMORY, or STABILITY goals |
 
+### Database Backup & Restore (5 tools) - NEW!
+
+| Tool | Description | Requires |
+|------|-------------|----------|
+| `backup_table` | Backup single table to SQL dump format | `utility` permission |
+| `backup_database` | Backup entire database to SQL dump | `utility` permission |
+| `restore_from_sql` | Restore database from SQL dump content | `ddl` permission |
+| `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)
+
+| Tool | Description | Requires |
+|------|-------------|----------|
+| `export_table_to_json` | Export table data to JSON format | `utility` permission |
+| `export_query_to_json` | Export query results to JSON format | `utility` permission |
+| `export_table_to_sql` | Export table data to SQL INSERT statements | `utility` permission |
+| `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
@@ -642,7 +558,10 @@ The MCP server provides **85 powerful tools**:
 For comprehensive documentation on all features, please see **[DOCUMENTATIONS.md](DOCUMENTATIONS.md)** which includes:
 
 - 🗃️ **DDL Operations** - Create, alter, and drop tables
-- 📤 **Data Export Tools** - Export data to CSV format
+- 📤 **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

@@ -129,6 +129,24 @@ exports.toolCategoryMap = {
     getServerInfo: ToolCategory.LIST,
     showBinaryLogs: ToolCategory.LIST,
     showReplicationStatus: ToolCategory.LIST,
+    // Backup and restore tools
+    backupTable: ToolCategory.UTILITY,
+    backupDatabase: ToolCategory.UTILITY,
+    restoreFromSql: ToolCategory.DDL,
+    getCreateTableStatement: ToolCategory.LIST,
+    getDatabaseSchema: ToolCategory.LIST,
+    // Extended data export/import tools
+    exportTableToJSON: ToolCategory.UTILITY,
+    exportQueryToJSON: ToolCategory.UTILITY,
+    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
@@ -218,6 +236,18 @@ class FeatureConfig {
             executeStoredProcedure: "execute stored procedures",
             exportTableToCSV: "export table data to CSV",
             exportQueryToCSV: "export query results to CSV",
+            // Backup and restore
+            backupTable: "backup table to SQL dump",
+            backupDatabase: "backup database to SQL dump",
+            restoreFromSql: "restore database from SQL dump",
+            getCreateTableStatement: "get CREATE TABLE statement",
+            getDatabaseSchema: "get database schema overview",
+            // Extended export/import
+            exportTableToJSON: "export table data to JSON",
+            exportQueryToJSON: "export query results to JSON",
+            exportTableToSql: "export table data to SQL INSERT statements",
+            importFromCSV: "import data from CSV",
+            importFromJSON: "import data from JSON",
         };
         const toolDescription = toolDescriptions[toolName] || actionDescriptions[category];
         const requiredPermission = category;

package/dist/index.d.ts

@@ -18,6 +18,8 @@ export declare class MySQLMCP {
     private constraintTools;
     private maintenanceTools;
     private processTools;
+    private backupRestoreTools;
+    private migrationTools;
     private security;
     private featureConfig;
     constructor(permissionsConfig?: string);
@@ -278,6 +280,189 @@ export declare class MySQLMCP {
         error?: string;
         queryLog?: string;
     }>;
+    exportTableToJSON(params: {
+        table_name: string;
+        filters?: any[];
+        pagination?: {
+            page: number;
+            limit: number;
+        };
+        sorting?: {
+            field: string;
+            direction: "asc" | "desc";
+        };
+        pretty?: boolean;
+        database?: string;
+    }): Promise<{
+        status: string;
+        data?: any;
+        error?: string;
+        queryLog?: string;
+    }>;
+    exportQueryToJSON(params: {
+        query: string;
+        params?: any[];
+        pretty?: boolean;
+    }): Promise<{
+        status: string;
+        data?: any;
+        error?: string;
+        queryLog?: string;
+    }>;
+    exportTableToSql(params: {
+        table_name: string;
+        filters?: any[];
+        include_create_table?: boolean;
+        batch_size?: number;
+        database?: string;
+    }): Promise<{
+        status: string;
+        data?: any;
+        error?: string;
+        queryLog?: string;
+    }>;
+    importFromCSV(params: {
+        table_name: string;
+        csv_data: string;
+        has_headers?: boolean;
+        column_mapping?: Record<string, string>;
+        skip_errors?: boolean;
+        batch_size?: number;
+        database?: string;
+    }): Promise<{
+        status: string;
+        data?: any;
+        error?: string;
+        queryLog?: string;
+    }>;
+    importFromJSON(params: {
+        table_name: string;
+        json_data: string;
+        column_mapping?: Record<string, string>;
+        skip_errors?: boolean;
+        batch_size?: number;
+        database?: string;
+    }): Promise<{
+        status: string;
+        data?: any;
+        error?: string;
+        queryLog?: string;
+    }>;
+    backupTable(params: {
+        table_name: string;
+        include_data?: boolean;
+        include_drop?: boolean;
+        database?: string;
+    }): Promise<{
+        status: string;
+        data?: any;
+        error?: string;
+        queryLog?: string;
+    }>;
+    backupDatabase(params: {
+        include_data?: boolean;
+        include_drop?: boolean;
+        tables?: string[];
+        database?: string;
+    }): Promise<{
+        status: string;
+        data?: any;
+        error?: string;
+        queryLog?: string;
+    }>;
+    restoreFromSql(params: {
+        sql_dump: string;
+        stop_on_error?: boolean;
+        database?: string;
+    }): Promise<{
+        status: string;
+        data?: any;
+        error?: string;
+        queryLog?: string;
+    }>;
+    getCreateTableStatement(params: {
+        table_name: string;
+        database?: string;
+    }): Promise<{
+        status: string;
+        data?: any;
+        error?: string;
+        queryLog?: string;
+    }>;
+    getDatabaseSchema(params: {
+        database?: string;
+        include_views?: boolean;
+        include_procedures?: boolean;
+        include_functions?: boolean;
+        include_triggers?: boolean;
+    }): Promise<{
+        status: string;
+        data?: any;
+        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

@@ -19,6 +19,8 @@ const indexTools_1 = require("./tools/indexTools");
 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");
@@ -45,6 +47,8 @@ class MySQLMCP {
         this.constraintTools = new constraintTools_1.ConstraintTools(this.security);
         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) {
@@ -284,6 +288,115 @@ class MySQLMCP {
         }
         return await this.dataExportTools.exportQueryToCSV(params);
     }
+    // Extended Data Export Tools (JSON, SQL)
+    async exportTableToJSON(params) {
+        const check = this.checkToolEnabled("exportTableToJSON");
+        if (!check.enabled) {
+            return { status: "error", error: check.error };
+        }
+        return await this.dataExportTools.exportTableToJSON(params);
+    }
+    async exportQueryToJSON(params) {
+        const check = this.checkToolEnabled("exportQueryToJSON");
+        if (!check.enabled) {
+            return { status: "error", error: check.error };
+        }
+        return await this.dataExportTools.exportQueryToJSON(params);
+    }
+    async exportTableToSql(params) {
+        const check = this.checkToolEnabled("exportTableToSql");
+        if (!check.enabled) {
+            return { status: "error", error: check.error };
+        }
+        return await this.dataExportTools.exportTableToSql(params);
+    }
+    // Data Import Tools
+    async importFromCSV(params) {
+        const check = this.checkToolEnabled("importFromCSV");
+        if (!check.enabled) {
+            return { status: "error", error: check.error };
+        }
+        return await this.dataExportTools.importFromCSV(params);
+    }
+    async importFromJSON(params) {
+        const check = this.checkToolEnabled("importFromJSON");
+        if (!check.enabled) {
+            return { status: "error", error: check.error };
+        }
+        return await this.dataExportTools.importFromJSON(params);
+    }
+    // Backup and Restore Tools
+    async backupTable(params) {
+        const check = this.checkToolEnabled("backupTable");
+        if (!check.enabled) {
+            return { status: "error", error: check.error };
+        }
+        return await this.backupRestoreTools.backupTable(params);
+    }
+    async backupDatabase(params) {
+        const check = this.checkToolEnabled("backupDatabase");
+        if (!check.enabled) {
+            return { status: "error", error: check.error };
+        }
+        return await this.backupRestoreTools.backupDatabase(params);
+    }
+    async restoreFromSql(params) {
+        const check = this.checkToolEnabled("restoreFromSql");
+        if (!check.enabled) {
+            return { status: "error", error: check.error };
+        }
+        return await this.backupRestoreTools.restoreFromSql(params);
+    }
+    async getCreateTableStatement(params) {
+        const check = this.checkToolEnabled("getCreateTableStatement");
+        if (!check.enabled) {
+            return { status: "error", error: check.error };
+        }
+        return await this.backupRestoreTools.getCreateTableStatement(params);
+    }
+    async getDatabaseSchema(params) {
+        const check = this.checkToolEnabled("getDatabaseSchema");
+        if (!check.enabled) {
+            return { status: "error", error: check.error };
+        }
+        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 {