@neverinfamous/mysql-mcp 2.1.0 → 2.3.0

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

@@ -0,0 +1,239 @@
+# mysql-mcp v2.2.0 Release Notes
+
+**Release Date:** February 8, 2026
+**Status:** Production/Stable
+
+---
+
+## 🎉 Release Highlights
+
+**mysql-mcp v2.2.0** is a comprehensive stabilization and hardening release. Every tool group now implements the **P154 Object Existence Verification** pattern, returning structured `{ exists: false }` responses instead of raw MySQL errors. Combined with universal graceful error handling, payload optimization, SQL injection hardening, and 20+ new server instruction sections, this release transforms the developer and AI-agent experience.
+
+### At a Glance
+
+- **~120 Bug Fixes** — P154 existence checks across all 23+ tool groups, graceful error handling, payload reductions, response consistency
+- **~55 Behavioral Changes** — Default limits, payload optimization (P137), tool group migration, Node.js 24 LTS baseline
+- **~20 New Features** — Summary modes, new tool (`mysql_fulltext_drop`), new parameters, comprehensive ServerInstructions
+- **6 Security Items** — CVE fixes (hono), SQL injection hardening (5 categories), dependency cleanup
+- **8 Dependency Bumps** — MCP SDK 1.26.0, mysql2, zod, vitest, and more
+
+---
+
+## 🔒 Security
+
+### SQL Injection Hardening
+
+- **Role Tools** — Added `validateIdentifier()` for role names and `validateMySQLUserHost()` for user/host values across all 5 role tool handlers
+- **Privilege Allowlist** — Added `validateMySQLPrivilege()` with 30+ valid MySQL privilege keywords for GRANT statement validation
+- **Subquery Detection** — Blocked `(SELECT ...` pattern in WHERE clauses to prevent data exfiltration
+- **Isolation Level Allowlist** — Explicit allowlist validation for transaction isolation levels
+- **LIKE Pattern Escaping** — `mysql_role_list` now escapes user-supplied LIKE patterns
+
+### CVE Fixes
+
+- **hono Multiple Vulnerabilities** — Fixed JWT algorithm confusion, XSS in ErrorBoundary, Web Cache Deception, IPv4 validation bypass, and arbitrary key read in serve static middleware
+
+### Dependency Cleanup
+
+- Removed unused `commander`, `cors`, and `@types/cors` to reduce attack surface
+
+---
+
+## 🐛 Bug Fixes (Highlights)
+
+### Universal P154 Existence Checks
+
+Every tool group now returns `{ exists: false, table/schema/collection }` for nonexistent objects instead of raw MySQL errors or ambiguous empty arrays:
+
+- **Core** — `mysql_describe_table`, `mysql_get_indexes`, `mysql_table_stats`, `mysql_index_recommendation`, `mysql_create_index`, `mysql_force_index`
+- **Schema** — `mysql_list_views`, `mysql_list_triggers`, `mysql_list_events`, `mysql_list_stored_procedures`, `mysql_list_functions`, `mysql_list_constraints`
+- **Text** — All 6 text tools
+- **Fulltext** — All 5 fulltext tools
+- **JSON** — All 15 table-querying JSON tools
+- **Stats** — All 8 stats tools
+- **Spatial** — All 12 spatial tools
+- **Admin** — `mysql_flush_tables`, `mysql_index_usage`, `mysql_import_data`, `mysql_export_table`
+- **Performance** — `mysql_explain`, `mysql_explain_analyze`, `mysql_optimizer_trace`
+- **Events** — `mysql_event_status`, `mysql_event_list`
+- **Roles** — `mysql_user_roles`, `mysql_role_grants`
+- **Security** — `mysql_security_user_privileges`, `mysql_security_sensitive_tables`
+- **Document Store** — `mysql_doc_collection_info`, `mysql_doc_find`, `mysql_doc_list_collections`
+- **Sys Schema** — `mysql_sys_schema_stats`
+- **Partitioning** — `mysql_partition_info`, `mysql_binlog_events`
+- **Shell** — All 8 shell tools
+- **Cluster** — `mysql_cluster_instances`, `mysql_cluster_topology`
+- **ProxySQL** — Credential redaction for `password`/`credentials` variables
+- **Router** — All 9 router tools return `{ available: false, reason }` for unreachable API
+
+### Graceful Error Handling
+
+Create/drop operations now return structured `{ success: false, reason }` instead of raw errors:
+
+- `mysql_create_table`, `mysql_drop_table`, `mysql_create_schema`, `mysql_drop_schema`
+- `mysql_create_index`, `mysql_create_view`, `mysql_role_create`, `mysql_role_drop`
+- `mysql_event_create`, `mysql_event_alter`, `mysql_event_drop`
+- `mysql_doc_create_collection`, `mysql_doc_drop_collection`
+- All transaction tools (commit, rollback, savepoints)
+
+### Informative No-Op Messaging
+
+When `ifExists`/`ifNotExists` flag prevents an action, tools now return `{ skipped: true, reason }` instead of ambiguous `{ success: true }`:
+
+- `mysql_create_schema` / `mysql_drop_schema`
+- `mysql_create_table` (new) / `mysql_drop_table` (new)
+- `mysql_role_create` / `mysql_role_drop`
+- `mysql_event_drop`, `mysql_doc_drop_collection`
+
+### Notable Individual Fixes
+
+- **`mysql_create_index` FULLTEXT/SPATIAL SQL** — Fixed invalid `USING FULLTEXT` syntax; now uses correct `CREATE FULLTEXT INDEX` prefix
+- **Spatial GeoJSON axis order** — Fixed coordinate conversion for SRID 4326 across 7 spatial tools
+- **JSON auto-quoting** — Bare strings like `"green"` now auto-wrapped as valid JSON
+- **`mysql_export_table` datetime** — Fixed extra JSON-style quotes wrapping datetime values
+- **`mysql_transaction_execute` SELECT data** — Fixed missing row data for SELECT statements in atomic transactions
+- **`mysql_stats_distribution` bucket boundaries** — Fixed string concatenation instead of arithmetic
+- **`mysql_sys_io_summary` file type** — Fixed wrong column name (`total_write` → `total_written`)
+
+---
+
+## ✨ New Features
+
+### New Tool
+
+- **`mysql_fulltext_drop`** — Drop FULLTEXT indexes, providing symmetry with `mysql_fulltext_create`
+
+### Summary Modes
+
+Reduce payload size dramatically for status/diagnostic tools:
+
+| Tool                          | Full → Summary       |
+| ----------------------------- | -------------------- |
+| `mysql_cluster_status`        | ~21KB → ~500B        |
+| `mysql_cluster_router_status` | ~12KB → ~300B/router |
+| `mysql_innodb_status`         | ~5KB → ~200B         |
+| `mysql_optimizer_trace`       | ~10KB → ~500B        |
+| `proxysql_status`             | ~4KB → ~500B         |
+| `proxysql_runtime_status`     | ~3KB → ~300B         |
+
+### New Parameters
+
+- **`mysql_export_table`** — `limit` parameter to cap exported rows
+- **`mysql_index_usage`** — `limit` parameter (default: 20 → 10)
+- **`proxysql_global_variables`** — `limit` and `like` filter parameters
+- **`mysql_spatial_buffer`** — `segments` parameter for buffer polygon approximation
+- **Text tools** — `where` parameter on `mysql_regexp_match`, `mysql_like_search`, `mysql_soundex`
+- **Fulltext tools** — `maxLength` parameter to truncate large TEXT values
+- **`mysql_concat`** — `includeSourceColumns` option for minimal payload
+- **`mysql_security_user_privileges`** — `summary` mode for condensed privilege info
+
+### Comprehensive Server Instructions
+
+Added 15+ new documentation sections to `ServerInstructions.ts`:
+
+Core, Transaction, Admin, Performance, Optimization, Monitoring, Replication, Schema, Events, Sys Schema, Stats, Security, ProxySQL, InnoDB Cluster, Shell, Fulltext, Text, Backup, Partitioning, Role Management, Document Store
+
+---
+
+## 📊 Payload Optimization
+
+### Default Limits
+
+| Tool                        | Before     | After    |
+| --------------------------- | ---------- | -------- |
+| `mysql_export_table`        | Unbounded  | 100 rows |
+| `mysql_show_status`         | ~517 rows  | 100      |
+| `mysql_show_variables`      | ~600 rows  | 100      |
+| `mysql_binlog_events`       | 100 events | 20       |
+| `mysql_query_stats`         | 20         | 10       |
+| `mysql_index_usage`         | 50 → 20    | 10       |
+| `mysql_sys_schema_stats`    | 50 → 20    | 10       |
+| `mysql_sys_memory_summary`  | 20         | 10       |
+| `proxysql_global_variables` | 200        | 50       |
+
+### Minimal Payload (P137)
+
+- **Fulltext tools** — Return only `id`, searched column(s), and `relevance`
+- **Text tools** — Return only `id`, target column(s), and computed result
+- **`mysql_json_contains`/`mysql_json_search`** — Return only relevant columns instead of `SELECT *`
+- **`mysql_slow_queries`/`mysql_query_stats`** — Digest text truncated to 200 chars
+
+---
+
+## ⚙️ Changed
+
+### Infrastructure
+
+- **Node.js 24 LTS Baseline** — Upgraded from Node 20 across Dockerfile, CI, and `package.json`
+- **Docker Workflow** — Docker publishing now depends on both `quality-gate` and `codeql` jobs
+- **Dependabot Grouping** — Added groups for vitest, eslint, and types
+- **`cluster` tool group** — Migrated from `dba-secure` to `ecosystem` shortcut (42 → 32 / 31 → 41 tools)
+
+### Response Improvements
+
+- **`mysql_replication_status` / `mysql_slave_status`** — Return `{ configured: false }` instead of empty object
+- **Cluster payload reduction** — `Configuration` blobs stripped from `mysql_cluster_status` and `mysql_cluster_router_status` full mode
+- **`mysql_json_diff`** — Enhanced with value-level comparison (`addedKeys`, `removedKeys`, `differences`)
+- **`mysql_json_insert`** — Returns `{ changed: true/false }` indicator
+- **`mysql_create_table`** — Boolean defaults auto-converted (`true` → `1`, `false` → `0`)
+
+---
+
+## 📦 Dependencies
+
+- `@modelcontextprotocol/sdk` `^1.25.2` → `^1.26.0`
+- `@types/node` `^25.0.8` → `^25.2.2`
+- `@vitest/coverage-v8` `^4.0.17` → `^4.0.18`
+- `globals` `^17.0.0` → `^17.3.0`
+- `mysql2` `^3.16.0` → `^3.16.3`
+- `typescript-eslint` `^8.53.0` → `^8.54.0`
+- `vitest` `^4.0.17` → `^4.0.18`
+- `zod` `^4.3.5` → `^4.3.6`
+
+---
+
+## 📦 Installation & Upgrade
+
+### Docker (Recommended)
+
+```bash
+# Latest v2.2.0
+docker pull writenotenow/mysql-mcp:v2.2.0
+docker pull writenotenow/mysql-mcp:latest
+
+# Run with stdio transport
+docker run -i --rm writenotenow/mysql-mcp:v2.2.0 \
+  --transport stdio \
+  --mysql mysql://user:password@host.docker.internal:3306/database
+```
+
+### NPM
+
+```bash
+npm install -g @neverinfamous/mysql-mcp@2.2.0
+```
+
+### From Source
+
+```bash
+git clone https://github.com/neverinfamous/mysql-mcp.git
+cd mysql-mcp
+git checkout v2.2.0
+npm install
+npm run build
+node dist/cli.js --transport stdio --mysql mysql://user:pass@localhost:3306/db
+```
+
+---
+
+## 🔗 Links
+
+- **GitHub Repository:** https://github.com/neverinfamous/mysql-mcp
+- **Docker Hub:** https://hub.docker.com/r/writenotenow/mysql-mcp
+- **NPM Package:** https://www.npmjs.com/package/@neverinfamous/mysql-mcp
+- **Changelog:** https://github.com/neverinfamous/mysql-mcp/blob/master/CHANGELOG.md
+- **Issues:** https://github.com/neverinfamous/mysql-mcp/issues
+- **License:** MIT
+
+---
+
+**Full Changelog:** [v2.1.0...v2.2.0](https://github.com/neverinfamous/mysql-mcp/compare/v2.1.0...v2.2.0)

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

@@ -0,0 +1,191 @@
+# mysql-mcp v2.3.0 Release Notes
+
+**Release Date:** February 18, 2026
+**Status:** Production/Stable
+
+---
+
+## 🎉 Release Highlights
+
+**mysql-mcp v2.3.0** introduces **Code Mode** — a sandboxed JavaScript/TypeScript execution environment that lets AI agents compose multi-step MySQL workflows in a single tool call, reducing token usage by 70–90%. This release also adds **Parameter Aliases** (Split Schema) for more natural tool inputs, a configurable `--server-host` CLI option, and delivers **55+ bug fixes** across nearly every tool group — including many fixes to tools that existed before Code Mode.
+
+### At a Glance
+
+- **1 Major Feature** — Code Mode (`mysql_execute_code`): 22 API groups, 168+ methods, VM-based sandboxed execution
+- **3 New Capabilities** — Parameter Aliases (Split Schema), `--server-host` CLI option, Stale Router Detection
+- **~55 Bug Fixes** — Code mode group registrations, tool help examples, text tool schema violations, event SQL ordering, timer overflows, spatial precision, error handling improvements
+- **3 Security Items** — CodeQL temp file hardening, `ajv` ReDoS CVE, `qs` DoS CVE
+- **5 Dependency Bumps** — eslint 10.x, mysql2, @types/node, typescript-eslint
+
+---
+
+## ⚡ Code Mode (`mysql_execute_code`)
+
+The headline feature of v2.3.0. Code Mode provides a sandboxed `mysql.*` API namespace enabling AI agents to execute multi-step database workflows as JavaScript/TypeScript code in a single tool call.
+
+### Key Capabilities
+
+| Feature | Details |
+|---|---|
+| **22 API Groups** | `mysql.core`, `mysql.json`, `mysql.transactions`, `mysql.spatial`, `mysql.stats`, `mysql.security`, `mysql.cluster`, `mysql.router`, and 14 more |
+| **168+ Methods** | Full coverage of all mysql-mcp tools |
+| **VM Isolation** | Sandboxed execution with security validation and rate limiting |
+| **Auto-Cleanup** | Automatic transaction rollback on completion — no dangling locks |
+| **Help System** | `mysql.help()` and `mysql.{group}.help()` for introspection |
+| **Token Savings** | 70–90% reduction vs. individual tool calls for multi-step operations |
+
+### API Groups
+
+`core` · `json` · `text` · `fulltext` · `performance` · `optimization` · `admin` · `monitoring` · `backup` · `replication` · `partitioning` · `schema` · `shell` · `events` · `sysschema` · `stats` · `spatial` · `security` · `roles` · `docstore` · `cluster` · `router`
+
+### Auto-Injection
+
+Code Mode is automatically included in all preset shortcuts (`starter`, `essential`, `dev-power`, etc.) and is auto-injected when using raw group filters (e.g., `--tool-filter core`). Explicit exclusion via `-codemode` is respected.
+
+---
+
+## 🆕 Parameter Aliases (Split Schema)
+
+Tools now accept alternative parameter names for commonly used fields, normalized automatically via Zod schema preprocessing:
+
+| Alias | Canonical | Applies To |
+|---|---|---|
+| `table` / `tableName` / `name` | table parameter | Core, Text, Backup, Partitioning, Performance, Admin |
+| `query` / `sql` | query parameter | `mysql_read_query`, `mysql_write_query`, `mysql_explain`, `mysql_explain_analyze`, `mysql_query_rewrite`, `mysql_optimizer_trace` |
+| `where` / `filter` | WHERE clause | `mysql_export_table` and all Text tools |
+| `column` / `col` | column parameter | Text tools |
+
+Schema definitions use a **Dual-Schema pattern**: `SchemaBase` (with aliases visible to MCP clients) for `inputSchema`, and the runtime `Schema` (with preprocessing + transformation) for handler validation.
+
+---
+
+## 🔒 Security
+
+### CVE Fixes
+
+- **`ajv` ReDoS via `$data` Option (GHSA-2g4f-4pwh-qvx6)** — Overrode transitive `ajv` from 8.17.1 to 8.18.0 to fix ReDoS vulnerability in runtime regex patterns
+- **`qs` ArrayLimit Bypass (GHSA-w7fw-mjwx-w883)** — Updated transitive `qs` from 6.14.1 to 6.14.2 to fix DoS via comma parsing bypass
+
+### CodeQL Remediation
+
+- **`mysqlsh_run_script` Secure Temporary File Handling** — Replaced insecure `os.tmpdir()` with `fs.mkdtemp()` for SQL script temp files, eliminating predictable file paths flagged by CodeQL
+
+---
+
+## 🐛 Bug Fixes (Highlights)
+
+### Code Mode Group Registration Fixes
+
+Five tool groups were completely inaccessible in Code Mode due to prefix-stripping misconfigurations. All returned `TypeError: ... is not a function`:
+
+| Group | Tools Affected | Root Cause |
+|---|---|---|
+| **Security** | 9 tools | `security` in `keepPrefix` set |
+| **Stats** | 8 tools | `stats` in `keepPrefix` set |
+| **Spatial** | 12 tools | `spatial` in `keepPrefix` set |
+| **Router** | 9 tools | `router` in `keepPrefix` set |
+| **Shell** | 10 tools | Missing `groupPrefixMap` entry |
+
+### Code Mode Help Example Fixes
+
+Corrected inaccurate parameter names and method references in `help()` output for: `backup`, `optimization`, `security`, `stats`, `spatial`, `json`, `sysschema`, `cluster`, `replication`, `router`, and `shell` groups.
+
+### Non-Code-Mode Bug Fixes
+
+These fixes affect tools that existed in v2.2.0:
+
+- **`mysql_event_alter` Clause Ordering** — Generated invalid SQL when combining `newName` with other clauses. Reordered to match MySQL's required syntax
+- **`mysql_explain` TRADITIONAL Format** — Returned TREE format when TRADITIONAL was requested. Now explicitly uses `EXPLAIN FORMAT=TRADITIONAL`
+- **Text Tool Schema Violations** — `mysql_substring`, `mysql_concat`, `mysql_collation_convert` lacked parameter alias support. Replaced with proper Dual-Schema definitions
+- **Timer Overflow Detection** — `mysql_slow_queries` / `mysql_query_stats` returned absurdly large values (~213 days) due to unsigned 64-bit picosecond counter wrapping. Now clamped to `-1` with `overflow: true`
+- **Timer Value Type Consistency** — Non-overflowed timer values returned as strings instead of numbers. Now consistently numbers
+- **`mysql_security_mask_data`** — Three fixes: credit card 8-digit boundary masking, warning message accuracy, partial masking silent no-op detection
+- **`mysql_spatial_create_index`** — Duplicate index error consistency and duplicate column index detection
+- **`mysql_spatial_buffer` Precision** — Added `precision` parameter (default: 6) to control GeoJSON decimal places, significantly reducing payload size for geographic buffers
+- **`mysql_json_update` Missing Reason** — Now returns `{ success: false, reason }` when target row doesn't exist
+- **`mysql_json_validate` Auto-Conversion** — Removed auto-conversion that made it impossible to return `valid: false`
+- **`mysql_read_query` / `mysql_write_query`** — Uniform structured error handling (`{ success: false, error }`) for all query errors
+- **`mysql_buffer_pool_stats` Payload Reduction** — Curated 23 operationally meaningful columns instead of all 32
+- **`mysql_query_rewrite` / `mysql_optimizer_trace`** — Missing `sql` alias for `query` parameter
+- **`mysql_explain_analyze`** — Missing `sql` alias for `query` parameter
+- **`mysql_transaction_execute`** — Empty statements now return structured error instead of Zod validation error
+- **`mysql_event_create`** — Informative existing event messaging with `{ skipped: true, reason }`
+- **`mysql_sys_memory_summary` / `mysql_sys_schema_stats`** — Added missing count fields for response consistency
+- **Partitioning Write Tools** — `mysql_add_partition`, `mysql_drop_partition`, `mysql_reorganize_partition` now perform P154 existence checks
+- **`mysql_router_pool_status`** — Enabled Router connection pool REST API infrastructure
+- **`mysqlsh_export_table`** — Shell dump-specific error extraction instead of generic privilege-hint message
+- **`mysqlsh_load_dump`** — Dry run now captures and returns `dryRunOutput` field
+- **Code Mode Auto-Rollback** — Fixed orphaned transaction cleanup to run unconditionally, not just on failure
+- **Code Mode Negative Memory Metric** — Clamped to `Math.max(0, ...)` when GC reclaims heap between snapshots
+
+---
+
+## ✨ New Features
+
+### `mysql_cluster_router_status` Stale Router Detection
+
+Router responses now include `isStale` boolean per router (true when `lastCheckIn` is null or >1 hour old) and a top-level `staleCount` field, making stale/abandoned router entries immediately identifiable.
+
+### `--server-host` CLI Option / `MCP_HOST` Environment Variable
+
+Configurable host binding for HTTP/SSE transport. Defaults to `localhost`. Set to `0.0.0.0` for containerized deployments.
+
+---
+
+## 📦 Dependencies
+
+- `@eslint/js` `^9.39.2` → `^10.0.1`
+- `@types/node` `^25.2.2` → `^25.2.3`
+- `eslint` `^9.39.2` → `^10.0.0`
+- `mysql2` `^3.16.3` → `^3.17.2`
+- `typescript-eslint` `^8.54.0` → `^8.56.0`
+
+---
+
+## 📦 Installation & Upgrade
+
+### Docker (Recommended)
+
+```bash
+# Latest v2.3.0
+docker pull writenotenow/mysql-mcp:v2.3.0
+docker pull writenotenow/mysql-mcp:latest
+
+# Run with stdio transport
+docker run -i --rm writenotenow/mysql-mcp:v2.3.0 \
+  --transport stdio \
+  --mysql mysql://user:password@host.docker.internal:3306/database
+```
+
+### NPM
+
+```bash
+npm install -g @neverinfamous/mysql-mcp@2.3.0
+```
+
+### From Source
+
+```bash
+git clone https://github.com/neverinfamous/mysql-mcp.git
+cd mysql-mcp
+git checkout v2.3.0
+npm install
+npm run build
+node dist/cli.js --transport stdio --mysql mysql://user:pass@localhost:3306/db
+```
+
+---
+
+## 🔗 Links
+
+- **GitHub Repository:** https://github.com/neverinfamous/mysql-mcp
+- **Docker Hub:** https://hub.docker.com/r/writenotenow/mysql-mcp
+- **NPM Package:** https://www.npmjs.com/package/@neverinfamous/mysql-mcp
+- **Changelog:** https://github.com/neverinfamous/mysql-mcp/blob/master/CHANGELOG.md
+- **Wiki:** https://github.com/neverinfamous/mysql-mcp/wiki
+- **Issues:** https://github.com/neverinfamous/mysql-mcp/issues
+- **License:** MIT
+
+---
+
+**Full Changelog:** [v2.2.0...v2.3.0](https://github.com/neverinfamous/mysql-mcp/compare/v2.2.0...v2.3.0)

package/server.json

@@ -30,4 +30,4 @@
     "source": "github"
   },
   "license": "MIT"
-}
+}