@berthojoris/mcp-mysql-server 1.2.6 → 1.4.1

package/CHANGELOG.md

@@ -0,0 +1,75 @@
+# Changelog
+
+All notable changes to the MySQL MCP Server will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [1.4.1] - 2025-01-04
+
+### Fixed
+- **Critical Parameter Validation Fix**: Fixed "Invalid parameters: must be object" error that occurred when AI agents called MCP tools without parameters
+  - Applied defensive parameter handling to all 27 tools that accept parameters
+  - Tools now properly handle cases where MCP SDK passes `undefined` or `null` instead of empty object `{}`
+  - Pattern applied: `(args || {})` ensures parameters are always objects before validation
+  - No breaking changes - existing valid calls continue to work exactly as before
+
+### Changed
+- Enhanced parameter handling in `mcp-server.ts` for all tool handlers:
+  - Database Tools: `list_tables`, `read_table_schema`, `get_table_relationships`
+  - CRUD Tools: `create_record`, `read_records`, `update_record`, `delete_record`, `bulk_insert`, `bulk_update`, `bulk_delete`
+  - Query Tools: `run_query`, `execute_sql`, `execute_ddl`
+  - DDL Tools: `create_table`, `alter_table`, `drop_table`
+  - Transaction Tools: `begin_transaction`, `commit_transaction`, `rollback_transaction`, `execute_in_transaction`
+  - Stored Procedure Tools: `list_stored_procedures`, `get_stored_procedure_info`, `execute_stored_procedure`, `create_stored_procedure`, `drop_stored_procedure`, `show_create_procedure`
+  - Data Export Tools: `export_table_to_csv`, `export_query_to_csv`
+
+### Documentation
+- Added troubleshooting section in README.md for parameter validation errors
+- Created CHANGELOG.md to track version changes
+- Documented the fix and upgrade path for users experiencing this issue
+
+## [1.4.0] - 2024-12-XX
+
+### Added
+- Data Export Tools (`export_table_to_csv`, `export_query_to_csv`)
+- Bulk Operations (`bulk_insert`, `bulk_update`, `bulk_delete`)
+- Transaction Management (5 tools)
+- Stored Procedure Support (5 tools)
+- Enhanced permission error messages
+- Per-project permission configuration
+
+### Changed
+- Improved security with fine-grained permission system
+- Better error handling and user feedback
+- Performance optimizations for bulk operations
+
+## [1.3.0] - 2024-XX-XX
+
+### Added
+- DDL Operations (Create, Alter, Drop Table)
+- Schema Management Tools
+- Permission-based access control
+- MCP protocol support
+
+## [1.2.0] - 2024-XX-XX
+
+### Added
+- REST API mode
+- Connection testing utilities
+- Foreign key relationship discovery
+
+## [1.1.0] - 2024-XX-XX
+
+### Added
+- CRUD operations
+- Custom SQL query execution
+- Parameterized queries
+
+## [1.0.0] - 2024-XX-XX
+
+### Added
+- Initial release
+- Basic database listing
+- Table schema inspection
+- MySQL connection support

package/README.md

@@ -157,12 +157,14 @@ The MCP server provides **30 powerful tools**:
 | `drop_table` | Delete tables | `ddl` permission |
 | `execute_ddl` | Execute raw DDL SQL (CREATE, ALTER, DROP, TRUNCATE, RENAME) | `ddl` permission |
 
-### Utilities (2 tools)
+### Utilities (4 tools)
 
 | Tool | Description |
 |------|-------------|
 | `test_connection` | Test database connectivity and measure latency |
 | `describe_connection` | Get current connection information |
+| `export_table_to_csv` | Export table data to CSV format with optional filtering, pagination, and sorting |
+| `export_query_to_csv` | Export the results of a SELECT query to CSV format |
 
 ### Transaction Management (5 tools)
 
@@ -281,6 +283,120 @@ 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"
+  ]
+}
+```
+
+---
+
 ## 🏗️ DDL Operations
 
 DDL (Data Definition Language) operations allow AI to create, modify, and delete tables.
@@ -366,6 +482,140 @@ DDL operations are **disabled by default** for safety. Add `ddl` to permissions
 
 ---
 
+## 📤 Data Export Tools
+
+The MySQL MCP Server provides powerful data export capabilities, allowing AI agents to export database content in CSV format for analysis, reporting, and data sharing.
+
+### Data Export Tools Overview
+
+- **`export_table_to_csv`** - Export all or filtered data from a table to CSV format
+- **`export_query_to_csv`** - Export the results of a custom SELECT query to CSV format
+
+Both tools support:
+- Filtering data with conditions
+- Pagination for large datasets
+- Sorting results
+- Optional column headers
+- Proper CSV escaping for special characters
+
+### Data Export Tool Examples
+
+#### Export Table to CSV
+
+**User prompt:** *"Export the first 100 users ordered by registration date to CSV"*
+
+**AI will execute:**
+```json
+{
+  "tool": "export_table_to_csv",
+  "arguments": {
+    "table_name": "users",
+    "sorting": {
+      "field": "registration_date",
+      "direction": "desc"
+    },
+    "pagination": {
+      "page": 1,
+      "limit": 100
+    },
+    "include_headers": true
+  }
+}
+```
+
+#### Export Filtered Data to CSV
+
+**User prompt:** *"Export all users from the marketing department to CSV"*
+
+**AI will execute:**
+```json
+{
+  "tool": "export_table_to_csv",
+  "arguments": {
+    "table_name": "users",
+    "filters": [
+      {
+        "field": "department",
+        "operator": "eq",
+        "value": "marketing"
+      }
+    ],
+    "include_headers": true
+  }
+}
+```
+
+#### Export Query Results to CSV
+
+**User prompt:** *"Export a report of total sales by product category to CSV"*
+
+**AI will execute:**
+```json
+{
+  "tool": "export_query_to_csv",
+  "arguments": {
+    "query": "SELECT category, SUM(sales_amount) as total_sales FROM sales GROUP BY category ORDER BY total_sales DESC",
+    "include_headers": true
+  }
+}
+```
+
+### Data Export Best Practices
+
+1. ✅ **Use filtering** - Export only the data you need to reduce file size
+2. ✅ **Implement pagination** - For large datasets, use pagination to avoid memory issues
+3. ✅ **Include headers** - Make CSV files more understandable with column headers
+4. ✅ **Test with small datasets first** - Verify export format before processing large amounts of data
+5. ✅ **Use proper permissions** - Data export tools require `utility` permission
+
+### Common Data Export Patterns
+
+**Pattern 1: Simple Table Export**
+```json
+{
+  "tool": "export_table_to_csv",
+  "arguments": {
+    "table_name": "products",
+    "include_headers": true
+  }
+}
+```
+
+**Pattern 2: Filtered and Sorted Export**
+```json
+{
+  "tool": "export_table_to_csv",
+  "arguments": {
+    "table_name": "orders",
+    "filters": [
+      {
+        "field": "order_date",
+        "operator": "gte",
+        "value": "2023-01-01"
+      }
+    ],
+    "sorting": {
+      "field": "order_date",
+      "direction": "desc"
+    },
+    "include_headers": true
+  }
+}
+```
+
+**Pattern 3: Complex Query Export**
+```json
+{
+  "tool": "export_query_to_csv",
+  "arguments": {
+    "query": "SELECT u.name, u.email, COUNT(o.id) as order_count FROM users u LEFT JOIN orders o ON u.id = o.user_id GROUP BY u.id HAVING order_count > 5",
+    "include_headers": true
+  }
+}
+```
+
+---
+
 ## 💰 Transaction Management
 
 The MySQL MCP Server provides full ACID transaction support, allowing you to group multiple database operations into atomic units.
@@ -1114,6 +1364,40 @@ FLUSH PRIVILEGES;
 }
 ```
 
+### Parameter Validation Errors
+
+**Problem:** "Invalid parameters: must be object" error
+
+**Symptoms:**
+- Tools fail when called without parameters
+- Error message: `Error: Invalid parameters: [{"instancePath":"","schemaPath":"#/type","keyword":"type","params":{"type":"object"},"message":"must be object"}]`
+- Occurs especially with tools that have optional parameters like `list_tables`, `begin_transaction`, `list_stored_procedures`
+
+**Cause:**
+This error occurred in earlier versions (< 1.4.1) when AI agents called MCP tools without providing parameters. The MCP SDK sometimes passes `undefined` or `null` instead of an empty object `{}`, causing JSON schema validation to fail.
+
+**Solution:**
+✅ **Fixed in version 1.4.1+** - All 33 tools now include defensive parameter handling that automatically converts `undefined`/`null` to empty objects.
+
+**If you're still experiencing this issue:**
+1. Update to the latest version:
+   ```bash
+   npx -y @berthojoris/mcp-mysql-server@latest mysql://user:pass@localhost:3306/db "permissions"
+   ```
+
+2. If using global installation:
+   ```bash
+   npm update -g @berthojoris/mcp-mysql-server
+   ```
+
+3. Restart your AI agent after updating
+
+**Technical Details:**
+- All tool handlers now use defensive pattern: `(args || {})` to ensure parameters are always objects
+- This fix applies to all 27 tools that accept parameters
+- Tools with no parameters (like `list_databases`, `test_connection`) were not affected
+- No breaking changes - existing valid calls continue to work exactly as before
+
 ---
 
 ## 📄 License
@@ -1148,6 +1432,45 @@ MIT License - see [LICENSE](LICENSE) file for details.
 - [ ] Oracle Database adapter
 - [ ] SQL Server adapter
 
+### Recommended Implementation Order
+
+#### **Phase 1: Performance & Monitoring** 🚀
+- [ ] **Query result caching** - Dramatically improve response times for repeated queries
+- [ ] **Performance metrics** - Track query execution times and database performance
+- [ ] **Connection pool monitoring** - Monitor database connection health and usage
+- [ ] **Database health checks** - Comprehensive system health monitoring
+
+#### **Phase 2: Data Management** 📊
+- [ ] **Database backup and restore tools** - Essential for production data safety
+- [ ] **Data migration utilities** - Move data between databases and environments
+- [ ] **Enhanced export/import** - Support for JSON, XML, Excel formats
+- [ ] **Query history & analytics** - Track and analyze database usage patterns
+
+#### **Phase 3: Enterprise Features** 🏢
+- [ ] **Audit logging and compliance** - Track all database operations for security
+- [ ] **Schema versioning and migrations** - Version control for database schema changes
+- [ ] **Query optimization** - Automatic query analysis and optimization suggestions
+- [ ] **Advanced security features** - Enhanced access control and monitoring
+
+#### **Phase 4: Multi-Database Support** 🌐
+- [ ] **PostgreSQL adapter** - Extend support to PostgreSQL databases
+- [ ] **MongoDB adapter** - Add NoSQL document database support
+- [ ] **SQLite adapter** - Support for lightweight embedded databases
+- [ ] **Database-agnostic operations** - Unified API across different database types
+
+#### **Implementation Priority Matrix**
+
+| Feature | Impact | Effort | Priority |
+|---------|--------|--------|----------|
+| Query Result Caching | High | Medium | 1 |
+| Database Backup/Restore | High | High | 2 |
+| Performance Monitoring | High | Medium | 3 |
+| Data Migration | High | High | 4 |
+| Query Optimization | Medium | Medium | 5 |
+| PostgreSQL Adapter | High | High | 6 |
+| Audit Logging | Medium | Low | 7 |
+| Schema Versioning | Medium | Medium | 8 |
+
 ---
 
 **Made with ❤️ for the AI community**

package/dist/config/featureConfig.d.ts

@@ -22,6 +22,7 @@ export declare const toolCategoryMap: Record<string, ToolCategory>;
  */
 export declare class FeatureConfig {
     private enabledCategories;
+    private originalConfigString;
     constructor(configStr?: string);
     /**
      * Parse MCP_CONFIG from provided string or environment variables
@@ -35,6 +36,10 @@ export declare class FeatureConfig {
      * Check if a specific tool is enabled
      */
     isToolEnabled(toolName: string): boolean;
+    /**
+     * Get detailed permission error message for a specific tool
+     */
+    getPermissionError(toolName: string): string;
     /**
      * Check if a category is enabled
      */

package/dist/config/featureConfig.js

@@ -36,6 +36,10 @@ exports.toolCategoryMap = {
     'readRecords': ToolCategory.READ,
     'updateRecord': ToolCategory.UPDATE,
     'deleteRecord': ToolCategory.DELETE,
+    // Bulk operations
+    'bulkInsert': ToolCategory.CREATE,
+    'bulkUpdate': ToolCategory.UPDATE,
+    'bulkDelete': ToolCategory.DELETE,
     // Query tools
     'runQuery': ToolCategory.READ,
     'executeSql': ToolCategory.EXECUTE,
@@ -48,6 +52,8 @@ exports.toolCategoryMap = {
     'describeConnection': ToolCategory.UTILITY,
     'testConnection': ToolCategory.UTILITY,
     'getTableRelationships': ToolCategory.UTILITY,
+    'exportTableToCSV': ToolCategory.UTILITY,
+    'exportQueryToCSV': ToolCategory.UTILITY,
     // Transaction tools
     'beginTransaction': ToolCategory.TRANSACTION,
     'commitTransaction': ToolCategory.TRANSACTION,
@@ -67,6 +73,7 @@ exports.toolCategoryMap = {
  */
 class FeatureConfig {
     constructor(configStr) {
+        this.originalConfigString = configStr || process.env.MCP_CONFIG || '';
         this.enabledCategories = this.parseConfig(configStr);
     }
     /**
@@ -88,6 +95,7 @@ class FeatureConfig {
      * Update configuration at runtime
      */
     setConfig(configStr) {
+        this.originalConfigString = configStr;
         this.enabledCategories = this.parseConfig(configStr);
     }
     /**
@@ -102,6 +110,57 @@ class FeatureConfig {
         }
         return this.enabledCategories.has(category);
     }
+    /**
+     * Get detailed permission error message for a specific tool
+     */
+    getPermissionError(toolName) {
+        const category = exports.toolCategoryMap[toolName];
+        if (!category) {
+            return `Unknown tool '${toolName}'. This tool is not recognized by the MCP server.`;
+        }
+        const isAllPermissions = !this.originalConfigString.trim();
+        const currentPermissions = isAllPermissions ? 'all' : this.originalConfigString;
+        const actionDescriptions = {
+            [ToolCategory.LIST]: 'list databases and tables',
+            [ToolCategory.READ]: 'read data from tables',
+            [ToolCategory.CREATE]: 'create new records',
+            [ToolCategory.UPDATE]: 'update existing records',
+            [ToolCategory.DELETE]: 'delete records',
+            [ToolCategory.EXECUTE]: 'execute custom SQL queries',
+            [ToolCategory.DDL]: 'create, alter, or drop tables (schema changes)',
+            [ToolCategory.UTILITY]: 'use utility functions',
+            [ToolCategory.TRANSACTION]: 'manage database transactions',
+            [ToolCategory.PROCEDURE]: 'manage stored procedures'
+        };
+        const toolDescriptions = {
+            'createTable': 'create new tables',
+            'alterTable': 'modify table structure',
+            'dropTable': 'delete tables',
+            'executeDdl': 'execute DDL statements',
+            'createRecord': 'insert new records',
+            'updateRecord': 'update existing records',
+            'deleteRecord': 'delete records',
+            'bulkInsert': 'insert multiple records in batches',
+            'bulkUpdate': 'update multiple records in batches',
+            'bulkDelete': 'delete multiple records in batches',
+            'executeSql': 'execute custom SQL statements',
+            'runQuery': 'run SELECT queries',
+            'beginTransaction': 'start database transactions',
+            'commitTransaction': 'commit database transactions',
+            'rollbackTransaction': 'rollback database transactions',
+            'executeInTransaction': 'execute queries within transactions',
+            'createStoredProcedure': 'create stored procedures',
+            'dropStoredProcedure': 'delete stored procedures',
+            'executeStoredProcedure': 'execute stored procedures',
+            'exportTableToCSV': 'export table data to CSV',
+            'exportQueryToCSV': 'export query results to CSV'
+        };
+        const toolDescription = toolDescriptions[toolName] || actionDescriptions[category];
+        const requiredPermission = category;
+        return `Permission denied: Cannot ${toolDescription}. ` +
+            `This action requires '${requiredPermission}' permission, but your current MCP configuration only allows: ${currentPermissions}. ` +
+            `To enable this feature, update your MCP server configuration to include '${requiredPermission}' in the permissions list.`;
+    }
     /**
      * Check if a category is enabled
      */

package/dist/index.d.ts

@@ -10,6 +10,7 @@ export declare class MySQLMCP {
     private ddlTools;
     private transactionTools;
     private storedProcedureTools;
+    private dataExportTools;
     private security;
     private featureConfig;
     constructor(permissionsConfig?: string);
@@ -224,6 +225,32 @@ export declare class MySQLMCP {
         data?: any;
         error?: string;
     }>;
+    exportTableToCSV(params: {
+        table_name: string;
+        filters?: any[];
+        pagination?: {
+            page: number;
+            limit: number;
+        };
+        sorting?: {
+            field: string;
+            direction: 'asc' | 'desc';
+        };
+        include_headers?: boolean;
+    }): Promise<{
+        status: string;
+        data?: any;
+        error?: string;
+    }>;
+    exportQueryToCSV(params: {
+        query: string;
+        params?: any[];
+        include_headers?: boolean;
+    }): Promise<{
+        status: string;
+        data?: any;
+        error?: string;
+    }>;
     getFeatureStatus(): {
         status: string;
         data: {

package/dist/index.js

@@ -11,6 +11,7 @@ const utilityTools_1 = require("./tools/utilityTools");
 const ddlTools_1 = require("./tools/ddlTools");
 const transactionTools_1 = require("./tools/transactionTools");
 const storedProcedureTools_1 = require("./tools/storedProcedureTools");
+const dataExportTools_1 = require("./tools/dataExportTools");
 const securityLayer_1 = __importDefault(require("./security/securityLayer"));
 const connection_1 = __importDefault(require("./db/connection"));
 const featureConfig_1 = require("./config/featureConfig");
@@ -29,13 +30,14 @@ class MySQLMCP {
         this.ddlTools = new ddlTools_1.DdlTools();
         this.transactionTools = new transactionTools_1.TransactionTools();
         this.storedProcedureTools = new storedProcedureTools_1.StoredProcedureTools(this.security);
+        this.dataExportTools = new dataExportTools_1.DataExportTools(this.security);
     }
     // Helper method to check if tool is enabled
     checkToolEnabled(toolName) {
         if (!this.featureConfig.isToolEnabled(toolName)) {
             return {
                 enabled: false,
-                error: `Tool '${toolName}' is disabled in the current configuration. Enabled categories: ${this.featureConfig.getEnabledCategories().join(', ')}`
+                error: this.featureConfig.getPermissionError(toolName)
             };
         }
         return { enabled: true };
@@ -253,6 +255,21 @@ class MySQLMCP {
         }
         return await this.storedProcedureTools.showCreateProcedure(params);
     }
+    // Data Export Tools
+    async exportTableToCSV(params) {
+        const check = this.checkToolEnabled('exportTableToCSV');
+        if (!check.enabled) {
+            return { status: 'error', error: check.error };
+        }
+        return await this.dataExportTools.exportTableToCSV(params);
+    }
+    async exportQueryToCSV(params) {
+        const check = this.checkToolEnabled('exportQueryToCSV');
+        if (!check.enabled) {
+            return { status: 'error', error: check.error };
+        }
+        return await this.dataExportTools.exportQueryToCSV(params);
+    }
     // Get feature configuration status
     getFeatureStatus() {
         return {