@neverinfamous/mysql-mcp 2.1.0 → 2.3.0

package/DOCKER_README.md

@@ -1,19 +1,18 @@
 # MySQL MCP Server
 
-*Last updated January 3, 2026 - Production/Stable v2.1.0*
+**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)
 [![CodeQL](https://github.com/neverinfamous/mysql-mcp/actions/workflows/codeql.yml/badge.svg)](https://github.com/neverinfamous/mysql-mcp/actions/workflows/codeql.yml)
-![Version](https://img.shields.io/badge/version-2.1.0-green)
-![Status](https://img.shields.io/badge/status-Production%2FStable-brightgreen)
+[![npm version](https://img.shields.io/npm/v/@neverinfamous/mysql-mcp.svg)](https://www.npmjs.com/package/@neverinfamous/mysql-mcp)
 [![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-1590%20passing-brightgreen.svg)
-![Coverage](https://img.shields.io/badge/Coverage-97%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)**
+**[📚 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)**
 
 ## The Most Comprehensive MySQL MCP Server Available
 
@@ -21,20 +20,20 @@
 
 ### 🎯 What Sets Us Apart
 
-| Feature | Description |
-|---------|-------------|
-| **191 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 |
-| **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 1550+ tests and 97% coverage |
-| **MCP 2025-11-25 Compliant** | Full protocol support with tool safety hints, resource priorities, and progress notifications |
+| Feature                        | Description                                                                                                                                                       |
+| ------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **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**       | 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 1833 tests and 86% coverage                                                                                                          |
+| **MCP 2025-11-25 Compliant**   | Full protocol support with tool safety hints, resource priorities, and progress notifications                                                                     |
 
 ---
 
@@ -42,21 +41,26 @@
 
 ### Prerequisites
 
-- Node.js 18+
+- Node.js 24+
 - MySQL 5.7+ or 8.0+ server
 - npm or yarn
 
 ### Installation
 
+#### NPM (Recommended)
+
 ```bash
-git clone https://github.com/neverinfamous/mysql-mcp.git
-cd mysql-mcp
-npm install
-npm run build
-node dist/cli.js --transport stdio --mysql mysql://user:password@localhost:3306/database
+# Install globally
+npm install -g @neverinfamous/mysql-mcp
+
+# Run
+mysql-mcp --transport stdio --mysql mysql://user:password@localhost:3306/database
+
+# Or use npx without installing
+npx @neverinfamous/mysql-mcp --transport stdio --mysql mysql://user:password@localhost:3306/database
 ```
 
-### Docker
+#### Docker
 
 ```bash
 docker run -i --rm writenotenow/mysql-mcp:latest \
@@ -64,6 +68,16 @@ docker run -i --rm writenotenow/mysql-mcp:latest \
   --mysql mysql://user:password@host.docker.internal:3306/database
 ```
 
+#### From Source
+
+```bash
+git clone https://github.com/neverinfamous/mysql-mcp.git
+cd mysql-mcp
+npm install
+npm run build
+node dist/cli.js --transport stdio --mysql mysql://user:password@localhost:3306/database
+```
+
 ---
 
 ## ⚡ MCP Client Configuration
@@ -73,6 +87,7 @@ docker run -i --rm writenotenow/mysql-mcp:latest \
 > **When to use HTTP mode:** Use HTTP mode when deploying `mysql-mcp` as a standalone server that multiple clients can connect to remotely. For local development with Claude Desktop or Cursor IDE, use the default `stdio` mode shown below instead.
 
 **Use cases for HTTP mode:**
+
 - Running the server in a Docker container accessible over a network
 - Deploying to cloud platforms (AWS, GCP, Azure)
 - Enabling OAuth 2.1 authentication for enterprise security
@@ -85,11 +100,13 @@ For enterprise deployments, mysql-mcp supports OAuth 2.1 authentication with Key
 ### Quick Setup
 
 **1. Start with OAuth disabled (default)**
+
 ```bash
 mysql-mcp --mysql mysql://root:pass@localhost/db
 ```
 
 **2. Enable OAuth with an identity provider**
+
 ```bash
 mysql-mcp --mysql mysql://root:pass@localhost/db \
           --oauth-enabled \
@@ -101,16 +118,18 @@ 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
 ```
 
 **Available endpoints:**
+
 - `GET /sse` - Establish MCP connection via Server-Sent Events
 - `POST /messages` - Send JSON-RPC messages to the server
 - `GET /health` - Health check endpoint
@@ -127,8 +146,10 @@ docker run -p 3000:3000 writenotenow/mysql-mcp \
       "command": "node",
       "args": [
         "C:/path/to/mysql-mcp/dist/cli.js",
-        "--transport", "stdio",
-        "--mysql", "mysql://user:password@localhost:3306/database"
+        "--transport",
+        "stdio",
+        "--mysql",
+        "mysql://user:password@localhost:3306/database"
       ]
     }
   }
@@ -142,20 +163,20 @@ docker run -p 3000:3000 writenotenow/mysql-mcp \
   "mcpServers": {
     "mysql-mcp": {
       "command": "node",
-      "args": [
-        "C:/path/to/mysql-mcp/dist/cli.js",
-        "--transport", "stdio"
-      ],
+      "args": ["C:/path/to/mysql-mcp/dist/cli.js", "--transport", "stdio"],
       "env": {
         "MYSQL_HOST": "localhost",
         "MYSQL_PORT": "3306",
         "MYSQL_USER": "your_user",
         "MYSQL_PASSWORD": "your_password",
-        "MYSQL_DATABASE": "your_database"
+        "MYSQL_DATABASE": "your_database",
+        "MYSQL_XPORT": "33060"
       }
     }
   }
 }
+
+> **Note:** `MYSQL_XPORT` (X Protocol port) defaults to `33060` if omitted. Only needed for `mysqlsh_import_json` and `docstore` tools. Set to your MySQL Router X Protocol port (e.g., `6448`) when using InnoDB Cluster.
 ```
 
 > **📖 See the [Configuration Wiki](https://github.com/neverinfamous/mysql-mcp/wiki/Configuration)** for more configuration options.
@@ -164,20 +185,24 @@ docker run -p 3000:3000 writenotenow/mysql-mcp \
 
 ## 🔗 Database Connection Scenarios
 
-| Scenario | Host to Use | Example Connection String |
-|----------|-------------|---------------------------|
-| **MySQL on host machine** | `host.docker.internal` | `mysql://user:pass@host.docker.internal:3306/db` |
-| **MySQL in Docker** | Container name or network | `mysql://user:pass@mysql-container:3306/db` |
-| **Remote/Cloud MySQL** | Hostname or IP | `mysql://user:pass@db.example.com:3306/db` |
+| Scenario                  | Host to Use               | Example Connection String                        |
+| ------------------------- | ------------------------- | ------------------------------------------------ |
+| **MySQL on host machine** | `host.docker.internal`    | `mysql://user:pass@host.docker.internal:3306/db` |
+| **MySQL in Docker**       | Container name or network | `mysql://user:pass@mysql-container:3306/db`      |
+| **Remote/Cloud MySQL**    | Hostname or IP            | `mysql://user:pass@db.example.com:3306/db`       |
 
 ### MySQL on Host Machine
+
 If MySQL is installed directly on your computer (via installer, Homebrew, etc.):
+
 ```json
 "--mysql", "mysql://user:password@host.docker.internal:3306/database"
 ```
 
 ### MySQL in Another Docker Container
+
 Add both containers to the same Docker network, then use the container name:
+
 ```bash
 # Create network and run MySQL
 docker network create mynet
@@ -188,83 +213,102 @@ docker run -i --rm --network mynet writenotenow/mysql-mcp:latest \
 ```
 
 ### Remote/Cloud MySQL (RDS, Cloud SQL, etc.)
+
 Use the remote hostname directly:
+
 ```json
 "--mysql", "mysql://user:password@your-instance.region.rds.amazonaws.com:3306/database"
 ```
 
-| Provider | Example Hostname |
-|----------|------------------|
-| AWS RDS | `your-instance.xxxx.us-east-1.rds.amazonaws.com` |
-| Google Cloud SQL | `project:region:instance` (via Cloud SQL Proxy) |
-| Azure MySQL | `your-server.mysql.database.azure.com` |
-| PlanetScale | `aws.connect.psdb.cloud` (SSL required) |
-| DigitalOcean | `your-cluster-do-user-xxx.db.ondigitalocean.com` |
+| Provider         | Example Hostname                                 |
+| ---------------- | ------------------------------------------------ |
+| AWS RDS          | `your-instance.xxxx.us-east-1.rds.amazonaws.com` |
+| Google Cloud SQL | `project:region:instance` (via Cloud SQL Proxy)  |
+| Azure MySQL      | `your-server.mysql.database.azure.com`           |
+| PlanetScale      | `aws.connect.psdb.cloud` (SSL required)          |
+| DigitalOcean     | `your-cluster-do-user-xxx.db.ondigitalocean.com` |
 
 > **Tip:** For remote connections, ensure your MySQL server allows connections from Docker's IP range and that firewalls/security groups permit port 3306.
 
 ---
 
+## 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 191 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?
 
 The `--tool-filter` argument accepts **shortcuts**, **groups**, or **tool names** — mix and match freely:
 
-| Filter Pattern | Example | Tools | Description |
-|----------------|---------|-------|-------------|
-| Shortcut only | `starter` | 38 | 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 |
+| Filter Pattern   | Example                     | Tools | Description               |
+| ---------------- | --------------------------- | ----- | ------------------------- |
+| Shortcut only    | `starter`                   | 39    | Use a predefined bundle   |
+| Groups only      | `core,json,transactions`    | 32    | Combine individual groups |
+| 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, trans, text |
-| `essential` | 15 | Minimal footprint | Core, trans |
-| `dev-power` | 45 | Power Developer | Core, schema, perf, stats, fulltext, trans |
-| `ai-data` | 44 | AI Data Analyst | Core, JSON, docstore, text, fulltext |
-| `ai-spatial` | 43 | AI Spatial Analyst | Core, spatial, stats, perf, trans |
-| `dba-monitor` | 35 | DBA Monitoring | Core, monitor, perf, sysschema, opt |
-| `dba-manage` | 33 | DBA Management | Core, admin, backup, repl, parts, events |
-| `dba-secure` | 42 | DBA Security | Core, security, roles, cluster, trans |
-| `base-core` | 48 | Base Ops | Core, JSON, trans, text, schema |
-| `base-advanced` | 39 | Advanced Features | DocStore, spatial, stats, fulltext, events |
-| `ecosystem` | 31 | External Tools | Router, ProxySQL, Shell |
-
-### Tool Groups (24 Available)
-
-| Group | Tools | Description |
-|-------|-------|-------------|
-| `core` | 8 | Read/write queries, 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, slow queries |
-| `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 | ProxySQL management |
-| `shell` | 10 | MySQL Shell utilities |
-| `schema` | 10 | Views, procedures, triggers, constraints |
-| `events` | 6 | Event Scheduler management |
-| `sysschema` | 8 | sys schema diagnostics |
-| `stats` | 8 | Statistical analysis tools |
-| `spatial` | 12 | Spatial/GIS operations |
-| `security` | 9 | Audit, SSL, encryption, masking |
-| `cluster` | 10 | Group Replication, InnoDB Cluster |
-| `roles` | 8 | MySQL 8.0 role management |
-| `docstore` | 9 | Document Store collections |
+| 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                              |
+| -------------- | ----- | ---------------------------------------- |
+| `core`         | 8     | Read/write queries, tables, indexes      |
+| `transactions` | 7     | BEGIN, COMMIT, ROLLBACK, savepoints      |
+| `json`         | 17    | JSON functions, merge, diff, stats       |
+| `text`         | 6     | REGEXP, LIKE, SOUNDEX                    |
+| `fulltext`     | 5     | Natural language & boolean search        |
+| `performance`  | 8     | EXPLAIN, query analysis, slow queries    |
+| `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                     |
+| `schema`       | 10    | Views, procedures, triggers, constraints |
+| `shell`        | 10    | MySQL Shell utilities                    |
+| `events`       | 6     | Event Scheduler management               |
+| `sysschema`    | 8     | sys schema diagnostics                   |
+| `stats`        | 8     | Statistical analysis tools               |
+| `spatial`      | 12    | Spatial/GIS operations                   |
+| `security`     | 9     | Audit, SSL, encryption, masking          |
+| `roles`        | 8     | MySQL 8.0 role management                |
+| `docstore`     | 9     | Document Store collections               |
+| `cluster`      | 10    | Group Replication, InnoDB Cluster        |
+| `proxysql`     | 12    | ProxySQL management                      |
+| `router`       | 9     | MySQL Router REST API                    |
+| `codemode`     | 1     | Sandboxed code execution                 |
 
 ---
 
@@ -272,7 +316,8 @@ 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.
 
 ```json
@@ -299,12 +344,50 @@ Add one of these configurations to your IDE's MCP settings file (e.g., `cline_mc
 }
 ```
 
-#### Option 2: Ecosystem (31 Tools for InnoDB Cluster Deployments)
+#### Option 2: Cluster (11 Tools for InnoDB Cluster Monitoring)
+
+**Best for:** Monitoring InnoDB Cluster, Group Replication status, and cluster topology.
+
+> **⚠️ Prerequisites:**
+>
+> - **InnoDB Cluster** must be configured and running with Group Replication enabled
+> - Connect to a cluster node directly (e.g., `localhost:3307`) — NOT a standalone MySQL instance
+> - Use `cluster_admin` or `root` user with appropriate privileges
+> - See [MySQL Ecosystem Setup Guide](https://github.com/neverinfamous/mysql-mcp/wiki/MySQL-Ecosystem-Setup) for cluster setup instructions
+
+```json
+{
+  "mcpServers": {
+    "mysql-mcp-cluster": {
+      "command": "node",
+      "args": [
+        "/path/to/mysql-mcp/dist/cli.js",
+        "--transport",
+        "stdio",
+        "--tool-filter",
+        "cluster"
+      ],
+      "env": {
+        "MYSQL_HOST": "localhost",
+        "MYSQL_PORT": "3307",
+        "MYSQL_USER": "cluster_admin",
+        "MYSQL_PASSWORD": "cluster_password",
+        "MYSQL_DATABASE": "mysql"
+      }
+    }
+  }
+}
+```
+
+#### Option 3: Ecosystem (42 Tools for InnoDB Cluster Deployments)
+
 **Best for:** MySQL Router, ProxySQL, MySQL Shell, and InnoDB Cluster deployments.
 
-> **⚠️ Prerequisites:** 
+> **⚠️ Prerequisites:**
+>
 > - **InnoDB Cluster** with MySQL Router requires the cluster to be running for Router REST API authentication (uses `metadata_cache` backend)
 > - Router REST API uses HTTPS with self-signed certificates by default — set `MYSQL_ROUTER_INSECURE=true` to bypass certificate verification
+> - **X Protocol:** InnoDB Cluster includes the MySQL X Plugin by default. Set `MYSQL_XPORT` to the Router's X Protocol port (e.g., `6448`) for `mysqlsh_import_json` and `docstore` tools
 > - See [MySQL Ecosystem Setup Guide](https://github.com/neverinfamous/mysql-mcp/wiki/MySQL-Ecosystem-Setup) for detailed instructions
 
 ```json
@@ -322,9 +405,10 @@ Add one of these configurations to your IDE's MCP settings file (e.g., `cline_mc
       "env": {
         "MYSQL_HOST": "localhost",
         "MYSQL_PORT": "3307",
+        "MYSQL_XPORT": "6448",
         "MYSQL_USER": "cluster_admin",
         "MYSQL_PASSWORD": "cluster_password",
-        "MYSQL_DATABASE": "mysql",
+        "MYSQL_DATABASE": "testdb",
         "MYSQL_ROUTER_URL": "https://localhost:8443",
         "MYSQL_ROUTER_USER": "rest_api",
         "MYSQL_ROUTER_PASSWORD": "router_password",
@@ -366,27 +450,27 @@ For debugging or manual reference, see the source: [`src/constants/ServerInstruc
 
 This server includes **19 intelligent prompts** for guided workflows:
 
-| Prompt | Description |
-|--------|-------------|
-| `mysql_query_builder` | Construct SQL queries with security best practices |
-| `mysql_schema_design` | Design table schemas with indexes and relationships |
-| `mysql_performance_analysis` | Analyze slow queries with optimization recommendations |
-| `mysql_migration` | Generate migration scripts with rollback options |
-| `mysql_database_health_check` | Comprehensive database health assessment |
-| `mysql_backup_strategy` | Enterprise backup planning with RTO/RPO |
-| `mysql_index_tuning` | Index analysis and optimization workflow |
-| `mysql_setup_router` | MySQL Router configuration guide |
-| `mysql_setup_proxysql` | ProxySQL configuration guide |
-| `mysql_setup_replication` | Replication setup guide |
-| `mysql_setup_shell` | MySQL Shell usage guide |
-| `mysql_tool_index` | Complete tool index with categories |
-| `mysql_quick_query` | Quick query execution shortcut |
-| `mysql_quick_schema` | Quick schema exploration |
-| **`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 |
+| Prompt                        | Description                                            |
+| ----------------------------- | ------------------------------------------------------ |
+| `mysql_query_builder`         | Construct SQL queries with security best practices     |
+| `mysql_schema_design`         | Design table schemas with indexes and relationships    |
+| `mysql_performance_analysis`  | Analyze slow queries with optimization recommendations |
+| `mysql_migration`             | Generate migration scripts with rollback options       |
+| `mysql_database_health_check` | Comprehensive database health assessment               |
+| `mysql_backup_strategy`       | Enterprise backup planning with RTO/RPO                |
+| `mysql_index_tuning`          | Index analysis and optimization workflow               |
+| `mysql_setup_router`          | MySQL Router configuration guide                       |
+| `mysql_setup_proxysql`        | ProxySQL configuration guide                           |
+| `mysql_setup_replication`     | Replication setup guide                                |
+| `mysql_setup_shell`           | MySQL Shell usage guide                                |
+| `mysql_tool_index`            | Complete tool index with categories                    |
+| `mysql_quick_query`           | Quick query execution shortcut                         |
+| `mysql_quick_schema`          | Quick schema exploration                               |
+| **`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                        |
 
 ---
 
@@ -394,26 +478,26 @@ This server includes **19 intelligent prompts** for guided workflows:
 
 This server exposes **18 resources** for database observability:
 
-| Resource | Description |
-|----------|-------------|
-| `mysql://schema` | Full database schema |
-| `mysql://tables` | Table listing with metadata |
-| `mysql://variables` | Server configuration variables |
-| `mysql://status` | Server status metrics |
-| `mysql://processlist` | Active connections and queries |
-| `mysql://pool` | Connection pool statistics |
-| `mysql://capabilities` | Server version, features, tool categories |
-| `mysql://health` | Comprehensive health status |
-| `mysql://performance` | Query performance metrics |
-| `mysql://indexes` | Index usage and statistics |
-| `mysql://replication` | Replication status and lag |
-| `mysql://innodb` | InnoDB buffer pool and engine metrics |
-| **`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 |
+| Resource                | Description                                 |
+| ----------------------- | ------------------------------------------- |
+| `mysql://schema`        | Full database schema                        |
+| `mysql://tables`        | Table listing with metadata                 |
+| `mysql://variables`     | Server configuration variables              |
+| `mysql://status`        | Server status metrics                       |
+| `mysql://processlist`   | Active connections and queries              |
+| `mysql://pool`          | Connection pool statistics                  |
+| `mysql://capabilities`  | Server version, features, tool categories   |
+| `mysql://health`        | Comprehensive health status                 |
+| `mysql://performance`   | Query performance metrics                   |
+| `mysql://indexes`       | Index usage and statistics                  |
+| `mysql://replication`   | Replication status and lag                  |
+| `mysql://innodb`        | InnoDB buffer pool and engine metrics       |
+| **`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                  |
 
 ---
 
@@ -421,43 +505,48 @@ This server exposes **18 resources** for database observability:
 
 For specialized setups, see these Wiki pages:
 
-| Topic | Description |
-|-------|-------------|
+| Topic                                                                        | Description                                         |
+| ---------------------------------------------------------------------------- | --------------------------------------------------- |
 | [MySQL Router](https://github.com/neverinfamous/mysql-mcp/wiki/MySQL-Router) | Configure Router REST API access for InnoDB Cluster |
-| [ProxySQL](https://github.com/neverinfamous/mysql-mcp/wiki/ProxySQL) | Configure ProxySQL admin interface access |
-| [MySQL Shell](https://github.com/neverinfamous/mysql-mcp/wiki/MySQL-Shell) | Configure MySQL Shell for dump/load operations |
+| [ProxySQL](https://github.com/neverinfamous/mysql-mcp/wiki/ProxySQL)         | Configure ProxySQL admin interface access           |
+| [MySQL Shell](https://github.com/neverinfamous/mysql-mcp/wiki/MySQL-Shell)   | Configure MySQL Shell for dump/load operations      |
 
 ---
 
 ## ⚡ Performance Tuning
 
-| Variable | Default | Description |
-|----------|---------|-------------|
-| `METADATA_CACHE_TTL_MS` | `30000` | Cache TTL for schema metadata (milliseconds) |
-| `LOG_LEVEL` | `info` | Log verbosity: `debug`, `info`, `warning`, `error` |
+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)       |
+| `LOG_LEVEL`             | `info`  | Log verbosity: `debug`, `info`, `warning`, `error` |
 
 > **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
 
-| Scope | Access Level |
-|-------|-------------|
-| `read` | Read-only queries |
-| `write` | Read + write operations |
+| Scope   | Access Level              |
+| ------- | ------------------------- |
+| `read`  | Read-only queries         |
+| `write` | Read + write operations   |
 | `admin` | Administrative operations |
-| `full` | All operations |
+| `full`  | All operations            |
 
 > **📖 See the [OAuth Wiki](https://github.com/neverinfamous/mysql-mcp/wiki/OAuth)** for Keycloak setup and detailed configuration.