@berthojoris/mcp-mysql-server 1.10.5 → 1.13.0

package/dist/mcp-server.js

@@ -10,6 +10,7 @@ const index_js_2 = require("./index.js");
 // 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 || "";
+const preset = process.env.MCP_PRESET || process.env.MCP_PERMISSION_PRESET || "";
 // Declare the MySQL MCP instance (will be initialized in main())
 let mysqlMCP;
 // Define all available tools with their schemas
@@ -35,6 +36,79 @@ const TOOLS = [
             },
         },
     },
+    {
+        name: "get_database_summary",
+        description: "Get a high-level summary of the database (tables, columns, row counts) optimized for AI context.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                database: {
+                    type: "string",
+                    description: "Optional: specific database name",
+                },
+            },
+        },
+    },
+    {
+        name: "get_schema_erd",
+        description: "Get a Mermaid.js ER diagram string representing the database schema and relationships.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                database: {
+                    type: "string",
+                    description: "Optional: specific database name",
+                },
+            },
+        },
+    },
+    {
+        name: "get_schema_rag_context",
+        description: "Return a compact schema-aware context pack (tables, PK/FK, columns, row estimates) optimized for RAG prompts.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                database: {
+                    type: "string",
+                    description: "Optional: specific database name",
+                },
+                max_tables: {
+                    type: "number",
+                    description: "Optional: maximum number of tables to include (default 50, max 200)",
+                },
+                max_columns: {
+                    type: "number",
+                    description: "Optional: maximum number of columns per table (default 12, max 200)",
+                },
+                include_relationships: {
+                    type: "boolean",
+                    description: "Whether to include FK relationships section (default: true)",
+                },
+            },
+        },
+    },
+    {
+        name: "get_column_statistics",
+        description: "Get detailed statistics for a specific column (min, max, avg, distinct counts, nulls).",
+        inputSchema: {
+            type: "object",
+            properties: {
+                table_name: {
+                    type: "string",
+                    description: "Name of the table",
+                },
+                column_name: {
+                    type: "string",
+                    description: "Name of the column",
+                },
+                database: {
+                    type: "string",
+                    description: "Optional: specific database name",
+                },
+            },
+            required: ["table_name", "column_name"],
+        },
+    },
     {
         name: "read_table_schema",
         description: "Reads the schema of a specified table, including columns, types, keys, and indexes.",
@@ -375,6 +449,10 @@ const TOOLS = [
                     type: "boolean",
                     description: "Whether to use query result caching (default: true)",
                 },
+                dry_run: {
+                    type: "boolean",
+                    description: "If true, returns query plan and estimated cost without executing (Safe Mode)",
+                },
             },
             required: ["query"],
         },
@@ -398,6 +476,24 @@ const TOOLS = [
             required: ["query"],
         },
     },
+    {
+        name: "repair_query",
+        description: "Analyzes a SQL query (and optional error) to suggest repairs or optimizations using EXPLAIN and heuristics.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                query: {
+                    type: "string",
+                    description: "The SQL query to analyze or repair",
+                },
+                error_message: {
+                    type: "string",
+                    description: "Optional error message received when executing the query",
+                },
+            },
+            required: ["query"],
+        },
+    },
     {
         name: "create_table",
         description: 'Creates a new table with the specified columns and indexes. Requires "ddl" permission.',
@@ -2563,7 +2659,7 @@ const TOOLS = [
     // Performance Monitoring Tools
     {
         name: "get_performance_metrics",
-        description: "Get comprehensive performance metrics including query performance, connection stats, buffer pool metrics, and InnoDB statistics.",
+        description: "Get comprehensive MySQL performance metrics including query performance, connection stats, buffer pool metrics, and InnoDB statistics.",
         inputSchema: {
             type: "object",
             properties: {},
@@ -2687,7 +2783,7 @@ const TOOLS = [
 // Create the MCP server
 const server = new index_js_1.Server({
     name: "mysql-mcp-server",
-    version: "1.4.4",
+    version: "1.12.0",
 }, {
     capabilities: {
         tools: {},
@@ -2721,38 +2817,20 @@ server.setRequestHandler(types_js_1.CallToolRequestSchema, async (request) => {
             case "list_tables":
                 result = await mysqlMCP.listTables((args || {}));
                 break;
-            case "read_table_schema":
-                result = await mysqlMCP.readTableSchema((args || {}));
-                break;
-            case "create_record":
-                result = await mysqlMCP.createRecord((args || {}));
-                break;
-            case "read_records":
-                result = await mysqlMCP.readRecords((args || {}));
-                break;
-            case "update_record":
-                result = await mysqlMCP.updateRecord((args || {}));
-                break;
-            case "delete_record":
-                result = await mysqlMCP.deleteRecord((args || {}));
+            case "get_database_summary":
+                result = await mysqlMCP.getDatabaseSummary((args || {}));
                 break;
-            case "bulk_insert":
-                result = await mysqlMCP.bulkInsert((args || {}));
+            case "get_schema_erd":
+                result = await mysqlMCP.getSchemaERD((args || {}));
                 break;
-            case "bulk_update":
-                result = await mysqlMCP.bulkUpdate((args || {}));
+            case "get_schema_rag_context":
+                result = await mysqlMCP.getSchemaRagContext((args || {}));
                 break;
-            case "bulk_delete":
-                result = await mysqlMCP.bulkDelete((args || {}));
+            case "get_column_statistics":
+                result = await mysqlMCP.getColumnStatistics((args || {}));
                 break;
-            case "run_query":
-                result = await mysqlMCP.runQuery((args || {}));
-                break;
-            case "execute_sql":
-                result = await mysqlMCP.executeSql((args || {}));
-                break;
-            case "create_table":
-                result = await mysqlMCP.createTable(args || {});
+            case "read_table_schema":
+                result = await mysqlMCP.readTableSchema((args || {}));
                 break;
             case "alter_table":
                 result = await mysqlMCP.alterTable(args || {});
@@ -3090,6 +3168,9 @@ server.setRequestHandler(types_js_1.CallToolRequestSchema, async (request) => {
             case "reset_performance_stats":
                 result = await mysqlMCP.resetPerformanceStats();
                 break;
+            case "repair_query":
+                result = await mysqlMCP.repairQuery((args || {}));
+                break;
             default:
                 throw new Error(`Unknown tool: ${name}`);
         }
@@ -3173,20 +3254,20 @@ 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, categories);
+    mysqlMCP = new index_js_2.MySQLMCP(permissions, categories, preset);
     // 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");
+    const accessProfile = mysqlMCP.getAccessProfile();
+    if (accessProfile.preset) {
+        console.error(`Preset: ${accessProfile.preset.name} (${accessProfile.preset.description})`);
     }
-    else if (permissions) {
-        console.error(`Active permissions: ${permissions}`);
-        console.error("Filtering mode: Single-layer");
+    else if (preset) {
+        console.error(`Preset requested but not recognized: ${preset}`);
     }
-    else {
-        console.error("Active permissions: all (default)");
+    console.error(`Permissions (resolved): ${accessProfile.permissions}`);
+    if (accessProfile.categories) {
+        console.error(`Categories (resolved): ${accessProfile.categories}`);
     }
+    console.error(`Filtering mode: ${accessProfile.filteringMode}`);
     // Log to stderr (not stdout, which is used for MCP protocol)
     console.error("MySQL MCP Server running on stdio");
 }

package/dist/optimization/explainAnalyzer.d.ts

@@ -0,0 +1,21 @@
+export interface ExplainAnalysis {
+    complexity: "LOW" | "MEDIUM" | "HIGH";
+    issues: string[];
+    suggestions: string[];
+    summary: string;
+}
+export declare class ExplainAnalyzer {
+    private static instance;
+    private constructor();
+    static getInstance(): ExplainAnalyzer;
+    /**
+     * Analyze EXPLAIN output (assumed to be in JSON format or standard table format)
+     * Note: The server should prefer EXPLAIN FORMAT=JSON for better analysis,
+     * but we will handle the standard result set array as well.
+     */
+    analyze(explainResult: any[]): ExplainAnalysis;
+    private analyzeJsonFormat;
+    private traverseJsonPlan;
+    private analyzeRow;
+    private generateSummary;
+}

package/dist/optimization/explainAnalyzer.js

@@ -0,0 +1,147 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ExplainAnalyzer = void 0;
+class ExplainAnalyzer {
+    constructor() { }
+    static getInstance() {
+        if (!ExplainAnalyzer.instance) {
+            ExplainAnalyzer.instance = new ExplainAnalyzer();
+        }
+        return ExplainAnalyzer.instance;
+    }
+    /**
+     * Analyze EXPLAIN output (assumed to be in JSON format or standard table format)
+     * Note: The server should prefer EXPLAIN FORMAT=JSON for better analysis,
+     * but we will handle the standard result set array as well.
+     */
+    analyze(explainResult) {
+        const issues = [];
+        const suggestions = [];
+        let maxComplexity = 0;
+        // Check if result is empty
+        if (!explainResult || explainResult.length === 0) {
+            return {
+                complexity: "LOW",
+                issues: ["No EXPLAIN output returned"],
+                suggestions: [],
+                summary: "Query validation failed or produced no execution plan."
+            };
+        }
+        // Detect format (JSON string in first column or standard columns)
+        // If using EXPLAIN FORMAT=JSON, output is usually [{ EXPLAIN: '...json...' }]
+        const firstRow = explainResult[0];
+        if (firstRow && (firstRow['EXPLAIN'] || firstRow['JSON_EXPLAIN'])) {
+            return this.analyzeJsonFormat(firstRow['EXPLAIN'] || firstRow['JSON_EXPLAIN']);
+        }
+        // Analyze standard tabular format
+        for (const row of explainResult) {
+            this.analyzeRow(row, issues, suggestions);
+            // Heuristic for complexity
+            if (row.type === 'ALL')
+                maxComplexity = Math.max(maxComplexity, 3);
+            else if (row.type === 'index')
+                maxComplexity = Math.max(maxComplexity, 2);
+            else
+                maxComplexity = Math.max(maxComplexity, 1);
+        }
+        let complexity = "LOW";
+        if (maxComplexity >= 3)
+            complexity = "HIGH";
+        else if (maxComplexity === 2)
+            complexity = "MEDIUM";
+        return {
+            complexity,
+            issues: Array.from(new Set(issues)),
+            suggestions: Array.from(new Set(suggestions)),
+            summary: this.generateSummary(complexity, issues)
+        };
+    }
+    analyzeJsonFormat(jsonString) {
+        try {
+            const data = JSON.parse(jsonString);
+            const queryBlock = data.query_block || data; // Root might be query_block directly in some versions
+            const issues = [];
+            const suggestions = [];
+            this.traverseJsonPlan(queryBlock, issues, suggestions);
+            const distinctIssues = Array.from(new Set(issues));
+            const complexity = distinctIssues.some(i => i.includes("Full Table Scan")) ? "HIGH" : "MEDIUM"; // Simplified
+            return {
+                complexity,
+                issues: distinctIssues,
+                suggestions: Array.from(new Set(suggestions)),
+                summary: this.generateSummary(complexity, distinctIssues)
+            };
+        }
+        catch (e) {
+            return {
+                complexity: "LOW",
+                issues: ["Failed to parse EXPLAIN JSON output"],
+                suggestions: [],
+                summary: "Could not analyze the execution plan details."
+            };
+        }
+    }
+    traverseJsonPlan(node, issues, suggestions) {
+        if (!node)
+            return;
+        // Check for full table scans
+        if (node.access_type === 'ALL') {
+            issues.push(`Full Table Scan on table '${node.table_name || 'unknown'}'`);
+            suggestions.push(`Consider adding an index on table '${node.table_name || 'unknown'}' for the columns used in WHERE clause.`);
+        }
+        // Check for filesort
+        if (node.filesort || (node.extra && node.extra.includes('Using filesort'))) {
+            issues.push("Using Filesort (sorting without index)");
+            suggestions.push("Consider adding an index that matches the ORDER BY clause.");
+        }
+        // Check for temporary tables
+        if (node.temporary_table || (node.extra && node.extra.includes('Using temporary'))) {
+            issues.push("Using Temporary Table");
+            suggestions.push("Optimize query to avoid temporary tables (e.g. check GROUP BY or ORDER BY columns).");
+        }
+        // Recursive traversal (simplified)
+        if (node.nested_loop) {
+            for (const child of node.nested_loop) {
+                this.traverseJsonPlan(child.table, issues, suggestions);
+            }
+        }
+        // TODO: Add more structural traversal if needed for specific JSON structures
+    }
+    analyzeRow(row, issues, suggestions) {
+        const table = row.table || 'unknown';
+        const type = row.type;
+        const extra = row.Extra || '';
+        const possible_keys = row.possible_keys;
+        const key = row.key;
+        if (type === 'ALL') {
+            issues.push(`Full Table Scan on table '${table}'`);
+            suggestions.push(`Add an index to '${table}' to avoid full scan.`);
+        }
+        if (type === 'index') {
+            issues.push(`Full Index Scan on table '${table}'`);
+            suggestions.push(`Query scans entire index tree for '${table}'. Consider specific range or key.`);
+        }
+        if (!key && possible_keys && type !== 'ALL') {
+            // Indexes exist but not used? Rare case if not ALL.
+        }
+        if (extra.includes('Using filesort')) {
+            issues.push(`Using Filesort on table '${table}'`);
+            suggestions.push(`Add index for ORDER BY clause on '${table}'.`);
+        }
+        if (extra.includes('Using temporary')) {
+            issues.push(`Using Temporary Table for '${table}'`);
+            suggestions.push(`Check GROUP BY / ORDER BY columns on '${table}'.`);
+        }
+        if (extra.includes('Range checked for each record')) {
+            issues.push(`Inefficient join buffer usage on '${table}'`);
+            suggestions.push(`Check join conditions and indexes on '${table}'.`);
+        }
+    }
+    generateSummary(complexity, issues) {
+        if (issues.length === 0) {
+            return "Query plan looks good. No obvious performance issues detected.";
+        }
+        return `Query has ${complexity} complexity with ${issues.length} potential performance issue(s): ${issues.join("; ")}`;
+    }
+}
+exports.ExplainAnalyzer = ExplainAnalyzer;

package/dist/tools/aiTools.d.ts

@@ -0,0 +1,22 @@
+import { SecurityLayer } from "../security/securityLayer";
+export declare class AiTools {
+    private db;
+    private security;
+    private analyzer;
+    private optimizer;
+    constructor(security: SecurityLayer);
+    /**
+     * guided_query_fixer
+     * Analyzes a query (and optional error) to suggest repairs or optimizations using EXPLAIN.
+     */
+    repairQuery(params: {
+        query: string;
+        error_message?: string;
+    }): Promise<{
+        status: string;
+        analysis?: any;
+        fixed_query?: string;
+        suggestions?: string[];
+        error?: string;
+    }>;
+}

package/dist/tools/aiTools.js

@@ -0,0 +1,80 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AiTools = void 0;
+const connection_1 = __importDefault(require("../db/connection"));
+const explainAnalyzer_1 = require("../optimization/explainAnalyzer");
+const queryOptimizer_1 = require("../optimization/queryOptimizer");
+class AiTools {
+    constructor(security) {
+        this.db = connection_1.default.getInstance();
+        this.security = security;
+        this.analyzer = explainAnalyzer_1.ExplainAnalyzer.getInstance();
+        this.optimizer = queryOptimizer_1.QueryOptimizer.getInstance();
+    }
+    /**
+     * guided_query_fixer
+     * Analyzes a query (and optional error) to suggest repairs or optimizations using EXPLAIN.
+     */
+    async repairQuery(params) {
+        const { query, error_message } = params;
+        // 1. If there is a syntax error provided, we can't run EXPLAIN.
+        // We try to provided simple heuristics or just return the analysis of the error.
+        if (error_message) {
+            return {
+                status: "success",
+                suggestions: [
+                    "Check SQL syntax matching your MySQL version.",
+                    "Verify table and column names using 'list_tables' or 'read_table_schema'.",
+                    "Ensure string literals are quoted correctly."
+                ],
+                fixed_query: query, // We can't auto-fix syntax errors reliably without an LLM
+                analysis: {
+                    issue: "Syntax/Execution Error",
+                    details: error_message
+                }
+            };
+        }
+        // 2. Validate query generally (security check)
+        // We assume this tool is used by an agent who might have 'read' permissions at least.
+        // If the query is unsafe (e.g. injection), we return that.
+        const validation = this.security.validateQuery(query, true); // validate with execute permission simulation to check structure
+        if (!validation.valid) {
+            return {
+                status: "error",
+                error: `Query rejected by security layer: ${validation.error}`
+            };
+        }
+        // 3. Run EXPLAIN
+        try {
+            const explainQuery = `EXPLAIN FORMAT=JSON ${query}`;
+            // Note: We use the raw connection or executeSql equivalent.
+            // But EXPLAIN is safe-ish if the inner query is safe.
+            // validation passed, so we try EXPLAIN.
+            const explainResult = await this.db.query(explainQuery);
+            const analysis = this.analyzer.analyze(explainResult);
+            // 4. Try to apply simple fixes based on analysis (e.g. Missing Limit)
+            let fixedQuery = query;
+            if (analysis.complexity === "HIGH" && !query.toLowerCase().includes("limit")) {
+                // Suggest adding LIMIT if not present and complexity is high
+                analysis.suggestions.push("Consider adding 'LIMIT 100' to prevent massive data transfer.");
+            }
+            return {
+                status: "success",
+                analysis: analysis,
+                suggestions: analysis.suggestions,
+                fixed_query: fixedQuery
+            };
+        }
+        catch (e) {
+            return {
+                status: "error",
+                error: `Failed to analyze query: ${e.message}`,
+                suggestions: ["Verify the query is valid SQL before analyzing."]
+            };
+        }
+    }
+}
+exports.AiTools = AiTools;

package/dist/tools/analysisTools.d.ts

@@ -0,0 +1,35 @@
+import { SecurityLayer } from "../security/securityLayer";
+export declare class AnalysisTools {
+    private db;
+    private security;
+    constructor(security: SecurityLayer);
+    /**
+     * Validate database access - ensures only the connected database can be accessed
+     */
+    private validateDatabaseAccess;
+    /**
+     * Get statistics for a specific column
+     */
+    getColumnStatistics(params: {
+        table_name: string;
+        column_name: string;
+        database?: string;
+    }): Promise<{
+        status: string;
+        data?: any;
+        error?: string;
+    }>;
+    /**
+     * Build a compact, schema-aware context pack for RAG (tables, PK/FK, columns, row estimates)
+     */
+    getSchemaRagContext(params?: {
+        database?: string;
+        max_tables?: number;
+        max_columns?: number;
+        include_relationships?: boolean;
+    }): Promise<{
+        status: string;
+        data?: any;
+        error?: string;
+    }>;
+}