@berthojoris/mcp-mysql-server 1.2.5 → 1.4.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

@@ -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.
@@ -1116,92 +1366,12 @@ FLUSH PRIVILEGES;
 
 ---
 
-## 📚 Development
-
-### Project Structure
-
-```
-mysql-mcp/
-├── src/
-│   ├── config/         # Configuration and permissions
-│   ├── db/             # Database connection
-│   ├── security/       # Security layer
-│   ├── tools/          # Tool implementations
-│   │   ├── databaseTools.ts   # Database discovery
-│   │   ├── crudTools.ts       # CRUD operations
-│   │   ├── queryTools.ts      # Query execution
-│   │   ├── ddlTools.ts        # DDL operations
-│   │   └── utilityTools.ts    # Utilities
-│   ├── validation/     # Input validation schemas
-│   ├── index.ts        # MySQLMCP class
-│   ├── mcp-server.ts   # MCP protocol server
-│   └── server.ts       # REST API server
-├── bin/
-│   └── mcp-mysql.js    # CLI entry point
-├── dist/               # Compiled JavaScript
-├── .env                # Local environment config
-├── package.json
-├── tsconfig.json
-└── README.md
-```
-
-### Development Commands
-
-```bash
-# Install dependencies
-npm install
-
-# Build TypeScript
-npm run build
-
-# Run in development mode (MCP)
-npm run dev:mcp
-
-# Run in development mode (API)
-npm run dev:api
-
-# Run tests
-npm test
-```
-
----
-
-## 🤝 Contributing
-
-Contributions are welcome!
-
-1. Fork the repository
-2. Create a feature branch: `git checkout -b feature/my-feature`
-3. Make your changes
-4. Build and test: `npm run build`
-5. Commit: `git commit -m "Add my feature"`
-6. Push: `git push origin feature/my-feature`
-7. Submit a pull request
-
----
-
 ## 📄 License
 
 MIT License - see [LICENSE](LICENSE) file for details.
 
 ---
 
-## 🙏 Acknowledgments
-
-- Built with [@modelcontextprotocol/sdk](https://github.com/modelcontextprotocol/typescript-sdk)
-- Compatible with [Claude Desktop](https://claude.ai/), [Cline](https://github.com/cline/cline), [Windsurf](https://codeium.com/windsurf), and other MCP-compatible tools
-- Inspired by the Model Context Protocol specification
-
----
-
-## 💬 Support
-
-- **Issues:** [GitHub Issues](https://github.com/berthojoris/mysql-mcp/issues)
-- **Discussions:** [GitHub Discussions](https://github.com/berthojoris/mysql-mcp/discussions)
-- **Documentation:** This README
-
----
-
 ## 🗺️ Roadmap
 
 ### Core Features
@@ -1228,6 +1398,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/auth/authService.d.ts

@@ -0,0 +1,29 @@
+import { Request, Response, NextFunction } from 'express';
+export interface User {
+    id: string;
+    username: string;
+    role: string;
+}
+export declare class AuthService {
+    /**
+     * Generate a JWT token for a user
+     */
+    generateToken(user: User): string;
+    /**
+     * Verify a JWT token
+     */
+    verifyToken(token: string): User;
+    /**
+     * Middleware to authenticate using JWT
+     */
+    authenticateJWT(req: Request, res: Response, next: NextFunction): void;
+    /**
+     * Middleware to authenticate using API key
+     */
+    authenticateApiKey(req: Request, res: Response, next: NextFunction): void;
+    /**
+     * Login endpoint handler
+     */
+    login(req: Request, res: Response): void;
+}
+export declare const authService: AuthService;

package/dist/auth/authService.js

@@ -0,0 +1,114 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.authService = exports.AuthService = void 0;
+const jsonwebtoken_1 = __importDefault(require("jsonwebtoken"));
+// Environment variables
+const JWT_SECRET = process.env.JWT_SECRET || 'default_secret_change_in_production';
+const JWT_EXPIRES_IN = process.env.JWT_EXPIRES_IN || '24h';
+const API_KEY = process.env.API_KEY;
+class AuthService {
+    /**
+     * Generate a JWT token for a user
+     */
+    generateToken(user) {
+        // Cast to any to bypass TypeScript's strict type checking for JWT
+        return jsonwebtoken_1.default.sign(user, JWT_SECRET, { expiresIn: JWT_EXPIRES_IN });
+    }
+    /**
+     * Verify a JWT token
+     */
+    verifyToken(token) {
+        // Cast to any to bypass TypeScript's strict type checking for JWT
+        return jsonwebtoken_1.default.verify(token, JWT_SECRET);
+    }
+    /**
+     * Middleware to authenticate using JWT
+     */
+    authenticateJWT(req, res, next) {
+        const authHeader = req.headers['authorization'];
+        const token = authHeader && authHeader.split(' ')[1];
+        if (!token) {
+            res.status(401).json({
+                error: {
+                    code: 'AUTH_TOKEN_MISSING',
+                    message: 'Authentication token is required',
+                    details: 'Please provide a valid JWT token in the Authorization header'
+                }
+            });
+            return;
+        }
+        try {
+            const user = this.verifyToken(token);
+            req.user = user;
+            next();
+        }
+        catch (error) {
+            res.status(403).json({
+                error: {
+                    code: 'AUTH_TOKEN_INVALID',
+                    message: 'Invalid or expired token',
+                    details: 'Please provide a valid JWT token'
+                }
+            });
+        }
+    }
+    /**
+     * Middleware to authenticate using API key
+     */
+    authenticateApiKey(req, res, next) {
+        const providedApiKey = req.headers['x-api-key'];
+        if (!API_KEY) {
+            console.warn('API_KEY environment variable is not set');
+            res.status(500).json({
+                error: {
+                    code: 'SERVER_CONFIG_ERROR',
+                    message: 'Server configuration error',
+                    details: 'API key authentication is not properly configured'
+                }
+            });
+            return;
+        }
+        if (!providedApiKey || providedApiKey !== API_KEY) {
+            res.status(401).json({
+                error: {
+                    code: 'INVALID_API_KEY',
+                    message: 'Invalid API key',
+                    details: 'Please provide a valid API key in the X-API-Key header'
+                }
+            });
+            return;
+        }
+        next();
+    }
+    /**
+     * Login endpoint handler
+     */
+    login(req, res) {
+        const { username, password } = req.body;
+        // In a real application, you would validate credentials against a database
+        // This is a simplified example for demonstration purposes
+        if (username === 'admin' && password === 'password') {
+            const user = {
+                id: '1',
+                username: 'admin',
+                role: 'admin'
+            };
+            const token = this.generateToken(user);
+            res.json({ token });
+        }
+        else {
+            res.status(401).json({
+                error: {
+                    code: 'INVALID_CREDENTIALS',
+                    message: 'Invalid username or password',
+                    details: 'Please check your credentials and try again'
+                }
+            });
+        }
+    }
+}
+exports.AuthService = AuthService;
+exports.authService = new AuthService();

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
      */