@berthojoris/mcp-mysql-server 1.4.4 → 1.4.6

package/CHANGELOG.md

@@ -5,6 +5,24 @@ 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.6] - 2025-11-21
+
+### Changed
+- Removed "Execute Permission & Advanced SQL Features" section from README.md
+- Removed "Configuration" section from README.md
+- Removed "REST API Mode" section from README.md
+- Removed "Testing" section from README.md
+- Streamlined documentation by removing outdated or less relevant sections
+
+## [1.4.5] - 2025-01-08
+
+### Changed
+- 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
+
+### Fixed
+- Minor documentation formatting improvements
+
 ## [1.4.4] - 2025-01-07
 
 ### Fixed

package/README.md

@@ -21,39 +21,6 @@ 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)
@@ -144,84 +111,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
 
@@ -316,103 +206,6 @@ 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.
@@ -527,6 +320,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.
@@ -1189,51 +1059,6 @@ END IF;
 
 ---
 
-## ⚙️ Configuration
-
-### Connection String Format
-
-```
-mysql://username:password@host:port/database
-```
-
-**Examples:**
-```
-mysql://root:pass@localhost:3306/myapp
-mysql://user:pass@192.168.1.100:3306/production
-mysql://admin:pass@db.example.com:3306/analytics
-```
-
-**Database name is optional:**
-```
-mysql://user:pass@localhost:3306/
-```
-
-When omitted, AI can switch between databases using SQL commands.
-
-### Environment Variables
-
-Create `.env` file for local development:
-
-```env
-# MySQL Connection
-DB_HOST=localhost
-DB_PORT=3306
-DB_USER=root
-DB_PASSWORD=yourpassword
-DB_NAME=yourdatabase
-
-# Default Permissions (optional, can be overridden per-project)
-MCP_CONFIG=list,read,utility
-
-# REST API Mode (optional)
-PORT=3000
-JWT_SECRET=your_jwt_secret
-NODE_ENV=development
-```
-
----
-
 ## 🔒 Security Features
 
 ### Built-in Security
@@ -1281,92 +1106,6 @@ NODE_ENV=development
 
 ---
 
-## 🌐 REST API Mode
-
-In addition to MCP protocol, this server can run as a REST API.
-
-### Start API Server
-
-```bash
-npm run start:api
-```
-
-Server runs on `http://localhost:3000` (or configured PORT).
-
-### API Endpoints
-
-All endpoints require JWT authentication (except `/health`).
-
-**Health Check:**
-```
-GET /health
-```
-
-**Database Operations:**
-```
-GET  /api/databases          # List databases
-GET  /api/tables             # List tables
-GET  /api/tables/:name/schema    # Get table schema
-GET  /api/tables/:name/records   # Read records
-POST /api/tables/:name/records   # Create record
-PUT  /api/tables/:name/records/:id  # Update record
-DELETE /api/tables/:name/records/:id  # Delete record
-```
-
-**Query Operations:**
-```
-POST /api/query    # Execute SELECT query
-POST /api/execute  # Execute write query
-```
-
-**Utilities:**
-```
-GET /api/connection       # Connection info
-GET /api/connection/test  # Test connection
-GET /api/tables/:name/relationships  # Get foreign keys
-```
-
-### Authentication
-
-Include JWT token in Authorization header:
-
-```bash
-curl -H "Authorization: Bearer YOUR_JWT_TOKEN" \
-     http://localhost:3000/api/tables
-```
-
----
-
-## 🧪 Testing
-
-### Test MCP Server Locally
-
-```bash
-# Test connection using npx (recommended)
-npx -y @berthojoris/mcp-mysql-server mysql://user:pass@localhost:3306/test "list,read,utility"
-
-# Or if you cloned the repository locally
-node bin/mcp-mysql.js mysql://user:pass@localhost:3306/test "list,read,utility"
-```
-
-### Test with Claude Desktop
-
-1. Configure `claude_desktop_config.json`
-2. Restart Claude Desktop
-3. Ask: *"What databases are available?"*
-
-### Test REST API
-
-```bash
-# Start API server
-npm run start:api
-
-# Test health endpoint
-curl http://localhost:3000/health
-```
-
----
-
 ## 🚀 Bulk Operations
 
 The MySQL MCP server includes powerful bulk operation tools designed for high-performance data processing. These tools are optimized for handling large datasets efficiently.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@berthojoris/mcp-mysql-server",
-  "version": "1.4.4",
+  "version": "1.4.6",
   "description": "Model Context Protocol server for MySQL database integration with dynamic per-project permissions and data export capabilities",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",