@berthojoris/mcp-mysql-server 1.26.1 → 1.28.0

package/CHANGELOG.md

@@ -5,6 +5,62 @@ 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.28.0] - 2025-12-21
+
+### Changed
+- **[BREAKING]** Removed `get_table_relationships` tool - use `get_all_tables_relationships` instead for better performance
+  - `get_all_tables_relationships` retrieves ALL table relationships in a single efficient query with in-memory processing
+  - Much faster than calling `get_table_relationships` repeatedly for each table
+- **Enhanced tool descriptions** for improved LLM understanding across 40+ critical tools:
+  - Added visual indicators (emojis) for tool categories: 🤖 AI-powered, ⚡ Performance, 🔒 Security, 📊 Analytics, etc.
+  - Clarified when to use each tool vs similar alternatives
+  - Added use-case context and examples in descriptions
+  - Highlighted AI-first tools for natural language operations
+  - Improved consistency in description length and detail level
+- Updated total tool count from 104 to 103 across all documentation
+
+### Fixed
+- Removed duplicate `get_all_tables_relationships` entry in DOCUMENTATIONS.md
+- Corrected references to deprecated `get_table_relationships` in documentation examples
+
+## [1.27.1] - 2025-12-21
+
+### Removed
+- **Deprecated Tools**: Removed legacy `runQuery` and `executeSql` tools completely
+  - These tools were replaced by `run_select_query` and `execute_write_query` in v1.27.0
+  - Removed from feature configuration mappings
+  - Removed validation schemas
+  - Updated all internal references to use new tool names
+
+### Changed
+- Updated transaction tools to use `executeWriteQuery` permission check instead of deprecated `executeSql`
+
+## [1.27.0] - 2025-12-21
+
+### Changed
+- **Renamed Tools for Clarity**:
+  - `run_query` -> `run_select_query`
+  - `execute_sql` -> `execute_write_query`
+- **Updated Error Messages**: Error messages now explicitly reference the new tool names to guide users/LLMs to the correct tool for the job.
+- **Updated Documentation**: Updated README.md and DOCUMENTATIONS.md to reflect the new tool names and configuration examples.
+
+## [1.26.2] - 2025-12-19
+
+### Fixed
+- Updated manifest.json version from 1.17.0 to 1.26.2 to match package.json
+- Verified `list_all_tools` tool is properly registered and available in MCP server
+- Updated documentation timestamps to reflect current changes
+
+## [1.26.3] - 2025-12-19
+
+### Documentation
+- Enhanced README documentation categories table with a "List Tools" column (per-category `list_all_tools` call)
+
+## [1.26.4] - 2025-12-19
+
+### Documentation
+- Fixed README "Documentation Categories (Recommended)" to list the actual tools per category in the "List Tools" column
+
 ## [1.26.1] - 2025-12-19
 
 ### Documentation

package/DOCUMENTATIONS.md

@@ -1,6 +1,6 @@
 # MySQL MCP Server - Detailed Documentation
 
-**Last Updated:** 2025-12-19 18:08:39
+**Last Updated:** 2025-12-21 17:00:00
 
 This file contains detailed documentation for all features of the MySQL MCP Server. For quick start and basic information, see [README.md](README.md).
 
@@ -9,7 +9,7 @@ This file contains detailed documentation for all features of the MySQL MCP Serv
 ## Table of Contents
 
 1. [Setup & Configuration (Extended)](#setup--configuration-extended) - Permissions + Categories
-2. [🔧 Complete Tools Reference](#🔧-complete-tools-reference) - All 145 tools organized by category
+2. [🔧 Complete Tools Reference](#🔧-complete-tools-reference) - All 103 tools organized by category
 3. [DDL Operations](#🏗️-ddl-operations)
 4. [Data Export Tools](#📤-data-export-tools)
 5. [Data Import Tools](#📥-data-import-tools)
@@ -131,7 +131,7 @@ Use both 2nd argument (permissions) and 3rd argument (categories):
 **Layer 1 (Permissions)**: Allows `list`, `read`, `utility` operations
 **Layer 2 (Categories)**: Further restricts to `database_discovery` and `performance_monitoring` tools
 
-**Enabled tools**: `list_databases`, `list_tables`, `read_table_schema`, `get_table_relationships`, `get_performance_metrics`, `get_slow_queries`, etc.
+**Enabled tools**: `list_databases`, `list_tables`, `read_table_schema`, `get_all_tables_relationships`, `get_performance_metrics`, `get_slow_queries`, etc.
 
 **Disabled tools**:
 - `read_records` - Has `read` permission but category is `crud_operations` (not allowed)
@@ -144,11 +144,11 @@ Use both 2nd argument (permissions) and 3rd argument (categories):
 | Permission | Operations Allowed | Example Tools |
 |------------|-------------------|---------------|
 | `list` | List/discover database objects | `list_databases`, `list_tables`, `list_views` |
-| `read` | Read data from tables | `read_records`, `run_query` |
+| `read` | Read data from tables | `read_records`, `run_select_query` |
 | `create` | Insert new records | `create_record`, `bulk_insert` |
 | `update` | Update existing records | `update_record`, `bulk_update` |
 | `delete` | Delete records | `delete_record`, `bulk_delete` |
-| `execute` | Execute custom SQL | `execute_sql`, `run_query` |
+| `execute` | Execute custom SQL | `execute_write_query` |
 | `ddl` | Schema changes | `create_table`, `alter_table`, `drop_table` |
 | `utility` | Utility operations | `test_connection`, `analyze_table` |
 | `transaction` | Transaction management | `begin_transaction`, `commit_transaction` |
@@ -210,7 +210,7 @@ This section provides a comprehensive reference of all 145 available tools organ
 | `list_databases` | Lists all databases on the MySQL server |
 | `list_tables` | Lists all tables in the current/specified database |
 | `read_table_schema` | Gets detailed schema (columns, types, keys, indexes) |
-| `get_table_relationships` | Discovers foreign key relationships |
+| `get_all_tables_relationships` | Gets all table relationships efficiently in one query |
 | `get_all_tables_relationships` | Gets foreign key relationships for ALL tables in a single call with in-memory processing |
 
 ### Data Operations - CRUD
@@ -234,8 +234,8 @@ This section provides a comprehensive reference of all 145 available tools organ
 
 | Tool | Description |
 |------|-------------|
-| `run_query` | Execute read-only SELECT queries |
-| `execute_sql` | Execute write operations (INSERT, UPDATE, DELETE, or DDL) |
+| `run_select_query` | Execute read-only SELECT queries |
+| `execute_write_query` | Execute write operations (INSERT, UPDATE, DELETE, or DDL) |
 
 ### Schema Management - DDL
 
@@ -3604,7 +3604,7 @@ Create a business glossary from database column names with auto-generated descri
 
 **User:** *"Show me the total number of orders per user for the last 30 days"*
 
-**AI uses `run_query`:**
+**AI uses `run_select_query`:**
 - Constructs JOIN query
 - Applies date filter
 - Groups by user
@@ -3891,12 +3891,12 @@ Parameters:
 
 Query logs are now included in responses from **ALL 30 tools**:
 
-✅ **Database Discovery** - `list_databases`, `list_tables`, `read_table_schema`, `get_table_relationships`, `get_all_tables_relationships`
+✅ **Database Discovery** - `list_databases`, `list_tables`, `read_table_schema`, `get_all_tables_relationships`
 ✅ **Data Operations** - `create_record`, `read_records`, `update_record`, `delete_record`
 ✅ **Bulk Operations** - `bulk_insert`, `bulk_update`, `bulk_delete`
-✅ **Custom Queries** - `run_query`, `execute_sql`
+✅ **Custom Queries** - `run_select_query`, `execute_write_query`
 ✅ **Schema Management** - `create_table`, `alter_table`, `drop_table`, `execute_ddl`
-✅ **Utilities** - `get_table_relationships`
+✅ **Utilities** - `get_all_tables_relationships`
 ✅ **Transactions** - `execute_in_transaction`
 ✅ **Stored Procedures** - `list_stored_procedures`, `get_stored_procedure_info`, `execute_stored_procedure`, etc.
 ✅ **Data Export** - `export_table_to_csv`, `export_query_to_csv`
@@ -3920,8 +3920,8 @@ Query logs are valuable for:
 ### Tools with Query Logging
 
 All tools that execute queries include logs:
-- `run_query` - SELECT query execution
-- `executeSql` - Write operations (INSERT, UPDATE, DELETE)
+- `run_select_query` - SELECT query execution
+- `execute_write_query` - Write operations (INSERT, UPDATE, DELETE)
 - `create_record` - Single record insertion
 - `read_records` - Record querying with filters
 - `update_record` - Record updates
@@ -4025,7 +4025,7 @@ console.log(`Query log memory usage: ~${estimatedMemory} KB`);
 
 - ✅ **Parameterized Queries** - All queries use prepared statements (SQL injection protection)
 - ✅ **Permission-Based Access** - Fine-grained control over operations
-- ✅ **Read-Only Validation** - `run_query` enforces SELECT-only operations
+- ✅ **Read-Only Validation** - `run_select_query` enforces SELECT-only operations
 - ✅ **DDL Gating** - Schema changes require explicit `ddl` permission
 - ✅ **Condition Requirements** - DELETE operations must include WHERE conditions
 - ✅ **Input Validation** - All inputs validated with JSON schemas
@@ -4145,7 +4145,7 @@ Returns:
 
 - **SELECT queries only**: Only SELECT queries are cached
 - **Automatic invalidation**: INSERT, UPDATE, DELETE operations automatically invalidate related cache entries
-- **Per-query control**: Use `useCache: false` in `run_query` to bypass cache for specific queries
+- **Per-query control**: Use `useCache: false` in `run_select_query` to bypass cache for specific queries
 
 ---
 
@@ -4161,11 +4161,11 @@ The MySQL MCP server provides advanced query optimization tools that help you im
 
 ### Using Optimizer Hints
 
-When running queries with `run_query`, you can include optimizer hints:
+When running queries with `run_select_query`, you can include optimizer hints:
 
 ```json
 {
-  "tool": "run_query",
+  "tool": "run_select_query",
   "arguments": {
     "query": "SELECT * FROM orders WHERE customer_id = ?",
     "params": [123],

package/README.md

@@ -4,7 +4,7 @@
 
 **A production-ready Model Context Protocol (MCP) server for MySQL database integration with AI agents**
 
-**Last Updated:** 2025-12-19 18:08:39
+**Last Updated:** 2025-12-21 17:00:00
 
 [![npm version](https://img.shields.io/npm/v/@berthojoris/mcp-mysql-server)](https://www.npmjs.com/package/@berthojoris/mysql-mcp)
 [![npm downloads](https://img.shields.io/npm/dm/@berthojoris/mysql-mcp)](https://www.npmjs.com/package/@berthojoris/mysql-mcp)
@@ -173,7 +173,7 @@ Alternative approach using environment variables instead of connection string:
         "DB_USER": "root",
         "DB_PASSWORD": "your_password",
         "DB_NAME": "your_database",
-        "MCP_PERMISSIONS": "list,read,utility"
+        "MCP_PERMISSIONS": "list,read,utility,create,update,delete"
       }
     }
   }
@@ -194,8 +194,8 @@ Alternative approach using environment variables instead of connection string:
         "DB_USER": "root",
         "DB_PASSWORD": "your_password",
         "DB_NAME": "your_database",
-        "MCP_PERMISSIONS": "list,read,utility",
-        "MCP_CATEGORIES": "database_discovery,performance_monitoring"
+        "MCP_PERMISSIONS": "list,read,utility,create,update,delete",
+        "MCP_CATEGORIES": "database_discovery,performance_monitoring,custom_queries"
       }
     }
   }
@@ -215,71 +215,7 @@ Control database access with a **dual-layer filtering system** that provides bot
 
 **Filtering Logic**: `Tool enabled = (Has Permission) AND (Has Category OR No categories specified)`
 
-### Documentation Categories (Recommended)
-
-Use documentation categories to fine-tune which tools are exposed (Layer 2):
-
-<table>
-  <thead>
-    <tr>
-      <th align="left">Category A</th>
-      <th align="left">Category B</th>
-      <th align="left">Category C</th>
-      <th align="left">Category D</th>
-    </tr>
-  </thead>
-  <tbody>
-    <tr>
-      <td><code>database_discovery</code></td>
-      <td><code>crud_operations</code></td>
-      <td><code>bulk_operations</code></td>
-      <td><code>custom_queries</code></td>
-    </tr>
-    <tr>
-      <td><code>schema_management</code></td>
-      <td><code>utilities</code></td>
-      <td><code>transaction_management</code></td>
-      <td><code>stored_procedures</code></td>
-    </tr>
-    <tr>
-      <td><code>views_management</code></td>
-      <td><code>triggers_management</code></td>
-      <td><code>functions_management</code></td>
-      <td><code>index_management</code></td>
-    </tr>
-    <tr>
-      <td><code>constraint_management</code></td>
-      <td><code>table_maintenance</code></td>
-      <td><code>server_management</code></td>
-      <td><code>performance_monitoring</code></td>
-    </tr>
-    <tr>
-      <td><code>cache_management</code></td>
-      <td><code>query_optimization</code></td>
-      <td><code>backup_restore</code></td>
-      <td><code>import_export</code></td>
-    </tr>
-    <tr>
-      <td><code>data_migration</code></td>
-      <td><code>schema_migrations</code></td>
-      <td><code>analysis</code></td>
-      <td><code>ai_enhancement</code></td>
-    </tr>
-  </tbody>
-</table>
-
-<details>
-  <summary>Copy/paste list (comma-separated, no spaces)</summary>
-
-```text
-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,ai_enhancement
-```
-
-</details>
-
-Full category → tool mapping (and examples) lives in **[DOCUMENTATIONS.md → Category Filtering System](DOCUMENTATIONS.md#🆕-category-filtering-system)**.
-
-### Legacy Categories (Backward Compatible)
+### Permissions
 
 | Permission | Operations | Use Case |
 |------------|------------|----------|
@@ -298,6 +234,50 @@ Common configuration examples are documented in **[DOCUMENTATIONS.md → Categor
 
 ---
 
+### Documentation Categories (Recommended)
+
+Use documentation categories to fine-tune which tools are exposed (Layer 2):
+
+| Category List | Use Case | List Tools |
+|---------------|----------|-----------|
+| `database_discovery` | Explore databases, tables, and schema structure | `get_all_tables_relationships, get_table_relationships, list_databases, list_tables, read_table_schema` |
+| `crud_operations` | Create, read, update, delete operations on data | `create_record, delete_record, read_records, update_record` |
+| `bulk_operations` | High-performance batch processing operations | `bulk_delete, bulk_insert, bulk_update` |
+| `custom_queries` | Execute custom SQL queries and advanced operations | `execute_write_query, run_select_query` |
+| `schema_management` | Manage database schema, tables, and structure | `alter_table, create_table, drop_table, execute_ddl` |
+| `utilities` | Database utilities, diagnostics, and helper functions | `describe_connection, export_query_to_csv, export_table_to_csv, list_all_tools, read_changelog, test_connection` |
+| `transaction_management` | Handle ACID transactions and rollback operations | `begin_transaction, commit_transaction, execute_in_transaction, get_transaction_status, rollback_transaction` |
+| `stored_procedures` | Create, execute, and manage stored procedures | `create_stored_procedure, drop_stored_procedure, execute_stored_procedure, get_stored_procedure_info, list_stored_procedures, show_create_procedure` |
+| `views_management` | Create and manage database views | `alter_view, create_view, drop_view, get_view_info, list_views, show_create_view` |
+| `triggers_management` | Create and manage database triggers | `create_trigger, drop_trigger, get_trigger_info, list_triggers, show_create_trigger` |
+| `functions_management` | Create and manage database functions | `create_function, drop_function, execute_function, get_function_info, list_functions, show_create_function` |
+| `index_management` | Optimize performance with index management | `analyze_index, create_index, drop_index, get_index_info, list_indexes` |
+| `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` |
+| `server_management` | MySQL server configuration and administration | `explain_query, get_server_info, kill_process, show_binary_logs, show_engine_status, show_process_list, show_replication_status, show_status, show_variables` |
+| `performance_monitoring` | Monitor and analyze database performance | `get_connection_pool_stats, get_database_health_check, get_index_usage_stats, get_performance_metrics, get_slow_queries, get_table_io_stats, get_top_queries_by_count, get_top_queries_by_time, get_unused_indexes, reset_performance_stats` |
+| `cache_management` | Manage query cache and optimization | `clear_cache, configure_cache_settings, get_cache_config, get_cache_stats, invalidate_cache_for_table` |
+| `query_optimization` | Analyze and optimize SQL queries | `analyze_query, get_optimization_hints` |
+| `backup_restore` | Create backups and restore databases | `backup_database, backup_table, get_create_table_statement, get_database_schema, restore_from_sql` |
+| `import_export` | Import and export data in various formats | `export_query_to_json, export_table_to_json, export_table_to_sql, import_from_csv, import_from_json, safe_export_table` |
+| `data_migration` | Migrate data between databases or systems | `clone_table, compare_table_structure, copy_table_data, move_table_data, sync_table_data` |
+| `schema_migrations` | Version control for database schema changes | `apply_migrations, create_migration, generate_migration_from_diff, get_migration_status, get_schema_version, init_migrations_table, reset_failed_migration, rollback_migration, validate_migrations` |
+| `analysis` | Data analysis and reporting tools | `get_column_statistics, get_database_summary, get_schema_erd, get_schema_rag_context` |
+| `ai_enhancement` | AI-powered features and smart automation | `analyze_schema_patterns, audit_database_security, build_query_from_intent, design_schema_from_requirements, discover_data_patterns, find_similar_columns, forecast_database_growth, generate_business_glossary, generate_data_dictionary, generate_documentation, generate_test_data, predict_query_performance, recommend_indexes, smart_search, suggest_query_improvements, visualize_query` |
+
+<details>
+  <summary>Copy/paste list (comma-separated, no spaces)</summary>
+
+```text
+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,ai_enhancement
+```
+
+</details>
+
+Full category → tool mapping (and examples) lives in **[DOCUMENTATIONS.md → Category Filtering System](DOCUMENTATIONS.md#🆕-category-filtering-system)**.
+
+---
+
 ## Available Tools
 
 The server exposes **145 tools** organized into categories (CRUD, schema, backups, migrations, perf/monitoring, and AI enhancement).

package/dist/config/featureConfig.js

@@ -79,8 +79,8 @@ exports.toolCategoryMap = {
     bulkUpdate: ToolCategory.UPDATE,
     bulkDelete: ToolCategory.DELETE,
     // Query tools
-    runQuery: ToolCategory.READ,
-    executeSql: ToolCategory.EXECUTE,
+    runSelectQuery: ToolCategory.READ,
+    executeWriteQuery: ToolCategory.EXECUTE,
     // DDL tools
     createTable: ToolCategory.DDL,
     alterTable: ToolCategory.DDL,
@@ -238,8 +238,8 @@ exports.toolDocCategoryMap = {
     bulkUpdate: DocCategory.BULK_OPERATIONS,
     bulkDelete: DocCategory.BULK_OPERATIONS,
     // Custom Queries
-    runQuery: DocCategory.CUSTOM_QUERIES,
-    executeSql: DocCategory.CUSTOM_QUERIES,
+    runSelectQuery: DocCategory.CUSTOM_QUERIES,
+    executeWriteQuery: DocCategory.CUSTOM_QUERIES,
     // Schema Management (DDL)
     createTable: DocCategory.SCHEMA_MANAGEMENT,
     alterTable: DocCategory.SCHEMA_MANAGEMENT,

package/dist/index.d.ts

@@ -119,7 +119,7 @@ export declare class MySQLMCP {
         };
         error?: string;
     }>;
-    runQuery(params: {
+    runSelectQuery(params: {
         query: string;
         params?: any[];
         hints?: any;
@@ -135,7 +135,7 @@ export declare class MySQLMCP {
         estimated_cost?: string;
         message?: string;
     }>;
-    executeSql(params: {
+    executeWriteQuery(params: {
         query: string;
         params?: any[];
     }): Promise<{

package/dist/index.js

@@ -159,8 +159,8 @@ class MySQLMCP {
         return await this.crudTools.deleteRecord(params);
     }
     // Query Tools
-    async runQuery(params) {
-        const check = this.checkToolEnabled("runQuery");
+    async runSelectQuery(params) {
+        const check = this.checkToolEnabled("runSelectQuery");
         if (!check.enabled) {
             return { status: "error", error: check.error };
         }
@@ -168,13 +168,13 @@ class MySQLMCP {
         if (!this.security.isReadOnlyQuery(params.query)) {
             return {
                 status: "error",
-                error: "Only SELECT queries are allowed with runQuery. Use executeSql for other operations.",
+                error: "Only SELECT queries are allowed with run_select_query. Use execute_write_query for other operations.",
             };
         }
-        return await this.queryTools.runQuery(params);
+        return await this.queryTools.runSelectQuery(params);
     }
-    async executeSql(params) {
-        const check = this.checkToolEnabled("executeSql");
+    async executeWriteQuery(params) {
+        const check = this.checkToolEnabled("executeWriteQuery");
         if (!check.enabled) {
             return { status: "error", error: check.error };
         }
@@ -184,11 +184,11 @@ class MySQLMCP {
             if (!this.featureConfig.isCategoryEnabled("ddl")) {
                 return {
                     status: "error",
-                    error: 'DDL operations (DROP, TRUNCATE, ALTER, CREATE) require the "ddl" permission. Use executeDdl tool or add "ddl" to permissions.',
+                    error: 'DDL operations (DROP, TRUNCATE, ALTER, CREATE) require the "ddl" permission. Use execute_ddl tool or add "ddl" to permissions.',
                 };
             }
         }
-        return await this.queryTools.executeSql(params);
+        return await this.queryTools.executeWriteQuery(params);
     }
     // Analysis Tools
     async getColumnStatistics(params) {
@@ -307,7 +307,7 @@ class MySQLMCP {
         return await this.transactionTools.getTransactionStatus();
     }
     async executeInTransaction(params) {
-        const check = this.checkToolEnabled("executeSql"); // Use executeSql permission for transaction queries
+        const check = this.checkToolEnabled("executeWriteQuery"); // Use executeWriteQuery permission for transaction queries
         if (!check.enabled) {
             return { status: "error", error: check.error };
         }