@berthojoris/mcp-mysql-server 1.15.0 → 1.16.1

package/CHANGELOG.md

@@ -5,6 +5,46 @@ 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.16.1] - 2025-12-09
+
+### Improved
+- **Enhanced Tool Descriptions** - Improved tool descriptions to help LLMs select the correct tool:
+  - `run_query`: Now explicitly states "⚡ USE THIS FOR SELECT QUERIES"
+  - `execute_sql`: Now explicitly states "⚡ USE THIS FOR INSERT/UPDATE/DELETE"
+  - `execute_ddl`: Now explicitly states "⚡ USE THIS FOR DDL ONLY" with clear guidance
+  - Added "NO SELECT queries!" warning to `execute_ddl` parameter description
+
+### Fixed
+- **Better Error Messages** - `execute_ddl` now suggests the correct tool when called with wrong query type:
+  - "For SELECT queries, use the 'run_query' tool instead"
+  - "For INSERT/UPDATE/DELETE, use the 'execute_sql' tool"
+
+## [1.16.0] - 2025-12-09
+
+### Added
+- **Phase 1: AI Enhancement Tools** - 8 new intelligent tools for AI-powered database interactions:
+
+  #### Intelligent Query Assistant
+  - `build_query_from_intent` - Converts natural language to optimized SQL with context-aware query generation. Supports analytics, reporting, data_entry, and schema_exploration contexts. Includes safety levels and complexity controls.
+  - `suggest_query_improvements` - Analyzes SQL queries and suggests optimizations for speed, memory, or readability.
+
+  #### Smart Data Discovery Agent
+  - `smart_search` - Finds relevant tables, columns, data patterns, and relationships using semantic search. Essential for exploring large databases with hundreds of tables.
+  - `find_similar_columns` - Discovers columns with similar names or data across tables. Identifies potential join candidates and implicit relationships.
+  - `discover_data_patterns` - Analyzes tables for patterns including uniqueness, null rates, duplicates, formats, and value ranges. Provides data quality scores and recommendations.
+
+  #### AI-Powered Documentation Generator
+  - `generate_documentation` - Creates comprehensive database documentation with business glossary in Markdown, HTML, or JSON format. Includes schema, relationships, and example queries.
+  - `generate_data_dictionary` - Generates detailed data dictionaries for specific tables with column descriptions, constraints, sample values, and business terms.
+  - `generate_business_glossary` - Creates business glossaries from database column names with inferred descriptions and categorization.
+
+- **New Documentation Category** - Added `ai_enhancement` category for organizing the new AI tools.
+- **Updated Presets** - Added AI Enhancement tools to the `analyst` preset for immediate access.
+
+### Changed
+- Updated tool count from 126 to 134 tools.
+- Enhanced enhancement tracking file to mark Phase 1 as completed.
+
 ## [1.15.0] - 2025-12-08
 
 ### Added

package/DOCUMENTATIONS.md

@@ -7,7 +7,7 @@ This file contains detailed documentation for all features of the MySQL MCP Serv
 ## Table of Contents
 
 1. [Category Filtering System](#🆕-category-filtering-system) - NEW!
-2. [🔧 Complete Tools Reference](#🔧-complete-tools-reference) - All 124 tools organized by category
+2. [🔧 Complete Tools Reference](#🔧-complete-tools-reference) - All 134 tools organized by category
 3. [DDL Operations](#🏗️-ddl-operations)
 4. [Data Export Tools](#📤-data-export-tools)
 5. [Data Import Tools](#📥-data-import-tools)
@@ -24,8 +24,9 @@ This file contains detailed documentation for all features of the MySQL MCP Serv
 16. [Table Maintenance](#🔧-table-maintenance)
 17. [Process & Server Management](#📊-process--server-management)
 18. [Performance Monitoring](#📈-performance-monitoring)
-19. [Usage Examples](#📋-usage-examples)
-20. [Query Logging & Automatic SQL Display](#📝-query-logging--automatic-sql-display)
+19. [AI Enhancement Tools](#🤖-ai-enhancement-tools) - NEW!
+20. [Usage Examples](#📋-usage-examples)
+21. [Query Logging & Automatic SQL Display](#📝-query-logging--automatic-sql-display)
 
 Control which database operations are available to AI using a **dual-layer filtering system**:
 
@@ -53,14 +54,14 @@ Control which database operations are available to AI using a **dual-layer filte
 ### Documentation Categories Reference
 
 ```bash
-# All 22 available categories (comma-separated):
+# All 23 available categories (comma-separated):
 database_discovery,crud_operations,bulk_operations,custom_queries,
 schema_management,utilities,transaction_management,stored_procedures,
 views_management,triggers_management,functions_management,index_management,
 constraint_management,table_maintenance,server_management,
 performance_monitoring,cache_management,query_optimization,
 backup_restore,import_export,data_migration,schema_migrations,
-analysis
+analysis,ai_enhancement
 ```
 
 ### Configuration Examples
@@ -3002,6 +3003,292 @@ Reset Performance Schema statistics to start fresh monitoring.
 
 ---
 
+## 🤖 AI Enhancement Tools
+
+The AI Enhancement tools provide intelligent, AI-powered features for database exploration, query generation, and documentation. These tools are part of **Phase 1: Core AI Enhancement**.
+
+### Tool Overview
+
+| Tool | Description | Category |
+|------|-------------|----------|
+| `build_query_from_intent` | Converts natural language to optimized SQL with context-aware generation | `ai_enhancement` |
+| `suggest_query_improvements` | Analyzes SQL queries and suggests optimizations | `ai_enhancement` |
+| `smart_search` | Finds relevant tables, columns, and patterns using semantic search | `ai_enhancement` |
+| `find_similar_columns` | Discovers columns with similar names or data across tables | `ai_enhancement` |
+| `discover_data_patterns` | Analyzes tables for data patterns and quality issues | `ai_enhancement` |
+| `generate_documentation` | Generates comprehensive database documentation | `ai_enhancement` |
+| `generate_data_dictionary` | Creates detailed data dictionaries for tables | `ai_enhancement` |
+| `generate_business_glossary` | Builds business glossaries from column names | `ai_enhancement` |
+
+### Intelligent Query Assistant
+
+#### `build_query_from_intent`
+
+Converts natural language descriptions to optimized SQL queries with context-aware generation.
+
+```javascript
+// Basic usage
+{
+  "tool": "build_query_from_intent",
+  "arguments": {
+    "natural_language": "show me all users who signed up last month"
+  }
+}
+
+// With context and safety settings
+{
+  "tool": "build_query_from_intent",
+  "arguments": {
+    "natural_language": "count orders by product category for 2024",
+    "context": "analytics",
+    "max_complexity": "medium",
+    "safety_level": "moderate"
+  }
+}
+```
+
+**Parameters:**
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `natural_language` | string | Natural language description of what you want to query (required) |
+| `context` | string | Query context: `analytics`, `reporting`, `data_entry`, `schema_exploration` |
+| `max_complexity` | string | Maximum complexity: `simple`, `medium`, `complex` |
+| `safety_level` | string | Safety level: `strict`, `moderate`, `permissive` |
+
+**Response includes:**
+- Generated SQL query
+- Explanation of what the query does
+- Tables and columns involved
+- Safety notes and optimization hints
+- Alternative query suggestions
+
+#### `suggest_query_improvements`
+
+Analyzes a SQL query and provides suggestions for optimization.
+
+```javascript
+{
+  "tool": "suggest_query_improvements",
+  "arguments": {
+    "query": "SELECT * FROM users WHERE email LIKE '%@gmail.com'",
+    "optimization_goal": "speed"
+  }
+}
+```
+
+**Optimization Goals:**
+- `speed` - Focuses on query execution time (default)
+- `memory` - Focuses on memory usage optimization
+- `readability` - Suggests formatting and clarity improvements
+
+### Smart Data Discovery
+
+#### `smart_search`
+
+Search across the database schema using semantic matching to find relevant tables, columns, and data patterns.
+
+```javascript
+// Search for anything related to "customer"
+{
+  "tool": "smart_search",
+  "arguments": {
+    "search_term": "customer",
+    "search_type": "all",
+    "include_sample_data": true
+  }
+}
+
+// Search specifically for columns
+{
+  "tool": "smart_search",
+  "arguments": {
+    "search_term": "email",
+    "search_type": "column",
+    "similarity_threshold": 0.5
+  }
+}
+```
+
+**Search Types:**
+- `all` - Search across tables, columns, patterns, and relationships
+- `table` - Search table names only
+- `column` - Search column names only
+- `data_pattern` - Search for patterns in actual data
+- `relationship` - Search for relationships between tables
+
+#### `find_similar_columns`
+
+Discover columns with similar names or data across tables to identify potential joins and relationships.
+
+```javascript
+// Find columns similar to "user_id" in "orders" table
+{
+  "tool": "find_similar_columns",
+  "arguments": {
+    "column_name": "user_id",
+    "table_name": "orders",
+    "include_data_comparison": true
+  }
+}
+
+// Find all potential join candidates across the database
+{
+  "tool": "find_similar_columns",
+  "arguments": {
+    "include_data_comparison": false,
+    "max_results": 50
+  }
+}
+```
+
+#### `discover_data_patterns`
+
+Analyze a table to discover data patterns, quality issues, and get recommendations.
+
+```javascript
+{
+  "tool": "discover_data_patterns",
+  "arguments": {
+    "table_name": "users",
+    "pattern_types": ["unique", "null", "duplicate", "format", "range"]
+  }
+}
+```
+
+**Pattern Types:**
+- `unique` - Find potentially unique columns not marked as UNIQUE
+- `null` - Detect high null rates and nullable mismatches
+- `duplicate` - Find duplicate values in columns
+- `format` - Detect data formats (email, phone, etc.)
+- `range` - Analyze numeric ranges and detect outliers
+
+**Response includes:**
+- Data quality score (0-100)
+- Patterns found per column
+- Recommendations for each issue
+- Column-level metrics
+
+### Documentation Generator
+
+#### `generate_documentation`
+
+Generate comprehensive database documentation in Markdown, HTML, or JSON format.
+
+```javascript
+// Generate full database documentation
+{
+  "tool": "generate_documentation",
+  "arguments": {
+    "format": "markdown",
+    "include_business_glossary": true,
+    "include_examples": true,
+    "include_statistics": true
+  }
+}
+
+// Document a specific table
+{
+  "tool": "generate_documentation",
+  "arguments": {
+    "scope": "table",
+    "table_name": "orders",
+    "format": "html"
+  }
+}
+```
+
+**Output Formats:**
+- `markdown` - Best for GitHub/GitLab wikis and documentation sites
+- `html` - Standalone HTML page with styling
+- `json` - Structured data for programmatic use
+
+**Documentation includes:**
+- Table of contents
+- ER relationship diagrams (Mermaid.js in markdown)
+- Column details with data types and constraints
+- Foreign key relationships
+- Index information
+- Example SQL queries
+- Business glossary
+
+#### `generate_data_dictionary`
+
+Generate a detailed data dictionary for a specific table.
+
+```javascript
+{
+  "tool": "generate_data_dictionary",
+  "arguments": {
+    "table_name": "products",
+    "include_sample_values": true,
+    "include_constraints": true
+  }
+}
+```
+
+**Response includes:**
+- Column name, type, and description
+- Constraints (PK, FK, NOT NULL, UNIQUE)
+- Default values
+- Sample values from actual data
+- Business terms (auto-inferred)
+
+#### `generate_business_glossary`
+
+Create a business glossary from database column names with auto-generated descriptions.
+
+```javascript
+{
+  "tool": "generate_business_glossary",
+  "arguments": {
+    "include_descriptions": true,
+    "group_by": "category"
+  }
+}
+```
+
+**Grouping Options:**
+- `category` - Group by inferred category (Identifiers, Timestamps, Contact, etc.)
+- `table` - Group by source table
+- `alphabetical` - A-Z sorting
+
+### AI Enhancement Best Practices
+
+1. **Start with Discovery**: Use `smart_search` and `find_similar_columns` to understand unfamiliar databases
+2. **Use Context**: When building queries, specify the `context` parameter for better results
+3. **Validate Generated SQL**: Always review generated SQL before executing, especially for complex queries
+4. **Update Documentation**: Regenerate documentation after schema changes
+5. **Quality Checks**: Run `discover_data_patterns` regularly to catch data quality issues early
+
+### Example Workflow: Exploring a New Database
+
+```javascript
+// Step 1: Get an overview
+{ "tool": "get_database_summary" }
+
+// Step 2: Search for relevant tables
+{
+  "tool": "smart_search",
+  "arguments": { "search_term": "order sales revenue" }
+}
+
+// Step 3: Generate documentation
+{
+  "tool": "generate_documentation",
+  "arguments": { "format": "markdown" }
+}
+
+// Step 4: Build a query from natural language
+{
+  "tool": "build_query_from_intent",
+  "arguments": {
+    "natural_language": "total sales by month for the last year"
+  }
+}
+```
+
+---
+
 ## 📋 Usage Examples
 
 ### Example 1: Read Data

package/README.md

@@ -40,20 +40,19 @@ Add to your AI agent config (`.mcp.json`, `.cursor/mcp.json`, etc.):
 
 ## Table of Contents
 
-- [Features](#-features)
-- [Installation](#-installation)
-- [Quick Start](#-quick-start)
-- [AI Agent Configuration](#-ai-agent-configuration)
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+- [AI Agent Configuration](#ai-agent-configuration)
   - [Standard JSON Config](#standard-json-configuration)
   - [OpenAI Codex (TOML)](#openai-codex-cli--vs-code-extension)
-- [Zed IDE](#zed-ide)
+  - [Zed IDE](#zed-ide)
   - [Environment Variables](#environment-variables-configuration)
   - [Local Development](#local-path-configuration)
-- [Permission System](#-permission-system)
-- [Available Tools (126 total)](#-available-tools)
-- [Documentation](#-detailed-documentation)
-- [Comparison: MCP vs Manual Access](#-mysql-mcp-vs-manual-database-access)
-- [License](#-license)
+- [Permission System](#permission-system)
+- [Available Tools (134 total)](#available-tools)
+- [Documentation](DOCUMENTATIONS.md)
+- [Comparison: MCP vs Manual Access](#mysql-mcp-vs-manual-database-access)
+- [License](#license)
 
 ---
 | **Data Masking** | Protect PII/Secrets in responses with configurable profiles (soft/partial/strict) |
@@ -647,11 +646,11 @@ Use both 2nd argument (permissions) and 3rd argument (categories):
 
 ## Available Tools
 
-The MCP server provides **126 powerful tools** organized into 22 categories:
+The MCP server provides **134 powerful tools** organized into 23 categories:
 
 ### Quick Reference
 
-**126 Tools Available** - Organized into 22 categories
+**134 Tools Available** - Organized into 23 categories
 
 | Category | Count | Key Tools |
 |----------|-------|-----------|
@@ -677,7 +676,8 @@ The MCP server provides **126 powerful tools** organized into 22 categories:
 | Data Migration | 5 | `copy_table_data`, `sync_table_data` |
 | Schema Migrations | 9 | `create_migration`, `apply_migrations` |
 | Utilities | 4 | `test_connection`, `export_table_to_csv` |
-| Analysis | 4 | `get_column_statistics`, `get_database_summary`, `get_schema_erd`, `get_schema_rag_context` |
+| Analysis | 4 | `get_column_statistics`, `get_database_summary`, `get_schema_erd` |
+| **AI Enhancement** | 8 | `build_query_from_intent`, `smart_search`, `generate_documentation` |
 
 > **📖 For detailed tool descriptions, parameters, and examples, see [DOCUMENTATIONS.md](DOCUMENTATIONS.md#🔧-complete-tools-reference)**
 
@@ -695,6 +695,7 @@ For comprehensive documentation, see **[DOCUMENTATIONS.md](DOCUMENTATIONS.md)**:
 - **Schema Versioning** - Version control for database schema changes
 - **Transaction Management** - ACID transactions
 - **Stored Procedures** - Create and execute with IN/OUT/INOUT parameters
+- **AI Enhancement** - Natural language to SQL, smart discovery, and auto-documentation
 - **Query Logging** - See all SQL queries executed automatically
 - **Security Features** - Built-in security and best practices
 - **Bulk Operations** - High-performance batch processing

package/dist/config/featureConfig.d.ts

@@ -40,7 +40,8 @@ export declare enum DocCategory {
     IMPORT_EXPORT = "import_export",
     DATA_MIGRATION = "data_migration",
     SCHEMA_MIGRATIONS = "schema_migrations",
-    ANALYSIS = "analysis"
+    ANALYSIS = "analysis",
+    AI_ENHANCEMENT = "ai_enhancement"
 }
 /**
  * Permission preset bundles for faster, safer configuration

package/dist/config/featureConfig.js

@@ -52,6 +52,7 @@ var DocCategory;
     DocCategory["DATA_MIGRATION"] = "data_migration";
     DocCategory["SCHEMA_MIGRATIONS"] = "schema_migrations";
     DocCategory["ANALYSIS"] = "analysis";
+    DocCategory["AI_ENHANCEMENT"] = "ai_enhancement";
 })(DocCategory || (exports.DocCategory = DocCategory = {}));
 const normalizePresetName = (value) => (value || "").toLowerCase().replace(/[\s_-]/g, "");
 const permissionPresets = {
@@ -84,6 +85,7 @@ const permissionPresets = {
             DocCategory.QUERY_OPTIMIZATION,
             DocCategory.CACHE_MANAGEMENT,
             DocCategory.SERVER_MANAGEMENT,
+            DocCategory.AI_ENHANCEMENT,
         ],
     },
     dbalite: {
@@ -310,6 +312,15 @@ exports.toolCategoryMap = {
     getConnectionPoolStats: ToolCategory.UTILITY,
     getDatabaseHealthCheck: ToolCategory.UTILITY,
     resetPerformanceStats: ToolCategory.UTILITY,
+    // Phase 1: AI Enhancement Tools
+    buildQueryFromIntent: ToolCategory.READ,
+    suggestQueryImprovements: ToolCategory.UTILITY,
+    smartSearch: ToolCategory.LIST,
+    findSimilarColumns: ToolCategory.LIST,
+    discoverDataPatterns: ToolCategory.READ,
+    generateDocumentation: ToolCategory.UTILITY,
+    generateDataDictionary: ToolCategory.UTILITY,
+    generateBusinessGlossary: ToolCategory.UTILITY,
 };
 /**
  * Map of tool names to their documentation categories (New Enhanced System)
@@ -463,6 +474,15 @@ exports.toolDocCategoryMap = {
     getSchemaERD: DocCategory.ANALYSIS,
     getColumnStatistics: DocCategory.ANALYSIS,
     getSchemaRagContext: DocCategory.ANALYSIS,
+    // Phase 1: AI Enhancement
+    buildQueryFromIntent: DocCategory.AI_ENHANCEMENT,
+    suggestQueryImprovements: DocCategory.AI_ENHANCEMENT,
+    smartSearch: DocCategory.AI_ENHANCEMENT,
+    findSimilarColumns: DocCategory.AI_ENHANCEMENT,
+    discoverDataPatterns: DocCategory.AI_ENHANCEMENT,
+    generateDocumentation: DocCategory.AI_ENHANCEMENT,
+    generateDataDictionary: DocCategory.AI_ENHANCEMENT,
+    generateBusinessGlossary: DocCategory.AI_ENHANCEMENT,
 };
 /**
  * Mapping between legacy categories and documentation categories