@berthojoris/mcp-mysql-server 1.10.0 → 1.10.2

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;