# mysql-mcp v2.0.0 Release Notes
**Release Date:** December 16, 2025
**Status:** Production/Stable
---
## 🎉 Major Release Highlights
**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
- **19 Prompts** (was 14) - 36% increase
- **24 Tool Groups** (was 15) - 60% increase
- **Smart Shortcuts** - 7 intelligent tool presets (starter, ai, dba, dev, etc.)
- **HTTP Streaming** - Full SSE transport support
- **AI Protocol Features** - Tool annotations, progress notifications, logging
- **Interactive Tutorial** - Comprehensive Jupyter Notebook with Python SDK
- **97% Test Coverage** - 1,500+ tests passing
- **Security Hardened** - Input validation, HTTP headers, SQL injection prevention
---
## 🚀 What's New
### HTTP/SSE Streaming Transport
**NEW in v2.0** - Full support for HTTP-based deployments with Server-Sent Events (SSE):
```bash
# Start HTTP server
node dist/cli.js --transport http --port 3000 --mysql mysql://user:pass@localhost/db
# Docker with HTTP
docker run -p 3000:3000 writenotenow/mysql-mcp:v2.0.0 \
--transport http \
--port 3000 \
--mysql mysql://user:pass@host.docker.internal:3306/db
```
**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
- HTTP security headers (CSP, X-Frame-Options, etc.)
### 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`
- `mysql_spatial_contains`, `mysql_spatial_within`, `mysql_spatial_intersection`
- `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`
**Plus:** 5 enhanced JSON tools (`mysql_json_merge`, `mysql_json_diff`, etc.)
### 6 New Resources
- `mysql://events` - Event Scheduler status and scheduled events
- `mysql://sysschema` - sys schema diagnostics summary
- `mysql://locks` - InnoDB lock contention detection
- `mysql://cluster` - Group Replication/InnoDB Cluster status
- `mysql://spatial` - Spatial columns and indexes
- `mysql://docstore` - Document Store collections
### 5 New Prompts
- `mysql_setup_events` - Event Scheduler setup guide
- `mysql_sys_schema_guide` - sys schema usage and diagnostics
- `mysql_setup_spatial` - Spatial/GIS data setup guide
- `mysql_setup_cluster` - InnoDB Cluster/Group Replication guide
- `mysql_setup_docstore` - Document Store / X DevAPI guide
### 2 New Meta-Groups
- **`ai`** (77 tools) - AI/ML workloads: JSON, Document Store, spatial, statistics
- **`dba`** (103 tools) - DBA tasks: admin, monitoring, security, sysschema, roles
### Smart Shortcuts - One-Command Tool Customization
**NEW in v2.0** - Instantly customize your tool selection with intelligent presets! With 191 tools, AI IDEs hit their limits fast (typically 40-50 tools). Our **Smart Shortcuts** system lets you pick exactly what you need with a single flag.
**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 |
**Quick Examples:**
```bash
# Start with essentials (38 tools)
--tool-filter "-base,-ecosystem,+starter"
# AI/ML development (77 tools)
--tool-filter "-base,-ecosystem,+ai"
# Database administration (103 tools)
--tool-filter "-base,-ecosystem,+dba"
# Mix and match: Starter + GIS support (50 tools)
--tool-filter "-base,-ecosystem,+starter,+spatial"
```
**Why Smart Shortcuts?**
- ✅ **Instant setup** - One command, perfect toolset
- ✅ **IDE-friendly** - Stay within tool limits
- ✅ **Role-based** - Presets for developers, DBAs, data scientists
- ✅ **Composable** - Combine shortcuts with individual groups
### Interactive Python Tutorial - Jupyter Notebook
**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
- 🤖 Building AI-powered data applications
### AI-Optimized Protocol Features
**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 |
**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
- ✅ **Future-proof** - Latest MCP specification compliance
---
## 🔒 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
- `Content-Security-Policy: default-src 'none'` - Restrictive CSP
- `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
- `TokenValidator.test.ts` - 5 OAuth edge case tests
---
## ⚡ 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
---
## 🏗️ 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
---
## 🧪 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
- Schema management tests - 6 modular test files
- Performance tests - timing-based regression protection
---
## 📦 Installation & Upgrade
### Docker (Recommended)
```bash
# Latest v2.0.0
docker pull writenotenow/mysql-mcp:v2.0.0
docker pull writenotenow/mysql-mcp:latest
# Run with stdio transport
docker run -i --rm writenotenow/mysql-mcp:v2.0.0 \
--transport stdio \
--mysql mysql://user:password@host.docker.internal:3306/database
# Run with HTTP transport
docker run -p 3000:3000 writenotenow/mysql-mcp:v2.0.0 \
--transport http \
--port 3000 \
--mysql mysql://user:password@host.docker.internal:3306/database
```
### NPM Installation
```bash
git clone https://github.com/neverinfamous/mysql-mcp.git
cd mysql-mcp
git checkout v2.0.0
npm install
npm run build
node dist/cli.js --transport stdio --mysql mysql://user:pass@localhost:3306/db
```
### MCP Client Configuration
#### Claude Desktop / Cursor IDE (stdio)
```json
{
"mcpServers": {
"mysql-mcp": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"writenotenow/mysql-mcp:v2.0.0",
"--transport",
"stdio",
"--mysql",
"mysql://user:password@host.docker.internal:3306/database",
"--tool-filter",
"-base,-ecosystem,+starter"
]
}
}
}
```
#### Remote HTTP Connection
```json
{
"mcpServers": {
"mysql-mcp-remote": {
"url": "http://your-server:3000/sse"
}
}
}
```
---
## 🎯 Tool Filtering (Important!)
**With 191 tools, you MUST use tool filtering** to stay within IDE limits (typically 40-50 tools).
### Recommended Starter Configuration
```bash
--tool-filter "-base,-ecosystem,+starter"
```
This gives you **38 essential tools**: core CRUD, JSON, transactions, text search.
### 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) |
### Examples
```bash
# AI/ML Development (77 tools)
--tool-filter "-base,-ecosystem,+ai"
# Database Administration (103 tools)
--tool-filter "-base,-ecosystem,+dba"
# Starter + Spatial GIS (50 tools)
--tool-filter "-base,-ecosystem,+starter,+spatial"
# Starter + Document Store (47 tools)
--tool-filter "-base,-ecosystem,+starter,+docstore"
```
---
## 📚 Documentation
- **[Full Documentation (Wiki)](https://github.com/neverinfamous/mysql-mcp/wiki)**
- **[Changelog](https://github.com/neverinfamous/mysql-mcp/blob/master/CHANGELOG.md)**
- **[Security Policy](https://github.com/neverinfamous/mysql-mcp/blob/master/SECURITY.md)**
- **[Tool Reference](https://github.com/neverinfamous/mysql-mcp/wiki/Tool-Reference)**
- **[Tool Filtering Guide](https://github.com/neverinfamous/mysql-mcp/wiki/Tool-Filtering)**
- **[Configuration Guide](https://github.com/neverinfamous/mysql-mcp/wiki/Configuration)**
- **[OAuth Setup](https://github.com/neverinfamous/mysql-mcp/wiki/OAuth)**
- **[Python Quickstart Notebook](https://github.com/neverinfamous/mysql-mcp/blob/master/examples/notebooks/quickstart.ipynb)**
---
## 🔄 Breaking Changes
**None!** - v2.0.0 maintains full backward compatibility with v1.0.0. The major version bump reflects the significant scope of improvements rather than breaking changes.
---
## 🐛 Bug Fixes
- Fixed `ExitError` handling in CLI tests
- Fixed injection vulnerability in `mysqlsh_import_table` (field/line terminators)
- Fixed false coverage reports in spatial tests
- Fixed undefined property handling in `indexes` and `locks` resources
- Improved mock resilience across test suite
---
## 📊 Complete Feature Set
### 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** |
---
## 🙏 Acknowledgments
Thank you to the MySQL and MCP communities for your feedback and support. This release represents months of development focused on making mysql-mcp the most comprehensive, secure, and production-ready MySQL MCP server available.
---
## 🔗 Links
- **GitHub Repository:** https://github.com/neverinfamous/mysql-mcp
- **Docker Hub:** https://hub.docker.com/r/writenotenow/mysql-mcp
- **Issues:** https://github.com/neverinfamous/mysql-mcp/issues
- **Discussions:** https://github.com/neverinfamous/mysql-mcp/discussions
- **License:** MIT
---
**Want to contribute?** See our [Contributing Guidelines](https://github.com/neverinfamous/mysql-mcp/blob/master/CONTRIBUTING.md)
**Found a security issue?** See our [Security Policy](https://github.com/neverinfamous/mysql-mcp/blob/master/SECURITY.md)
