@berthojoris/mcp-mysql-server 1.10.5 → 1.13.0

package/dist/tools/analysisTools.js

@@ -0,0 +1,327 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AnalysisTools = void 0;
+const connection_1 = __importDefault(require("../db/connection"));
+const config_1 = require("../config/config");
+class AnalysisTools {
+    constructor(security) {
+        this.db = connection_1.default.getInstance();
+        this.security = security;
+    }
+    /**
+     * Validate database access - ensures only the connected database can be accessed
+     */
+    validateDatabaseAccess(requestedDatabase) {
+        const connectedDatabase = config_1.dbConfig.database;
+        if (!connectedDatabase) {
+            return {
+                valid: false,
+                database: "",
+                error: "No database specified in connection string. Cannot access any database.",
+            };
+        }
+        if (!requestedDatabase) {
+            return {
+                valid: true,
+                database: connectedDatabase,
+            };
+        }
+        if (requestedDatabase !== connectedDatabase) {
+            return {
+                valid: false,
+                database: "",
+                error: `Access denied. You can only access the connected database '${connectedDatabase}'. Requested database '${requestedDatabase}' is not allowed.`,
+            };
+        }
+        return {
+            valid: true,
+            database: connectedDatabase,
+        };
+    }
+    /**
+     * Get statistics for a specific column
+     */
+    async getColumnStatistics(params) {
+        try {
+            const dbValidation = this.validateDatabaseAccess(params?.database);
+            if (!dbValidation.valid) {
+                return { status: "error", error: dbValidation.error };
+            }
+            const { table_name, column_name } = params;
+            const database = dbValidation.database;
+            // Validate names
+            if (!this.security.validateIdentifier(table_name).valid) {
+                return { status: "error", error: "Invalid table name" };
+            }
+            if (!this.security.validateIdentifier(column_name).valid) {
+                return { status: "error", error: "Invalid column name" };
+            }
+            // Check if column exists and get its type
+            const colCheckQuery = `
+        SELECT DATA_TYPE 
+        FROM INFORMATION_SCHEMA.COLUMNS 
+        WHERE TABLE_SCHEMA = ? AND TABLE_NAME = ? AND COLUMN_NAME = ?
+      `;
+            const colCheck = await this.db.query(colCheckQuery, [
+                database,
+                table_name,
+                column_name,
+            ]);
+            if (colCheck.length === 0) {
+                return {
+                    status: "error",
+                    error: `Column '${column_name}' not found in table '${table_name}'`,
+                };
+            }
+            const dataType = colCheck[0].DATA_TYPE;
+            const isNumeric = [
+                "int",
+                "tinyint",
+                "smallint",
+                "mediumint",
+                "bigint",
+                "float",
+                "double",
+                "decimal",
+            ].includes(dataType);
+            const isDate = [
+                "date",
+                "datetime",
+                "timestamp",
+                "time",
+                "year",
+            ].includes(dataType);
+            // Build statistics query
+            let query = `
+        SELECT
+          COUNT(*) as total_rows,
+          COUNT(\`${column_name}\`) as non_null_count,
+          COUNT(DISTINCT \`${column_name}\`) as distinct_count,
+          SUM(CASE WHEN \`${column_name}\` IS NULL THEN 1 ELSE 0 END) as null_count
+      `;
+            if (isNumeric || isDate) {
+                query += `,
+          MIN(\`${column_name}\`) as min_value,
+          MAX(\`${column_name}\`) as max_value
+        `;
+            }
+            if (isNumeric) {
+                query += `,
+          AVG(\`${column_name}\`) as avg_value
+        `;
+            }
+            query += ` FROM \`${database}\`.\`${table_name}\``;
+            const statsResult = await this.db.query(query);
+            const stats = statsResult[0];
+            // Get top frequent values
+            const topValuesQuery = `
+        SELECT \`${column_name}\` as value, COUNT(*) as count
+        FROM \`${database}\`.\`${table_name}\`
+        GROUP BY \`${column_name}\`
+        ORDER BY count DESC
+        LIMIT 5
+      `;
+            const topValues = await this.db.query(topValuesQuery);
+            return {
+                status: "success",
+                data: {
+                    column_name,
+                    data_type: dataType,
+                    statistics: {
+                        total_rows: stats.total_rows,
+                        non_null_count: stats.non_null_count,
+                        null_count: stats.null_count,
+                        distinct_count: stats.distinct_count,
+                        unique_ratio: stats.total_rows > 0
+                            ? (stats.distinct_count / stats.total_rows).toFixed(4)
+                            : 0,
+                        ...(isNumeric || isDate
+                            ? { min_value: stats.min_value, max_value: stats.max_value }
+                            : {}),
+                        ...(isNumeric ? { avg_value: stats.avg_value } : {}),
+                    },
+                    top_values: topValues,
+                },
+            };
+        }
+        catch (error) {
+            return {
+                status: "error",
+                error: error.message,
+            };
+        }
+    }
+    /**
+     * Build a compact, schema-aware context pack for RAG (tables, PK/FK, columns, row estimates)
+     */
+    async getSchemaRagContext(params = {}) {
+        try {
+            const dbValidation = this.validateDatabaseAccess(params?.database);
+            if (!dbValidation.valid) {
+                return { status: "error", error: dbValidation.error };
+            }
+            const database = dbValidation.database;
+            const maxTables = Math.min(Math.max(params.max_tables ?? 50, 1), 200);
+            const maxColumns = Math.min(Math.max(params.max_columns ?? 12, 1), 200);
+            const includeRelationships = params.include_relationships ?? true;
+            // Count total tables for truncation note
+            const totalTablesResult = await this.db.query(`SELECT COUNT(*) as total FROM INFORMATION_SCHEMA.TABLES WHERE TABLE_SCHEMA = ?`, [database]);
+            const totalTables = totalTablesResult[0]?.total ?? 0;
+            // Fetch tables limited for context pack
+            const tables = await this.db.query(`
+          SELECT TABLE_NAME, TABLE_ROWS
+          FROM INFORMATION_SCHEMA.TABLES
+          WHERE TABLE_SCHEMA = ?
+          ORDER BY TABLE_NAME
+          LIMIT ?
+        `, [database, maxTables]);
+            if (!tables.length) {
+                return {
+                    status: "success",
+                    data: {
+                        database,
+                        total_tables: 0,
+                        tables: [],
+                        relationships: [],
+                        context_text: `Schema-Aware RAG Context Pack (${database}): no tables found.`,
+                    },
+                };
+            }
+            const tableNames = tables.map((t) => t.TABLE_NAME);
+            const placeholders = tableNames.map(() => "?").join(",");
+            const columnParams = [database, ...tableNames];
+            const columns = await this.db.query(`
+          SELECT TABLE_NAME, COLUMN_NAME, DATA_TYPE, COLUMN_KEY, IS_NULLABLE
+          FROM INFORMATION_SCHEMA.COLUMNS
+          WHERE TABLE_SCHEMA = ?
+            AND TABLE_NAME IN (${placeholders})
+          ORDER BY TABLE_NAME, ORDINAL_POSITION
+        `, columnParams);
+            let foreignKeys = [];
+            if (includeRelationships) {
+                const fkParams = [database, ...tableNames, ...tableNames];
+                foreignKeys = await this.db.query(`
+            SELECT TABLE_NAME, COLUMN_NAME, REFERENCED_TABLE_NAME, REFERENCED_COLUMN_NAME
+            FROM INFORMATION_SCHEMA.KEY_COLUMN_USAGE
+            WHERE TABLE_SCHEMA = ?
+              AND TABLE_NAME IN (${placeholders})
+              AND REFERENCED_TABLE_NAME IN (${placeholders})
+              AND REFERENCED_TABLE_NAME IS NOT NULL
+          `, fkParams);
+            }
+            const fkLookup = new Map();
+            foreignKeys.forEach((fk) => {
+                fkLookup.set(`${fk.TABLE_NAME}.${fk.COLUMN_NAME}`, {
+                    table: fk.REFERENCED_TABLE_NAME,
+                    column: fk.REFERENCED_COLUMN_NAME,
+                });
+            });
+            const tableEntries = tables.map((table) => {
+                const tableColumns = columns.filter((c) => c.TABLE_NAME === table.TABLE_NAME);
+                const truncatedColumns = tableColumns.length > maxColumns ? tableColumns.length - maxColumns : 0;
+                const columnsForContext = tableColumns.slice(0, maxColumns).map((col) => {
+                    const key = col.COLUMN_KEY === "PRI"
+                        ? "PK"
+                        : col.COLUMN_KEY === "UNI"
+                            ? "UNI"
+                            : undefined;
+                    const fkRef = fkLookup.get(`${col.TABLE_NAME}.${col.COLUMN_NAME}`);
+                    return {
+                        name: col.COLUMN_NAME,
+                        data_type: col.DATA_TYPE,
+                        nullable: col.IS_NULLABLE === "YES",
+                        key: fkRef ? "FK" : key,
+                        references: fkRef
+                            ? `${fkRef.table}.${fkRef.column}`
+                            : undefined,
+                    };
+                });
+                const primaryKeys = tableColumns
+                    .filter((col) => col.COLUMN_KEY === "PRI")
+                    .map((col) => col.COLUMN_NAME);
+                const foreignKeyList = foreignKeys
+                    .filter((fk) => fk.TABLE_NAME === table.TABLE_NAME)
+                    .map((fk) => ({
+                    column: fk.COLUMN_NAME,
+                    references: `${fk.REFERENCED_TABLE_NAME}.${fk.REFERENCED_COLUMN_NAME}`,
+                }));
+                return {
+                    table_name: table.TABLE_NAME,
+                    row_estimate: typeof table.TABLE_ROWS === "number"
+                        ? table.TABLE_ROWS
+                        : parseInt(table.TABLE_ROWS || "0", 10) || 0,
+                    primary_keys: primaryKeys,
+                    columns: columnsForContext,
+                    foreign_keys: foreignKeyList,
+                    truncated_columns: truncatedColumns > 0 ? truncatedColumns : 0,
+                };
+            });
+            const relationships = foreignKeys.map((fk) => ({
+                from_table: fk.TABLE_NAME,
+                from_column: fk.COLUMN_NAME,
+                to_table: fk.REFERENCED_TABLE_NAME,
+                to_column: fk.REFERENCED_COLUMN_NAME,
+            }));
+            const lines = [];
+            lines.push(`Schema-Aware RAG Context Pack (${database})`);
+            lines.push(`Tables shown: ${tableEntries.length}/${totalTables || tableEntries.length} (rows are approximate)`);
+            lines.push(`Per-table column limit: ${maxColumns}${tableEntries.some((t) => t.truncated_columns > 0)
+                ? " (additional columns truncated)"
+                : ""}`);
+            lines.push("");
+            tableEntries.forEach((t) => {
+                const approxRows = typeof t.row_estimate === "number" && t.row_estimate >= 0
+                    ? `~${t.row_estimate}`
+                    : "~0";
+                const columnSnippets = t.columns.map((c) => {
+                    const tags = [];
+                    if (c.key)
+                        tags.push(c.key);
+                    if (c.references)
+                        tags.push(`-> ${c.references}`);
+                    const nullability = c.nullable ? "null" : "not null";
+                    return `${c.name} ${c.data_type} (${nullability})${tags.length ? ` [${tags.join(", ")}]` : ""}`;
+                });
+                lines.push(`- ${t.table_name} (${approxRows} rows) PK: ${t.primary_keys.length ? t.primary_keys.join(", ") : "none"}`);
+                lines.push(`  Columns: ${columnSnippets.join("; ")}`);
+                if (t.truncated_columns) {
+                    lines.push(`  ...and ${t.truncated_columns} more columns not shown`);
+                }
+            });
+            if (includeRelationships && relationships.length) {
+                lines.push("");
+                lines.push("Relationships:");
+                relationships.forEach((rel) => {
+                    lines.push(`- ${rel.from_table}.${rel.from_column} -> ${rel.to_table}.${rel.to_column}`);
+                });
+            }
+            if (totalTables > tableEntries.length) {
+                lines.push(`\nNote: ${totalTables - tableEntries.length} table(s) omitted (max_tables=${maxTables}).`);
+            }
+            return {
+                status: "success",
+                data: {
+                    database,
+                    total_tables: totalTables,
+                    tables: tableEntries,
+                    relationships: includeRelationships ? relationships : [],
+                    context_text: lines.join("\n"),
+                    limits: {
+                        max_tables: maxTables,
+                        max_columns: maxColumns,
+                    },
+                },
+            };
+        }
+        catch (error) {
+            return {
+                status: "error",
+                error: error.message,
+            };
+        }
+    }
+}
+exports.AnalysisTools = AnalysisTools;

package/dist/tools/databaseTools.d.ts

@@ -31,4 +31,25 @@ export declare class DatabaseTools {
         data?: ColumnInfo[];
         error?: string;
     }>;
+    /**
+     * Get a high-level summary of the database (tables, columns, row counts)
+     * Optimized for AI context window
+     */
+    getDatabaseSummary(params: {
+        database?: string;
+    }): Promise<{
+        status: string;
+        data?: string;
+        error?: string;
+    }>;
+    /**
+     * Get a Mermaid.js ER diagram for the database schema
+     */
+    getSchemaERD(params: {
+        database?: string;
+    }): Promise<{
+        status: string;
+        data?: string;
+        error?: string;
+    }>;
 }

package/dist/tools/databaseTools.js

@@ -139,5 +139,143 @@ class DatabaseTools {
             };
         }
     }
+    /**
+     * Get a high-level summary of the database (tables, columns, row counts)
+     * Optimized for AI context window
+     */
+    async getDatabaseSummary(params) {
+        try {
+            // Security validation
+            if (params.database && params.database !== config_1.dbConfig.database) {
+                return {
+                    status: "error",
+                    error: `Access denied. You can only access the connected database '${config_1.dbConfig.database}'.`,
+                };
+            }
+            const database = params.database || config_1.dbConfig.database;
+            if (!database) {
+                return {
+                    status: "error",
+                    error: "No database specified and none connected.",
+                };
+            }
+            // Get tables and row counts
+            const tablesQuery = `
+        SELECT TABLE_NAME, TABLE_ROWS
+        FROM INFORMATION_SCHEMA.TABLES 
+        WHERE TABLE_SCHEMA = ?
+      `;
+            const tables = await this.db.query(tablesQuery, [database]);
+            // Get columns for all tables
+            const columnsQuery = `
+        SELECT TABLE_NAME, COLUMN_NAME, DATA_TYPE, COLUMN_KEY
+        FROM INFORMATION_SCHEMA.COLUMNS 
+        WHERE TABLE_SCHEMA = ?
+        ORDER BY TABLE_NAME, ORDINAL_POSITION
+      `;
+            const columns = await this.db.query(columnsQuery, [database]);
+            // Build text summary
+            let summary = `# Database Summary: ${database}\n\n`;
+            for (const table of tables) {
+                summary += `## Table: ${table.TABLE_NAME} (~${table.TABLE_ROWS || 0} rows)\n`;
+                const tableColumns = columns.filter(c => c.TABLE_NAME === table.TABLE_NAME);
+                const columnDefs = tableColumns.map(c => {
+                    let def = `${c.COLUMN_NAME} (${c.DATA_TYPE})`;
+                    if (c.COLUMN_KEY === 'PRI')
+                        def += " [PK]";
+                    if (c.COLUMN_KEY === 'MUL')
+                        def += " [FK/Index]";
+                    if (c.COLUMN_KEY === 'UNI')
+                        def += " [Unique]";
+                    return def;
+                });
+                summary += `Columns: ${columnDefs.join(", ")}\n\n`;
+            }
+            return {
+                status: "success",
+                data: summary
+            };
+        }
+        catch (error) {
+            return {
+                status: "error",
+                error: error.message
+            };
+        }
+    }
+    /**
+     * Get a Mermaid.js ER diagram for the database schema
+     */
+    async getSchemaERD(params) {
+        try {
+            // Security validation
+            if (params.database && params.database !== config_1.dbConfig.database) {
+                return {
+                    status: "error",
+                    error: `Access denied. You can only access the connected database '${config_1.dbConfig.database}'.`,
+                };
+            }
+            const database = params.database || config_1.dbConfig.database;
+            if (!database) {
+                return {
+                    status: "error",
+                    error: "No database specified and none connected.",
+                };
+            }
+            // Get tables and columns
+            const columnsQuery = `
+        SELECT TABLE_NAME, COLUMN_NAME, DATA_TYPE, COLUMN_KEY
+        FROM INFORMATION_SCHEMA.COLUMNS 
+        WHERE TABLE_SCHEMA = ?
+        ORDER BY TABLE_NAME, ORDINAL_POSITION
+      `;
+            const columns = await this.db.query(columnsQuery, [database]);
+            // Get foreign keys
+            const fkQuery = `
+        SELECT 
+          TABLE_NAME, COLUMN_NAME, 
+          REFERENCED_TABLE_NAME, REFERENCED_COLUMN_NAME
+        FROM INFORMATION_SCHEMA.KEY_COLUMN_USAGE
+        WHERE TABLE_SCHEMA = ? 
+          AND REFERENCED_TABLE_SCHEMA = ? 
+          AND REFERENCED_TABLE_NAME IS NOT NULL
+      `;
+            const fks = await this.db.query(fkQuery, [database, database]);
+            // Build Mermaid ER diagram
+            let mermaid = "erDiagram\n";
+            // Add entities (tables)
+            const tables = [...new Set(columns.map(c => c.TABLE_NAME))];
+            for (const table of tables) {
+                mermaid += `    ${table} {\n`;
+                const tableColumns = columns.filter(c => c.TABLE_NAME === table);
+                for (const col of tableColumns) {
+                    let type = col.DATA_TYPE;
+                    let key = "";
+                    if (col.COLUMN_KEY === 'PRI')
+                        key = "PK";
+                    else if (col.COLUMN_KEY === 'MUL')
+                        key = "FK";
+                    mermaid += `        ${type} ${col.COLUMN_NAME} ${key}\n`;
+                }
+                mermaid += `    }\n`;
+            }
+            // Add relationships
+            for (const fk of fks) {
+                // Relationship logic: referenced_table ||--o{ table
+                // This is a simplification, usually FK implies 1 to Many
+                mermaid += `    ${fk.REFERENCED_TABLE_NAME} ||--o{ ${fk.TABLE_NAME} : "${fk.COLUMN_NAME}"\n`;
+            }
+            return {
+                status: "success",
+                data: mermaid
+            };
+        }
+        catch (error) {
+            return {
+                status: "error",
+                error: error.message
+            };
+        }
+    }
 }
 exports.DatabaseTools = DatabaseTools;

package/dist/tools/queryTools.d.ts

@@ -13,11 +13,16 @@ export declare class QueryTools {
         params?: any[];
         hints?: QueryHints;
         useCache?: boolean;
+        dry_run?: boolean;
     }): Promise<{
         status: string;
         data?: any[];
         error?: string;
         optimizedQuery?: string;
+        dry_run?: boolean;
+        execution_plan?: any;
+        estimated_cost?: string;
+        message?: string;
     }>;
     /**
      * Analyze a query and get optimization suggestions

package/dist/tools/queryTools.js

@@ -61,6 +61,33 @@ class QueryTools {
                     optimizedQuery = finalQuery;
                 }
             }
+            // Handle dry_run: return query plan and cost estimate without executing
+            if (queryParams.dry_run) {
+                const explainQuery = `EXPLAIN FORMAT=JSON ${finalQuery}`;
+                const explainResult = await this.db.query(explainQuery, paramValidation.sanitizedParams);
+                // Try to get cost from JSON format
+                let estimatedCost = "Unknown";
+                let executionPlan = explainResult;
+                if (explainResult[0] && explainResult[0].EXPLAIN) {
+                    try {
+                        const explainJson = JSON.parse(explainResult[0].EXPLAIN);
+                        estimatedCost = explainJson.query_block?.cost_info?.query_cost || "Unknown";
+                        executionPlan = explainJson;
+                    }
+                    catch (e) {
+                        // Ignore parsing error
+                    }
+                }
+                return {
+                    status: "success",
+                    data: [],
+                    optimizedQuery,
+                    dry_run: true,
+                    execution_plan: executionPlan,
+                    estimated_cost: estimatedCost,
+                    message: "Dry run completed. Query was not executed."
+                };
+            }
             // Execute the query with sanitized parameters
             const results = await this.db.query(finalQuery, paramValidation.sanitizedParams, useCache);
             return {

package/manifest.json

@@ -1,7 +1,7 @@
 {
   "name": "mysql-mcp",
   "description": "A Model Context Protocol for MySQL database interaction",
-  "version": "1.4.4",
+  "version": "1.12.0",
   "tools": [
     {
       "name": "list_databases",
@@ -244,6 +244,27 @@
         }
       }
     },
+    {
+      "name": "get_schema_rag_context",
+      "description": "Returns a condensed schema-aware context pack with tables, PK/FK details, and row estimates for RAG prompts.",
+      "input_schema": {
+        "type": "object",
+        "properties": {
+          "database": { "type": "string", "description": "Optional specific database name" },
+          "max_tables": { "type": "number", "description": "Max tables to include (default 50, max 200)" },
+          "max_columns": { "type": "number", "description": "Max columns per table (default 12, max 200)" },
+          "include_relationships": { "type": "boolean", "description": "Whether to include FK relationships (default true)" }
+        }
+      },
+      "output_schema": {
+        "type": "object",
+        "properties": {
+          "database": { "type": "string" },
+          "total_tables": { "type": "number" },
+          "context_text": { "type": "string" }
+        }
+      }
+    },
     {
       "name": "get_table_size",
       "description": "Gets size information for one or all tables including data and index sizes.",