@berthojoris/mcp-mysql-server 1.9.3 → 1.10.1

package/dist/index.d.ts

@@ -21,9 +21,10 @@ export declare class MySQLMCP {
     private backupRestoreTools;
     private migrationTools;
     private schemaVersioningTools;
+    private performanceTools;
     private security;
     private featureConfig;
-    constructor(permissionsConfig?: string);
+    constructor(permissionsConfig?: string, categoriesConfig?: string);
     private checkToolEnabled;
     listDatabases(): Promise<{
         status: string;
@@ -587,6 +588,12 @@ export declare class MySQLMCP {
             categoryStatus: Record<import("./config/featureConfig").ToolCategory, boolean>;
         };
     };
+    /**
+     * Check if a specific tool is enabled based on current permissions and categories
+     * @param toolName - The tool name in camelCase (e.g., 'listDatabases')
+     * @returns boolean indicating if the tool is enabled
+     */
+    isToolEnabled(toolName: string): boolean;
     /**
      * Bulk insert multiple records into the specified table
      */
@@ -1093,5 +1100,80 @@ export declare class MySQLMCP {
         error?: string;
         queryLog?: string;
     }>;
+    getPerformanceMetrics(): Promise<{
+        status: string;
+        data?: any;
+        error?: string;
+        queryLog?: string;
+    }>;
+    getTopQueriesByTime(params?: {
+        limit?: number;
+    }): Promise<{
+        status: string;
+        data?: any[];
+        error?: string;
+        queryLog?: string;
+    }>;
+    getTopQueriesByCount(params?: {
+        limit?: number;
+    }): Promise<{
+        status: string;
+        data?: any[];
+        error?: string;
+        queryLog?: string;
+    }>;
+    getSlowQueries(params?: {
+        limit?: number;
+        threshold_seconds?: number;
+    }): Promise<{
+        status: string;
+        data?: any[];
+        error?: string;
+        queryLog?: string;
+    }>;
+    getTableIOStats(params?: {
+        limit?: number;
+        table_schema?: string;
+    }): Promise<{
+        status: string;
+        data?: any[];
+        error?: string;
+        queryLog?: string;
+    }>;
+    getIndexUsageStats(params?: {
+        limit?: number;
+        table_schema?: string;
+    }): Promise<{
+        status: string;
+        data?: any[];
+        error?: string;
+        queryLog?: string;
+    }>;
+    getUnusedIndexes(params?: {
+        table_schema?: string;
+    }): Promise<{
+        status: string;
+        data?: any[];
+        error?: string;
+        queryLog?: string;
+    }>;
+    getConnectionPoolStats(): Promise<{
+        status: string;
+        data?: any;
+        error?: string;
+        queryLog?: string;
+    }>;
+    getDatabaseHealthCheck(): Promise<{
+        status: string;
+        data?: any;
+        error?: string;
+        queryLog?: string;
+    }>;
+    resetPerformanceStats(): Promise<{
+        status: string;
+        message?: string;
+        error?: string;
+        queryLog?: string;
+    }>;
 }
 export default MySQLMCP;

package/dist/index.js

@@ -22,6 +22,7 @@ const processTools_1 = require("./tools/processTools");
 const backupRestoreTools_1 = require("./tools/backupRestoreTools");
 const migrationTools_1 = require("./tools/migrationTools");
 const schemaVersioningTools_1 = require("./tools/schemaVersioningTools");
+const performanceTools_1 = require("./tools/performanceTools");
 const securityLayer_1 = __importDefault(require("./security/securityLayer"));
 const connection_1 = __importDefault(require("./db/connection"));
 const featureConfig_1 = require("./config/featureConfig");
@@ -30,8 +31,8 @@ const featureConfig_1 = require("./config/featureConfig");
  * A secure interface for AI models to interact with MySQL databases
  */
 class MySQLMCP {
-    constructor(permissionsConfig) {
-        this.featureConfig = new featureConfig_1.FeatureConfig(permissionsConfig);
+    constructor(permissionsConfig, categoriesConfig) {
+        this.featureConfig = new featureConfig_1.FeatureConfig(permissionsConfig, categoriesConfig);
         this.security = new securityLayer_1.default(this.featureConfig);
         this.dbTools = new databaseTools_1.DatabaseTools();
         this.crudTools = new crudTools_1.CrudTools(this.security);
@@ -51,6 +52,7 @@ class MySQLMCP {
         this.backupRestoreTools = new backupRestoreTools_1.BackupRestoreTools(this.security);
         this.migrationTools = new migrationTools_1.MigrationTools(this.security);
         this.schemaVersioningTools = new schemaVersioningTools_1.SchemaVersioningTools(this.security);
+        this.performanceTools = new performanceTools_1.PerformanceTools(this.security);
     }
     // Helper method to check if tool is enabled
     checkToolEnabled(toolName) {
@@ -502,6 +504,14 @@ class MySQLMCP {
             },
         };
     }
+    /**
+     * Check if a specific tool is enabled based on current permissions and categories
+     * @param toolName - The tool name in camelCase (e.g., 'listDatabases')
+     * @returns boolean indicating if the tool is enabled
+     */
+    isToolEnabled(toolName) {
+        return this.featureConfig.isToolEnabled(toolName);
+    }
     /**
      * Bulk insert multiple records into the specified table
      */
@@ -925,6 +935,69 @@ class MySQLMCP {
             return { status: "error", error: check.error };
         return await this.processTools.showReplicationStatus(params);
     }
+    // ==========================================
+    // Performance Monitoring Tools
+    // ==========================================
+    async getPerformanceMetrics() {
+        const check = this.checkToolEnabled("getPerformanceMetrics");
+        if (!check.enabled)
+            return { status: "error", error: check.error };
+        return await this.performanceTools.getPerformanceMetrics();
+    }
+    async getTopQueriesByTime(params) {
+        const check = this.checkToolEnabled("getTopQueriesByTime");
+        if (!check.enabled)
+            return { status: "error", error: check.error };
+        return await this.performanceTools.getTopQueriesByTime(params);
+    }
+    async getTopQueriesByCount(params) {
+        const check = this.checkToolEnabled("getTopQueriesByCount");
+        if (!check.enabled)
+            return { status: "error", error: check.error };
+        return await this.performanceTools.getTopQueriesByCount(params);
+    }
+    async getSlowQueries(params) {
+        const check = this.checkToolEnabled("getSlowQueries");
+        if (!check.enabled)
+            return { status: "error", error: check.error };
+        return await this.performanceTools.getSlowQueries(params);
+    }
+    async getTableIOStats(params) {
+        const check = this.checkToolEnabled("getTableIOStats");
+        if (!check.enabled)
+            return { status: "error", error: check.error };
+        return await this.performanceTools.getTableIOStats(params);
+    }
+    async getIndexUsageStats(params) {
+        const check = this.checkToolEnabled("getIndexUsageStats");
+        if (!check.enabled)
+            return { status: "error", error: check.error };
+        return await this.performanceTools.getIndexUsageStats(params);
+    }
+    async getUnusedIndexes(params) {
+        const check = this.checkToolEnabled("getUnusedIndexes");
+        if (!check.enabled)
+            return { status: "error", error: check.error };
+        return await this.performanceTools.getUnusedIndexes(params);
+    }
+    async getConnectionPoolStats() {
+        const check = this.checkToolEnabled("getConnectionPoolStats");
+        if (!check.enabled)
+            return { status: "error", error: check.error };
+        return await this.performanceTools.getConnectionPoolStats();
+    }
+    async getDatabaseHealthCheck() {
+        const check = this.checkToolEnabled("getDatabaseHealthCheck");
+        if (!check.enabled)
+            return { status: "error", error: check.error };
+        return await this.performanceTools.getDatabaseHealthCheck();
+    }
+    async resetPerformanceStats() {
+        const check = this.checkToolEnabled("resetPerformanceStats");
+        if (!check.enabled)
+            return { status: "error", error: check.error };
+        return await this.performanceTools.resetPerformanceStats();
+    }
 }
 exports.MySQLMCP = MySQLMCP;
 exports.default = MySQLMCP;

package/dist/mcp-server.js

@@ -5,9 +5,11 @@ const index_js_1 = require("@modelcontextprotocol/sdk/server/index.js");
 const stdio_js_1 = require("@modelcontextprotocol/sdk/server/stdio.js");
 const types_js_1 = require("@modelcontextprotocol/sdk/types.js");
 const index_js_2 = require("./index.js");
-// Get permissions from environment variable (set by bin/mcp-mysql.js)
-// Priority: MCP_PERMISSIONS (from command line) > MCP_CONFIG (from .env) > all permissions
+// Get permissions and categories from environment variables (set by bin/mcp-mysql.js)
+// Layer 1 (Permissions): MCP_PERMISSIONS or MCP_CONFIG (backward compatible)
+// Layer 2 (Categories): MCP_CATEGORIES (optional, for fine-grained control)
 const permissions = process.env.MCP_PERMISSIONS || process.env.MCP_CONFIG || "";
+const categories = process.env.MCP_CATEGORIES || "";
 // Declare the MySQL MCP instance (will be initialized in main())
 let mysqlMCP;
 // Define all available tools with their schemas
@@ -2558,6 +2560,129 @@ const TOOLS = [
             required: ["table1", "table2", "migration_name"],
         },
     },
+    // Performance Monitoring Tools
+    {
+        name: "get_performance_metrics",
+        description: "Get comprehensive performance metrics including query performance, connection stats, buffer pool metrics, and InnoDB statistics.",
+        inputSchema: {
+            type: "object",
+            properties: {},
+        },
+    },
+    {
+        name: "get_top_queries_by_time",
+        description: "Get the top queries ordered by total execution time. Useful for identifying slow queries.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                limit: {
+                    type: "number",
+                    description: "Maximum number of queries to return (default: 10, max: 100)",
+                },
+            },
+        },
+    },
+    {
+        name: "get_top_queries_by_count",
+        description: "Get the top queries ordered by execution count. Useful for identifying frequently executed queries.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                limit: {
+                    type: "number",
+                    description: "Maximum number of queries to return (default: 10, max: 100)",
+                },
+            },
+        },
+    },
+    {
+        name: "get_slow_queries",
+        description: "Get queries that exceed a specified execution time threshold.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                limit: {
+                    type: "number",
+                    description: "Maximum number of queries to return (default: 10, max: 100)",
+                },
+                threshold_seconds: {
+                    type: "number",
+                    description: "Execution time threshold in seconds (default: 1)",
+                },
+            },
+        },
+    },
+    {
+        name: "get_table_io_stats",
+        description: "Get I/O statistics for tables including read/write operations and timings.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                limit: {
+                    type: "number",
+                    description: "Maximum number of tables to return (default: 20, max: 100)",
+                },
+                table_schema: {
+                    type: "string",
+                    description: "Filter by specific database schema",
+                },
+            },
+        },
+    },
+    {
+        name: "get_index_usage_stats",
+        description: "Get index usage statistics showing how often each index is used.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                limit: {
+                    type: "number",
+                    description: "Maximum number of indexes to return (default: 20, max: 100)",
+                },
+                table_schema: {
+                    type: "string",
+                    description: "Filter by specific database schema",
+                },
+            },
+        },
+    },
+    {
+        name: "get_unused_indexes",
+        description: "Identify indexes that are not being used by queries. These may be candidates for removal to improve write performance.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                table_schema: {
+                    type: "string",
+                    description: "Filter by specific database schema",
+                },
+            },
+        },
+    },
+    {
+        name: "get_connection_pool_stats",
+        description: "Get connection pool statistics including current connections, max usage, configuration, and health indicators.",
+        inputSchema: {
+            type: "object",
+            properties: {},
+        },
+    },
+    {
+        name: "get_database_health_check",
+        description: "Perform a comprehensive health check of the database including connection usage, buffer pool efficiency, aborted connections, and slow queries.",
+        inputSchema: {
+            type: "object",
+            properties: {},
+        },
+    },
+    {
+        name: "reset_performance_stats",
+        description: "Reset performance schema statistics. This clears query digest statistics, table I/O stats, and index usage stats. Requires 'utility' permission.",
+        inputSchema: {
+            type: "object",
+            properties: {},
+        },
+    },
 ];
 // Create the MCP server
 const server = new index_js_1.Server({
@@ -2568,10 +2693,20 @@ const server = new index_js_1.Server({
         tools: {},
     },
 });
-// Handle list tools request
+// Handle list tools request - filter tools based on permissions and categories
 server.setRequestHandler(types_js_1.ListToolsRequestSchema, async () => {
+    // Filter tools to only return those that are enabled based on current config
+    const enabledTools = TOOLS.filter((tool) => {
+        // Convert tool name from snake_case to camelCase for checking
+        // e.g., "list_databases" -> "listDatabases"
+        const toolNameCamelCase = tool.name.replace(/_([a-z])/g, (_, letter) => letter.toUpperCase());
+        // Check if tool is enabled based on permissions and categories
+        return mysqlMCP.isToolEnabled(toolNameCamelCase);
+    });
+    // Log the filtering results
+    console.error(`Tools available: ${enabledTools.length} of ${TOOLS.length} total tools`);
     return {
-        tools: TOOLS,
+        tools: enabledTools,
     };
 });
 // Handle tool call requests
@@ -2924,6 +3059,37 @@ server.setRequestHandler(types_js_1.CallToolRequestSchema, async (request) => {
             case "generate_migration_from_diff":
                 result = await mysqlMCP.generateMigrationFromDiff((args || {}));
                 break;
+            // Performance Monitoring Tools
+            case "get_performance_metrics":
+                result = await mysqlMCP.getPerformanceMetrics();
+                break;
+            case "get_top_queries_by_time":
+                result = await mysqlMCP.getTopQueriesByTime((args || {}));
+                break;
+            case "get_top_queries_by_count":
+                result = await mysqlMCP.getTopQueriesByCount((args || {}));
+                break;
+            case "get_slow_queries":
+                result = await mysqlMCP.getSlowQueries((args || {}));
+                break;
+            case "get_table_io_stats":
+                result = await mysqlMCP.getTableIOStats((args || {}));
+                break;
+            case "get_index_usage_stats":
+                result = await mysqlMCP.getIndexUsageStats((args || {}));
+                break;
+            case "get_unused_indexes":
+                result = await mysqlMCP.getUnusedIndexes((args || {}));
+                break;
+            case "get_connection_pool_stats":
+                result = await mysqlMCP.getConnectionPoolStats();
+                break;
+            case "get_database_health_check":
+                result = await mysqlMCP.getDatabaseHealthCheck();
+                break;
+            case "reset_performance_stats":
+                result = await mysqlMCP.resetPerformanceStats();
+                break;
             default:
                 throw new Error(`Unknown tool: ${name}`);
         }
@@ -3028,10 +3194,16 @@ async function main() {
     await server.connect(transport);
     // Initialize the MySQL MCP instance AFTER transport is connected
     // This ensures the database connection pool is created when the server is ready
-    mysqlMCP = new index_js_2.MySQLMCP(permissions);
-    // Log the effective permissions to stderr
-    if (permissions) {
+    mysqlMCP = new index_js_2.MySQLMCP(permissions, categories);
+    // Log the effective filtering configuration to stderr
+    if (permissions && categories) {
+        console.error(`Active permissions (Layer 1): ${permissions}`);
+        console.error(`Active categories (Layer 2): ${categories}`);
+        console.error("Filtering mode: Dual-layer");
+    }
+    else if (permissions) {
         console.error(`Active permissions: ${permissions}`);
+        console.error("Filtering mode: Single-layer");
     }
     else {
         console.error("Active permissions: all (default)");

package/dist/security/securityLayer.d.ts

@@ -6,6 +6,10 @@ export declare class SecurityLayer {
     private readonly ddlOperations;
     private featureConfig;
     constructor(featureConfig?: FeatureConfig);
+    /**
+     * Check if a query is a read-only information query (SHOW, DESCRIBE, EXPLAIN, etc.)
+     */
+    private isInformationQuery;
     /**
      * Validate input against a JSON schema
      */
@@ -39,7 +43,7 @@ export declare class SecurityLayer {
         sanitizedParams?: any[];
     };
     /**
-     * Check if a query is a read-only SELECT query
+     * Check if a query is a read-only SELECT query or information query (SHOW, DESCRIBE, etc.)
      */
     isReadOnlyQuery(query: string): boolean;
     /**

package/dist/security/securityLayer.js

@@ -34,6 +34,14 @@ class SecurityLayer {
         // Define DDL operations that require special permission
         this.ddlOperations = ["CREATE", "ALTER", "DROP", "TRUNCATE", "RENAME"];
     }
+    /**
+     * Check if a query is a read-only information query (SHOW, DESCRIBE, EXPLAIN, etc.)
+     */
+    isInformationQuery(query) {
+        const trimmedQuery = query.trim().toUpperCase();
+        const readOnlyCommands = ["SHOW", "DESCRIBE", "DESC", "EXPLAIN", "HELP"];
+        return readOnlyCommands.some((cmd) => trimmedQuery.startsWith(cmd));
+    }
     /**
      * Validate input against a JSON schema
      */
@@ -132,6 +140,10 @@ class SecurityLayer {
         }
         // Remove trailing semicolon for analysis
         const cleanQuery = trimmedQuery.replace(/;$/, "");
+        // Check if it's an information query (SHOW, DESCRIBE, EXPLAIN, etc.) - these are always allowed
+        if (this.isInformationQuery(trimmedQuery)) {
+            return { valid: true, queryType: "INFORMATION" };
+        }
         // Determine query type - check basic operations first
         let queryType = "";
         for (const operation of this.allowedOperations) {
@@ -257,9 +269,14 @@ class SecurityLayer {
         return { valid: true, sanitizedParams };
     }
     /**
-     * Check if a query is a read-only SELECT query
+     * Check if a query is a read-only SELECT query or information query (SHOW, DESCRIBE, etc.)
      */
     isReadOnlyQuery(query) {
+        // Check if it's an information query first (SHOW, DESCRIBE, EXPLAIN, etc.)
+        if (this.isInformationQuery(query)) {
+            return true;
+        }
+        // Check if it's a SELECT query
         const validation = this.validateQuery(query);
         return validation.valid && validation.queryType === "SELECT";
     }

package/dist/tools/performanceTools.d.ts

@@ -0,0 +1,111 @@
+import { SecurityLayer } from '../security/securityLayer';
+export declare class PerformanceTools {
+    private db;
+    private security;
+    constructor(security: SecurityLayer);
+    /**
+     * Get comprehensive performance metrics
+     */
+    getPerformanceMetrics(): Promise<{
+        status: string;
+        data?: any;
+        error?: string;
+        queryLog?: string;
+    }>;
+    /**
+     * Get top queries by execution time
+     */
+    getTopQueriesByTime(params?: {
+        limit?: number;
+    }): Promise<{
+        status: string;
+        data?: any[];
+        error?: string;
+        queryLog?: string;
+    }>;
+    /**
+     * Get top queries by execution count
+     */
+    getTopQueriesByCount(params?: {
+        limit?: number;
+    }): Promise<{
+        status: string;
+        data?: any[];
+        error?: string;
+        queryLog?: string;
+    }>;
+    /**
+     * Get slow queries
+     */
+    getSlowQueries(params?: {
+        limit?: number;
+        threshold_seconds?: number;
+    }): Promise<{
+        status: string;
+        data?: any[];
+        error?: string;
+        queryLog?: string;
+    }>;
+    /**
+     * Get table I/O statistics
+     */
+    getTableIOStats(params?: {
+        limit?: number;
+        table_schema?: string;
+    }): Promise<{
+        status: string;
+        data?: any[];
+        error?: string;
+        queryLog?: string;
+    }>;
+    /**
+     * Get index usage statistics
+     */
+    getIndexUsageStats(params?: {
+        limit?: number;
+        table_schema?: string;
+    }): Promise<{
+        status: string;
+        data?: any[];
+        error?: string;
+        queryLog?: string;
+    }>;
+    /**
+     * Get unused indexes
+     */
+    getUnusedIndexes(params?: {
+        table_schema?: string;
+    }): Promise<{
+        status: string;
+        data?: any[];
+        error?: string;
+        queryLog?: string;
+    }>;
+    /**
+     * Get connection pool statistics
+     */
+    getConnectionPoolStats(): Promise<{
+        status: string;
+        data?: any;
+        error?: string;
+        queryLog?: string;
+    }>;
+    /**
+     * Get database health check
+     */
+    getDatabaseHealthCheck(): Promise<{
+        status: string;
+        data?: any;
+        error?: string;
+        queryLog?: string;
+    }>;
+    /**
+     * Reset performance schema statistics
+     */
+    resetPerformanceStats(): Promise<{
+        status: string;
+        message?: string;
+        error?: string;
+        queryLog?: string;
+    }>;
+}