@berthojoris/mcp-mysql-server 1.42.1 → 1.43.0

package/CHANGELOG.md

@@ -5,6 +5,23 @@ All notable changes to the MySQL MCP Server will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.43.0] - 2026-05-25
+
+### Added
+- Added `find_tables_by_keyword`, `search_schema`, and `search_data_across_tables` to help agents answer natural-language schema discovery questions such as “which table stores survey data?”.
+- Added keyword filtering and optional TABLE/COLUMN comments to `get_schema_rag_context`.
+
+### Changed
+- Updated analysis tool totals and version metadata to `1.43.0`.
+
+## [1.42.2] - 2026-05-25
+
+### Fixed
+- Blocked DELETE SQL in `execute_write_query` and `execute_in_transaction` unless the `delete` permission is explicitly enabled, closing a bypass where `execute` alone could delete data via custom SQL.
+
+### Changed
+- Clarified tool and permission documentation: `execute` covers INSERT/UPDATE custom SQL; DELETE requires the separate `delete` permission.
+
 ## [1.42.1] - 2026-05-11
 
 ### Changed

package/DOCUMENTATIONS.md

@@ -1,8 +1,8 @@
 # MySQL MCP Server - Documentation
 
-**Last Updated:** 2026-05-11 13:33:42
-**Version:** 1.42.1
-**Total Tools:** 85
+**Last Updated:** 2026-05-25 14:52:30
+**Version:** 1.43.0
+**Total Tools:** 88
 
 Comprehensive documentation for the MySQL MCP Server. For quick start, see [README.md](README.md).
 
@@ -111,8 +111,8 @@ For CSV exports, use `export_table_to_csv` for table-based exports and `export_q
 | `read` | Read data | `read_records`, `run_select_query` |
 | `create` | Insert records and seed data | `create_record`, `bulk_insert`, `execute_seed_plan` |
 | `update` | Update records | `update_record`, `bulk_update` |
-| `delete` | Delete records | `delete_record`, `bulk_delete` |
-| `execute` | Custom SQL | `execute_write_query` |
+| `delete` | Delete records | `delete_record`, `bulk_delete`, DELETE via `execute_write_query` (requires both `execute` and `delete`) |
+| `execute` | Custom SQL (INSERT/UPDATE; not DELETE without `delete`) | `execute_write_query` |
 | `ddl` | Schema changes | `create_table`, `alter_table` |
 | `utility` | Utility operations | `test_connection`, `analyze_table` |
 | `transaction` | Transaction management | `begin_transaction`, `commit_transaction` |
@@ -134,11 +134,14 @@ Tool enabled = (Has Permission) AND (Has Category OR No categories specified)
 - `read_table_schema` - Get table structure
 - `get_all_tables_relationships` - Get all FK relationships
 
-### 2. Analysis (4 tools)
+### 2. Analysis (7 tools)
 - `get_database_summary` - Database overview with statistics
 - `get_schema_erd` - Generate Mermaid.js ER diagram
-- `get_schema_rag_context` - Compact schema for LLM context
+- `get_schema_rag_context` - Compact schema for LLM context, with optional comments and keyword filtering
 - `get_column_statistics` - Column data profiling
+- `find_tables_by_keyword` - Ranked schema keyword search across table names, column names, and comments
+- `search_schema` - Unified discovery for “where is X?” questions using schema metadata and optional sample-data search
+- `search_data_across_tables` - Guarded read-only keyword search across text-like data columns
 
 ### 3. Data Operations (7 tools)
 - `create_record` - Insert single record
@@ -159,7 +162,7 @@ Tool enabled = (Has Permission) AND (Has Category OR No categories specified)
 
 ### 5. Query Management (3 tools)
 - `run_select_query` - Execute SELECT queries
-- `execute_write_query` - Execute INSERT/UPDATE/DELETE
+- `execute_write_query` - Execute INSERT/UPDATE (DELETE requires the `delete` permission)
 - `repair_query` - Diagnose and fix SQL errors
 
 ### 6. Schema Management (4 tools)
@@ -270,6 +273,35 @@ await mcp.call("get_database_summary", {
 await mcp.call("get_schema_erd", {});
 ```
 
+### Schema & Data Discovery
+
+Use these tools when users ask natural-language questions like “which table stores survey data?” or “where is customer feedback saved?”:
+
+```javascript
+// Fast metadata search across table names, column names, and comments
+await mcp.call("find_tables_by_keyword", {
+  keyword: "survey",
+  search_in: "all",
+  limit: 20
+});
+
+// Unified discovery with optional guarded sample-data scan
+await mcp.call("search_schema", {
+  query: "survey",
+  modes: ["table_names", "column_names", "comments", "sample_data"],
+  max_results: 20
+});
+
+// Direct bounded data scan when the keyword may only exist in row values
+await mcp.call("search_data_across_tables", {
+  keyword: "survey",
+  max_tables: 20,
+  limit_per_table: 3
+});
+```
+
+`find_tables_by_keyword` requires `list`; `search_data_across_tables` requires `read`; `search_schema` uses `list` and requires `read` only when `sample_data` mode is enabled.
+
 ### Data Operations
 
 Basic CRUD operations:
@@ -326,8 +358,11 @@ The server includes analysis tools for database insights:
 
 - **Database Summary**: Provides readable overviews with statistics
 - **ER Diagram Generation**: Automatic Mermaid.js diagrams
-- **RAG Context**: Compact schema for LLM prompts
+- **RAG Context**: Compact schema for LLM prompts, with optional `TABLE_COMMENT` / `COLUMN_COMMENT` inclusion and keyword filtering
 - **Column Profiling**: Data quality and distribution analysis
+- **Schema Keyword Discovery**: Ranked search for concepts across table names, column names, and metadata comments
+- **Unified Search**: One entry point for schema and bounded sample-data discovery
+- **Guarded Data Search**: Read-only LIKE scans across text-like columns with strict table/result limits
 
 ### Bulk Operations
 

package/README.md

@@ -4,7 +4,7 @@
 
 **A production-ready Model Context Protocol (MCP) server for MySQL database integration with AI agents**
 
-**Last Updated:** 2026-05-11 13:33:42
+**Last Updated:** 2026-05-25 14:52:30
 
 [![npm version](https://img.shields.io/npm/v/@berthojoris/mcp-mysql-server)](https://www.npmjs.com/package/@berthojoris/mcp-mysql-server)
 [![npm downloads](https://img.shields.io/npm/dm/@berthojoris/mcp-mysql-server)](https://www.npmjs.com/package/@berthojoris/mcp-mysql-server)
@@ -263,7 +263,7 @@ Control database access with a **dual-layer filtering system** that provides bot
 | `create` | INSERT new records | Data entry |
 | `update` | UPDATE existing records | Data maintenance |
 | `delete` | DELETE records | Data cleanup |
-| `execute` | Execute custom SQL (DML) + Advanced SQL | Complex operations |
+| `execute` | Execute custom INSERT/UPDATE SQL (DELETE requires `delete` permission too) | Complex write operations |
 | `ddl` | CREATE/ALTER/DROP tables | Schema management |
 | `procedure` | Stored procedures (CREATE/DROP/EXECUTE) | Procedure management |
 | `transaction` | BEGIN, COMMIT, ROLLBACK | ACID operations |
@@ -294,7 +294,7 @@ Use documentation categories to fine-tune which tools are exposed (Layer 2):
 | `constraint_management` | Manage data integrity constraints | `add_check_constraint, add_foreign_key, add_unique_constraint, drop_constraint, drop_foreign_key, list_constraints, list_foreign_keys` |
 | `table_maintenance` | Table optimization, repair, and maintenance | `analyze_table, check_table, flush_table, get_table_size, get_table_status, optimize_table, repair_table, truncate_table` |
 | `query_optimization` | Analyze and optimize SQL queries | `analyze_query, get_optimization_hints` |
-| `analysis` | Data analysis and reporting tools | `get_column_statistics, get_database_summary, get_schema_erd, get_schema_rag_context` |
+| `analysis` | Data analysis, schema discovery, and reporting tools | `find_tables_by_keyword, get_column_statistics, get_database_summary, get_schema_erd, get_schema_rag_context, search_data_across_tables, search_schema` |
 
 <details>
   <summary>Copy/paste list (comma-separated, no spaces)</summary>
@@ -311,7 +311,7 @@ Full category → tool mapping (and examples) lives in **[DOCUMENTATIONS.md →
 
 ## Available Tools
 
-The server exposes **85 tools** organized into categories (CRUD, seed, schema, and utilities).
+The server exposes **88 tools** organized into categories (CRUD, seed, schema, discovery, and utilities).
 
 - Complete list of tools: **[DOCUMENTATIONS.md → Complete Tools Reference](DOCUMENTATIONS.md#🔧-complete-tools-reference)**
 

package/dist/config/featureConfig.js

@@ -62,6 +62,13 @@ exports.toolCategoryMap = {
     getSchemaErd: ToolCategory.LIST,
     get_schema_erd: ToolCategory.LIST,
     getSchemaRagContext: ToolCategory.LIST,
+    findTablesByKeyword: ToolCategory.LIST,
+    find_tables_by_keyword: ToolCategory.LIST,
+    searchSchema: ToolCategory.LIST,
+    search_schema: ToolCategory.LIST,
+    searchSchemaWithSampleData: ToolCategory.READ,
+    searchDataAcrossTables: ToolCategory.READ,
+    search_data_across_tables: ToolCategory.READ,
     // CRUD tools
     createRecord: ToolCategory.CREATE,
     readRecords: ToolCategory.READ,
@@ -287,6 +294,13 @@ exports.toolDocCategoryMap = {
     get_schema_erd: DocCategory.ANALYSIS,
     getColumnStatistics: DocCategory.ANALYSIS,
     getSchemaRagContext: DocCategory.ANALYSIS,
+    findTablesByKeyword: DocCategory.ANALYSIS,
+    find_tables_by_keyword: DocCategory.ANALYSIS,
+    searchSchema: DocCategory.ANALYSIS,
+    search_schema: DocCategory.ANALYSIS,
+    searchSchemaWithSampleData: DocCategory.ANALYSIS,
+    searchDataAcrossTables: DocCategory.ANALYSIS,
+    search_data_across_tables: DocCategory.ANALYSIS,
     // Full-Text Search
     createFulltextIndex: DocCategory.INDEX_MANAGEMENT,
     fulltextSearch: DocCategory.INDEX_MANAGEMENT,

package/dist/index.d.ts

@@ -140,11 +140,49 @@ export declare class MySQLMCP {
         data?: any;
         error?: string;
     }>;
+    findTablesByKeyword(params: {
+        keyword: string;
+        search_in?: "table_names" | "column_names" | "comments" | "all";
+        database?: string;
+        limit?: number;
+    }): Promise<{
+        status: string;
+        data?: any;
+        error?: string;
+    }>;
+    searchSchema(params: {
+        query: string;
+        modes?: Array<"table_names" | "column_names" | "comments" | "sample_data">;
+        max_results?: number;
+        database?: string;
+        tables?: string[];
+        columns?: string[];
+        max_tables?: number;
+        limit_per_table?: number;
+    }): Promise<{
+        status: string;
+        data?: any;
+        error?: string;
+    }>;
+    searchDataAcrossTables(params: {
+        keyword: string;
+        tables?: string[];
+        columns?: string[];
+        database?: string;
+        limit_per_table?: number;
+        max_tables?: number;
+    }): Promise<{
+        status: string;
+        data?: any;
+        error?: string;
+    }>;
     getSchemaRagContext(params: {
         database?: string;
         max_tables?: number;
         max_columns?: number;
         include_relationships?: boolean;
+        include_comments?: boolean;
+        keyword_filter?: string;
     }): Promise<{
         status: string;
         data?: any;

package/dist/index.js

@@ -169,6 +169,33 @@ class MySQLMCP {
         }
         return await this.analysisTools.getColumnStatistics(params);
     }
+    async findTablesByKeyword(params) {
+        const check = this.checkToolEnabled("findTablesByKeyword");
+        if (!check.enabled) {
+            return { status: "error", error: check.error };
+        }
+        return await this.analysisTools.findTablesByKeyword(params);
+    }
+    async searchSchema(params) {
+        const check = this.checkToolEnabled("searchSchema");
+        if (!check.enabled) {
+            return { status: "error", error: check.error };
+        }
+        if (params?.modes?.includes("sample_data")) {
+            const readCheck = this.checkToolEnabled("searchSchemaWithSampleData");
+            if (!readCheck.enabled) {
+                return { status: "error", error: readCheck.error };
+            }
+        }
+        return await this.analysisTools.searchSchema(params);
+    }
+    async searchDataAcrossTables(params) {
+        const check = this.checkToolEnabled("searchDataAcrossTables");
+        if (!check.enabled) {
+            return { status: "error", error: check.error };
+        }
+        return await this.analysisTools.searchDataAcrossTables(params);
+    }
     async getSchemaRagContext(params) {
         const check = this.checkToolEnabled("getSchemaRagContext");
         if (!check.enabled) {

package/dist/mcp-server.js

@@ -18,7 +18,7 @@ const toolArgumentValidation_js_1 = require("./tools/toolArgumentValidation.js")
 const permissions = process.env.MCP_PERMISSIONS || process.env.MCP_CONFIG || "";
 const categories = process.env.MCP_CATEGORIES || "";
 const SERVER_NAME = "mysql-mcp-server";
-const SERVER_VERSION = "1.42.1";
+const SERVER_VERSION = "1.43.0";
 // Declare the MySQL MCP instance (will be initialized in main())
 let mysqlMCP;
 // Define all available tools with their schemas
@@ -80,7 +80,7 @@ const TOOLS = [
     },
     {
         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.",
         inputSchema: {
             type: "object",
             properties: {
@@ -100,7 +100,126 @@ const TOOLS = [
                     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",
+                },
+            },
+        },
+    },
+    {
+        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.",
+        inputSchema: {
+            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"],
+        },
+    },
+    {
+        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.",
+        inputSchema: {
+            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"],
+        },
+    },
+    {
+        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.",
+        inputSchema: {
+            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"],
         },
     },
     {
@@ -695,7 +814,7 @@ const TOOLS = [
     },
     {
         name: "run_select_query",
-        description: "⚡ PRIMARY TOOL FOR SELECT QUERIES. Executes read-only SELECT statements with parameterization, optimizer hints, query caching, and dry-run mode. Supports complex queries with JOINs, subqueries, and aggregations. ⚠️ ONLY for SELECT - use execute_write_query for INSERT/UPDATE/DELETE, use execute_ddl for CREATE/ALTER/DROP.",
+        description: "⚡ PRIMARY TOOL FOR SELECT QUERIES. Executes read-only SELECT statements with parameterization, optimizer hints, query caching, and dry-run mode. Supports complex queries with JOINs, subqueries, and aggregations. ⚠️ ONLY for SELECT - use execute_write_query for INSERT/UPDATE, use execute_ddl for CREATE/ALTER/DROP.",
         inputSchema: {
             type: "object",
             properties: {
@@ -762,13 +881,13 @@ const TOOLS = [
     },
     {
         name: "execute_write_query",
-        description: '⚡ PRIMARY TOOL FOR INSERT/UPDATE/DELETE QUERIES. Executes data modification statements with parameterization support. Returns affected row count and execution details. ⚠️ NOT for SELECT (use run_select_query), NOT for DDL (use execute_ddl for CREATE/ALTER/DROP/TRUNCATE/RENAME).',
+        description: '⚡ PRIMARY TOOL FOR INSERT/UPDATE QUERIES. Executes data modification statements with parameterization support. Returns affected row count and execution details. DELETE SQL requires the separate "delete" permission in addition to "execute". ⚠️ NOT for SELECT (use run_select_query), NOT for DDL (use execute_ddl for CREATE/ALTER/DROP/TRUNCATE/RENAME).',
         inputSchema: {
             type: "object",
             properties: {
                 query: {
                     type: "string",
-                    description: "SQL query to execute (INSERT, UPDATE, DELETE, or DDL if permitted)",
+                    description: "SQL query to execute (INSERT or UPDATE; DELETE requires the delete permission)",
                 },
                 params: {
                     type: "array",
@@ -2306,6 +2425,15 @@ server.setRequestHandler(types_js_1.CallToolRequestSchema, async (request) => {
             case "get_schema_rag_context":
                 result = await mysqlMCP.getSchemaRagContext((args || {}));
                 break;
+            case "find_tables_by_keyword":
+                result = await mysqlMCP.findTablesByKeyword((args || {}));
+                break;
+            case "search_schema":
+                result = await mysqlMCP.searchSchema((args || {}));
+                break;
+            case "search_data_across_tables":
+                result = await mysqlMCP.searchDataAcrossTables((args || {}));
+                break;
             case "get_column_statistics":
                 result = await mysqlMCP.getColumnStatistics((args || {}));
                 break;

package/dist/security/securityLayer.js

@@ -273,6 +273,15 @@ class SecurityLayer {
                         };
                     }
                 }
+                // DELETE requires explicit delete permission (execute alone is not sufficient)
+                if (type === "DELETE") {
+                    if (!this.featureConfig.isCategoryEnabled(featureConfig_js_1.ToolCategory.DELETE)) {
+                        return {
+                            valid: false,
+                            error: "DELETE operation requires 'delete' permission. Add 'delete' to your permissions configuration, or use delete_record / bulk_delete.",
+                        };
+                    }
+                }
                 return { valid: true, queryType: type };
             }
         }

package/dist/tools/analysisTools.d.ts

@@ -1,4 +1,6 @@
 import { SecurityLayer } from "../security/securityLayer";
+type SchemaSearchScope = "table_names" | "column_names" | "comments" | "all";
+type SearchSchemaMode = "table_names" | "column_names" | "comments" | "sample_data";
 export declare class AnalysisTools {
     private db;
     private security;
@@ -7,6 +9,13 @@ export declare class AnalysisTools {
      * Validate database access - ensures only the connected database can be accessed
      */
     private validateDatabaseAccess;
+    private clampNumber;
+    private escapeLikePattern;
+    private quoteIdentifier;
+    private truncateValue;
+    private getMatchScore;
+    private addMatchedField;
+    private getTablesByName;
     /**
      * Get statistics for a specific column
      */
@@ -19,6 +28,51 @@ export declare class AnalysisTools {
         data?: any;
         error?: string;
     }>;
+    /**
+     * Find candidate tables by keyword across schema metadata.
+     */
+    findTablesByKeyword(params: {
+        keyword: string;
+        search_in?: SchemaSearchScope;
+        database?: string;
+        limit?: number;
+    }): Promise<{
+        status: string;
+        data?: any;
+        error?: string;
+    }>;
+    /**
+     * Guarded read-only keyword search across text-like data columns.
+     */
+    searchDataAcrossTables(params: {
+        keyword: string;
+        tables?: string[];
+        columns?: string[];
+        database?: string;
+        limit_per_table?: number;
+        max_tables?: number;
+    }): Promise<{
+        status: string;
+        data?: any;
+        error?: string;
+    }>;
+    /**
+     * Unified discovery entry point for "where is X?" questions.
+     */
+    searchSchema(params: {
+        query: string;
+        modes?: SearchSchemaMode[];
+        max_results?: number;
+        database?: string;
+        tables?: string[];
+        columns?: string[];
+        max_tables?: number;
+        limit_per_table?: number;
+    }): Promise<{
+        status: string;
+        data?: any;
+        error?: string;
+    }>;
     /**
      * Build a compact, schema-aware context pack for RAG (tables, PK/FK, columns, row estimates)
      */
@@ -27,9 +81,12 @@ export declare class AnalysisTools {
         max_tables?: number;
         max_columns?: number;
         include_relationships?: boolean;
+        include_comments?: boolean;
+        keyword_filter?: string;
     }): Promise<{
         status: string;
         data?: any;
         error?: string;
     }>;
 }
+export {};