@berthojoris/mcp-mysql-server 1.8.0 → 1.9.0

package/README.md

@@ -1,6 +1,6 @@
 # MySQL MCP Server
 
-A fully-featured **Model Context Protocol (MCP)** server for MySQL database integration with AI agents like Claude Desktop, Cline, Windsurf, and other MCP-compatible tools.
+A fully-featured **Model Context Protocol (MCP)** server for MySQL database integration with AI agents like Claude Code, Cursor, Windsurf, Zed, Cline, Kilo Code, Roo Code, Gemini CLI, and other MCP-compatible tools.
 
 [![npm version](https://img.shields.io/npm/v/@berthojoris/mcp-mysql-server)](https://www.npmjs.com/package/@berthojoris/mcp-mysql-server)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
@@ -9,7 +9,7 @@ A fully-featured **Model Context Protocol (MCP)** server for MySQL database inte
 
 ## 🌟 Features
 
-- ✅ **Full MCP Protocol Support** - Works with Claude Desktop, Cline, Windsurf, and any MCP-compatible AI agent
+- ✅ **Full MCP Protocol Support** - Works with Claude Code, Cursor, Windsurf, Zed, Cline, Kilo Code, Roo Code, Gemini CLI, and any MCP-compatible AI agent
 - 🔐 **Secure by Default** - Parameterized queries, SQL injection protection, permission-based access control
 - 🛠️ **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
@@ -21,6 +21,120 @@ A fully-featured **Model Context Protocol (MCP)** server for MySQL database inte
 
 ---
 
+## 🔄 MySQL MCP vs Manual Database Access: A Comprehensive Comparison
+
+This MySQL MCP is a **powerful intermediary layer** between AI assistants and MySQL databases. Here's how it compares to manual database access:
+
+### Data Access & Querying
+
+| Feature | MySQL MCP | Manual Database Access |
+|---------|-----------|------------------------|
+| **Query Execution** | AI can run SELECT/INSERT/UPDATE/DELETE via natural language | Requires manual SQL writing in terminal/client |
+| **Parameterized Queries** | Automatic protection against SQL injection | Must manually parameterize |
+| **Bulk Operations** | Up to 10,000 records per batch with auto-batching | Manual scripting required |
+| **Query Caching** | Built-in LRU cache with TTL | Must implement yourself |
+
+### Data Analysis
+
+| Feature | MySQL MCP | Manual Database Access |
+|---------|-----------|------------------------|
+| **Query Analysis** | Auto-detects complexity, joins, bottlenecks | Run EXPLAIN manually, interpret yourself |
+| **Optimization Hints** | Auto-generates MySQL 8.0+ optimizer hints | Must know hint syntax |
+| **Execution Plans** | Get EXPLAIN in JSON/TREE/TRADITIONAL formats | Run EXPLAIN manually |
+| **Server Diagnostics** | 9 tools for status, processes, replication | Multiple manual commands |
+
+### Data Validation
+
+| Feature | MySQL MCP | Manual Database Access |
+|---------|-----------|------------------------|
+| **Input Validation** | Automatic type/length/format validation | Manual validation code |
+| **SQL Injection Prevention** | Multi-layer protection (identifiers, keywords, params) | Depends on your code |
+| **Permission Enforcement** | 10 granular permission categories | Configure in MySQL grants |
+| **Dangerous Query Blocking** | Blocks GRANT, DROP USER, system schema access | No automatic protection |
+
+### Schema Inspection
+
+| Feature | MySQL MCP | Manual Database Access |
+|---------|-----------|------------------------|
+| **Table Structure** | One command shows columns, keys, indexes | Multiple SHOW/DESCRIBE commands |
+| **Foreign Key Discovery** | Auto-discovers relationships | Manual INFORMATION_SCHEMA queries |
+| **Full Schema Export** | Get entire DB schema (tables, views, procs, triggers) | Multiple manual exports |
+| **Object Comparison** | Compare table structures automatically | Manual diff work |
+
+### Debugging & Diagnostics
+
+| Feature | MySQL MCP | Manual Database Access |
+|---------|-----------|------------------------|
+| **Query Logging** | Automatic logging with timing, params, status | Enable general_log manually |
+| **Formatted Output** | SQL formatted with highlighted keywords | Raw output |
+| **Process Management** | View/kill processes via simple commands | SHOW PROCESSLIST + KILL manually |
+| **Cache Monitoring** | Hit rate, memory usage, statistics | No built-in tracking |
+
+### Advanced Operations
+
+| Feature | MySQL MCP | Manual Database Access |
+|---------|-----------|------------------------|
+| **Transactions** | Begin/Commit/Rollback via commands | Manual SQL |
+| **Stored Procedures** | Create, execute, manage with parameter handling | Write DDL manually |
+| **Data Migration** | Copy, move, clone, sync tables with one command | Complex scripts required |
+| **Backup/Restore** | Full DB or table backup/restore | mysqldump + manual restore |
+| **Import/Export** | CSV, JSON, SQL formats supported | Manual scripting |
+
+### Key Benefits of Using This MCP
+
+1. **Natural Language Interface** - Ask Claude "show me all users with orders > $100" instead of writing SQL
+
+2. **Built-in Security** - 5+ validation layers protect against:
+   - SQL injection
+   - Privilege escalation
+   - Cross-database access
+   - Dangerous operations
+
+3. **Audit Trail** - Every query automatically logged with timing and parameters
+
+4. **100 Tools in 16 Categories** - Covers virtually every database task
+
+5. **Permission Granularity** - Give AI read-only access in production, full access in dev
+
+6. **Error Handling** - Detailed, human-readable error messages
+
+### Example Workflows
+
+**Without MCP (Manual):**
+```sql
+-- Connect to MySQL client
+mysql -u user -p database
+-- Write schema query
+DESCRIBE users;
+SHOW INDEX FROM users;
+-- Write analysis query  
+EXPLAIN SELECT * FROM users WHERE email LIKE '%@gmail.com';
+-- Check if safe, then run
+SELECT * FROM users WHERE email LIKE '%@gmail.com';
+```
+
+**With MCP (AI-Assisted):**
+> "Show me the users table structure and find all Gmail users"
+- AI calls `read_table_schema`, `explain_query`, `read_records`
+- Returns formatted results with execution time
+- All queries logged, validated, parameterized automatically
+
+### When to Use This MCP
+
+| Use Case | Recommendation |
+|----------|----------------|
+| Quick data lookups | MCP - faster, safer |
+| Complex analysis | MCP - AI can iterate and refine |
+| Schema exploration | MCP - comprehensive tools |
+| Production debugging | MCP with read-only permissions |
+| Bulk data operations | MCP - auto-batching |
+| Data migrations | MCP - 5 migration tools |
+| Learning SQL | Both - MCP shows what it executes |
+
+This MCP transforms database work from "write SQL, hope it's safe, interpret results" to "describe what you need, get validated results with full audit trail."
+
+---
+
 ## 📦 Installation
 
 ### Option 1: Quick Start (npx)
@@ -65,13 +179,13 @@ npm run build
 
 ### 3. Configure AI Agent
 
-#### Claude Desktop
+This MCP server works with multiple AI coding assistants. Below are configuration examples for each platform.
+
+#### Claude Code (CLI)
 
-**Location:**
-- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
-- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
+Claude Code uses a `.mcp.json` file in your project root or home directory.
 
-**Configuration (using npx - recommended):**
+**Project-level config (`.mcp.json` in project root):**
 
 ```json
 {
@@ -89,7 +203,249 @@ npm run build
 }
 ```
 
-**Configuration (using local path - for development):**
+**Global config (`~/.mcp.json`):**
+
+```json
+{
+  "mcpServers": {
+    "mysql": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "@berthojoris/mcp-mysql-server",
+        "mysql://user:password@localhost:3306/database",
+        "list,read,create,update,delete,ddl"
+      ]
+    }
+  }
+}
+```
+
+#### Cursor
+
+Cursor uses `.cursor/mcp.json` in your project root.
+
+**Configuration (`.cursor/mcp.json`):**
+
+```json
+{
+  "mcpServers": {
+    "mysql": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "@berthojoris/mcp-mysql-server",
+        "mysql://user:password@localhost:3306/database",
+        "list,read,utility"
+      ]
+    }
+  }
+}
+```
+
+#### Windsurf
+
+Windsurf uses `~/.codeium/windsurf/mcp_config.json`.
+
+**Configuration:**
+
+```json
+{
+  "mcpServers": {
+    "mysql": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "@berthojoris/mcp-mysql-server",
+        "mysql://user:password@localhost:3306/database",
+        "list,read,utility"
+      ]
+    }
+  }
+}
+```
+
+#### Cline (VS Code Extension)
+
+Add to Cline MCP settings in VS Code settings or cline config file.
+
+**Configuration:**
+
+```json
+{
+  "mcpServers": {
+    "mysql": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "@berthojoris/mcp-mysql-server",
+        "mysql://user:password@localhost:3306/database",
+        "list,read,utility"
+      ]
+    }
+  }
+}
+```
+
+#### Gemini CLI
+
+Gemini CLI uses `~/.gemini/settings.json`.
+
+**Configuration:**
+
+```json
+{
+  "mcpServers": {
+    "mysql": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "@berthojoris/mcp-mysql-server",
+        "mysql://user:password@localhost:3306/database",
+        "list,read,utility"
+      ]
+    }
+  }
+}
+```
+
+#### Trae AI
+
+Trae AI uses MCP configuration in its settings.
+
+**Configuration:**
+
+```json
+{
+  "mcpServers": {
+    "mysql": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "@berthojoris/mcp-mysql-server",
+        "mysql://user:password@localhost:3306/database",
+        "list,read,utility"
+      ]
+    }
+  }
+}
+```
+
+#### Qwen Code
+
+Qwen Code supports MCP servers with standard configuration.
+
+**Configuration:**
+
+```json
+{
+  "mcpServers": {
+    "mysql": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "@berthojoris/mcp-mysql-server",
+        "mysql://user:password@localhost:3306/database",
+        "list,read,utility"
+      ]
+    }
+  }
+}
+```
+
+#### Droid CLI
+
+Droid CLI uses MCP configuration in its settings file.
+
+**Configuration:**
+
+```json
+{
+  "mcpServers": {
+    "mysql": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "@berthojoris/mcp-mysql-server",
+        "mysql://user:password@localhost:3306/database",
+        "list,read,utility"
+      ]
+    }
+  }
+}
+```
+
+#### Zed IDE
+
+Zed IDE uses `~/.config/zed/settings.json` for MCP configuration.
+
+**Configuration:**
+
+```json
+{
+  "context_servers": {
+    "mysql": {
+      "command": {
+        "path": "npx",
+        "args": [
+          "-y",
+          "@berthojoris/mcp-mysql-server",
+          "mysql://user:password@localhost:3306/database",
+          "list,read,utility"
+        ]
+      }
+    }
+  }
+}
+```
+
+#### Kilo Code (VS Code Extension)
+
+Kilo Code is a VS Code extension that supports MCP servers.
+
+**Configuration:**
+
+```json
+{
+  "mcpServers": {
+    "mysql": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "@berthojoris/mcp-mysql-server",
+        "mysql://user:password@localhost:3306/database",
+        "list,read,utility"
+      ]
+    }
+  }
+}
+```
+
+#### Roo Code (VS Code Extension)
+
+Roo Code is a VS Code extension with MCP support.
+
+**Configuration:**
+
+```json
+{
+  "mcpServers": {
+    "mysql": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "@berthojoris/mcp-mysql-server",
+        "mysql://user:password@localhost:3306/database",
+        "list,read,utility"
+      ]
+    }
+  }
+}
+```
+
+#### Local Path Configuration (for development)
+
+If you've cloned the repository locally:
 
 ```json
 {
@@ -97,7 +453,7 @@ npm run build
     "mysql": {
       "command": "node",
       "args": [
-        "C:\\DEKSTOP\\MCP\\mcp_mysql\\bin\\mcp-mysql.js",
+        "/path/to/mcp_mysql/bin/mcp-mysql.js",
         "mysql://user:password@localhost:3306/database",
         "list,read,utility"
       ]
@@ -106,7 +462,9 @@ npm run build
 }
 ```
 
-**Configuration (using environment variables - alternative local approach):**
+#### Environment Variables Configuration
+
+Alternative approach using environment variables:
 
 ```json
 {
@@ -114,13 +472,13 @@ npm run build
     "mysql": {
       "command": "node",
       "args": [
-        "C:\\DEKSTOP\\MCP\\mcp_mysql\\dist\\mcp-server.js"
+        "/path/to/mcp_mysql/dist/mcp-server.js"
       ],
       "env": {
         "DB_HOST": "localhost",
         "DB_PORT": "3306",
         "DB_USER": "root",
-        "DB_PASSWORD": "",
+        "DB_PASSWORD": "your_password",
         "DB_NAME": "your_database",
         "MCP_PERMISSIONS": "list,read,utility"
       }
@@ -129,14 +487,6 @@ npm run build
 }
 ```
 
-#### Cline (VS Code Extension)
-
-Add to Cline MCP settings (same JSON format as Claude Desktop).
-
-#### Windsurf
-
-Add to Windsurf MCP settings (same JSON format as Claude Desktop).
-
 ### 4. Restart AI Agent
 
 Completely restart your AI agent application to load the MCP server.
@@ -227,7 +577,7 @@ Use the local path approach when you:
 
 ---
 
-##  Permission System
+## 🔐 Permission System
 
 ### Permission Categories
 
@@ -541,7 +891,7 @@ The MCP server provides **100 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!
+### Data Migration (5 tools)
 
 | Tool | Description | Requires |
 |------|-------------|----------|
@@ -551,6 +901,20 @@ The MCP server provides **100 powerful tools**:
 | `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 |
 
+### Schema Versioning & Migrations (9 tools) - NEW!
+
+| Tool | Description | Requires |
+|------|-------------|----------|
+| `init_migrations_table` | Initialize the migrations tracking table | `ddl` permission |
+| `create_migration` | Create a new migration with up/down SQL | `ddl` permission |
+| `apply_migrations` | Apply pending migrations (with dry-run support) | `ddl` permission |
+| `rollback_migration` | Rollback applied migrations by steps or version | `ddl` permission |
+| `get_migration_status` | Get migration history and status | `list` permission |
+| `get_schema_version` | Get current schema version | `list` permission |
+| `validate_migrations` | Validate migrations for issues | `list` permission |
+| `reset_failed_migration` | Reset failed migration to pending | `ddl` permission |
+| `generate_migration_from_diff` | Generate migration from table comparison | `ddl` permission |
+
 ---
 
 ## 📚 Detailed Documentation
@@ -562,6 +926,7 @@ For comprehensive documentation on all features, please see **[DOCUMENTATIONS.md
 - 📥 **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
+- 🔄 **Schema Versioning & Migrations** - Version control for database schema changes
 - 💎 **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

@@ -147,6 +147,16 @@ exports.toolCategoryMap = {
     cloneTable: ToolCategory.DDL,
     compareTableStructure: ToolCategory.LIST,
     syncTableData: ToolCategory.UPDATE,
+    // Schema versioning and migrations tools
+    initMigrationsTable: ToolCategory.DDL,
+    createMigration: ToolCategory.DDL,
+    applyMigrations: ToolCategory.DDL,
+    rollbackMigration: ToolCategory.DDL,
+    getMigrationStatus: ToolCategory.LIST,
+    getSchemaVersion: ToolCategory.LIST,
+    validateMigrations: ToolCategory.LIST,
+    resetFailedMigration: ToolCategory.DDL,
+    generateMigrationFromDiff: ToolCategory.DDL,
 };
 /**
  * Class to manage feature configuration based on runtime or environment variables

package/dist/index.d.ts

@@ -20,6 +20,7 @@ export declare class MySQLMCP {
     private processTools;
     private backupRestoreTools;
     private migrationTools;
+    private schemaVersioningTools;
     private security;
     private featureConfig;
     constructor(permissionsConfig?: string);
@@ -463,6 +464,122 @@ export declare class MySQLMCP {
         error?: string;
         queryLog?: string;
     }>;
+    /**
+     * Initialize the migrations tracking table
+     */
+    initMigrationsTable(params: {
+        database?: string;
+    }): Promise<{
+        status: string;
+        data?: any;
+        error?: string;
+        queryLog?: string;
+    }>;
+    /**
+     * Create a new migration
+     */
+    createMigration(params: {
+        name: string;
+        up_sql: string;
+        down_sql?: string;
+        description?: string;
+        version?: string;
+        database?: string;
+    }): Promise<{
+        status: string;
+        data?: any;
+        error?: string;
+        queryLog?: string;
+    }>;
+    /**
+     * Apply pending migrations
+     */
+    applyMigrations(params: {
+        target_version?: string;
+        dry_run?: boolean;
+        database?: string;
+    }): Promise<{
+        status: string;
+        data?: any;
+        error?: string;
+        queryLog?: string;
+    }>;
+    /**
+     * Rollback migrations
+     */
+    rollbackMigration(params: {
+        target_version?: string;
+        steps?: number;
+        dry_run?: boolean;
+        database?: string;
+    }): Promise<{
+        status: string;
+        data?: any;
+        error?: string;
+        queryLog?: string;
+    }>;
+    /**
+     * Get migration status and history
+     */
+    getMigrationStatus(params: {
+        version?: string;
+        status?: "pending" | "applied" | "failed" | "rolled_back";
+        limit?: number;
+        database?: string;
+    }): Promise<{
+        status: string;
+        data?: any;
+        error?: string;
+        queryLog?: string;
+    }>;
+    /**
+     * Get current schema version
+     */
+    getSchemaVersion(params: {
+        database?: string;
+    }): Promise<{
+        status: string;
+        data?: any;
+        error?: string;
+        queryLog?: string;
+    }>;
+    /**
+     * Validate migrations for issues
+     */
+    validateMigrations(params: {
+        database?: string;
+    }): Promise<{
+        status: string;
+        data?: any;
+        error?: string;
+        queryLog?: string;
+    }>;
+    /**
+     * Reset a failed migration to pending status
+     */
+    resetFailedMigration(params: {
+        version: string;
+        database?: string;
+    }): Promise<{
+        status: string;
+        data?: any;
+        error?: string;
+        queryLog?: string;
+    }>;
+    /**
+     * Generate a migration from table structure differences
+     */
+    generateMigrationFromDiff(params: {
+        table1: string;
+        table2: string;
+        migration_name: string;
+        database?: string;
+    }): Promise<{
+        status: string;
+        data?: any;
+        error?: string;
+        queryLog?: string;
+    }>;
     getFeatureStatus(): {
         status: string;
         data: {