@berthojoris/mcp-mysql-server 1.4.3 → 1.4.5

package/CHANGELOG.md

@@ -5,84 +5,107 @@ 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.4.3] - 2025-01-04
+## [1.4.5] - 2025-01-08
 
 ### Changed
-- Updated README.md with comprehensive parameter validation error troubleshooting section
-- Ensured all documentation is up-to-date with latest fixes
-- No functional code changes from version 1.4.2
+- Reorganized README.md structure - moved "Permission System" section to appear before "Available Tools" section for better user understanding
+- Updated documentation organization to improve readability and user experience
 
-## [1.4.2] - 2025-01-04
+### Fixed
+- Minor documentation formatting improvements
 
-### Changed
-- Re-published package to ensure README.md displays correctly on npmjs.com
-- No functional changes from version 1.4.1
-
-## [1.4.1] - 2025-01-04
+## [1.4.4] - 2025-01-07
 
 ### Fixed
-- **Critical Parameter Validation Fix**: Fixed "Invalid parameters: must be object" error that occurred when AI agents called MCP tools without parameters
-  - Applied defensive parameter handling to all 27 tools that accept parameters
-  - Tools now properly handle cases where MCP SDK passes `undefined` or `null` instead of empty object `{}`
-  - Pattern applied: `(args || {})` ensures parameters are always objects before validation
-  - No breaking changes - existing valid calls continue to work exactly as before
 
-### Changed
-- Enhanced parameter handling in `mcp-server.ts` for all tool handlers:
-  - Database Tools: `list_tables`, `read_table_schema`, `get_table_relationships`
-  - CRUD Tools: `create_record`, `read_records`, `update_record`, `delete_record`, `bulk_insert`, `bulk_update`, `bulk_delete`
-  - Query Tools: `run_query`, `execute_sql`, `execute_ddl`
-  - DDL Tools: `create_table`, `alter_table`, `drop_table`
-  - Transaction Tools: `begin_transaction`, `commit_transaction`, `rollback_transaction`, `execute_in_transaction`
-  - Stored Procedure Tools: `list_stored_procedures`, `get_stored_procedure_info`, `execute_stored_procedure`, `create_stored_procedure`, `drop_stored_procedure`, `show_create_procedure`
-  - Data Export Tools: `export_table_to_csv`, `export_query_to_csv`
-
-### Documentation
-- Added troubleshooting section in README.md for parameter validation errors
-- Created CHANGELOG.md to track version changes
-- Documented the fix and upgrade path for users experiencing this issue
-
-## [1.4.0] - 2024-12-XX
-
-### Added
-- Data Export Tools (`export_table_to_csv`, `export_query_to_csv`)
-- Bulk Operations (`bulk_insert`, `bulk_update`, `bulk_delete`)
-- Transaction Management (5 tools)
-- Stored Procedure Support (5 tools)
-- Enhanced permission error messages
-- Per-project permission configuration
+#### First Tool Call Failure Issue
+- **Problem**: The first tool call would fail with "Connection closed" error (-32000), but subsequent calls would succeed
+- **Root Cause**: MySQL MCP instance was initialized at module load time, before the MCP transport was fully connected, causing a race condition
+- **Solution**: Moved the initialization to occur after the MCP transport is connected in `src/mcp-server.ts`
+- **Impact**: First tool calls now work reliably without needing retry
+- **Files Changed**: `src/mcp-server.ts`
+
+#### Execute Permission Not Respected
+- **Problem**: Users with `execute` permission would still get "Dangerous keyword detected" errors when using legitimate SQL functions like `LOAD_FILE()`, `UNION`, or accessing `INFORMATION_SCHEMA`
+- **Root Cause**: Security layer blocked certain SQL keywords unconditionally, regardless of granted permissions
+- **Solution**: 
+  - Modified `validateQuery()` in `src/security/securityLayer.ts` to accept `bypassDangerousCheck` parameter
+  - Added `hasExecutePermission()` method to check if execute permission is enabled
+  - Updated `executeSql()` and `runQuery()` in `src/tools/queryTools.ts` to respect execute permission
+  - Reduced "always blocked" keywords to only critical security threats (GRANT, REVOKE, INTO OUTFILE, etc.)
+  - Allowed advanced SQL features when execute permission is granted:
+    - SQL functions: `LOAD_FILE()`, `BENCHMARK()`, `SLEEP()`
+    - Advanced SELECT: `UNION`, subqueries in FROM clause
+    - Database metadata: `INFORMATION_SCHEMA` access
+- **Impact**: Users with full permissions can now use advanced SQL features as intended
+- **Files Changed**: 
+  - `src/security/securityLayer.ts`
+  - `src/tools/queryTools.ts`
 
 ### Changed
-- Improved security with fine-grained permission system
-- Better error handling and user feedback
-- Performance optimizations for bulk operations
+- Updated version from 1.4.3 to 1.4.4
+- Enhanced README.md with detailed documentation on execute permission and advanced SQL features
+- Added "Recent Updates" section to README.md documenting bug fixes
 
-## [1.3.0] - 2024-XX-XX
+### Security
+- Critical security operations remain blocked even with execute permission:
+  - `GRANT` / `REVOKE` - User privilege management
+  - `INTO OUTFILE` / `INTO DUMPFILE` - Writing files to server
+  - `LOAD DATA` - Loading data from files
+  - Direct access to `mysql`, `performance_schema`, `sys` databases
+  - `USER` / `PASSWORD` manipulation
+
+## [1.4.3] - 2025-01-06
 
 ### Added
-- DDL Operations (Create, Alter, Drop Table)
-- Schema Management Tools
-- Permission-based access control
-- MCP protocol support
+- Improved permission error handling with detailed messages
+- Enhanced documentation for permission system
 
-## [1.2.0] - 2024-XX-XX
+### Fixed
+- Fixed undefined/null parameter handling in all tool calls
+- Improved MySQL operations error handling
+
+## [1.4.2] - 2025-01-05
 
 ### Added
-- REST API mode
-- Connection testing utilities
-- Foreign key relationship discovery
+- Dynamic per-project permissions system
+- Enhanced security layer with permission-based access control
+
+### Changed
+- Improved documentation and examples
 
-## [1.1.0] - 2024-XX-XX
+## [1.4.1] - 2025-01-04
 
 ### Added
-- CRUD operations
-- Custom SQL query execution
-- Parameterized queries
+- Stored procedure support
+- Transaction management tools
+- Bulk operations (insert, update, delete)
 
-## [1.0.0] - 2024-XX-XX
+### Changed
+- Enhanced error messages
+- Improved query validation
+
+## [1.4.0] - 2025-01-03
 
 ### Added
-- Initial release
-- Basic database listing
-- Table schema inspection
-- MySQL connection support
+- Data export tools (CSV export)
+- DDL operations (CREATE, ALTER, DROP tables)
+- Utility tools (connection testing, table relationships)
+
+### Changed
+- Major refactoring of tool organization
+- Improved TypeScript type definitions
+
+---
+
+## Version History Summary
+
+- **1.4.4** - Bug fixes: First call failure & execute permission
+- **1.4.3** - Permission error handling improvements
+- **1.4.2** - Dynamic per-project permissions
+- **1.4.1** - Stored procedures, transactions, bulk operations
+- **1.4.0** - Data export, DDL operations, utilities
+- **1.3.x** - Core CRUD operations and query tools
+- **1.2.x** - Security layer implementation
+- **1.1.x** - MCP protocol integration
+- **1.0.x** - Initial release

package/README.md

@@ -21,6 +21,39 @@ A fully-featured **Model Context Protocol (MCP)** server for MySQL database inte
 
 ---
 
+## 🆕 Recent Updates (v1.4.4)
+
+### Bug Fixes
+
+#### ✅ Fixed: First Tool Call Failure Issue
+**Problem**: The first tool call would fail with "Connection closed" error (-32000), but subsequent calls would succeed.
+
+**Root Cause**: The MySQL MCP instance was initialized at module load time, before the MCP transport was fully connected, causing a race condition.
+
+**Solution**: Moved the initialization to occur after the MCP transport is connected, ensuring proper startup sequence.
+
+**Impact**: First tool calls now work reliably without needing retry.
+
+#### ✅ Fixed: Execute Permission Not Respected
+**Problem**: Users with `execute` permission would still get "Dangerous keyword detected" errors when using legitimate SQL functions like `LOAD_FILE()`, `UNION`, or accessing `INFORMATION_SCHEMA`.
+
+**Root Cause**: The security layer blocked certain SQL keywords unconditionally, regardless of granted permissions.
+
+**Solution**: 
+- Modified security validation to respect the `execute` permission
+- Users with `execute` permission can now use:
+  - SQL functions like `LOAD_FILE()`, `BENCHMARK()`, `SLEEP()`
+  - Advanced SELECT features like `UNION` and subqueries
+  - Access to `INFORMATION_SCHEMA` for metadata queries
+- Critical security operations remain blocked (GRANT, REVOKE, INTO OUTFILE, etc.)
+
+**Impact**: Users with full permissions can now use advanced SQL features as intended.
+
+### Breaking Changes
+None - all changes are backward compatible.
+
+---
+
 ## 📦 Installation
 
 ### Option 1: Quick Start (npx)
@@ -111,84 +144,7 @@ Try asking your AI:
 
 ---
 
-## 🛠️ Available Tools
-
-The MCP server provides **30 powerful tools**:
-
-### Database Discovery (4 tools)
-
-| Tool | Description |
-|------|-------------|
-| `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 |
-
-### Data Operations - CRUD (4 tools)
-
-| Tool | Description |
-|------|-------------|
-| `create_record` | Insert new records with automatic SQL generation |
-| `read_records` | Query records with filtering, pagination, and sorting |
-| `update_record` | Update records based on conditions |
-| `delete_record` | Delete records with safety checks |
-
-### Bulk Operations (3 tools)
-
-| Tool | Description | Performance |
-|------|-------------|-------------|
-| `bulk_insert` | Insert multiple records in batches for optimal performance | Up to 10,000 records per batch |
-| `bulk_update` | Update multiple records with different conditions in batches | Up to 1,000 operations per batch |
-| `bulk_delete` | Delete multiple record sets based on different conditions | Up to 1,000 operations per batch |
-
-### Custom Queries (2 tools)
-
-| Tool | Description |
-|------|-------------|
-| `run_query` | Execute read-only SELECT queries |
-| `execute_sql` | Execute write operations (INSERT, UPDATE, DELETE, or DDL with permission) |
-
-### Schema Management - DDL (4 tools)
-
-| Tool | Description | Requires |
-|------|-------------|----------|
-| `create_table` | Create new tables with columns and indexes | `ddl` permission |
-| `alter_table` | Modify table structure (add/drop/modify columns, indexes) | `ddl` permission |
-| `drop_table` | Delete tables | `ddl` permission |
-| `execute_ddl` | Execute raw DDL SQL (CREATE, ALTER, DROP, TRUNCATE, RENAME) | `ddl` permission |
-
-### Utilities (4 tools)
-
-| Tool | Description |
-|------|-------------|
-| `test_connection` | Test database connectivity and measure latency |
-| `describe_connection` | Get current connection information |
-| `export_table_to_csv` | Export table data to CSV format with optional filtering, pagination, and sorting |
-| `export_query_to_csv` | Export the results of a SELECT query to CSV format |
-
-### Transaction Management (5 tools)
-
-| Tool | Description |
-|------|-------------|
-| `begin_transaction` | Start a new database transaction |
-| `commit_transaction` | Commit the current transaction |
-| `rollback_transaction` | Rollback the current transaction |
-| `get_transaction_status` | Check if a transaction is active |
-| `execute_in_transaction` | Execute SQL within a transaction context |
-
-### Stored Procedures (5 tools)
-
-| Tool | Description | Requires |
-|------|-------------|----------|
-| `list_stored_procedures` | List all stored procedures in a database | `procedure` permission |
-| `create_stored_procedure` | Create new stored procedures with parameters | `procedure` permission |
-| `get_stored_procedure_info` | Get detailed information about a stored procedure | `procedure` permission |
-| `execute_stored_procedure` | Execute stored procedures with IN/OUT/INOUT parameters | `procedure` permission |
-| `drop_stored_procedure` | Delete stored procedures | `procedure` permission |
-
----
-
-## 🔐 Permission System
+##  Permission System
 
 ### Permission Categories
 
@@ -201,7 +157,7 @@ Control access with these permission categories:
 | **`create`** | INSERT new records | Data entry |
 | **`update`** | UPDATE existing records | Data maintenance |
 | **`delete`** | DELETE records | Data cleanup |
-| **`execute`** | Execute custom SQL (DML) | Complex operations |
+| **`execute`** | Execute custom SQL (DML) + Advanced SQL features | Complex operations, advanced queries |
 | **`ddl`** | CREATE/ALTER/DROP tables | Schema management |
 | **`procedure`** | CREATE/DROP/EXECUTE stored procedures | Stored procedure management |
 | **`transaction`** | BEGIN, COMMIT, ROLLBACK transactions | ACID operations |
@@ -283,6 +239,103 @@ You can have different databases with different permissions in the same AI agent
 
 ---
 
+## 🔓 Execute Permission & Advanced SQL Features
+
+The `execute` permission unlocks advanced SQL capabilities that are restricted by default for security reasons.
+
+### What Execute Permission Enables
+
+When you grant the `execute` permission, users can:
+
+#### 1. **Advanced SQL Functions**
+- `LOAD_FILE()` - Read files from the server
+- `BENCHMARK()` - Performance testing
+- `SLEEP()` - Delay execution
+- And other MySQL built-in functions
+
+#### 2. **Advanced SELECT Features**
+- `UNION` queries - Combine multiple SELECT results
+- Subqueries in FROM clause - Complex nested queries
+- Access to `INFORMATION_SCHEMA` - Database metadata queries
+
+#### 3. **Execute Custom SQL**
+- Use `execute_sql` tool for INSERT, UPDATE, DELETE with advanced features
+- Use `run_query` tool for complex SELECT queries with UNION and subqueries
+
+### Security Considerations
+
+**Without `execute` permission:**
+```sql
+-- ❌ BLOCKED: UNION queries
+SELECT * FROM users WHERE id = 1 UNION SELECT * FROM admin;
+
+-- ❌ BLOCKED: Subqueries in FROM
+SELECT * FROM (SELECT * FROM users WHERE active = 1) AS active_users;
+
+-- ❌ BLOCKED: LOAD_FILE function
+SELECT LOAD_FILE('/etc/passwd');
+
+-- ❌ BLOCKED: INFORMATION_SCHEMA access
+SELECT * FROM INFORMATION_SCHEMA.TABLES;
+```
+
+**With `execute` permission:**
+```sql
+-- ✅ ALLOWED: All advanced SQL features
+SELECT * FROM users WHERE id = 1 UNION SELECT * FROM admin;
+SELECT * FROM (SELECT * FROM users WHERE active = 1) AS active_users;
+SELECT LOAD_FILE('/path/to/file.txt');
+SELECT * FROM INFORMATION_SCHEMA.TABLES WHERE TABLE_SCHEMA = 'mydb';
+```
+
+### When to Grant Execute Permission
+
+**Grant `execute` when:**
+- Users need complex analytical queries with UNION or subqueries
+- Developers need access to INFORMATION_SCHEMA for metadata analysis
+- Advanced SQL functions are required for specific operations
+- You trust the user with broader database access
+
+**Don't grant `execute` when:**
+- Users only need basic CRUD operations
+- Working with untrusted AI agents
+- Production environments with strict security policies
+- Read-only access is sufficient
+
+### Example: Analytics with Execute Permission
+
+```json
+{
+  "args": [
+    "mysql://analyst:pass@localhost:3306/analytics_db",
+    "list,read,execute,utility"
+  ]
+}
+```
+
+This allows the AI agent to run complex analytical queries:
+
+```sql
+-- Complex query with UNION and subqueries
+SELECT 'Q1' as quarter, SUM(revenue) as total
+FROM (SELECT * FROM sales WHERE date BETWEEN '2024-01-01' AND '2024-03-31') AS q1_sales
+UNION
+SELECT 'Q2' as quarter, SUM(revenue) as total
+FROM (SELECT * FROM sales WHERE date BETWEEN '2024-04-01' AND '2024-06-30') AS q2_sales;
+```
+
+### Critical Security Keywords (Always Blocked)
+
+Even with `execute` permission, these operations are **always blocked** for security:
+
+- `GRANT` / `REVOKE` - User privilege management
+- `INTO OUTFILE` / `INTO DUMPFILE` - Writing files to server
+- `LOAD DATA` - Loading data from files
+- Direct access to `mysql`, `performance_schema`, `sys` databases
+- `USER` / `PASSWORD` manipulation
+
+---
+
 ## 🚫 Permission Error Handling
 
 The MySQL MCP Server provides clear, user-friendly error messages when operations are attempted without proper permissions. This helps users understand exactly what permissions are needed and how to enable them.
@@ -397,6 +450,83 @@ After (DDL enabled):
 
 ---
 
+## 🛠️ Available Tools
+
+The MCP server provides **30 powerful tools**:
+
+### Database Discovery (4 tools)
+
+| Tool | Description |
+|------|-------------|
+| `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 |
+
+### Data Operations - CRUD (4 tools)
+
+| Tool | Description |
+|------|-------------|
+| `create_record` | Insert new records with automatic SQL generation |
+| `read_records` | Query records with filtering, pagination, and sorting |
+| `update_record` | Update records based on conditions |
+| `delete_record` | Delete records with safety checks |
+
+### Bulk Operations (3 tools)
+
+| Tool | Description | Performance |
+|------|-------------|-------------|
+| `bulk_insert` | Insert multiple records in batches for optimal performance | Up to 10,000 records per batch |
+| `bulk_update` | Update multiple records with different conditions in batches | Up to 1,000 operations per batch |
+| `bulk_delete` | Delete multiple record sets based on different conditions | Up to 1,000 operations per batch |
+
+### Custom Queries (2 tools)
+
+| Tool | Description |
+|------|-------------|
+| `run_query` | Execute read-only SELECT queries |
+| `execute_sql` | Execute write operations (INSERT, UPDATE, DELETE, or DDL with permission) |
+
+### Schema Management - DDL (4 tools)
+
+| Tool | Description | Requires |
+|------|-------------|----------|
+| `create_table` | Create new tables with columns and indexes | `ddl` permission |
+| `alter_table` | Modify table structure (add/drop/modify columns, indexes) | `ddl` permission |
+| `drop_table` | Delete tables | `ddl` permission |
+| `execute_ddl` | Execute raw DDL SQL (CREATE, ALTER, DROP, TRUNCATE, RENAME) | `ddl` permission |
+
+### Utilities (4 tools)
+
+| Tool | Description |
+|------|-------------|
+| `test_connection` | Test database connectivity and measure latency |
+| `describe_connection` | Get current connection information |
+| `export_table_to_csv` | Export table data to CSV format with optional filtering, pagination, and sorting |
+| `export_query_to_csv` | Export the results of a SELECT query to CSV format |
+
+### Transaction Management (5 tools)
+
+| Tool | Description |
+|------|-------------|
+| `begin_transaction` | Start a new database transaction |
+| `commit_transaction` | Commit the current transaction |
+| `rollback_transaction` | Rollback the current transaction |
+| `get_transaction_status` | Check if a transaction is active |
+| `execute_in_transaction` | Execute SQL within a transaction context |
+
+### Stored Procedures (5 tools)
+
+| Tool | Description | Requires |
+|------|-------------|----------|
+| `list_stored_procedures` | List all stored procedures in a database | `procedure` permission |
+| `create_stored_procedure` | Create new stored procedures with parameters | `procedure` permission |
+| `get_stored_procedure_info` | Get detailed information about a stored procedure | `procedure` permission |
+| `execute_stored_procedure` | Execute stored procedures with IN/OUT/INOUT parameters | `procedure` permission |
+| `drop_stored_procedure` | Delete stored procedures | `procedure` permission |
+
+---
+
 ## 🏗️ DDL Operations
 
 DDL (Data Definition Language) operations allow AI to create, modify, and delete tables.