@berthojoris/mcp-mysql-server 1.0.2 → 1.2.0

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2025
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2025
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -130,7 +130,7 @@ Try asking your AI:
 
 ## 🛠️ Available Tools
 
-The MCP server provides **27 powerful tools**:
+The MCP server provides **30 powerful tools**:
 
 ### Database Discovery (4 tools)
 
@@ -150,6 +150,14 @@ The MCP server provides **27 powerful tools**:
 | `update_record` | Update records based on conditions |
 | `delete_record` | Delete records with safety checks |
 
+### Bulk Operations (3 tools)
+
+| Tool | Description | Performance |
+|------|-------------|-------------|
+| `bulk_insert` | Insert multiple records in batches for optimal performance | Up to 10,000 records per batch |
+| `bulk_update` | Update multiple records with different conditions in batches | Up to 1,000 operations per batch |
+| `bulk_delete` | Delete multiple record sets based on different conditions | Up to 1,000 operations per batch |
+
 ### Custom Queries (2 tools)
 
 | Tool | Description |
@@ -740,6 +748,77 @@ END IF;
 **AI uses `get_transaction_status`:**
 - Returns transaction status and ID if active
 
+### Example 7: Bulk Insert
+
+**User:** *"Insert 1000 new products from this CSV data"*
+
+**AI uses `bulk_insert`:**
+```json
+{
+  "tool": "bulk_insert",
+  "arguments": {
+    "table_name": "products",
+    "data": [
+      {"name": "Product 1", "price": 19.99, "category": "Electronics"},
+      {"name": "Product 2", "price": 29.99, "category": "Books"},
+      // ... up to 1000 records
+    ],
+    "batch_size": 1000
+  }
+}
+```
+- Processes records in optimized batches
+- Returns total inserted count and performance metrics
+
+### Example 8: Bulk Update
+
+**User:** *"Update prices for all products in specific categories with different discounts"*
+
+**AI uses `bulk_update`:**
+```json
+{
+  "tool": "bulk_update",
+  "arguments": {
+    "table_name": "products",
+    "updates": [
+      {
+        "data": {"price": "price * 0.9"},
+        "conditions": [{"field": "category", "operator": "eq", "value": "Electronics"}]
+      },
+      {
+        "data": {"price": "price * 0.8"},
+        "conditions": [{"field": "category", "operator": "eq", "value": "Books"}]
+      }
+    ],
+    "batch_size": 100
+  }
+}
+```
+- Applies different updates based on conditions
+- Processes in batches for optimal performance
+
+### Example 9: Bulk Delete
+
+**User:** *"Delete all inactive users and expired sessions"*
+
+**AI uses `bulk_delete`:**
+```json
+{
+  "tool": "bulk_delete",
+  "arguments": {
+    "table_name": "users",
+    "condition_sets": [
+      [{"field": "status", "operator": "eq", "value": "inactive"}],
+      [{"field": "last_login", "operator": "lt", "value": "2023-01-01"}],
+      [{"field": "email_verified", "operator": "eq", "value": false}]
+    ],
+    "batch_size": 100
+  }
+}
+```
+- Deletes records matching any of the condition sets
+- Processes deletions in safe batches
+
 **User:** *"Rollback the current transaction"*
 
 **AI uses `rollback_transaction`:**
@@ -925,48 +1004,82 @@ curl http://localhost:3000/health
 
 ---
 
-## 🚀 Publishing to npm
+## 🚀 Bulk Operations
+
+The MySQL MCP server includes powerful bulk operation tools designed for high-performance data processing. These tools are optimized for handling large datasets efficiently.
 
-To make your MCP server available to the world:
+### Performance Characteristics
 
-### 1. Update package.json
+- **Batch Processing**: Operations are processed in configurable batches to optimize memory usage and database performance
+- **Transaction Safety**: Each batch is wrapped in a transaction for data consistency
+- **Error Handling**: Detailed error reporting with batch-level granularity
+- **Memory Efficient**: Streaming approach prevents memory overflow with large datasets
 
+### Best Practices
+
+#### Batch Size Optimization
 ```json
 {
-  "name": "@your-username/mcp-mysql",
-  "author": "Your Name <your.email@example.com>",
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/berthojoris/mysql-mcp.git"
-  }
+  "batch_size": 1000  // Recommended for most operations
 }
 ```
 
-### 2. Build
+**Guidelines:**
+- **Small records (< 1KB)**: Use batch sizes of 1000-5000
+- **Large records (> 10KB)**: Use batch sizes of 100-500
+- **Complex operations**: Start with 100 and increase based on performance
 
-```bash
-npm run build
-```
+#### Bulk Insert Tips
+- Use consistent data structure across all records
+- Pre-validate data to avoid mid-batch failures
+- Consider using `ON DUPLICATE KEY UPDATE` for upsert operations
+- Monitor MySQL's `max_allowed_packet` setting for large batches
 
-### 3. Publish
+#### Bulk Update Optimization
+- Use indexed columns in conditions for better performance
+- Group similar updates together
+- Consider using raw SQL expressions for calculated updates
+- Test with small batches first to verify logic
 
-```bash
-# Login to npm
-npm login
+#### Bulk Delete Safety
+- Always test delete conditions with `SELECT` first
+- Use smaller batch sizes for delete operations
+- Consider soft deletes for important data
+- Monitor foreign key constraints
+
+### Error Handling
 
-# Publish (for scoped packages)
-npm publish --access public
+Bulk operations provide detailed error information:
+
+```json
+{
+  "success": false,
+  "error": "Batch 3 failed: Duplicate entry 'user123' for key 'username'",
+  "processed_batches": 2,
+  "total_batches": 5,
+  "successful_operations": 2000,
+  "failed_operations": 1000
+}
 ```
 
-### 4. Users Can Install
+### Performance Monitoring
 
-```bash
-npx @your-username/mcp-mysql mysql://user:pass@localhost:3306/db "list,read,utility"
+Each bulk operation returns performance metrics:
+
+```json
+{
+  "success": true,
+  "total_processed": 10000,
+  "batches_processed": 10,
+  "execution_time_ms": 2500,
+  "average_batch_time_ms": 250,
+  "records_per_second": 4000
+}
 ```
 
 ---
 
-## 🐛 Troubleshooting
+##  Troubleshooting
 
 ### MCP Server Not Connecting
 
@@ -1111,7 +1224,7 @@ MIT License - see [LICENSE](LICENSE) file for details.
 ### Core Features
 - ✅ **Transaction support (BEGIN, COMMIT, ROLLBACK)** - **COMPLETED!**
 - ✅ **Stored procedure execution** - **COMPLETED!**
-- [ ] Bulk operations (batch insert/update/delete)
+- ✅ **Bulk operations (batch insert/update/delete)** - **COMPLETED!**
 - [ ] Query result caching
 - [ ] Advanced query optimization hints
 

package/dist/index.d.ts

@@ -231,6 +231,45 @@ export declare class MySQLMCP {
             categoryStatus: Record<import("./config/featureConfig").ToolCategory, boolean>;
         };
     };
+    /**
+     * Bulk insert multiple records into the specified table
+     */
+    bulkInsert(params: {
+        table_name: string;
+        data: Record<string, any>[];
+        batch_size?: number;
+    }): Promise<{
+        status: string;
+        data?: any;
+        error?: string;
+    }>;
+    /**
+     * Bulk update multiple records with different conditions and data
+     */
+    bulkUpdate(params: {
+        table_name: string;
+        updates: Array<{
+            data: Record<string, any>;
+            conditions: any[];
+        }>;
+        batch_size?: number;
+    }): Promise<{
+        status: string;
+        data?: any;
+        error?: string;
+    }>;
+    /**
+     * Bulk delete records based on multiple condition sets
+     */
+    bulkDelete(params: {
+        table_name: string;
+        condition_sets: any[][];
+        batch_size?: number;
+    }): Promise<{
+        status: string;
+        data?: any;
+        error?: string;
+    }>;
     close(): Promise<void>;
 }
 export default MySQLMCP;

package/dist/index.js

@@ -263,6 +263,27 @@ class MySQLMCP {
             }
         };
     }
+    /**
+     * Bulk insert multiple records into the specified table
+     */
+    async bulkInsert(params) {
+        this.checkToolEnabled('bulk_insert');
+        return this.crudTools.bulkInsert(params);
+    }
+    /**
+     * Bulk update multiple records with different conditions and data
+     */
+    async bulkUpdate(params) {
+        this.checkToolEnabled('bulk_update');
+        return this.crudTools.bulkUpdate(params);
+    }
+    /**
+     * Bulk delete records based on multiple condition sets
+     */
+    async bulkDelete(params) {
+        this.checkToolEnabled('bulk_delete');
+        return this.crudTools.bulkDelete(params);
+    }
     // Close database connection
     async close() {
         const db = connection_1.default.getInstance();

package/dist/mcp-server.js

@@ -182,6 +182,130 @@ const TOOLS = [
             required: ['table_name', 'conditions'],
         },
     },
+    {
+        name: 'bulk_insert',
+        description: 'Bulk insert multiple records into the specified table with batch processing for optimal performance.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                table_name: {
+                    type: 'string',
+                    description: 'Name of the table to insert into',
+                },
+                data: {
+                    type: 'array',
+                    description: 'Array of objects containing column names and values to insert',
+                    minItems: 1,
+                    items: {
+                        type: 'object',
+                        additionalProperties: true,
+                    },
+                },
+                batch_size: {
+                    type: 'number',
+                    description: 'Optional batch size for processing (default: 1000, max: 10000)',
+                    minimum: 1,
+                    maximum: 10000,
+                },
+            },
+            required: ['table_name', 'data'],
+        },
+    },
+    {
+        name: 'bulk_update',
+        description: 'Bulk update multiple records with different conditions and data using batch processing.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                table_name: {
+                    type: 'string',
+                    description: 'Name of the table to update',
+                },
+                updates: {
+                    type: 'array',
+                    description: 'Array of update operations with data and conditions',
+                    minItems: 1,
+                    items: {
+                        type: 'object',
+                        properties: {
+                            data: {
+                                type: 'object',
+                                description: 'Object containing column names and new values',
+                                additionalProperties: true,
+                            },
+                            conditions: {
+                                type: 'array',
+                                description: 'Array of conditions to identify which records to update',
+                                minItems: 1,
+                                items: {
+                                    type: 'object',
+                                    properties: {
+                                        field: { type: 'string' },
+                                        operator: {
+                                            type: 'string',
+                                            enum: ['eq', 'neq', 'gt', 'gte', 'lt', 'lte', 'like', 'in']
+                                        },
+                                        value: {},
+                                    },
+                                    required: ['field', 'operator', 'value'],
+                                },
+                            },
+                        },
+                        required: ['data', 'conditions'],
+                    },
+                },
+                batch_size: {
+                    type: 'number',
+                    description: 'Optional batch size for processing (default: 100, max: 1000)',
+                    minimum: 1,
+                    maximum: 1000,
+                },
+            },
+            required: ['table_name', 'updates'],
+        },
+    },
+    {
+        name: 'bulk_delete',
+        description: 'Bulk delete records based on multiple condition sets using batch processing.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                table_name: {
+                    type: 'string',
+                    description: 'Name of the table to delete from',
+                },
+                condition_sets: {
+                    type: 'array',
+                    description: 'Array of condition sets, each defining records to delete',
+                    minItems: 1,
+                    items: {
+                        type: 'array',
+                        description: 'Array of conditions for this delete operation',
+                        minItems: 1,
+                        items: {
+                            type: 'object',
+                            properties: {
+                                field: { type: 'string' },
+                                operator: {
+                                    type: 'string',
+                                    enum: ['eq', 'neq', 'gt', 'gte', 'lt', 'lte', 'like', 'in']
+                                },
+                                value: {},
+                            },
+                            required: ['field', 'operator', 'value'],
+                        },
+                    },
+                },
+                batch_size: {
+                    type: 'number',
+                    description: 'Optional batch size for processing (default: 100, max: 1000)',
+                    minimum: 1,
+                    maximum: 1000,
+                },
+            },
+            required: ['table_name', 'condition_sets'],
+        },
+    },
     {
         name: 'run_query',
         description: 'Runs a read-only SQL SELECT query with optional parameters. Only SELECT statements are allowed.',
@@ -611,6 +735,15 @@ server.setRequestHandler(types_js_1.CallToolRequestSchema, async (request) => {
             case 'delete_record':
                 result = await mysqlMCP.deleteRecord(args);
                 break;
+            case 'bulk_insert':
+                result = await mysqlMCP.bulkInsert(args);
+                break;
+            case 'bulk_update':
+                result = await mysqlMCP.bulkUpdate(args);
+                break;
+            case 'bulk_delete':
+                result = await mysqlMCP.bulkDelete(args);
+                break;
             case 'run_query':
                 result = await mysqlMCP.runQuery(args);
                 break;

package/dist/tools/crudTools.d.ts

@@ -56,4 +56,43 @@ export declare class CrudTools {
         };
         error?: string;
     }>;
+    /**
+     * Bulk insert multiple records into the specified table
+     */
+    bulkInsert(params: {
+        table_name: string;
+        data: Record<string, any>[];
+        batch_size?: number;
+    }): Promise<{
+        status: string;
+        data?: any;
+        error?: string;
+    }>;
+    /**
+     * Bulk update multiple records with different conditions and data
+     */
+    bulkUpdate(params: {
+        table_name: string;
+        updates: Array<{
+            data: Record<string, any>;
+            conditions: FilterCondition[];
+        }>;
+        batch_size?: number;
+    }): Promise<{
+        status: string;
+        data?: any;
+        error?: string;
+    }>;
+    /**
+     * Bulk delete records based on multiple condition sets
+     */
+    bulkDelete(params: {
+        table_name: string;
+        condition_sets: FilterCondition[][];
+        batch_size?: number;
+    }): Promise<{
+        status: string;
+        data?: any;
+        error?: string;
+    }>;
 }