@berthojoris/mcp-mysql-server 1.9.3 → 1.10.1

package/README.md

@@ -50,7 +50,7 @@ Add to your AI agent config (`.mcp.json`, `.cursor/mcp.json`, etc.):
   - [Environment Variables](#environment-variables-configuration)
   - [Local Development](#local-path-configuration)
 - [Permission System](#-permission-system)
-- [Available Tools (98 total)](#-available-tools)
+- [Available Tools (119 total)](#-available-tools)
 - [Documentation](#-detailed-documentation)
 - [Comparison: MCP vs Manual Access](#-mysql-mcp-vs-manual-database-access)
 - [License](#-license)
@@ -63,8 +63,8 @@ Add to your AI agent config (`.mcp.json`, `.cursor/mcp.json`, etc.):
 |----------|-------------|
 | **Full MCP Support** | Works with Claude Code, Cursor, Windsurf, Zed, Cline, Kilo Code, Roo Code, Gemini CLI, OpenAI Codex, and any MCP-compatible AI agent |
 | **Security First** | Parameterized queries, SQL injection protection, permission-based access control |
-| **98 Powerful Tools** | Complete database operations including CRUD, DDL, transactions, stored procedures, backup/restore, migrations |
-| **Granular Permissions** | 10 permission categories for fine-grained access control per project |
+| **119 Powerful Tools** | Complete database operations including CRUD, DDL, transactions, stored procedures, backup/restore, migrations |
+| **🆕 Category Filtering** | 22 documentation categories for intuitive, fine-grained access control (backward compatible with 10 legacy categories) |
 | **Transaction Support** | Full ACID transaction management (BEGIN, COMMIT, ROLLBACK) |
 | **Schema Migrations** | Version control for database schema with up/down migrations |
 | **Dual Mode** | Run as MCP server OR as REST API |
@@ -394,9 +394,43 @@ npm run build
 
 ## Permission System
 
-Control database access with granular permission categories:
-
-### Permission Categories
+Control database access with a **dual-layer filtering system** that provides both broad and fine-grained control:
+
+- **Layer 1 (Permissions)**: Broad operation-level control using legacy categories
+- **Layer 2 (Categories)**: Optional fine-grained tool-level filtering using documentation categories
+
+**Filtering Logic**: `Tool enabled = (Has Permission) AND (Has Category OR No categories specified)`
+
+### 🆕 Documentation Categories (Recommended)
+
+Use these categories for fine-grained control that matches the tool organization:
+
+| Category | Tools Count | Description |
+|----------|-------------|-------------|
+| `database_discovery` | 4 | List databases, tables, schemas, relationships |
+| `crud_operations` | 4 | Basic Create, Read, Update, Delete operations |
+| `bulk_operations` | 3 | Bulk insert, update, delete with batching |
+| `custom_queries` | 2 | Run custom SELECT or execute SQL |
+| `schema_management` | 4 | CREATE/ALTER/DROP tables (DDL) |
+| `utilities` | 4 | Connection testing, diagnostics, CSV export |
+| `transaction_management` | 5 | BEGIN, COMMIT, ROLLBACK transactions |
+| `stored_procedures` | 6 | Create, execute, manage stored procedures |
+| `views_management` | 6 | Create, alter, drop views |
+| `triggers_management` | 5 | Create, drop triggers |
+| `functions_management` | 6 | Create, execute functions |
+| `index_management` | 5 | Create, drop, analyze indexes |
+| `constraint_management` | 7 | Foreign keys, unique, check constraints |
+| `table_maintenance` | 8 | Analyze, optimize, repair tables |
+| `server_management` | 9 | Process list, explain queries, server info |
+| `performance_monitoring` | 10 | Metrics, slow queries, health checks |
+| `cache_management` | 5 | Query cache stats and configuration |
+| `query_optimization` | 2 | Analyze queries, get optimization hints |
+| `backup_restore` | 5 | Backup/restore database and tables |
+| `import_export` | 5 | Import/export JSON, CSV, SQL |
+| `data_migration` | 5 | Copy, move, clone, sync table data |
+| `schema_migrations` | 9 | Version control for database schema |
+
+### Legacy Categories (Backward Compatible)
 
 | Permission | Operations | Use Case |
 |------------|------------|----------|
@@ -411,7 +445,22 @@ Control database access with granular permission categories:
 | `transaction` | BEGIN, COMMIT, ROLLBACK | ACID operations |
 | `utility` | Connection testing, diagnostics | Troubleshooting |
 
-### Common Permission Sets
+### Common Category Sets
+
+#### Using Documentation Categories (Recommended)
+
+| Environment | Categories | Description |
+|-------------|------------|-------------|
+| **Production Read-Only** | `database_discovery,utilities` | Safe exploration only |
+| **Analytics & Reporting** | `database_discovery,crud_operations,custom_queries,performance_monitoring` | Read and analyze |
+| **Data Entry** | `database_discovery,crud_operations,utilities` | Basic CRUD operations |
+| **Data Management** | `database_discovery,crud_operations,bulk_operations,utilities` | CRUD + bulk operations |
+| **Application Backend** | `database_discovery,crud_operations,bulk_operations,custom_queries,transaction_management` | Full app support |
+| **Development & Testing** | `database_discovery,crud_operations,bulk_operations,custom_queries,schema_management,utilities,transaction_management` | Development access |
+| **DBA & DevOps** | `database_discovery,schema_management,table_maintenance,backup_restore,schema_migrations,performance_monitoring` | Admin tasks |
+| **Full Access** | *(leave empty)* | All 119 tools enabled |
+
+#### Using Legacy Categories (Backward Compatible)
 
 | Environment | Permissions | Description |
 |-------------|-------------|-------------|
@@ -424,14 +473,87 @@ Control database access with granular permission categories:
 
 ### Per-Project Configuration
 
-Each project can have different permissions - specify as the second argument after the connection string:
+#### Single-Layer: Permissions Only (Backward Compatible)
+
+Use only the 2nd argument for broad permission-based filtering:
+
+```json
+{
+  "mcpServers": {
+    "mysql": {
+      "command": "node",
+      "args": [
+        "/path/to/bin/mcp-mysql.js",
+        "mysql://user:password@localhost:3306/db",
+        "list,read,utility"
+      ]
+    }
+  }
+}
+```
+
+**Result**: All tools within `list`, `read`, and `utility` permissions are enabled.
+
+#### Dual-Layer: Permissions + Categories (Recommended for Fine Control)
+
+Use both 2nd argument (permissions) and 3rd argument (categories):
 
 ```json
 {
-  "args": [
-    "mysql://user:pass@localhost:3306/db",
-    "list,read,utility"
-  ]
+  "mcpServers": {
+    "mysql-prod": {
+      "command": "node",
+      "args": [
+        "/path/to/bin/mcp-mysql.js",
+        "mysql://readonly:pass@prod:3306/app_db",
+        "list,read,utility",
+        "database_discovery,performance_monitoring"
+      ]
+    }
+  }
+}
+```
+
+**Result**: Only tools that have BOTH:
+- Permission: `list`, `read`, OR `utility` AND
+- Category: `database_discovery` OR `performance_monitoring`
+
+**Enabled**: `list_databases`, `list_tables`, `read_table_schema`, `get_table_relationships`, `get_performance_metrics`, `get_slow_queries`, etc.
+
+**Disabled**: `test_connection` (has `utility` permission but not in allowed categories), `read_records` (has `read` permission but category is `crud_operations`), etc.
+
+#### Multiple Environments Example
+
+```json
+{
+  "mcpServers": {
+    "mysql-prod-readonly": {
+      "command": "node",
+      "args": [
+        "/path/to/bin/mcp-mysql.js",
+        "mysql://readonly:pass@prod:3306/app_db",
+        "list,read,utility",
+        "database_discovery,performance_monitoring"
+      ]
+    },
+    "mysql-dev-full": {
+      "command": "node",
+      "args": [
+        "/path/to/bin/mcp-mysql.js",
+        "mysql://dev:pass@localhost:3306/dev_db",
+        "list,read,create,update,delete,ddl,transaction,utility"
+      ]
+    },
+    "mysql-dba": {
+      "command": "node",
+      "args": [
+        "/path/to/bin/mcp-mysql.js",
+        "mysql://dba:pass@server:3306/app_db",
+        "list,ddl,utility",
+        "database_discovery,schema_management,table_maintenance,backup_restore,index_management"
+      ]
+    }
+  }
 }
 ```
 
@@ -439,7 +561,7 @@ Each project can have different permissions - specify as the second argument aft
 
 ## Available Tools
 
-The MCP server provides **98 powerful tools** organized into categories:
+The MCP server provides **119 powerful tools** organized into categories:
 
 ### Quick Reference
 
@@ -459,6 +581,7 @@ The MCP server provides **98 powerful tools** organized into categories:
 | [Constraints](#constraint-management) | 7 | `add_foreign_key`, `add_unique_constraint` |
 | [Table Maintenance](#table-maintenance) | 8 | `analyze_table`, `optimize_table`, `repair_table` |
 | [Server Management](#process--server-management) | 9 | `show_process_list`, `explain_query` |
+| [Performance Monitoring](#performance-monitoring) | 10 | `get_performance_metrics`, `get_database_health_check` |
 | [Cache](#cache-management) | 5 | `get_cache_stats`, `clear_cache` |
 | [Query Optimization](#query-optimization) | 2 | `analyze_query`, `get_optimization_hints` |
 | [Backup & Restore](#database-backup--restore) | 5 | `backup_database`, `restore_from_sql` |
@@ -622,6 +745,21 @@ The MCP server provides **98 powerful tools** organized into categories:
 | `show_binary_logs` | Show binary log files | `utility` |
 | `show_replication_status` | Show replication status | `utility` |
 
+### Performance Monitoring
+
+| Tool | Description | Requires |
+|------|-------------|----------|
+| `get_performance_metrics` | Get comprehensive performance metrics | `utility` |
+| `get_top_queries_by_time` | Find slowest queries by execution time | `utility` |
+| `get_top_queries_by_count` | Find most frequently executed queries | `utility` |
+| `get_slow_queries` | Identify queries exceeding time threshold | `utility` |
+| `get_table_io_stats` | Monitor table I/O operations | `utility` |
+| `get_index_usage_stats` | Track index usage statistics | `utility` |
+| `get_unused_indexes` | Identify unused indexes | `utility` |
+| `get_connection_pool_stats` | Monitor connection pool health | `utility` |
+| `get_database_health_check` | Comprehensive health assessment | `utility` |
+| `reset_performance_stats` | Reset performance schema statistics | `utility` |
+
 ### Cache Management
 
 | Tool | Description |

package/bin/mcp-mysql.js

@@ -6,25 +6,70 @@
  * It implements the Model Context Protocol using stdio transport
  */
 
-const path = require('path');
-const { spawn } = require('child_process');
-require('dotenv').config();
+const path = require("path");
+const { spawn } = require("child_process");
+require("dotenv").config();
 
-// Get MySQL connection string and optional permissions from command line arguments
+// Get MySQL connection string, permissions, and optional categories from command line arguments
 const mysqlUrl = process.argv[2];
-const permissions = process.argv[3]; // Optional: comma-separated list of permissions
+const permissions = process.argv[3]; // Optional: comma-separated list of permissions (legacy categories)
+const categories = process.argv[4]; // Optional: comma-separated list of documentation categories
 
 if (!mysqlUrl) {
-  console.error('Error: MySQL connection URL is required');
-  console.error('Usage: mcp-mysql mysql://user:password@host:port/dbname [permissions]');
-  console.error('');
-  console.error('Examples:');
-  console.error('  mcp-mysql mysql://root:pass@localhost:3306/mydb');
-  console.error('  mcp-mysql mysql://root:pass@localhost:3306/mydb "list,read,utility"');
-  console.error('  mcp-mysql mysql://root:pass@localhost:3306/mydb "list,read,create,update,delete,utility"');
-  console.error('');
-  console.error('Available permissions: list, read, create, update, delete, execute, utility');
-  console.error('If not specified, all permissions are enabled.');
+  console.error("Error: MySQL connection URL is required");
+  console.error(
+    "Usage: mcp-mysql mysql://user:password@host:port/dbname [permissions] [categories]",
+  );
+  console.error("");
+  console.error("Examples:");
+  console.error("  # All tools enabled (no filtering)");
+  console.error("  mcp-mysql mysql://root:pass@localhost:3306/mydb");
+  console.error("");
+  console.error("  # Permission-based filtering only (Layer 1)");
+  console.error(
+    '  mcp-mysql mysql://root:pass@localhost:3306/mydb "list,read,utility"',
+  );
+  console.error("");
+  console.error(
+    "  # Dual-layer: Permissions + Categories (fine-grained control)",
+  );
+  console.error(
+    '  mcp-mysql mysql://root:pass@localhost:3306/mydb "list,read,utility" "database_discovery,performance_monitoring"',
+  );
+  console.error("");
+  console.error("Permissions (Layer 1 - Broad Control):");
+  console.error(
+    "  list, read, create, update, delete, execute, ddl, utility, transaction, procedure",
+  );
+  console.error("");
+  console.error("Categories (Layer 2 - Fine-Grained Control, Optional):");
+  console.error(
+    "  database_discovery, crud_operations, bulk_operations, custom_queries,",
+  );
+  console.error(
+    "  schema_management, utilities, transaction_management, stored_procedures,",
+  );
+  console.error(
+    "  views_management, triggers_management, functions_management, index_management,",
+  );
+  console.error(
+    "  constraint_management, table_maintenance, server_management,",
+  );
+  console.error(
+    "  performance_monitoring, cache_management, query_optimization,",
+  );
+  console.error(
+    "  backup_restore, import_export, data_migration, schema_migrations",
+  );
+  console.error("");
+  console.error("Filtering Logic:");
+  console.error(
+    "  - If only permissions: All tools within those permissions enabled",
+  );
+  console.error(
+    "  - If permissions + categories: Only tools matching BOTH layers enabled",
+  );
+  console.error("  - If nothing specified: All 119 tools enabled");
   process.exit(1);
 }
 
@@ -33,22 +78,23 @@ let connectionConfig;
 let database;
 try {
   const url = new URL(mysqlUrl);
-  
+
   // Remove leading slash from pathname and make database optional
-  database = url.pathname.replace(/^\//, '') || null;
-  
+  database = url.pathname.replace(/^\//, "") || null;
+
   // Extract username and password from auth
-  const auth = url.username && url.password 
-    ? { user: url.username, password: url.password }
-    : { user: url.username || 'root', password: url.password || '' };
-  
+  const auth =
+    url.username && url.password
+      ? { user: url.username, password: url.password }
+      : { user: url.username || "root", password: url.password || "" };
+
   connectionConfig = {
     host: url.hostname,
     port: url.port || 3306,
     ...auth,
-    ...(database ? { database } : {})
+    ...(database ? { database } : {}),
   };
-  
+
   // Set environment variables for the server
   process.env.DB_HOST = connectionConfig.host;
   process.env.DB_PORT = connectionConfig.port;
@@ -57,23 +103,35 @@ try {
   if (database) {
     process.env.DB_NAME = database;
   }
-  
 } catch (error) {
-  console.error('Error parsing MySQL URL:', error.message);
-  console.error('Usage: npx @berthojoris/mcp-mysql-server mysql://user:password@host:port/dbname');
+  console.error("Error parsing MySQL URL:", error.message);
+  console.error(
+    "Usage: npx @berthojoris/mcp-mysql-server mysql://user:password@host:port/dbname",
+  );
   process.exit(1);
 }
 
-const dbMessage = database 
+const dbMessage = database
   ? `${connectionConfig.host}:${connectionConfig.port}/${database}`
   : `${connectionConfig.host}:${connectionConfig.port} (no specific database selected)`;
 
-// Set permissions as environment variable if provided
+// Set permissions/categories as environment variables if provided
 if (permissions) {
   process.env.MCP_PERMISSIONS = permissions;
-  console.error(`Permissions: ${permissions}`);
-} else {
-  console.error('Permissions: all (default)');
+  console.error(`Permissions (Layer 1): ${permissions}`);
+}
+
+if (categories) {
+  process.env.MCP_CATEGORIES = categories;
+  console.error(`Categories (Layer 2): ${categories}`);
+}
+
+if (!permissions && !categories) {
+  console.error("Access Control: All tools enabled (no filtering)");
+} else if (permissions && !categories) {
+  console.error("Filtering Mode: Permission-based only");
+} else if (permissions && categories) {
+  console.error("Filtering Mode: Dual-layer (Permissions + Categories)");
 }
 
 // Log to stderr (not stdout, which is used for MCP protocol)
@@ -82,41 +140,40 @@ console.error(`Starting MySQL MCP server with connection to ${dbMessage}`);
 // Run the MCP server
 try {
   // Determine the path to the compiled MCP server file
-  const serverPath = path.resolve(__dirname, '../dist/mcp-server.js');
-  
+  const serverPath = path.resolve(__dirname, "../dist/mcp-server.js");
+
   // Spawn the MCP server process with stdio transport
   // stdin/stdout are used for MCP protocol communication
   // stderr is used for logging
-  const server = spawn('node', [serverPath], {
-    stdio: ['inherit', 'inherit', 'inherit'],
-    env: process.env
+  const server = spawn("node", [serverPath], {
+    stdio: ["inherit", "inherit", "inherit"],
+    env: process.env,
   });
-  
+
   // Handle server process events
-  server.on('error', (err) => {
-    console.error('Failed to start MCP server:', err);
+  server.on("error", (err) => {
+    console.error("Failed to start MCP server:", err);
     process.exit(1);
   });
-  
-  server.on('exit', (code) => {
+
+  server.on("exit", (code) => {
     if (code !== 0 && code !== null) {
       console.error(`MCP server exited with code ${code}`);
       process.exit(code);
     }
   });
-  
+
   // Handle termination signals
-  process.on('SIGINT', () => {
-    console.error('Shutting down MySQL MCP server...');
-    server.kill('SIGINT');
+  process.on("SIGINT", () => {
+    console.error("Shutting down MySQL MCP server...");
+    server.kill("SIGINT");
   });
-  
-  process.on('SIGTERM', () => {
-    console.error('Shutting down MySQL MCP server...');
-    server.kill('SIGTERM');
+
+  process.on("SIGTERM", () => {
+    console.error("Shutting down MySQL MCP server...");
+    server.kill("SIGTERM");
   });
-  
 } catch (error) {
-  console.error('Error starting MCP server:', error.message);
+  console.error("Error starting MCP server:", error.message);
   process.exit(1);
-}
+}

package/dist/config/featureConfig.d.ts

@@ -1,5 +1,5 @@
 /**
- * Available MCP tool categories
+ * Available MCP tool categories (Legacy - for backward compatibility)
  */
 export declare enum ToolCategory {
     LIST = "list",// List databases, tables, etc.
@@ -14,26 +14,69 @@ export declare enum ToolCategory {
     PROCEDURE = "procedure"
 }
 /**
- * Map of tool names to their categories
+ * Documentation categories from README (21 categories)
+ * More intuitive and matches user mental model
+ */
+export declare enum DocCategory {
+    DATABASE_DISCOVERY = "database_discovery",
+    CRUD_OPERATIONS = "crud_operations",
+    BULK_OPERATIONS = "bulk_operations",
+    CUSTOM_QUERIES = "custom_queries",
+    SCHEMA_MANAGEMENT = "schema_management",
+    UTILITIES = "utilities",
+    TRANSACTION_MANAGEMENT = "transaction_management",
+    STORED_PROCEDURES = "stored_procedures",
+    VIEWS_MANAGEMENT = "views_management",
+    TRIGGERS_MANAGEMENT = "triggers_management",
+    FUNCTIONS_MANAGEMENT = "functions_management",
+    INDEX_MANAGEMENT = "index_management",
+    CONSTRAINT_MANAGEMENT = "constraint_management",
+    TABLE_MAINTENANCE = "table_maintenance",
+    SERVER_MANAGEMENT = "server_management",
+    PERFORMANCE_MONITORING = "performance_monitoring",
+    CACHE_MANAGEMENT = "cache_management",
+    QUERY_OPTIMIZATION = "query_optimization",
+    BACKUP_RESTORE = "backup_restore",
+    IMPORT_EXPORT = "import_export",
+    DATA_MIGRATION = "data_migration",
+    SCHEMA_MIGRATIONS = "schema_migrations"
+}
+/**
+ * Map of tool names to their legacy categories
  */
 export declare const toolCategoryMap: Record<string, ToolCategory>;
+/**
+ * Map of tool names to their documentation categories (New Enhanced System)
+ */
+export declare const toolDocCategoryMap: Record<string, DocCategory>;
 /**
  * Class to manage feature configuration based on runtime or environment variables
+ * Supports dual-layer filtering:
+ * - Layer 1 (Permissions): Legacy categories (broad control)
+ * - Layer 2 (Categories): Documentation categories (fine-grained control, optional)
  */
 export declare class FeatureConfig {
-    private enabledCategories;
-    private originalConfigString;
-    constructor(configStr?: string);
+    private enabledLegacyCategories;
+    private enabledDocCategories;
+    private originalPermissionsString;
+    private originalCategoriesString;
+    private useDualLayer;
+    constructor(permissionsStr?: string, categoriesStr?: string);
     /**
-     * Parse MCP_CONFIG from provided string or environment variables
+     * Parse permissions and categories for dual-layer filtering
+     * Layer 1 (permissions): Broad control using legacy categories
+     * Layer 2 (categories): Fine-grained control using documentation categories (optional)
      */
     private parseConfig;
     /**
      * Update configuration at runtime
      */
-    setConfig(configStr: string): void;
+    setConfig(permissionsStr: string, categoriesStr?: string): void;
     /**
      * Check if a specific tool is enabled
+     * Dual-layer logic:
+     * - Layer 1 (Permission): Tool must be allowed by its legacy category
+     * - Layer 2 (Category): If categories specified, tool must also be in allowed doc category
      */
     isToolEnabled(toolName: string): boolean;
     /**
@@ -41,16 +84,36 @@ export declare class FeatureConfig {
      */
     getPermissionError(toolName: string): string;
     /**
-     * Check if a category is enabled
+     * Check if a legacy category is enabled
      */
     isCategoryEnabled(category: ToolCategory): boolean;
     /**
-     * Get all enabled categories
+     * Check if a documentation category is enabled
+     */
+    isDocCategoryEnabled(category: DocCategory): boolean;
+    /**
+     * Get all enabled legacy categories
      */
     getEnabledCategories(): ToolCategory[];
+    /**
+     * Get all enabled documentation categories
+     */
+    getEnabledDocCategories(): DocCategory[];
     /**
      * Get all available categories with their status
      */
     getCategoryStatus(): Record<ToolCategory, boolean>;
+    /**
+     * Get all available documentation categories with their status
+     */
+    getDocCategoryStatus(): Record<DocCategory, boolean>;
+    /**
+     * Check if using dual-layer filtering mode
+     */
+    isUsingDualLayer(): boolean;
+    /**
+     * Get filtering mode description
+     */
+    getFilteringMode(): string;
 }
 export declare const featureConfig: FeatureConfig;