@berthojoris/mcp-mysql-server 1.42.1 → 1.43.0

package/dist/tools/toolArgumentValidation.js

@@ -95,6 +95,111 @@ const validateSeedFromTemplateArgs = (args) => {
     validateRowsPerTable(args.rows_per_table, errors);
     return errors.length ? { valid: false, errors } : { valid: true };
 };
+const validateDiscoveryKeyword = (value, key, errors) => {
+    if (!value || typeof value !== "string" || !value.trim()) {
+        errors.push(`${key} is required`);
+        return;
+    }
+    if (value.length > 255) {
+        errors.push(`${key} must be 255 characters or fewer`);
+        return;
+    }
+    const validation = (0, inputValidation_js_1.validateValue)(value);
+    if (!validation.valid)
+        errors.push(validation.error || `Invalid ${key}`);
+};
+const validatePositiveNumber = (value, key, min, max, errors) => {
+    if (value === undefined)
+        return;
+    const numeric = Number(value);
+    if (!Number.isFinite(numeric) || numeric < min || numeric > max) {
+        errors.push(`${key} must be a number between ${min} and ${max}`);
+    }
+};
+const validateColumnList = (value, key, errors) => {
+    if (value === undefined)
+        return;
+    if (!Array.isArray(value)) {
+        errors.push(`${key} must be an array`);
+        return;
+    }
+    for (const column of value) {
+        const validation = (0, inputValidation_js_1.validateTableName)(column);
+        if (!validation.valid) {
+            errors.push(`Invalid ${key} column '${column}': ${validation.error}`);
+        }
+    }
+};
+const validateFindTablesByKeywordArgs = (args) => {
+    const errors = [];
+    validateDiscoveryKeyword(args.keyword, "keyword", errors);
+    if (args.search_in !== undefined && !["table_names", "column_names", "comments", "all"].includes(args.search_in)) {
+        errors.push("search_in must be one of table_names, column_names, comments, all");
+    }
+    if (args.database !== undefined) {
+        const validation = (0, inputValidation_js_1.validateValue)(args.database);
+        if (!validation.valid)
+            errors.push(validation.error || "Invalid database name");
+    }
+    validatePositiveNumber(args.limit, "limit", 1, 100, errors);
+    return errors.length ? { valid: false, errors } : { valid: true };
+};
+const validateSearchDataAcrossTablesArgs = (args) => {
+    const errors = [];
+    validateDiscoveryKeyword(args.keyword, "keyword", errors);
+    if (args.database !== undefined) {
+        const validation = (0, inputValidation_js_1.validateValue)(args.database);
+        if (!validation.valid)
+            errors.push(validation.error || "Invalid database name");
+    }
+    validateTableList(args.tables, "tables", errors);
+    validateColumnList(args.columns, "columns", errors);
+    validatePositiveNumber(args.max_tables, "max_tables", 1, 100, errors);
+    validatePositiveNumber(args.limit_per_table, "limit_per_table", 1, 20, errors);
+    return errors.length ? { valid: false, errors } : { valid: true };
+};
+const validateSearchSchemaArgs = (args) => {
+    const errors = [];
+    validateDiscoveryKeyword(args.query, "query", errors);
+    if (args.database !== undefined) {
+        const validation = (0, inputValidation_js_1.validateValue)(args.database);
+        if (!validation.valid)
+            errors.push(validation.error || "Invalid database name");
+    }
+    if (args.modes !== undefined) {
+        if (!Array.isArray(args.modes) || args.modes.length === 0) {
+            errors.push("modes must be a non-empty array");
+        }
+        else {
+            const validModes = ["table_names", "column_names", "comments", "sample_data"];
+            for (const mode of args.modes) {
+                if (!validModes.includes(mode)) {
+                    errors.push(`Invalid mode '${mode}'. Must be one of ${validModes.join(", ")}`);
+                }
+            }
+        }
+    }
+    validateTableList(args.tables, "tables", errors);
+    validateColumnList(args.columns, "columns", errors);
+    validatePositiveNumber(args.max_results, "max_results", 1, 100, errors);
+    validatePositiveNumber(args.max_tables, "max_tables", 1, 100, errors);
+    validatePositiveNumber(args.limit_per_table, "limit_per_table", 1, 20, errors);
+    return errors.length ? { valid: false, errors } : { valid: true };
+};
+const validateSchemaRagContextArgs = (args) => {
+    const errors = [];
+    if (args.database !== undefined) {
+        const validation = (0, inputValidation_js_1.validateValue)(args.database);
+        if (!validation.valid)
+            errors.push(validation.error || "Invalid database name");
+    }
+    if (args.keyword_filter !== undefined) {
+        validateDiscoveryKeyword(args.keyword_filter, "keyword_filter", errors);
+    }
+    validatePositiveNumber(args.max_tables, "max_tables", 1, 200, errors);
+    validatePositiveNumber(args.max_columns, "max_columns", 1, 200, errors);
+    return errors.length ? { valid: false, errors } : { valid: true };
+};
 const validatePlanIdArgs = (args) => {
     if (!args.plan_id || typeof args.plan_id !== "string") {
         return { valid: false, errors: ["plan_id is required"] };
@@ -138,9 +243,16 @@ function validateToolArguments(name, args) {
                 return validateInferSeedRulesArgs(args);
             case "seed_from_template":
                 return validateSeedFromTemplateArgs(args);
+            case "find_tables_by_keyword":
+                return validateFindTablesByKeywordArgs(args);
+            case "search_schema":
+                return validateSearchSchemaArgs(args);
+            case "search_data_across_tables":
+                return validateSearchDataAcrossTablesArgs(args);
+            case "get_schema_rag_context":
+                return validateSchemaRagContextArgs(args);
             case "list_tables":
             case "get_schema_erd":
-            case "get_schema_rag_context":
             case "get_database_summary":
                 if (args.database !== undefined) {
                     const validation = (0, inputValidation_js_1.validateValue)(args.database);

package/dist/tools/utilityTools.js

@@ -347,6 +347,13 @@ class UtilityTools {
                                 "get_database_summary",
                                 "get_schema_rag_context",
                             ],
+                            discover_concept_location: [
+                                "find_tables_by_keyword",
+                                "search_schema",
+                                "read_table_schema on likely matches",
+                                "read_records on likely matches for verification",
+                                "search_data_across_tables only when the keyword may exist only in row data",
+                            ],
                             inspect_table: [
                                 "read_table_schema",
                                 "get_column_statistics",
@@ -375,9 +382,11 @@ class UtilityTools {
                             ],
                         },
                         selection_rules: [
-                            "Use get_schema_rag_context before generating SQL to reduce token usage.",
+                            "Use get_schema_rag_context before generating SQL to reduce token usage; add keyword_filter for concept-focused context.",
+                            "Use find_tables_by_keyword or search_schema when users ask which table stores a concept.",
+                            "Use search_data_across_tables only as a bounded fallback after schema metadata is inconclusive.",
                             "Use run_select_query only for SELECT statements.",
-                            "Use execute_write_query for INSERT, UPDATE, and DELETE.",
+                            "Use execute_write_query for INSERT and UPDATE. DELETE requires the delete permission.",
                             "Use execute_ddl only for CREATE, ALTER, DROP, TRUNCATE, and RENAME.",
                             "Use seed_operations for relational dummy data instead of manually chaining bulk_insert across foreign keys.",
                             "Prefer structured tools over raw SQL when possible.",

package/manifest.json

@@ -1,7 +1,7 @@
 {
   "name": "mysql-mcp",
   "description": "A Model Context Protocol for MySQL database interaction",
-  "version": "1.42.1",
+  "version": "1.43.0",
   "tools": [
     {
       "name": "list_databases",
@@ -72,7 +72,7 @@
     },
     {
       "name": "get_schema_rag_context",
-      "description": "🎯 AI-OPTIMIZED: Returns ultra-compact schema information (tables, columns, keys, relationships, row estimates) designed specifically for LLM context windows. Use this when you need schema awareness but want to minimize token usage. Configurable limits for tables/columns.",
+      "description": "🎯 AI-OPTIMIZED: Returns ultra-compact schema information (tables, columns, keys, relationships, comments, row estimates) designed specifically for LLM context windows. Use keyword_filter for concept-focused schema discovery.",
       "input_schema": {
         "type": "object",
         "properties": {
@@ -91,6 +91,14 @@
           "include_relationships": {
             "type": "boolean",
             "description": "Whether to include FK relationships section (default: true)"
+          },
+          "include_comments": {
+            "type": "boolean",
+            "description": "Optional: include TABLE_COMMENT and COLUMN_COMMENT metadata (default: false)"
+          },
+          "keyword_filter": {
+            "type": "string",
+            "description": "Optional: only include tables relevant to this keyword, ranked by table names, column names, and comments"
           }
         }
       },
@@ -98,6 +106,150 @@
         "type": "object"
       }
     },
+    {
+      "name": "find_tables_by_keyword",
+      "description": "🔎 Schema discovery: finds candidate tables for a concept or keyword by searching table names, column names, TABLE_COMMENT, and COLUMN_COMMENT metadata. Use when users ask 'which table stores X?' before reading sample data.",
+      "input_schema": {
+        "type": "object",
+        "properties": {
+          "keyword": {
+            "type": "string",
+            "description": "Concept or keyword to find, such as survey, invoice, feedback, or customer"
+          },
+          "search_in": {
+            "type": "string",
+            "enum": [
+              "table_names",
+              "column_names",
+              "comments",
+              "all"
+            ],
+            "description": "Where to search (default: all)"
+          },
+          "database": {
+            "type": "string",
+            "description": "Optional: specific database name"
+          },
+          "limit": {
+            "type": "number",
+            "description": "Optional: maximum number of ranked tables to return (default 20, max 100)"
+          }
+        },
+        "required": [
+          "keyword"
+        ]
+      },
+      "output_schema": {
+        "type": "object"
+      }
+    },
+    {
+      "name": "search_schema",
+      "description": "🧭 Unified schema discovery for natural-language 'where is X?' questions. Searches schema metadata by default and can optionally perform a guarded sample-data scan when mode sample_data is requested.",
+      "input_schema": {
+        "type": "object",
+        "properties": {
+          "query": {
+            "type": "string",
+            "description": "Concept or keyword to discover"
+          },
+          "modes": {
+            "type": "array",
+            "items": {
+              "type": "string",
+              "enum": [
+                "table_names",
+                "column_names",
+                "comments",
+                "sample_data"
+              ]
+            },
+            "description": "Discovery modes (default: table_names, column_names, comments). sample_data requires read permission."
+          },
+          "max_results": {
+            "type": "number",
+            "description": "Optional: maximum combined results to return (default 20, max 100)"
+          },
+          "database": {
+            "type": "string",
+            "description": "Optional: specific database name"
+          },
+          "tables": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "Optional: restrict sample_data mode to these tables"
+          },
+          "columns": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "Optional: restrict sample_data mode to these columns"
+          },
+          "max_tables": {
+            "type": "number",
+            "description": "Optional: max tables scanned in sample_data mode (default 20, max 100)"
+          },
+          "limit_per_table": {
+            "type": "number",
+            "description": "Optional: max matching rows returned per table in sample_data mode (default 5, max 20)"
+          }
+        },
+        "required": [
+          "query"
+        ]
+      },
+      "output_schema": {
+        "type": "object"
+      }
+    },
+    {
+      "name": "search_data_across_tables",
+      "description": "🔍 Guarded read-only keyword scan across text-like table data. Use only when schema metadata does not reveal where a concept is stored; enforces max table and per-table result limits.",
+      "input_schema": {
+        "type": "object",
+        "properties": {
+          "keyword": {
+            "type": "string",
+            "description": "Keyword to search inside text-like column values"
+          },
+          "tables": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "Optional: restrict scan to these tables"
+          },
+          "columns": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "Optional: restrict scan to these column names"
+          },
+          "database": {
+            "type": "string",
+            "description": "Optional: specific database name"
+          },
+          "max_tables": {
+            "type": "number",
+            "description": "Optional: maximum tables to scan (default 20, max 100)"
+          },
+          "limit_per_table": {
+            "type": "number",
+            "description": "Optional: maximum rows returned per table (default 5, max 20)"
+          }
+        },
+        "required": [
+          "keyword"
+        ]
+      },
+      "output_schema": {
+        "type": "object"
+      }
+    },
     {
       "name": "get_column_statistics",
       "description": "Returns detailed statistics for a specific column: min/max values, average, distinct count, null percentage, and value distribution. Use to understand data quality and ranges in a column before writing queries.",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@berthojoris/mcp-mysql-server",
-  "version": "1.42.1",
+  "version": "1.43.0",
   "description": "Model Context Protocol server for MySQL database integration with dynamic per-project permissions",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",