@berthojoris/mcp-mysql-server 1.14.1 → 1.16.0

package/CHANGELOG.md

@@ -5,6 +5,43 @@ 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.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
+- **Connection Profiles** - New `dev`, `stage`, and `prod` presets.
+  - `dev`: Full access to all tools.
+  - `stage`: Allows CRUD but blocks destructive DDL (drop, truncate).
+  - `prod`: Strict read-only with explicit denials for modification tools.
+  - Implements allowed/denied tools logic for robust security enforcement.
+- **Agent-Facing Changelog Feed** - New `read_changelog` tool.
+  - Allows AI agents to read the CHANGELOG.md directly to understand new features and changes.
+
 ## [1.14.1] - 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
@@ -192,6 +193,16 @@ Preset bundles provide safe starting points and **merge** with any explicit perm
 | `readonly` | `list,read,utility` | `database_discovery,crud_operations,custom_queries,utilities,import_export,performance_monitoring,analysis` | Safe read-only access, exports, and diagnostics |
 | `analyst` | `list,read,utility` | `database_discovery,crud_operations,custom_queries,utilities,import_export,performance_monitoring,analysis,query_optimization,cache_management,server_management` | Exploration with EXPLAIN, cache, and performance visibility |
 | `dba-lite` | `list,read,utility,ddl,transaction,procedure` | `database_discovery,custom_queries,utilities,server_management,schema_management,table_maintenance,index_management,constraint_management,backup_restore,schema_migrations,performance_monitoring,views_management,triggers_management,functions_management,stored_procedures` | Admin-lite schema care, maintenance, and migrations |
+| `dev` | ALL | ALL | Full access to all tools (Development environment) |
+| `stage` | `list,read,create,update,delete,utility,transaction` | Most categories (except schema_management) | Data modification allowed, but destructive DDL (drop_table, truncate_table) is **explicitly denied** |
+| `prod` | `list,read,utility` | `database_discovery,crud_operations,custom_queries,utilities,performance_monitoring,analysis` | Strict read-only. Data modification and DDL are **strictly denied** (even if permissions suggest otherwise) |
+
+### Connection Profiles (Allow/Deny Lists)
+
+The new mechanism introduces "Connection Profiles" which can enforce strict `allow` and `deny` lists for tools, providing security beyond standard permissions.
+
+- **Explicit Deny**: Tools in the `deniedTools` list are blocked *regardless* of their permissions. E.g., `prod` profile denies `create_record` even if `create` permission is somehow granted.
+- **Explicit Allow**: Tools in the `allowedTools` list are enabled even if their category is not listed (unless denied).
 
 **Usage**
 
@@ -324,6 +335,7 @@ This section provides a comprehensive reference of all 120 available tools organ
 |------|-------------|
 | `test_connection` | Test database connectivity and measure latency |
 | `describe_connection` | Get current connection information |
+| `read_changelog` | Read the changelog to see new features/changes |
 | `export_table_to_csv` | Export table data to CSV format |
 | `export_query_to_csv` | Export query results to CSV format |
 
@@ -520,6 +532,11 @@ This section provides a comprehensive reference of all 120 available tools organ
 - Safety: respects the connected database only—cannot introspect other schemas—and notes when tables/columns are truncated.
 - Output includes per-table PKs, FK targets, nullable flags, and approximate row counts from `INFORMATION_SCHEMA.TABLES` (InnoDB estimates).
 
+#### Agent-Facing Changelog Feed
+- **`read_changelog`**: Allows AI agents to read the project's CHANGELOG.md directly.
+- **Purpose**: Enables the agent to understand new features, changes, and deprecations in the version it is running.
+- **Usage**: Call `read_changelog()` to get the latest changes, or `read_changelog(version='1.15.0')` for specific version details.
+
 ---
 
 ## 🏗️ DDL Operations
@@ -2986,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
@@ -3824,6 +4127,61 @@ Each bulk operation returns performance metrics:
  
  ---
  
+
+ ---
+ 
+ ## ⚡ Workflow Macros
+
+ Workflow macros are high-level tools that combine multiple operations into a single, safe, and efficient workflow. They are designed to simplify complex tasks and ensure best practices (like data masking) are automatically applied.
+
+ ### Safe Export Table
+
+ The `safe_export_table` tool allows you to export table data to CSV while strictly enforcing data masking rules. This ensures that sensitive information (PII) is never leaked during exports, even if the agent forgets to apply masking manually.
+
+ #### Features
+
+ - **Forced Masking**: Applies a masking profile (default: `strict`) to all exported data.
+ - **Hard Limit**: Enforces a maximum row limit (10,000) to prevent Out-Of-Memory errors during large exports.
+ - **CSV Formatting**: Automatically handles special characters, quotes, and newlines.
+ - **Header Control**: Option to include or exclude CSV headers.
+
+ #### Usage
+
+ ```json
+ {
+   "tool": "safe_export_table",
+   "arguments": {
+     "table_name": "users",
+     "masking_profile": "partial",
+     "limit": 1000
+   }
+ }
+ ```
+
+ #### Parameters
+
+ | Parameter | Type | Required | Description | Default |
+ |-----------|------|----------|-------------|---------|
+ | `table_name` | string | Yes | Name of the table to export | - |
+ | `masking_profile` | string | No | Masking profile to apply (`strict`, `partial`, `soft`) | `strict` |
+ | `limit` | number | No | Number of rows to export (max 10,000) | 1000 |
+ | `include_headers` | boolean | No | Whether to include CSV headers | `true` |
+
+ #### Response
+
+ ```json
+ {
+   "status": "success",
+   "data": {
+     "csv": "id,name,email\n1,John Doe,j***@example.com...",
+     "row_count": 50,
+     "applied_profile": "partial"
+   }
+ }
+ ```
+
+ ---
+
  ## 🤖 OpenAI Codex Integration
 
 OpenAI Codex CLI and VS Code Extension support MCP servers through a shared TOML configuration file. This section provides detailed setup instructions for integrating the MySQL MCP Server with Codex.
@@ -4210,9 +4568,9 @@ MIT License - see [LICENSE](LICENSE) file for details.
 | Safety Sandbox Mode (runQuery dry-run/EXPLAIN-only) | Medium | Low | 5 | ✅ Completed |
 | Anomaly & Slow-Query Watcher | Medium | Medium | 6 | ✅ Completed |
 | Data Masking Profiles for Responses | Medium | Medium | 7 | ✅ Completed |
-| Workflow Macros (e.g., safe_export_table) | Medium | Low | 8 | Planned |
-| Agent-Facing Changelog Feed | Medium | Low | 9 | Planned |
-| Connection Profiles (dev/stage/prod with allow/deny) | High | Low | 10 | Planned |
+| Workflow Macros (e.g., safe_export_table) | Medium | Low | 8 | ✅ Completed |
+| Agent-Facing Changelog Feed | Medium | Low | 9 | ✅ Completed |
+| Connection Profiles (dev/stage/prod with allow/deny) | High | Low | 10 | ✅ Completed |
 
 ---
 

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 (124 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) |
@@ -388,6 +387,12 @@ Alternative approach using environment variables instead of connection string:
 
 Add `MCP_PRESET` for the base bundle and optionally layer on `MCP_PERMISSIONS` / `MCP_CATEGORIES` for project-specific overrides.
 
+#### Connection Profiles (dev/stage/prod)
+New presets are available for environment-specific control:
+- `dev`: Full access to all tools (explicitly allows everything).
+- `stage`: Allows data modification but blocks destructive DDL (drop/truncate).
+- `prod`: Strict read-only mode, explicitly denying keys modification keys.
+
 ---
 
 ### Local Path Configuration
@@ -641,11 +646,11 @@ Use both 2nd argument (permissions) and 3rd argument (categories):
 
 ## Available Tools
 
-The MCP server provides **124 powerful tools** organized into categories:
+The MCP server provides **134 powerful tools** organized into 23 categories:
 
 ### Quick Reference
 
-**124 Tools Available** - Organized into 22 categories
+**134 Tools Available** - Organized into 23 categories
 
 | Category | Count | Key Tools |
 |----------|-------|-----------|
@@ -667,11 +672,12 @@ The MCP server provides **124 powerful tools** organized into categories:
 | Cache | 5 | `get_cache_stats`, `clear_cache` |
 | Query Optimization | 3 | `analyze_query`, `get_optimization_hints`, `repair_query` |
 | Backup & Restore | 5 | `backup_database`, `restore_from_sql` |
-| Import/Export | 5 | `export_table_to_json`, `import_from_csv` |
+| Import/Export | 6 | `safe_export_table`, `export_table_to_json`, `import_from_csv` |
 | 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)**
 
@@ -689,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
@@ -50,6 +51,8 @@ export interface PermissionPreset {
     description: string;
     permissions: ToolCategory[];
     categories: DocCategory[];
+    allowedTools?: string[];
+    deniedTools?: string[];
 }
 /**
  * Map of tool names to their legacy categories
@@ -68,6 +71,8 @@ export declare const toolDocCategoryMap: Record<string, DocCategory>;
 export declare class FeatureConfig {
     private enabledLegacyCategories;
     private enabledDocCategories;
+    private allowedTools;
+    private deniedTools;
     private originalPermissionsString;
     private originalCategoriesString;
     private useDualLayer;