@berthojoris/mcp-mysql-server 1.42.2 → 1.43.2

package/CHANGELOG.md

@@ -5,6 +5,31 @@ 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.2] - 2026-07-23
+
+### Changed
+- Version bump to `1.43.2` for npm publish.
+- Synchronized version across `package.json`, `src/mcp-server.ts`, `DOCUMENTATIONS.md`, `README.md`, and `manifest.json`.
+
+## [1.43.1] - 2026-05-26
+
+### Fixed
+- **URL-encoded credentials in MySQL connection strings** (#4): authentication failed when the username or password contained URL-encoded special characters (e.g. `@` → `%40`, `:` → `%3A`).
+  - Both `url.username` and `url.password` are now passed through `decodeURIComponent()` before being handed to the MySQL client.
+  - The decoding is also applied when only one of the two is set (e.g. `mysql://:p%40ss%3Aw0rd@host/db` or `mysql://us%40er@host/db`), which previously bypassed decoding entirely.
+
+### Changed
+- Synchronized version to `1.43.1` across `package.json`, `src/mcp-server.ts`, `DOCUMENTATIONS.md`, and `README.md`.
+
+## [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

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-07-23 05:00:00
+**Version:** 1.43.2
+**Total Tools:** 88
 
 Comprehensive documentation for the MySQL MCP Server. For quick start, see [README.md](README.md).
 
@@ -47,6 +47,8 @@ Configure MySQL MCP with two access-control layers:
 **Layer 1 (Permissions)**: Broad operation control  
 **Layer 2 (Categories)**: Fine-grained tool filtering  
 
+> **Credentials with special characters**: if the username or password in the connection string contains URL-reserved characters (`@`, `:`, `/`, `?`, `#`, `%`, `&`, etc.), URL-encode them — e.g. the password `p@ss:w0rd` becomes `p%40ss%3Aw0rd`, giving `mysql://user:p%40ss%3Aw0rd@host:3306/db`. The server passes both the username and password through `decodeURIComponent()` before connecting, including when only one of the two is set.
+
 ### Environment Variables
 
 ```json
@@ -134,11 +136,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
@@ -270,6 +275,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 +360,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-25 12:00:00
+**Last Updated:** 2026-07-23 05:00:00
 
 [![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)
@@ -66,6 +66,8 @@ npm install -g @berthojoris/mcp-mysql-server
 mcp-mysql mysql://user:pass@localhost:3306/db "list,read,utility"
 ```
 
+> **Credentials with special characters**: if your username or password contains characters that have a special meaning in URLs (`@`, `:`, `/`, `?`, `#`, `%`, `&`, etc.), URL-encode them before putting them in the connection string. For example, the password `p@ss:w0rd` becomes `p%40ss%3Aw0rd`, giving `mysql://user:p%40ss%3Aw0rd@host:3306/db`. The server decodes both the username and password before connecting.
+
 ---
 
 ## Quick Start
@@ -294,7 +296,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 +313,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/bin/mcp-mysql.js

@@ -95,11 +95,15 @@ try {
   // Remove leading slash from pathname and make database optional
   database = url.pathname.replace(/^\//, "") || null;
 
-  // Extract username and password from auth
-  const auth =
-    url.username && url.password
-      ? { user: url.username, password: url.password }
-      : { user: url.username || "root", password: url.password || "" };
+  // Extract username and password from auth.
+  // Both fields may be URL-encoded (e.g. "@" -> "%40"), so always decode
+  // whatever the URL parser hands us, including when only one side is set.
+  const decodeAuthField = (value) =>
+    value ? decodeURIComponent(value) : value;
+  const auth = {
+    user: decodeAuthField(url.username) || "root",
+    password: decodeAuthField(url.password) || "",
+  };
 
   connectionConfig = {
     host: url.hostname,

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.2";
+const SERVER_VERSION = "1.43.2";
 // 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"],
         },
     },
     {
@@ -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/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 {};