@neverinfamous/mysql-mcp 2.2.0 → 2.3.0

package/.github/workflows/docker-publish.yml

@@ -2,7 +2,6 @@ name: Build and Push Docker Images
 
 on:
   push:
-    branches: [master]
     tags: ["v*"]
   pull_request:
     branches: [master]
@@ -311,7 +310,7 @@ jobs:
           password: ${{ secrets.DOCKER_PASSWORD }}
           repository: ${{ env.IMAGE_NAME }}
           readme-filepath: ./DOCKER_README.md
-          short-description: "MySQL MCP with 191 tools, OAuth 2.1, HTTP Streamable, Smart Tool Filtering & Connection Pooling."
+          short-description: "MySQL MCP Server: 193 tools, Code Mode, Tool Filtering, Connection Pooling, HTTP/SSE & OAuth 2.1"
 
       - name: Deployment Summary
         if: github.ref == 'refs/heads/master'

package/CHANGELOG.md

@@ -7,6 +7,89 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [2.3.0] - 2026-02-18
+
+### Fixed
+
+- **`mysql://capabilities` Feature Flags on MySQL 9.x+** — `json` and `gtid` feature flags incorrectly reported `false` on MySQL 9.6.0 because detection used `startsWith("8.")` prefix matching, which doesn't match version strings like `"9.6.0"`. Replaced with `parseInt`-based major version comparison (`>= 8`) that handles 9.x, 10.x, and all future versions while preserving legacy 5.6/5.7 fallbacks.
+
+- **README / DOCKER_README Documentation Audit** — Corrected multiple stale numerical claims across both READMEs: meta-group/shortcut count (7→11), ecosystem Option 3 tool count (41→42), cluster Option 2 tool count (10→11, reflects codemode auto-injection), test badge (1794→1833), coverage badge (94%→86%), test runtime (~62s→~80s), and branch coverage (~81%→~72%). Also fixed stale JSDoc comments in `prompts/index.ts` (14→19 total) and `resources/index.ts` (12→18 total) to match actual function return counts.
+
+- **`mysqlsh_export_table` / Shell Dump Specific Error Extraction** — When `util.exportTable()` or other dump utilities fail with "Fatal error during dump", the error message now extracts specific MySQL `ERROR:` lines from stderr (e.g., `"Unknown column 'x' in 'where clause'"`) instead of returning the generic privilege-hint message. The generic message is retained as a fallback only when no specific `ERROR:` lines are found in stderr.
+- **Code Mode Backup `help()` Examples** — `mysql.backup.help()` examples contained two inaccuracies: `importData` used `filePath` (a string path) instead of `data` (an array of row objects), and `restoreDump` used `filePath` instead of `filename`. Also fixed `POSITIONAL_PARAM_MAP` entry for `restoreDump` (`filePath` → `filename`).
+- **Code Mode Security `passwordValidate` Positional Shorthand** — `mysql.security.passwordValidate("weak")` failed with a ZodError because `passwordValidate` was missing from `POSITIONAL_PARAM_MAP`. The string argument fell through to the generic fallback (`{ sql, query, table, name }`), leaving `password` undefined. Added `passwordValidate: "password"` entry so single-string positional calls work correctly.
+- **Code Mode Optimization `help()` Examples** — `mysql.optimization.help()` examples contained three inaccuracies: `indexRecommendation` used `sql` instead of `table`, `indexUsage` was listed (belongs to performance group, not optimization), and `forceIndex` used `sql`/`index` instead of `query`/`indexName`. Also removed broken `usage: "indexUsage"` alias from `METHOD_ALIASES.optimization` — `indexUsage` is a performance method, so this alias could not resolve.
+- **Code Mode Security `help()` Alias Misclassification** — `mysql.security.help()` listed `audit` and `firewallRules` as aliases-only instead of primary methods (7 methods + 9 aliases instead of 9 + 7). Caused by self-referential entries in `METHOD_ALIASES.security` (`audit: "audit"`, `firewallRules: "firewallRules"`) — `createSandboxBindings` excludes alias keys from the canonical methods list, so matching names were filtered out. Fix: removed both self-referential entries.
+- **Text Tool Split Schema Violations (`mysql_substring`, `mysql_concat`, `mysql_collation_convert`)** — All three tools used inline Zod schemas without parameter alias support, causing `tableName`/`name` aliases for `table` and the `filter` alias for `where` to be silently ignored. Replaced inline schemas with proper Dual-Schema definitions (`SubstringSchemaBase`/`SubstringSchema`, `ConcatSchemaBase`/`ConcatSchema`, `CollationConvertSchemaBase`/`CollationConvertSchema`) in `types.ts`, matching the pattern used by `mysql_regexp_match`, `mysql_like_search`, and `mysql_soundex`. `mysql_collation_convert` also gained `col` alias support for `column`.
+- **`mysql_security_mask_data` Credit Card Warning Accuracy** — Warning message for short credit card values said "expected at least 8 digits" but the guard (`<= 8`) correctly fully-masks 8-digit values since showing first 4 + last 4 would expose all digits with zero masking. Updated warning to "expected more than 8 digits" to match actual behavior.
+- **`ServerInstructions.ts` Credit Card Masking Threshold Wording** — Documentation said "requires at least 8 digits" but the guard (`<= 8`) fully-masks values with 8 or fewer digits. Updated to "requires more than 8 digits; values with 8 or fewer digits are fully masked" to match actual behavior.
+- **`mysql_security_mask_data` Partial Masking Silent No-Op** — Partial masking silently returned the original value unchanged when `keepFirst + keepLast >= value.length`, with no indication that masking was ineffective. Now returns a `warning` field ("Masking ineffective: keepFirst + keepLast covers entire value length; returned unchanged"), matching the warning pattern used by credit card short-value masking.
+- **Code Mode Security Group Registration** — All 9 security tools (`sslStatus`, `encryptionStatus`, `userPrivileges`, `sensitiveTables`, `audit`, `firewallStatus`, `firewallRules`, `maskData`, `passwordValidate`) were inaccessible in code mode, returning `TypeError: ... is not a function`. Root cause: `security` was in the `keepPrefix` set in `toolNameToMethodName`, so `mysql_security_ssl_status` → `securitySslStatus`. But `METHOD_ALIASES.security` and `GROUP_EXAMPLES.security` used stripped names (`sslStatus`, `audit`, etc.), causing all alias registrations and help examples to fail. Fix: removed `security` from `keepPrefix` so tools resolve directly to short names.
+- **`mysql_security_mask_data` Credit Card 8-Digit Masking** — Credit card masking returned all 8 digits unmasked when the input contained exactly 8 digits. The guard `ccDigits.length < 8` missed the boundary case where `slice(0, 4)` + `slice(-4)` = all 8 digits with zero mask characters in between. Changed to `ccDigits.length <= 8` so 8-digit values are fully masked with a warning, consistent with shorter inputs.
+- **Code Mode Stats Group Registration** — All 8 stats tools (`descriptive`, `percentiles`, `correlation`, `distribution`, `timeSeries`, `regression`, `sampling`, `histogram`) were inaccessible in code mode, returning `TypeError: ... is not a function`. Root cause: `stats` was in the `keepPrefix` set in `toolNameToMethodName`, so `mysql_stats_descriptive` → `statsDescriptive`. But `METHOD_ALIASES.stats` listed every `statsXxx` name as an alias key pointing to the short form (`descriptive`), which never existed as a canonical method. This caused `createGroupApi` to skip all alias registrations and `createSandboxBindings` to filter all methods out of `canonicalMethodNames`. Fix: removed `stats` from `keepPrefix` so tools resolve directly to short names (`descriptive`, `percentiles`, etc.), and removed the 8 now-redundant `statsXxx` prefix aliases.
+- **Code Mode Stats `help()` Examples** — `mysql.stats.help()` examples contained two inaccuracies: `percentiles` example used fractional values (`[0.5, 0.95, 0.99]`) instead of the expected integer percentiles (`[50, 95, 99]`), and `timeSeries` example used `interval: '1 HOUR'` instead of the valid enum value `interval: 'hour'`.
+- **Code Mode Spatial `help()` Examples** — `mysql.spatial.help()` examples used incorrect parameter names: `distance`/`distanceSphere` used `column` instead of `spatialColumn` and `{ x, y }` / `{ lat, lng }` instead of `{ longitude, latitude }` for the `point` object; `point` used `{ x, y }` instead of `{ longitude, latitude }`; `buffer` used `{ table, column }` instead of `{ geometry, distance }`. Also fixed `POSITIONAL_PARAM_MAP` entries for `distance`/`distanceSphere` (`column` → `spatialColumn`) and `point` (`x`/`y` → `longitude`/`latitude`).
+- **Code Mode Spatial Group Registration** — All 12 spatial tools (`createColumn`, `createIndex`, `distance`, `distanceSphere`, `point`, `polygon`, `contains`, `within`, `intersection`, `buffer`, `transform`, `geojson`) were inaccessible in code mode, returning `TypeError: ... is not a function`. Root cause: `spatial` was in the `keepPrefix` set in `toolNameToMethodName`, so `mysql_spatial_distance` → `spatialDistance`. But `METHOD_ALIASES.spatial`, `GROUP_EXAMPLES.spatial`, and `POSITIONAL_PARAM_MAP` all used stripped names (`distance`, `point`, etc.), causing all alias registrations and method lookups to fail. Fix: removed `spatial` from `keepPrefix` so tools resolve directly to short names. Also removed the redundant `geojson` → `geojson` self-alias.
+- **`mysql_spatial_create_index` Duplicate Index Error Consistency** — Tool returned `{ success: false, error: "Query failed: Execute failed: Duplicate key name '...'" }` for duplicate indexes — a raw MySQL error in the generic `error` field. Now returns `{ success: false, reason: "Index '...' already exists on table '...'" }` with a user-friendly message, consistent with `mysql_spatial_create_column` (duplicate column) and `mysql_fulltext_create` (duplicate index) error handling.
+- **Code Mode JSON `help()` Examples** — `mysql.json.help()` examples contained inaccuracies: `contains` example used `candidate` instead of `value`, and `merge` example used `base`/`overlay` with raw objects instead of `json1`/`json2` with JSON strings. Also fixed `POSITIONAL_PARAM_MAP` entries: `contains` (`candidate` → `value`), `merge` (`base`/`overlay` → `json1`/`json2`), and `diff` (`doc1`/`doc2` → `json1`/`json2`).
+- **`mysql_spatial_create_index` Duplicate Column Index Detection** — Tool allowed creating a second spatial index on a column that already had one (e.g., creating `idx_spatial_test_locations_geom` alongside the seeded `idx_locations_geom` on the same `geom` column). Now pre-checks `information_schema.STATISTICS` for existing `SPATIAL` indexes on the target column before attempting creation. Returns `{ success: false, reason: "Spatial index '...' already exists on column '...' of table '...'" }` when a duplicate is found.
+- **`mysql_spatial_buffer` Large GeoJSON Payload with Geographic SRIDs** — Buffering with SRID 4326 produced coordinates with 14+ decimal places (e.g., `-122.41939999999998`), causing unnecessarily large GeoJSON payloads. Added `precision` parameter (default: 6, ~0.11m accuracy) that controls `ST_AsGeoJSON` decimal digit truncation. Lower values (e.g., 2) significantly reduce payload size for geographic buffers where the `segments` parameter is ineffective.
+
+- **Code Mode `sysSchemaStats` Help Example** — `mysql.sysschema.help()` listed `sysSchemaStats({ table: 'users' })` as an example, but the tool accepts `schema`, not `table`. Updated to `sysSchemaStats({ schema: 'testdb' })`.
+- **`mysql_sys_memory_summary` Response Consistency** — Tool response lacked count fields, unlike other sysschema tools (e.g., `mysql_sys_innodb_lock_waits` which includes `count`). Added `globalMemoryCount` and `memoryByUserCount` to the response for response shape consistency across the sysschema group.
+- **`mysql_sys_schema_stats` Response Consistency** — Tool response lacked per-array count fields, unlike `mysql_sys_memory_summary` (which includes `globalMemoryCount` and `memoryByUserCount`). Added `tableStatisticsCount`, `indexStatisticsCount`, and `autoIncrementStatusCount` to the response. Also updated `ServerInstructions.ts` to document the count fields for both `mysql_sys_schema_stats` and `mysql_sys_memory_summary`.
+
+- **`mysql_event_alter` Clause Ordering** — Tool generated invalid SQL when combining `newName` with other clauses (`comment`, `enabled`, `body`). The handler emitted clauses as `ENABLE/DISABLE → COMMENT → RENAME TO → DO`, but MySQL's `ALTER EVENT` syntax requires `RENAME TO → ENABLE/DISABLE → COMMENT → DO`. Reordered all clause generation to match the MySQL-required syntax order: `ON SCHEDULE → ON COMPLETION → RENAME TO → ENABLE/DISABLE → COMMENT → DO`.
+- **`mysql_event_create` Informative Existing Event Messaging** — When `ifNotExists: true` (default), the tool now pre-checks event existence and returns `{ success: true, skipped: true, reason: "Event already exists", eventName }` when the event was already present, instead of a plain `{ success: true, eventName }` indistinguishable from an actual creation. Matches the informative messaging pattern established by `mysql_event_drop`, `mysql_drop_table`, and `mysql_create_schema`.
+- **Code Mode Shell Tool Naming Inconsistency** — Shell tool methods in code mode used unprefixed-stripping names (e.g., `mysql.shell.mysqlshVersion()`, `mysql.shell.mysqlshRunScript()`) instead of following the prefix-stripping convention used by all other groups. Added `shell: "mysqlsh_"` to `groupPrefixMap` in `api.ts`, so `mysqlsh_version` → `mysql.shell.version()`, `mysqlsh_run_script` → `mysql.shell.runScript()`, etc. Also added shell `METHOD_ALIASES`, `GROUP_EXAMPLES`, and `POSITIONAL_PARAM_MAP` entries.
+- **`mysqlsh_check_upgrade` ServerInstructions Clarification** — Documentation incorrectly stated the tool fails only when `targetVersion` is lower than the server version. Clarified that it also fails when MySQL Shell's version is lower than the server version (Shell cannot analyze a server newer than itself).
+- **`mysqlsh_load_dump` Dry Run Output** — `dryRun: true` previously returned only an opaque `result` field. Now uses `execMySQLShell` directly to capture stderr containing the dry run summary, returning it as a `dryRunOutput` field so the caller can see what schemas/tables would be loaded.
+- **Partitioning Write Tools Missing P154 Existence Check** — `mysql_add_partition`, `mysql_drop_partition`, and `mysql_reorganize_partition` returned raw MySQL errors for nonexistent tables instead of the `{ exists: false, table }` pattern used by `mysql_partition_info` and all other tools. All three write tools now perform an `information_schema.TABLES` pre-check before executing ALTER TABLE.
+
+- **`mysql_router_pool_status` Infrastructure & Documentation** — Enabled Router connection pool REST API by adding `[rest_connection_pool]` plugin and `connection_sharing=1` to the Router bootstrap config. Updated `routerSetup.ts` prompt to document the plugin. Corrected `ServerInstructions.ts` — clarified that `pool_status` requires both the REST plugin and `connection_sharing=1` on routes, and the pool name is `main`.
+- **Code Mode Router Alias Inconsistency** — `mysql.router` had intermediate aliases for `routeStatus` and `routeHealth` but not for the other route-specific tools. Added `routeConnections`, `routeDestinations`, and `routeBlockedHosts` as intermediate aliases mapping to `routerRouteConnections`, `routerRouteDestinations`, and `routerRouteBlockedHosts` respectively.
+- **Code Mode Router Group Registration** — All 9 router tools were registered with redundant `router` prefix in code mode (e.g., `routerStatus`, `routerMetadataStatus`), requiring users to call `mysql.router.routerStatus()` instead of the intuitive `mysql.router.status()`. Root cause: `router` was in the `keepPrefix` set in `toolNameToMethodName`, so `mysql_router_status` → `routerStatus`. But `GROUP_EXAMPLES.router` and `METHOD_ALIASES.router` referenced the prefixed names, making `help()` output show `routerStatus()`, `routerRoutes()`, etc. Fix: removed `router` from `keepPrefix` so tools resolve to short names (`status`, `routes`, `metadataStatus`, etc.), updated aliases to point to new canonical names, and removed 7 now-redundant self-aliases.
+- **Code Mode Replication `help()` Examples** — `mysql.replication.help()` listed `replicationStatus()` and `replicationLag()` as examples, neither of which exist as methods (causing `TypeError` when called). Updated examples to use the correct method names: `slaveStatus()` and `lag()`. Also removed the broken `lag → replicationLag` alias (the canonical method name is already `lag`) and fixed `status` alias to point to `slaveStatus` instead of the nonexistent `replicationStatus`.
+
+- **`mysql_query_rewrite` / `mysql_optimizer_trace` Missing `sql` Alias** — Both tools did not accept the `sql` parameter alias for `query`, despite being documented in ServerInstructions. Replaced inline Zod schemas with proper Dual-Schema pattern (`schemaBase` + `schema`) using `preprocessQueryOnlyParams`, matching the pattern used by `mysql_explain` and `mysql_explain_analyze`.
+- **`mysql_slow_queries` / `mysql_query_stats` Timer Overflow Detection** — Both tools returned absurdly large `avg_time_ms` / `total_time_ms` / `max_time_ms` values (e.g., ~213 days) for certain queries due to MySQL's `performance_schema` unsigned 64-bit picosecond counter wrapping. Timer values exceeding 24 hours are now clamped to `-1` with `overflow: true` on the row, signaling that the original value was a counter overflow artifact.
+- **`mysql_slow_queries` / `mysql_query_stats` Timer Value Type Consistency** — Both tools returned non-overflowed timer values (`avg_time_ms`, `total_time_ms`, `max_time_ms`) as strings when MySQL's `performance_schema` returned DECIMAL-typed values, while overflow-clamped values were numbers (`-1`). All timer values are now consistently returned as numbers.
+- **`mysql_explain` TRADITIONAL Format Output** — Tool returned TREE format output when TRADITIONAL was requested. The handler used bare `EXPLAIN ${query}` for the TRADITIONAL case, which MySQL 8.0+ defaults to TREE format. Now explicitly uses `EXPLAIN FORMAT=TRADITIONAL ${query}` for all three formats.
+- **`mysql_explain_analyze` Missing `sql` Alias** — Tool did not accept the `sql` parameter alias for `query`, despite being documented in ServerInstructions. Replaced inline Zod schema with proper Dual-Schema pattern (`ExplainAnalyzeSchemaBase` + `ExplainAnalyzeSchema`) using `preprocessQueryOnlyParams`, matching the pattern used by `mysql_explain`.
+- **`mysql_buffer_pool_stats` Payload Reduction (P137)** — Tool returned all 32 columns from `INNODB_BUFFER_POOL_STATS` via `SELECT *`, including many zero-count rate fields. Now returns a curated subset of 23 operationally meaningful columns (pool size, free buffers, database pages, modified pages, hit rate, I/O rates, page activity).
+- **ServerInstructions Parameter Alias Accuracy** — Removed `mysql_explain` and `mysql_explain_analyze` from the table name alias list (they accept `query`/`sql`, not `table`/`tableName`/`name`).
+
+- **`mysql_json_update` Missing Reason on No-Match** — Tool returned bare `{ success: false }` without context when the target row ID did not exist. Now returns `{ success: false, reason: "No row found with <idColumn> = <id>" }` matching the descriptive error pattern used by other write tools.
+- **`mysql_json_validate` Auto-Conversion Removed** — Tool previously auto-converted all input (including malformed JSON) to bare JSON strings before calling `JSON_VALID()`, making it impossible to return `valid: false`. Removed auto-conversion — the tool now validates input as-is, correctly returning `valid: false` for malformed JSON and bare strings. Auto-conversion remains in JSON write tools (`json_set`, `json_update`, etc.) where it serves a purpose.
+- **`mysql_read_query` / `mysql_write_query` Uniform Structured Error Handling (P154)** — Both query tools now return `{ success: false, error }` for all query errors (nonexistent table, syntax errors, permission failures, etc.), instead of propagating raw MCP exceptions. Matches the structured error pattern used by all other core tools.
+- **Code Mode Auto-Injection in Tool Filter Whitelist Mode** — `mysql_execute_code` is now automatically included when using raw group filters (e.g., `--tool-filter core`). Previously, only meta-group filters (e.g., `starter`, `essential`) included Code Mode, leaving it inaccessible when a raw group name was used. The auto-injection only applies in whitelist mode (filters not starting with `-`) and respects explicit exclusion via `-codemode` or `-mysql_execute_code`.
+- **Code Mode Negative Memory Metric** — Fixed `mysql_execute_code` returning negative `memoryUsedMb` values (e.g., `-1.09`) in execution metrics when garbage collection reclaims heap between measurement snapshots. Now clamped to `Math.max(0, ...)` in both `CodeModeSandbox` and `WorkerSandbox`.
+- **Code Mode Auto-Rollback on Success** — Fixed `mysql_execute_code` not rolling back uncommitted transactions when user code succeeds but leaves transactions open. The orphaned transaction cleanup previously only ran on execution failure (`!result.success`), causing dangling InnoDB transactions and table locks. Cleanup now runs unconditionally after every execution.
+- **`mysql_transaction_execute` Empty Statements Structured Error** — Fixed `mysql_transaction_execute` throwing a raw Zod validation error when called with an empty `statements` array. Now returns `{ success: false, reason: "No statements provided..." }` matching the structured error pattern used by all other transaction tools. Validation moved from Zod `.refine()` to handler-level guard to prevent unnecessary transaction creation.
+- **Code Mode Cluster `help()` Examples** — `mysql.cluster.help()` examples only showed parameterless calls (`clusterStatus()`, `clusterInstances()`, `grStatus()`). Updated to show the most useful patterns: `clusterStatus({ summary: true })`, `clusterRouterStatus({ summary: true })`, and `clusterSwitchover()`.
+- **`ServerInstructions.ts` Cluster Router Status Documentation** — Documentation for `mysql_cluster_router_status` said only "return only essential router info" for summary mode without listing specific fields. Updated to enumerate all summary fields (routerId, routerName, address, version, lastCheckIn, roPort, rwPort, localCluster) and document the new `isStale`/`staleCount` fields. Also clarified switchover suitability rating thresholds (GOOD/ACCEPTABLE/NOT_RECOMMENDED).
+
+### Added
+
+- **`mysql_cluster_router_status` Stale Router Detection** — Router responses now include an `isStale` boolean per router (true when `lastCheckIn` is null or >1 hour old) and a top-level `staleCount` field. Applied in both summary and full modes. Previously, stale/abandoned router entries were indistinguishable from active ones without external timestamp comparison.
+- **Code Mode (`mysql_execute_code`)** — New sandboxed code execution tool enabling LLM agents to compose multi-step MySQL workflows as JavaScript/TypeScript code. Provides the `mysql.*` API namespace with 22 groups (168+ methods) including `mysql.core`, `mysql.json`, `mysql.transactions`, `mysql.spatial`, `mysql.stats`, and more. Features VM-based isolation, security validation, rate limiting, automatic transaction cleanup, and comprehensive help/introspection via `mysql.help()`. Requires `admin` scope.
+- **`--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 where the server must accept connections from outside the container. Precedence: CLI flag > environment variable > default.
+- **Parameter Aliases (Split Schema)** — Tools now accept alternative parameter names for commonly used fields, normalized automatically via Zod schema preprocessing. Aliases: `table`/`tableName`/`name` for table parameters (Core, Text, Backup, Partitioning, Performance, Admin tools); `query`/`sql` for SQL parameters (`mysql_read_query`, `mysql_write_query`, `mysql_explain`, `mysql_explain_analyze`, `mysql_query_rewrite`, `mysql_optimizer_trace`); `where`/`filter` for WHERE clause (`mysql_export_table` and all Text tools); `column`/`col` for column parameters (Text tools). Admin maintenance tools also accept singular `table` as an alias for the `tables` array. 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
+
+- **`mysqlsh_run_script` Secure Temporary File Handling (CodeQL)** — Replaced insecure `os.tmpdir()` + manual filename pattern with `fs.mkdtemp()` for SQL script temp files. The previous approach created predictable files in the shared OS temp directory, flagged by CodeQL as `js/insecure-temporary-file`. Now creates a unique temporary directory with restrictive permissions via `mkdtemp`, writes the script inside it, and recursively removes the directory after execution.
+- **CVE Fix: `ajv` ReDoS via `$data` Option (GHSA-2g4f-4pwh-qvx6)** — Overrode transitive dependency `ajv` (via `@modelcontextprotocol/sdk` → `ajv-formats`) from 8.17.1 to 8.18.0 to fix a ReDoS vulnerability when the `$data` option accepts runtime regex patterns via JSON Pointer.
+- **CVE Fix: `qs` ArrayLimit Bypass (GHSA-w7fw-mjwx-w883)** — Updated transitive dependency `qs` (via `express` → `@modelcontextprotocol/sdk`) from 6.14.1 to 6.14.2 to fix an arrayLimit bypass in comma parsing that allows denial of service.
+
+### Dependencies
+
+- Bumped `@eslint/js` from `^9.39.2` to `^10.0.1`
+- Bumped `@types/node` from `^25.2.2` to `^25.2.3`
+- Bumped `eslint` from `^9.39.2` to `^10.0.0`
+- Bumped `mysql2` from `^3.16.3` to `^3.17.2`
+- Bumped `typescript-eslint` from `^8.54.0` to `^8.56.0`
+
 ## [2.2.0] - 2026-02-08
 
 ### Fixed
@@ -45,6 +128,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - **`mysql_role_revoke` User Existence Pre-Check** — Fixed `mysql_role_revoke` returning the "not assigned" message for nonexistent users instead of distinguishing them from valid users with unassigned roles. Now pre-checks `mysql.user` before the `role_edges` assignment check and returns `{ success: false, error: "User does not exist" }` for nonexistent users, matching `mysql_role_assign` behavior.
 - **`mysql_role_revoke` Assignment Pre-Check** — Fixed `mysql_role_revoke` returning `success: true` when revoking a role that was not assigned to the user. Now pre-checks `mysql.role_edges` and returns `{ success: false, reason: "Role '...' is not assigned to user '...'@'...'" }` when the role is not currently assigned.
 - **`mysql_role_create` / `mysql_role_drop` Informative No-Op Messaging** — When `ifNotExists: true` (default), `mysql_role_create` now pre-checks role existence via `mysql.user` and returns `{ success: true, skipped: true, reason: "Role already exists", roleName }` when the role was already present. Similarly, `mysql_role_drop` with `ifExists: true` (default) returns `{ success: true, skipped: true, reason: "Role did not exist", roleName }` when the role was already absent. Previously both returned a plain `{ success: true, roleName }` indistinguishable from an actual create/drop. Matches the informative messaging pattern established by `mysql_drop_table`, `mysql_create_schema`, and `mysql_event_drop`.
+- **Code Mode Roles `help()` Example Inaccuracy** — `mysql.roles.help()` listed `roleGrant({ role: 'app_reader', privileges: 'SELECT', on: 'mydb.*' })` as an example, but the tool accepts `privileges` as an array (`['SELECT']`) and uses `database`/`table` parameters instead of `on`. Updated to `roleGrant({ role: 'app_reader', privileges: ['SELECT'], database: 'mydb' })`.
+- **Code Mode Docstore `help()` Examples** — `mysql.docstore.help()` examples contained two inaccuracies: `docAdd` example used singular `document` parameter instead of the correct `documents` array, and `docFind` example used `filter: 'price > 5'` (comparison operator) instead of a JSON path existence filter (`$.name`). `doc_find` only supports JSON path existence checks per ServerInstructions.
 - **`mysql_role_grant` Error Message Sanitization** — Fixed `mysql_role_grant` leaking internal adapter prefix (`Raw query failed: Query failed:`) in error messages for nonexistent tables. Now strips the prefix to return clean MySQL error messages (e.g., `"Table 'testdb.nonexistent' doesn't exist"`).
 - **Roles Tool Graceful Error Handling** — `mysql_role_create` returns `{ success: false, reason }` for duplicate roles (without `ifNotExists`). `mysql_role_drop` returns `{ success: false, reason }` for nonexistent roles (without `ifExists`). `mysql_role_assign` and `mysql_role_revoke` return `{ success: false, error }` for nonexistent users. `mysql_role_grant` returns `{ success: false, error }` for nonexistent tables. `mysql_user_roles` returns `{ exists: false }` for nonexistent users (P154). Previously all propagated raw MySQL errors.
 - **Stats Tools Graceful Error Handling (P154)** — All 8 stats tools (`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`) now return `{ exists: false, table }` for nonexistent tables and `{ success: false, error }` for other query errors (e.g., unknown column), instead of propagating raw MySQL errors.

package/CODE_MODE.md

@@ -0,0 +1,245 @@
+# Code Mode
+
+**Execute multi-step MySQL workflows in a single tool call.**
+
+Code Mode (`mysql_execute_code`) runs JavaScript/TypeScript code in a sandboxed VM with full access to all 192 MySQL tools via the `mysql.*` API namespace. Instead of chaining dozens of sequential tool calls, write a single script that queries, transforms, and acts on your data.
+
+---
+
+## When to Use Code Mode
+
+| Scenario                     | Without Code Mode                          | With Code Mode                         |
+| ---------------------------- | ------------------------------------------ | -------------------------------------- |
+| Multi-step data pipeline     | 5-10 sequential tool calls                 | 1 `mysql_execute_code` call            |
+| Conditional branching        | Agent decides after each tool result       | `if/else` logic in one script          |
+| Cross-table aggregation      | Multiple reads + manual aggregation        | Loop and aggregate in JS               |
+| Schema migration with checks | Describe → check → alter → verify sequence | Single script with error handling      |
+| Batch operations             | Repeated tool calls per item               | `for` loop over items in one execution |
+
+**Rule of thumb**: If a task requires **3+ sequential tool calls** or **conditional logic based on query results**, use Code Mode.
+
+---
+
+## Tool Reference
+
+### `mysql_execute_code`
+
+| Parameter | Type   | Required | Description                              |
+| --------- | ------ | -------- | ---------------------------------------- |
+| `code`    | string | ✅       | JavaScript/TypeScript code to execute    |
+| `timeout` | number | ❌       | Execution timeout in ms (default: 30000) |
+
+**Scope**: Requires `admin` scope.
+
+**Returns**: The value of the last expression in the code block, wrapped in an execution result with timing and memory metrics.
+
+---
+
+## API Namespace
+
+The `mysql` global object exposes **24 tool groups** as sub-objects:
+
+| Group                | Tools | Description                              |
+| -------------------- | ----- | ---------------------------------------- |
+| `mysql.core`         | 8     | Read/write queries, tables, indexes      |
+| `mysql.transactions` | 7     | BEGIN, COMMIT, ROLLBACK, savepoints      |
+| `mysql.json`         | 17    | JSON functions, merge, diff, stats       |
+| `mysql.text`         | 6     | REGEXP, LIKE, SOUNDEX                    |
+| `mysql.fulltext`     | 5     | Natural language & boolean search        |
+| `mysql.performance`  | 8     | EXPLAIN, query analysis, slow queries    |
+| `mysql.optimization` | 4     | Index hints, recommendations             |
+| `mysql.admin`        | 6     | OPTIMIZE, ANALYZE, CHECK                 |
+| `mysql.monitoring`   | 7     | PROCESSLIST, status variables            |
+| `mysql.backup`       | 4     | Export, import, mysqldump                |
+| `mysql.replication`  | 5     | Master/slave, binlog                     |
+| `mysql.partitioning` | 4     | Partition management                     |
+| `mysql.schema`       | 10    | Views, procedures, triggers, constraints |
+| `mysql.shell`        | 10    | MySQL Shell utilities                    |
+| `mysql.events`       | 6     | Event Scheduler management               |
+| `mysql.sysschema`    | 8     | sys schema diagnostics                   |
+| `mysql.stats`        | 8     | Statistical analysis tools               |
+| `mysql.spatial`      | 12    | Spatial/GIS operations                   |
+| `mysql.security`     | 9     | Audit, SSL, encryption, masking          |
+| `mysql.roles`        | 8     | MySQL 8.0 role management                |
+| `mysql.docstore`     | 9     | Document Store collections               |
+| `mysql.cluster`      | 10    | Group Replication, InnoDB Cluster        |
+| `mysql.proxysql`     | 12    | ProxySQL management                      |
+| `mysql.router`       | 9     | MySQL Router REST API                    |
+
+### Method Naming Convention
+
+Tool names map to methods by stripping the group prefix and converting to camelCase:
+
+```
+mysql_read_query      → mysql.core.readQuery()
+mysql_json_extract    → mysql.json.extract()
+mysql_describe_table  → mysql.core.describeTable()
+mysql_spatial_point   → mysql.spatial.point()
+mysql_show_processlist → mysql.monitoring.showProcesslist()
+```
+
+### Positional Shorthand
+
+Common tools accept positional arguments for convenience:
+
+```javascript
+// Object form
+mysql.core.readQuery({
+  query: "SELECT * FROM users WHERE id = ?",
+  params: [1],
+});
+
+// Positional shorthand
+mysql.core.readQuery("SELECT * FROM users WHERE id = ?", [1]);
+```
+
+### Discovery
+
+```javascript
+// List all groups and their methods
+mysql.help();
+
+// Group-specific help with examples
+mysql.core.help();
+mysql.json.help();
+mysql.transactions.help();
+```
+
+---
+
+## Usage Examples
+
+### Basic: Multi-Step Data Pipeline
+
+```javascript
+// Get table stats, identify large tables, and analyze their indexes
+const tables = await mysql.core.readQuery(
+  "SELECT table_name, table_rows FROM information_schema.tables WHERE table_schema = DATABASE() ORDER BY table_rows DESC LIMIT 5",
+);
+
+const results = [];
+for (const table of tables.rows) {
+  const indexes = await mysql.core.getIndexes({ table: table.table_name });
+  const stats = await mysql.performance.tableStats({ table: table.table_name });
+  results.push({
+    table: table.table_name,
+    rows: table.table_rows,
+    indexCount: indexes.indexes?.length || 0,
+    stats,
+  });
+}
+results;
+```
+
+### Conditional Logic
+
+```javascript
+// Check if a column exists before adding it
+const desc = await mysql.core.describeTable({ table: "users" });
+const hasEmail = desc.columns.some((c) => c.Field === "email_verified");
+
+if (!hasEmail) {
+  await mysql.core.writeQuery({
+    query: "ALTER TABLE users ADD COLUMN email_verified TINYINT(1) DEFAULT 0",
+  });
+  ("Column added");
+} else {
+  ("Column already exists");
+}
+```
+
+### Transactions with Error Handling
+
+```javascript
+// Atomic transfer between accounts
+const tx = await mysql.transactions.begin();
+try {
+  await mysql.core.writeQuery({
+    query: "UPDATE accounts SET balance = balance - ? WHERE id = ?",
+    params: [100, 1],
+    transactionId: tx.transactionId,
+  });
+  await mysql.core.writeQuery({
+    query: "UPDATE accounts SET balance = balance + ? WHERE id = ?",
+    params: [100, 2],
+    transactionId: tx.transactionId,
+  });
+  await mysql.transactions.commit({ transactionId: tx.transactionId });
+  ("Transfer complete");
+} catch (e) {
+  await mysql.transactions.rollback({ transactionId: tx.transactionId });
+  `Transfer failed: ${e.message}`;
+}
+```
+
+### Cross-Group Aggregation
+
+```javascript
+// Comprehensive database health check
+const [health, pool, processlist, variables] = await Promise.all([
+  mysql.monitoring.serverHealth(),
+  mysql.monitoring.poolStats(),
+  mysql.monitoring.showProcesslist({ full: false }),
+  mysql.monitoring.showStatus({ like: "%Threads%" }),
+]);
+
+({
+  serverVersion: health.version,
+  uptime: health.uptime,
+  activeConnections: pool.active,
+  idleConnections: pool.idle,
+  runningQueries:
+    processlist.processes?.filter((p) => p.Command === "Query").length || 0,
+  threadMetrics: variables.variables,
+});
+```
+
+---
+
+## Security & Sandbox
+
+### Isolation
+
+Code runs in an **isolated VM sandbox** (Node.js `vm` module) with no access to:
+
+- File system (`fs`, `path`, `os`)
+- Network (`http`, `https`, `net`, `fetch`)
+- Process control (`process`, `child_process`)
+- Module system (`require`, `import`)
+
+### Blocked Patterns
+
+The following patterns are detected and rejected **before execution**:
+
+| Pattern             | Reason                    |
+| ------------------- | ------------------------- |
+| `require(...)`      | Module loading            |
+| `import ...`        | ES module imports         |
+| `process.`          | Process access            |
+| `eval(...)`         | Dynamic code execution    |
+| `new Function(...)` | Dynamic function creation |
+| `__dirname`         | File system path access   |
+| `__filename`        | File system path access   |
+
+### Rate Limiting
+
+Code Mode is rate-limited to prevent abuse. Excessive calls within a short window will return an error with a retry-after suggestion.
+
+### Transaction Cleanup
+
+Any transactions opened during code execution but **not explicitly committed** are automatically rolled back when execution completes. This prevents orphaned locks.
+
+### Timeout
+
+Default execution timeout is **30 seconds**. Use the `timeout` parameter to adjust for long-running operations.
+
+---
+
+## Tips
+
+1. **Use `await`** — All `mysql.*` methods return Promises.
+2. **Return values** — The last expression in your code is returned as the result.
+3. **Error handling** — Wrap operations in `try/catch` for graceful error handling.
+4. **Parallel queries** — Use `Promise.all()` for independent queries to reduce execution time.
+5. **Transaction safety** — Always use `try/catch/finally` with transactions to ensure cleanup.
+6. **Help system** — Call `mysql.help()` or `mysql.<group>.help()` to discover available methods.

package/DOCKER_README.md

@@ -1,6 +1,6 @@
 # MySQL MCP Server
 
-**Last Updated: February 8, 2026**
+**Last Updated February 18, 2026**
 
 [![GitHub](https://img.shields.io/badge/GitHub-neverinfamous/mysql--mcp-blue?logo=github)](https://github.com/neverinfamous/mysql-mcp)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
@@ -9,8 +9,8 @@
 [![Docker Pulls](https://img.shields.io/docker/pulls/writenotenow/mysql-mcp)](https://hub.docker.com/r/writenotenow/mysql-mcp)
 [![Security](https://img.shields.io/badge/Security-Enhanced-green.svg)](SECURITY.md)
 ![TypeScript](https://img.shields.io/badge/TypeScript-Strict-blue.svg)
-![Tests](https://img.shields.io/badge/Tests-1794%20passing-brightgreen.svg)
-![Coverage](https://img.shields.io/badge/Coverage-94%25-green.svg)
+![Tests](https://img.shields.io/badge/Tests-1835%20passing-brightgreen.svg)
+![Coverage](https://img.shields.io/badge/Coverage-86%25-green.svg)
 
 **[📚 Full Documentation (Wiki)](https://github.com/neverinfamous/mysql-mcp/wiki)** • **[Changelog](https://github.com/neverinfamous/mysql-mcp/blob/master/CHANGELOG.md)** • **[Security](https://github.com/neverinfamous/mysql-mcp/blob/master/SECURITY.md)** • **[Release Article](https://adamic.tech/articles/mysql-mcp-server)**
 
@@ -22,17 +22,17 @@
 
 | Feature                        | Description                                                                                                                                                       |
 | ------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| **192 Specialized Tools**      | The largest MySQL tool collection for MCP — from core CRUD and native JSON functions (MySQL 5.7+) to advanced spatial/GIS, document store, and cluster management |
+| **193 Specialized Tools**      | The largest MySQL tool collection for MCP — from core CRUD and native JSON functions (MySQL 5.7+) to advanced spatial/GIS, document store, and cluster management |
 | **18 Observability Resources** | Real-time schema, performance metrics, process lists, status variables, replication status, and InnoDB diagnostics                                                |
 | **19 AI-Powered Prompts**      | Guided workflows for query building, schema design, performance tuning, and infrastructure setup                                                                  |
 | **OAuth 2.1 + Access Control** | Enterprise-ready security with RFC 9728/8414 compliance, granular scopes (`read`, `write`, `admin`, `full`, `db:*`, `table:*:*`), and Keycloak integration        |
-| **Smart Tool Filtering**       | 24 tool groups + 7 meta-groups let you stay within IDE limits while exposing exactly what you need                                                                |
+| **Smart Tool Filtering**       | 25 tool groups + 11 shortcuts let you stay within IDE limits while exposing exactly what you need                                                                 |
 | **HTTP Streaming Transport**   | SSE-based streaming with `/sse`, `/messages`, and `/health` endpoints for remote deployments                                                                      |
 | **High-Performance Pooling**   | Built-in connection pooling for efficient, concurrent database access                                                                                             |
 | **Ecosystem Integrations**     | First-class support for **MySQL Router**, **ProxySQL**, and **MySQL Shell** utilities                                                                             |
 | **Advanced Encryption**        | Full TLS/SSL support for secure connections, plus tools for managing data masking, encryption monitoring, and compliance                                          |
 | **Production-Ready Security**  | SQL injection protection, parameterized queries, input validation, and audit capabilities                                                                         |
-| **Strict TypeScript**          | 100% type-safe codebase with 1794 tests and 94% coverage                                                                                                          |
+| **Strict TypeScript**          | 100% type-safe codebase with 1833 tests and 86% coverage                                                                                                          |
 | **MCP 2025-11-25 Compliant**   | Full protocol support with tool safety hints, resource priorities, and progress notifications                                                                     |
 
 ---
@@ -118,12 +118,13 @@ mysql-mcp --mysql mysql://root:pass@localhost/db \
 
 ```bash
 # Local installation
-node dist/cli.js --transport http --port 3000 --mysql mysql://user:password@localhost:3306/database
+node dist/cli.js --transport http --port 3000 --server-host 0.0.0.0 --mysql mysql://user:password@localhost:3306/database
 
 # Docker (expose port 3000)
 docker run -p 3000:3000 writenotenow/mysql-mcp \
   --transport http \
   --port 3000 \
+  --server-host 0.0.0.0 \
   --mysql mysql://user:password@host.docker.internal:3306/database
 ```
 
@@ -231,10 +232,26 @@ Use the remote hostname directly:
 
 ---
 
+## Code Mode: Maximum Efficiency
+
+Code Mode (`mysql_execute_code`) dramatically reduces token usage (70–90%) and is included by default in all presets.
+
+> [!TIP]
+> **Maximize Token Savings:** For the best results, instruct your AI agent to prefer Code Mode over individual tool calls. Add a rule like this to your agent's prompt or system configuration:
+>
+> _"When using mysql-mcp, prefer `mysql_execute_code` (Code Mode) for multi-step database operations to minimize token usage."_
+>
+> This ensures the agent batches operations into single calls instead of making many individual tool calls. See the [Code Mode wiki](https://github.com/neverinfamous/mysql-mcp/wiki/Code-Mode) for full API documentation.
+
+> [!NOTE]
+> **AntiGravity Users:** Server instructions are automatically sent to MCP clients during initialization. However, AntiGravity does not currently support MCP server instructions. For optimal Code Mode usage in AntiGravity, manually provide the contents of [`src/constants/ServerInstructions.ts`](https://github.com/neverinfamous/mysql-mcp/blob/master/src/constants/ServerInstructions.ts) to the agent in your prompt or user rules.
+
+---
+
 ## 🛠️ Tool Filtering
 
 > [!IMPORTANT]
-> **AI IDEs like Cursor have tool limits (typically 40-50 tools).** With 192 tools available, you MUST use tool filtering to stay within your IDE's limits. We recommend `starter` (38 tools) as a starting point.
+> **AI IDEs like Cursor have tool limits (typically 40-50 tools).** With 193 tools available, you MUST use tool filtering to stay within your IDE's limits. We recommend `starter` (39 tools) as a starting point. Code Mode is included in all presets by default for 70-90% token savings on multi-step operations.
 
 ### What Can You Filter?
 
@@ -242,28 +259,28 @@ The `--tool-filter` argument accepts **shortcuts**, **groups**, or **tool names*
 
 | Filter Pattern   | Example                     | Tools | Description               |
 | ---------------- | --------------------------- | ----- | ------------------------- |
-| Shortcut only    | `starter`                   | 38    | Use a predefined bundle   |
+| Shortcut only    | `starter`                   | 39    | Use a predefined bundle   |
 | Groups only      | `core,json,transactions`    | 32    | Combine individual groups |
-| Shortcut + Group | `starter,spatial`           | 50    | Extend a shortcut         |
-| Shortcut - Tool  | `starter,-mysql_drop_table` | 37    | Remove specific tools     |
+| Shortcut + Group | `starter,spatial`           | 51    | Extend a shortcut         |
+| Shortcut - Tool  | `starter,-mysql_drop_table` | 38    | Remove specific tools     |
 
 ### Shortcuts (Predefined Bundles)
 
-| Shortcut        | Tools  | Use Case           | What's Included                                          |
-| --------------- | ------ | ------------------ | -------------------------------------------------------- |
-| `starter`       | **38** | 🌟 **Recommended** | core, json, transactions, text                           |
-| `essential`     | 15     | Minimal footprint  | core, transactions                                       |
-| `dev-power`     | 46     | Power Developer    | core, schema, performance, stats, fulltext, transactions |
-| `ai-data`       | 45     | AI Data Analyst    | core, json, docstore, text, fulltext                     |
-| `ai-spatial`    | 43     | AI Spatial Analyst | core, spatial, stats, performance, transactions          |
-| `dba-monitor`   | 35     | DBA Monitoring     | core, monitoring, performance, sysschema, optimization   |
-| `dba-manage`    | 33     | DBA Management     | core, admin, backup, replication, partitioning, events   |
-| `dba-secure`    | 32     | DBA Security       | core, security, roles, transactions                      |
-| `base-core`     | 48     | Base Ops           | core, json, transactions, text, schema                   |
-| `base-advanced` | 40     | Advanced Features  | docstore, spatial, stats, fulltext, events               |
-| `ecosystem`     | 41     | External Tools     | cluster, proxysql, router, shell                         |
-
-### Tool Groups (24 Available)
+| Shortcut        | Tools  | Use Case           | What's Included                                                    |
+| --------------- | ------ | ------------------ | ------------------------------------------------------------------ |
+| `starter`       | **39** | 🌟 **Recommended** | core, json, transactions, text, codemode                           |
+| `essential`     | 16     | Minimal footprint  | core, transactions, codemode                                       |
+| `dev-power`     | 47     | Power Developer    | core, schema, performance, stats, fulltext, transactions, codemode |
+| `ai-data`       | 46     | AI Data Analyst    | core, json, docstore, text, fulltext, codemode                     |
+| `ai-spatial`    | 44     | AI Spatial Analyst | core, spatial, stats, performance, transactions, codemode          |
+| `dba-monitor`   | 36     | DBA Monitoring     | core, monitoring, performance, sysschema, optimization, codemode   |
+| `dba-manage`    | 34     | DBA Management     | core, admin, backup, replication, partitioning, events, codemode   |
+| `dba-secure`    | 33     | DBA Security       | core, security, roles, transactions, codemode                      |
+| `base-core`     | 49     | Base Ops           | core, json, transactions, text, schema, codemode                   |
+| `base-advanced` | 41     | Advanced Features  | docstore, spatial, stats, fulltext, events, codemode               |
+| `ecosystem`     | 42     | External Tools     | cluster, proxysql, router, shell, codemode                         |
+
+### Tool Groups (25 Available)
 
 | Group          | Tools | Description                              |
 | -------------- | ----- | ---------------------------------------- |
@@ -291,6 +308,7 @@ The `--tool-filter` argument accepts **shortcuts**, **groups**, or **tool names*
 | `cluster`      | 10    | Group Replication, InnoDB Cluster        |
 | `proxysql`     | 12    | ProxySQL management                      |
 | `router`       | 9     | MySQL Router REST API                    |
+| `codemode`     | 1     | Sandboxed code execution                 |
 
 ---
 
@@ -298,7 +316,7 @@ The `--tool-filter` argument accepts **shortcuts**, **groups**, or **tool names*
 
 Add one of these configurations to your IDE's MCP settings file (e.g., `cline_mcp_settings.json`, `.cursorrules`, or equivalent):
 
-#### Option 1: Starter (38 Essential Tools)
+#### Option 1: Starter (39 Essential Tools)
 
 **Best for:** General MySQL database work - CRUD operations, schema management, and monitoring.
 
@@ -326,7 +344,7 @@ Add one of these configurations to your IDE's MCP settings file (e.g., `cline_mc
 }
 ```
 
-#### Option 2: Cluster (10 Tools for InnoDB Cluster Monitoring)
+#### Option 2: Cluster (11 Tools for InnoDB Cluster Monitoring)
 
 **Best for:** Monitoring InnoDB Cluster, Group Replication status, and cluster topology.
 
@@ -361,7 +379,7 @@ Add one of these configurations to your IDE's MCP settings file (e.g., `cline_mc
 }
 ```
 
-#### Option 3: Ecosystem (41 Tools for InnoDB Cluster Deployments)
+#### Option 3: Ecosystem (42 Tools for InnoDB Cluster Deployments)
 
 **Best for:** MySQL Router, ProxySQL, MySQL Shell, and InnoDB Cluster deployments.
 
@@ -497,6 +515,8 @@ For specialized setups, see these Wiki pages:
 
 ## ⚡ Performance Tuning
 
+Schema metadata is cached to reduce repeated queries during tool/resource invocations.
+
 | Variable                | Default | Description                                        |
 | ----------------------- | ------- | -------------------------------------------------- |
 | `METADATA_CACHE_TTL_MS` | `30000` | Cache TTL for schema metadata (milliseconds)       |
@@ -504,17 +524,20 @@ For specialized setups, see these Wiki pages:
 
 > **Tip:** Lower `METADATA_CACHE_TTL_MS` for development (e.g., `5000`), or increase it for production with stable schemas (e.g., `300000` = 5 min).
 
+> **Built-in payload optimization:** Many tools support optional `summary: true` for condensed responses and `limit` parameters to cap result sizes. These are particularly useful for cluster status, monitoring, and sys schema tools where full responses can be large. See [`ServerInstructions.ts`](https://github.com/neverinfamous/mysql-mcp/blob/master/src/constants/ServerInstructions.ts) for per-tool details.
+
 ---
 
 ### CLI Options
 
-| Option                    | Environment Variable    | Description                 |
-| ------------------------- | ----------------------- | --------------------------- |
-| `--oauth-enabled`         | `OAUTH_ENABLED`         | Enable OAuth authentication |
-| `--oauth-issuer`          | `OAUTH_ISSUER`          | Authorization server URL    |
-| `--oauth-audience`        | `OAUTH_AUDIENCE`        | Expected token audience     |
-| `--oauth-jwks-uri`        | `OAUTH_JWKS_URI`        | JWKS URI (auto-discovered)  |
-| `--oauth-clock-tolerance` | `OAUTH_CLOCK_TOLERANCE` | Clock tolerance in seconds  |
+| Option                    | Environment Variable    | Description                                         |
+| ------------------------- | ----------------------- | --------------------------------------------------- |
+| `--server-host`           | `MCP_HOST`              | Host to bind HTTP transport to (default: localhost) |
+| `--oauth-enabled`         | `OAUTH_ENABLED`         | Enable OAuth authentication                         |
+| `--oauth-issuer`          | `OAUTH_ISSUER`          | Authorization server URL                            |
+| `--oauth-audience`        | `OAUTH_AUDIENCE`        | Expected token audience                             |
+| `--oauth-jwks-uri`        | `OAUTH_JWKS_URI`        | JWKS URI (auto-discovered)                          |
+| `--oauth-clock-tolerance` | `OAUTH_CLOCK_TOLERANCE` | Clock tolerance in seconds                          |
 
 ### Scopes