@neverinfamous/mysql-mcp 2.1.0 → 2.3.0

package/releases/v2.0.0-release-notes.md

@@ -10,8 +10,9 @@
 **mysql-mcp v2.0.0** is a transformative update representing our most significant release since v1.0. This release adds **85 new tools** (80% increase), introduces **HTTP/SSE streaming transport**, delivers **Smart Shortcuts** for instant tool customization, implements **AI-optimized protocol features** for seamless assistant integration, provides an **interactive Jupyter Notebook tutorial**, implements comprehensive **security enhancements**, and achieves **97% test coverage** with over 1,500 tests.
 
 ### At a Glance
+
 - **191 Tools** (was 106) - 80% increase
-- **18 Resources** (was 12) - 50% increase  
+- **18 Resources** (was 12) - 50% increase
 - **19 Prompts** (was 14) - 36% increase
 - **24 Tool Groups** (was 15) - 60% increase
 - **Smart Shortcuts** - 7 intelligent tool presets (starter, ai, dba, dev, etc.)
@@ -41,12 +42,14 @@ docker run -p 3000:3000 writenotenow/mysql-mcp:v2.0.0 \
 ```
 
 **Endpoints:**
+
 - `GET /sse` - Establish MCP connection via Server-Sent Events
 - `POST /messages` - Send JSON-RPC messages
 - `GET /health` - Health check endpoint
 - `GET /.well-known/oauth-protected-resource` - OAuth 2.0 metadata
 
 **Features:**
+
 - StreamableHTTPServerTransport from @modelcontextprotocol/sdk
 - CORS support for cross-origin requests
 - OAuth 2.0 integration for enterprise security
@@ -55,31 +58,41 @@ docker run -p 3000:3000 writenotenow/mysql-mcp:v2.0.0 \
 ### 85 New Tools Across 9 Categories
 
 #### 1. Schema Management (10 tools) - `schema` group
+
 Advanced schema object management:
+
 - `mysql_list_schemas`, `mysql_create_schema`, `mysql_drop_schema`
 - `mysql_list_views`, `mysql_create_view`
 - `mysql_list_stored_procedures`, `mysql_list_functions`
 - `mysql_list_triggers`, `mysql_list_constraints`, `mysql_list_events`
 
 #### 2. Event Scheduler (6 tools) - `events` group
+
 Complete event management:
+
 - `mysql_event_create`, `mysql_event_alter`, `mysql_event_drop`
 - `mysql_event_list`, `mysql_event_status`, `mysql_scheduler_status`
 
 #### 3. sys Schema Diagnostics (8 tools) - `sysschema` group
+
 Performance insights from MySQL sys schema:
+
 - `mysql_sys_user_summary`, `mysql_sys_io_summary`, `mysql_sys_statement_summary`
 - `mysql_sys_wait_summary`, `mysql_sys_innodb_lock_waits`
 - `mysql_sys_schema_stats`, `mysql_sys_host_summary`, `mysql_sys_memory_summary`
 
 #### 4. Statistical Analysis (8 tools) - `stats` group
+
 Data science capabilities:
+
 - `mysql_stats_descriptive`, `mysql_stats_percentiles`, `mysql_stats_correlation`
 - `mysql_stats_distribution`, `mysql_stats_time_series`, `mysql_stats_regression`
 - `mysql_stats_sampling`, `mysql_stats_histogram`
 
 #### 5. Spatial/GIS (12 tools) - `spatial` group
+
 Location-based data operations:
+
 - `mysql_spatial_create_column`, `mysql_spatial_create_index`
 - `mysql_spatial_point`, `mysql_spatial_polygon`
 - `mysql_spatial_distance`, `mysql_spatial_distance_sphere`
@@ -87,26 +100,34 @@ Location-based data operations:
 - `mysql_spatial_buffer`, `mysql_spatial_transform`, `mysql_spatial_geojson`
 
 #### 6. Security (9 tools) - `security` group
+
 Enterprise security features:
+
 - `mysql_security_audit`, `mysql_security_firewall_status`, `mysql_security_firewall_rules`
 - `mysql_security_mask_data`, `mysql_security_password_validate`
 - `mysql_security_ssl_status`, `mysql_security_user_privileges`
 - `mysql_security_sensitive_tables`, `mysql_security_encryption_status`
 
 #### 7. Cluster Management (10 tools) - `cluster` group
+
 InnoDB Cluster & Group Replication:
+
 - `mysql_gr_status`, `mysql_gr_members`, `mysql_gr_primary`, `mysql_gr_transactions`
 - `mysql_gr_flow_control`, `mysql_cluster_status`, `mysql_cluster_instances`
 - `mysql_cluster_topology`, `mysql_cluster_router_status`, `mysql_cluster_switchover`
 
 #### 8. Role Management (8 tools) - `roles` group
+
 MySQL 8.0 RBAC:
+
 - `mysql_role_list`, `mysql_role_create`, `mysql_role_drop`
 - `mysql_role_grants`, `mysql_role_grant`, `mysql_role_assign`
 - `mysql_role_revoke`, `mysql_user_roles`
 
 #### 9. Document Store (9 tools) - `docstore` group
+
 NoSQL/MongoDB-style API:
+
 - `mysql_doc_list_collections`, `mysql_doc_create_collection`, `mysql_doc_drop_collection`
 - `mysql_doc_find`, `mysql_doc_add`, `mysql_doc_modify`, `mysql_doc_remove`
 - `mysql_doc_create_index`, `mysql_doc_collection_info`
@@ -141,15 +162,15 @@ NoSQL/MongoDB-style API:
 
 **Available Shortcuts:**
 
-| Shortcut | Tools | Use Case | What's Included |
-|----------|-------|----------|-----------------|
-| `starter` | **38** | 🌟 **Recommended** | Core CRUD, JSON, transactions, text search |
-| `essential` | 15 | Minimal footprint | Only core + transactions |
-| `dev` | 67 | Full development | starter + fulltext, performance, schema, stats |
-| `ai` | 77 | **NEW** - AI/ML workloads | JSON, Document Store, spatial, statistics |
-| `dba` | 103 | **NEW** - Database admin | Admin, monitoring, security, replication, roles |
-| `base` | 160 | All core MySQL | Everything except Router/ProxySQL/Shell |
-| `ecosystem` | 31 | External tools | MySQL Router, ProxySQL, MySQL Shell |
+| Shortcut    | Tools  | Use Case                  | What's Included                                 |
+| ----------- | ------ | ------------------------- | ----------------------------------------------- |
+| `starter`   | **38** | 🌟 **Recommended**        | Core CRUD, JSON, transactions, text search      |
+| `essential` | 15     | Minimal footprint         | Only core + transactions                        |
+| `dev`       | 67     | Full development          | starter + fulltext, performance, schema, stats  |
+| `ai`        | 77     | **NEW** - AI/ML workloads | JSON, Document Store, spatial, statistics       |
+| `dba`       | 103    | **NEW** - Database admin  | Admin, monitoring, security, replication, roles |
+| `base`      | 160    | All core MySQL            | Everything except Router/ProxySQL/Shell         |
+| `ecosystem` | 31     | External tools            | MySQL Router, ProxySQL, MySQL Shell             |
 
 **Quick Examples:**
 
@@ -168,6 +189,7 @@ NoSQL/MongoDB-style API:
 ```
 
 **Why Smart Shortcuts?**
+
 - ✅ **Instant setup** - One command, perfect toolset
 - ✅ **IDE-friendly** - Stay within tool limits
 - ✅ **Role-based** - Presets for developers, DBAs, data scientists
@@ -178,23 +200,27 @@ NoSQL/MongoDB-style API:
 **NEW in v2.0** - Learn mysql-mcp interactively! Our comprehensive [Jupyter Notebook](https://github.com/neverinfamous/mysql-mcp/blob/master/examples/notebooks/quickstart.ipynb) demonstrates:
 
 **Basic Operations:**
+
 - Connecting via `mcp` Python SDK
 - Reading/Writing data with SQL tools
 - Accessing Resources (schema, tables, performance)
 - Error handling patterns
 
 **Advanced Features:**
+
 - **Transactions** - Atomic writes with COMMIT/ROLLBACK
 - **AI Prompts** - Using guided workflows for optimization
 - **Performance Analysis** - EXPLAIN plans and query tuning
 
 **NEW Capabilities in v2.0:**
+
 - **JSON Support** - Treating MySQL as a document store with `mysql_json_extract/set`
 - **Fulltext Search** - Building RAG-ready search with `mysql_fulltext_create/search`
 - **Spatial Data** - Location-based search (GIS) with `mysql_spatial_distance_sphere`
 - **Document Store** - NoSQL API (MongoDB-style) with `mysql_doc_create_collection/add/find`
 
 **Perfect for:**
+
 - 🎓 Learning MCP protocol
 - 🧪 Testing mysql-mcp features
 - 📝 Prototyping database workflows
@@ -204,16 +230,17 @@ NoSQL/MongoDB-style API:
 
 **NEW in v2.0** - Zero-configuration features that automatically enhance AI assistant interactions:
 
-| Feature | Benefit |
-|---------|---------|
-| **Tool Annotations** | AI knows which tools are safe to auto-run (`readOnlyHint`), which are destructive (`destructiveHint`), and which interact with external systems (`openWorldHint`) |
-| **Resource Metadata** | Resources include `priority` hints so AI can focus on the most relevant data (health, tables, schema) |
-| **Protocol Logging** | AI clients receive real-time log notifications for transparency during operations |
-| **Progress Notifications** | Long-running operations report progress to prevent timeouts and show status |
+| Feature                    | Benefit                                                                                                                                                           |
+| -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Tool Annotations**       | AI knows which tools are safe to auto-run (`readOnlyHint`), which are destructive (`destructiveHint`), and which interact with external systems (`openWorldHint`) |
+| **Resource Metadata**      | Resources include `priority` hints so AI can focus on the most relevant data (health, tables, schema)                                                             |
+| **Protocol Logging**       | AI clients receive real-time log notifications for transparency during operations                                                                                 |
+| **Progress Notifications** | Long-running operations report progress to prevent timeouts and show status                                                                                       |
 
 **MCP 2025-11-25 Compliant** - Works seamlessly with Claude Desktop, Cursor IDE, and all MCP clients.
 
 **Why This Matters:**
+
 - ✅ **Smarter AI** - Assistants understand tool safety and impact
 - ✅ **Better UX** - Real-time feedback during long operations
 - ✅ **Production-ready** - Proper logging and error handling
@@ -224,13 +251,17 @@ NoSQL/MongoDB-style API:
 ## 🔒 Security Enhancements
 
 ### Input Validation Module
+
 New centralized `src/utils/validators.ts`:
+
 - **`validateIdentifier()`** - Validates SQL identifiers against injection attacks
 - **`validateWhereClause()`** - Detects dangerous SQL patterns (UNION, stacked queries, timing attacks)
 - **`escapeIdentifier()`** and **`escapeLikePattern()`** - Safe escaping utilities
 
 ### HTTP Security Headers
+
 All HTTP responses include:
+
 - `X-Content-Type-Options: nosniff` - Prevents MIME type sniffing
 - `X-Frame-Options: DENY` - Prevents clickjacking
 - `X-XSS-Protection: 1; mode=block` - Enables XSS filtering
@@ -238,12 +269,15 @@ All HTTP responses include:
 - `Cache-Control: no-store` - Prevents caching of API responses
 
 ### SQL Injection Prevention
+
 Input validation applied to:
+
 - Backup tools (`backup.ts`) - Table name and WHERE clause validation
 - JSON tools (`json/core.ts`) - All 8 core JSON tools validated
 - Shell tools - Fixed injection vulnerability in `mysqlsh_import_table`
 
 ### Security Test Suite
+
 - `security_injection.test.ts` - 14 SQL injection prevention tests
 - `security_integration.test.ts` - 11 validation flow tests
 - `http.test.ts` - 6 security header verification tests
@@ -254,12 +288,15 @@ Input validation applied to:
 ## ⚡ Performance Optimizations
 
 ### Caching Improvements
+
 - **Tool Definition Caching** - `getToolDefinitions()` caches 191 tool definitions after first call
 - **O(1) Lookups** - `getToolGroup()` uses Map for instant lookup (was O(n×m) linear search)
 - **Cached Tool Names** - `getAllToolNames()` caches 191-tool array
 
 ### Performance Test Suite
+
 New `src/__tests__/perf.test.ts` with 11 timing-based regression tests:
+
 - Tool definition caching validation
 - Tool group lookup performance (Map vs linear)
 - Filter parsing performance for complex chains
@@ -269,33 +306,41 @@ New `src/__tests__/perf.test.ts` with 11 timing-based regression tests:
 ## 🏗️ Architectural Improvements
 
 ### Modular Refactoring
+
 Refactored large monolithic files (500+ lines) into focused modules:
 
 **Phase 1:**
+
 - `tools/spatial/` - Split into 4 modules: setup, geometry, queries, operations
 - `tools/admin/` - Split into 3 modules: maintenance, monitoring, backup
 - `tools/sysschema/` - Split into 3 modules: activity, performance, resources
 
 **Phase 2:**
+
 - `tools/performance/` - Split into 2 modules: analysis, optimization
 - `tools/text/` - Split into 2 modules: processing, fulltext
 - Separated `replication.ts` and `partitioning.ts` into distinct files
 
 **Phase 3:**
+
 - `tools/schema/` - Split into 6 modules: management, views, routines, triggers, constraints, scheduled_events
 
 **Phase 4:**
+
 - Extracted CLI argument parsing to `src/cli/args.ts`
 - Moved schema operations to `src/adapters/mysql/SchemaManager.ts`
 
 ### Test Suite Modularity
+
 Refactored monolithic test files:
+
 - Split `admin.test.ts` (626 lines) → 3 focused files
 - Split `json.test.ts` (729 lines) → 3 focused files
 - Split shell tests → 5 modular files
 - Split resource tests → 10 modular files
 
 ### Code Quality
+
 - **Removed ALL `eslint-disable` directives** - Strict type safety throughout
 - **Removed deprecated SSEServerTransport** - Migrated to StreamableHTTPServerTransport
 - **Zero breaking changes** - Full backward compatibility maintained
@@ -305,18 +350,21 @@ Refactored monolithic test files:
 ## 🧪 Testing Excellence
 
 ### Coverage Achievements
+
 - **Statement Coverage:** 97.34%
 - **Branch Coverage:** 83.87%
 - **Total Tests:** 1,500+ tests passing
 - **Test Files:** 84 modular test files
 
 ### Test Infrastructure
+
 - **Centralized mocks** in `src/__tests__/mocks/`
 - **Fully mocked** - Tests run without database connection
 - **Fast execution** - ~20 second total runtime
 - **Meaningful assertions** - Replaced coverage boosters with real tests
 
 ### New Test Coverage
+
 - CLI tests (91% coverage) - argument parsing, signal handling, error scenarios
 - HTTP transport tests - CORS, health checks, OAuth metadata
 - Security tests - injection prevention, validation flow
@@ -411,15 +459,15 @@ This gives you **38 essential tools**: core CRUD, JSON, transactions, text searc
 
 ### Meta-Groups
 
-| Shortcut | Tools | Use Case |
-|----------|-------|----------|
-| `starter` | 38 | 🌟 **Recommended** - Essential development tools |
-| `essential` | 15 | Minimal footprint - Core + transactions only |
-| `dev` | 67 | Full development - starter + fulltext, performance, schema |
-| `ai` | 77 | **NEW** - AI/ML workloads (JSON, spatial, stats, docstore) |
-| `dba` | 103 | **NEW** - DBA tasks (admin, monitoring, security, roles) |
-| `base` | 160 | All core MySQL tools |
-| `ecosystem` | 31 | External tools (Router, ProxySQL, Shell) |
+| Shortcut    | Tools | Use Case                                                   |
+| ----------- | ----- | ---------------------------------------------------------- |
+| `starter`   | 38    | 🌟 **Recommended** - Essential development tools           |
+| `essential` | 15    | Minimal footprint - Core + transactions only               |
+| `dev`       | 67    | Full development - starter + fulltext, performance, schema |
+| `ai`        | 77    | **NEW** - AI/ML workloads (JSON, spatial, stats, docstore) |
+| `dba`       | 103   | **NEW** - DBA tasks (admin, monitoring, security, roles)   |
+| `base`      | 160   | All core MySQL tools                                       |
+| `ecosystem` | 31    | External tools (Router, ProxySQL, Shell)                   |
 
 ### Examples
 
@@ -472,32 +520,32 @@ This gives you **38 essential tools**: core CRUD, JSON, transactions, text searc
 
 ### Tools by Category (191 Total)
 
-| Category | Count | Description |
-|----------|-------|-------------|
-| Core | 8 | CRUD, schema, tables, indexes |
-| Transactions | 7 | BEGIN, COMMIT, ROLLBACK, savepoints |
-| JSON | 17 | JSON functions + merge, diff, stats |
-| Text | 6 | REGEXP, LIKE, SOUNDEX |
-| FULLTEXT | 4 | Natural language search |
-| Performance | 8 | EXPLAIN, query analysis |
-| Optimization | 4 | Index hints, recommendations |
-| Admin | 6 | OPTIMIZE, ANALYZE, CHECK |
-| Monitoring | 7 | PROCESSLIST, status variables |
-| Backup | 4 | Export, import, mysqldump |
-| Replication | 5 | Master/slave, binlog |
-| Partitioning | 4 | Partition management |
-| Router | 9 | MySQL Router REST API |
-| ProxySQL | 12 | Proxy management |
-| Shell | 10 | MySQL Shell utilities |
-| **Schema** | **10** | **Views, procedures, triggers** |
-| **Events** | **6** | **Event Scheduler** |
-| **sys Schema** | **8** | **Diagnostics** |
-| **Statistics** | **8** | **Statistical analysis** |
-| **Spatial/GIS** | **12** | **Geospatial data** |
-| **Security** | **9** | **Audit, SSL, encryption** |
-| **Cluster** | **10** | **Group Replication, InnoDB Cluster** |
-| **Roles** | **8** | **RBAC** |
-| **Document Store** | **9** | **NoSQL API** |
+| Category           | Count  | Description                           |
+| ------------------ | ------ | ------------------------------------- |
+| Core               | 8      | CRUD, schema, tables, indexes         |
+| Transactions       | 7      | BEGIN, COMMIT, ROLLBACK, savepoints   |
+| JSON               | 17     | JSON functions + merge, diff, stats   |
+| Text               | 6      | REGEXP, LIKE, SOUNDEX                 |
+| FULLTEXT           | 4      | Natural language search               |
+| Performance        | 8      | EXPLAIN, query analysis               |
+| Optimization       | 4      | Index hints, recommendations          |
+| Admin              | 6      | OPTIMIZE, ANALYZE, CHECK              |
+| Monitoring         | 7      | PROCESSLIST, status variables         |
+| Backup             | 4      | Export, import, mysqldump             |
+| Replication        | 5      | Master/slave, binlog                  |
+| Partitioning       | 4      | Partition management                  |
+| Router             | 9      | MySQL Router REST API                 |
+| ProxySQL           | 12     | Proxy management                      |
+| Shell              | 10     | MySQL Shell utilities                 |
+| **Schema**         | **10** | **Views, procedures, triggers**       |
+| **Events**         | **6**  | **Event Scheduler**                   |
+| **sys Schema**     | **8**  | **Diagnostics**                       |
+| **Statistics**     | **8**  | **Statistical analysis**              |
+| **Spatial/GIS**    | **12** | **Geospatial data**                   |
+| **Security**       | **9**  | **Audit, SSL, encryption**            |
+| **Cluster**        | **10** | **Group Replication, InnoDB Cluster** |
+| **Roles**          | **8**  | **RBAC**                              |
+| **Document Store** | **9**  | **NoSQL API**                         |
 
 ---
 

package/releases/v2.1.0-release-notes.md

@@ -10,6 +10,7 @@
 **mysql-mcp v2.1.0** delivers significant bug fixes, performance improvements, and enhanced testing coverage. This release focuses on production stability with fixes for Document Store, Group Replication, InnoDB Cluster, spatial tools, and MySQL Shell integration.
 
 ### At a Glance
+
 - **12+ Bug Fixes** — Document Store filters, Group Replication MySQL 8.0 compatibility, spatial coordinate handling, Router TLS, and more
 - **Performance Improvements** — Native MCP SDK logging, parallelized health queries, batched index queries (N+1 → 1), configurable metadata cache
 - **112 New Tests** — Branch coverage improved from ~83% to ~86% (1590 tests total)
@@ -20,6 +21,7 @@
 ## 🐛 Bug Fixes
 
 ### Document Store
+
 - **Document Store Filter Tools** — Fixed `mysql_doc_modify` and `mysql_doc_remove` failing with "Invalid JSON path expression" error. Added `parseDocFilter()` function supporting three filter formats:
   - By `_id`: Direct 32-char hex string (e.g., `bbc83181703d43e68ffad119c4bbbfde`)
   - By `field=value`: Simple equality (e.g., `name=Alice`, `age=30`)
@@ -27,19 +29,24 @@
   - Now uses parameterized queries for SQL injection protection
 
 ### Group Replication & InnoDB Cluster
+
 - **Group Replication Tools MySQL 8.0 Compatibility** — Fixed `mysql_gr_members` and `mysql_gr_transactions` failing with "Unknown column" errors on MySQL 8.0.44. Removed non-existent columns from queries.
 - **InnoDB Cluster Status Tool** — Fixed `mysql_cluster_status` failing with "Unable to query cluster metadata" due to hardcoded column names. Changed to `SELECT *` for compatibility across MySQL versions.
 
 ### Spatial Tools
+
 - **Spatial Coordinate Order (Final Fix)** — Fixed `mysql_spatial_point`, `mysql_spatial_distance`, and `mysql_spatial_distance_sphere` to correctly accept longitude-latitude parameter order by using MySQL's `axis-order=long-lat` option.
 
 ### MySQL Router
+
 - **Router TLS with Node.js fetch** — Fixed `mysql_router_*` tools failing with "fetch failed" when `MYSQL_ROUTER_INSECURE=true`. Replaced with native `https.request()` module for proper self-signed certificate handling.
 
 ### Partitioning
+
 - **Partitioning Tools** — Fixed `mysql_reorganize_partition` to support both RANGE and LIST partition types (previously hardcoded to RANGE only). Added required `partitionType` parameter to schema.
 
 ### MySQL Shell
+
 - **MySQL Shell Tools Error Handling** — Improved error detection in `execShellJS()` to properly catch errors from stderr (e.g., `local_infile disabled`, privilege errors, fatal dump errors).
 - **MySQL Shell Export Table** — Removed unsupported `columns` option from `mysqlsh_export_table` (not supported by `util.exportTable()` in MySQL Shell 9.x).
 
@@ -48,23 +55,25 @@
 ## ✨ New Features
 
 ### New Tool Parameters
+
 - **`mysqlsh_import_table` / `mysqlsh_load_dump`** — Added `updateServerSettings` boolean option to automatically enable `local_infile` on the server before import/load operations
 - **`mysqlsh_dump_schemas`** — Added `ddlOnly` boolean option to dump only DDL (schema structure) without events, triggers, or routines
 - **`mysqlsh_dump_tables`** — Added `all` boolean option to control whether triggers are included in the dump
 
 ### Server Instructions
+
 - **Automatic Usage Instructions** — Usage instructions are now automatically provided to AI agents via the MCP protocol's `instructions` capability during server initialization
 
 ---
 
 ## ⚡ Performance Improvements
 
-| Improvement | Description |
-|------------|-------------|
-| **Native MCP Logging** | Upgraded to MCP SDK v1.25.1 with native `server.sendLoggingMessage()` |
+| Improvement                     | Description                                                                                        |
+| ------------------------------- | -------------------------------------------------------------------------------------------------- |
+| **Native MCP Logging**          | Upgraded to MCP SDK v1.25.1 with native `server.sendLoggingMessage()`                              |
 | **Parallelized Health Queries** | Health resource now executes status and max_connections queries concurrently using `Promise.all()` |
-| **Batched Index Queries** | `SchemaManager.getSchema()` now fetches all indexes in a single query (eliminates N+1 pattern) |
-| **Metadata Cache with TTL** | Added configurable TTL-based cache (default 30s, via `METADATA_CACHE_TTL_MS`) |
+| **Batched Index Queries**       | `SchemaManager.getSchema()` now fetches all indexes in a single query (eliminates N+1 pattern)     |
+| **Metadata Cache with TTL**     | Added configurable TTL-based cache (default 30s, via `METADATA_CACHE_TTL_MS`)                      |
 
 ---