@yanzhang123/readonly-db-mcp 0.7.2 → 0.7.4

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2024 Dana K. Williams
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+MIT License
+
+Copyright (c) 2024 Dana K. Williams
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 SOFTWARE.

package/README.md

@@ -1,18 +1,30 @@
 [![Tests](https://github.com/12zhangyan/mysql_mcp_server/actions/workflows/test.yml/badge.svg)](https://github.com/12zhangyan/mysql_mcp_server/actions)
-[![PyPI - Downloads](https://img.shields.io/pypi/dm/mysql-mcp-server)](https://pypi.org/project/mysql-mcp-server/)
-[![AgentAudit Safe](https://img.shields.io/badge/AgentAudit-safe-brightgreen)](https://www.agentaudit.dev/packages/mysql-mcp-server)
-# MySQL MCP Server
-A Model Context Protocol (MCP) implementation that enables secure interaction with MySQL databases. This server component facilitates communication between AI applications (hosts/clients) and MySQL databases, making database exploration and analysis safer and more structured through a controlled interface.
-
-> **Note**: MySQL MCP Server supports both standard input/output (STDIO) and Streamable HTTP (SSE) transport modes. The SSE mode is recommended for remote/self-hosted deployments.
-
-## Deployment options
-- **Hosted** — [Fronteir AI](https://fronteir.ai/mcp/designcomputer-mysql-mcp-server) runs the server for you; no local setup required.
-- **Local** — [Smithery](https://smithery.ai/server/designcomputer/mysql-mcp-server) installs and runs the server on your own machine.
-
+[![npm version](https://img.shields.io/npm/v/%40yanzhang123%2Freadonly-db-mcp)](https://www.npmjs.com/package/@yanzhang123/readonly-db-mcp)
+[![npm provenance](https://img.shields.io/badge/npm-provenance-blue)](https://www.npmjs.com/package/@yanzhang123/readonly-db-mcp)
+
+# MySQL MCP Server
+
+An enterprise-auditable, strictly read-only Model Context Protocol (MCP) server
+for exploring multiple MySQL environments and databases from one process.
+
+The supported npm distribution for this fork is
+[`@yanzhang123/readonly-db-mcp`](https://www.npmjs.com/package/@yanzhang123/readonly-db-mcp).
+It includes the matching Python wheel and a cross-platform launcher, so MCP
+clients do not need a repository checkout or a separate package installation.
+
+> **Note**: MySQL MCP Server supports both standard input/output (STDIO) and Streamable HTTP (SSE) transport modes. The SSE mode is recommended for remote/self-hosted deployments.
+
+> [!IMPORTANT]
+> Read-only enforcement does not trust the MySQL account grants. Even if the
+> supplied account has `INSERT`, `UPDATE`, `DELETE`, or DDL privileges, the MCP
+> SQL gate only accepts reviewed read statement families, runs them in a
+> read-only transaction, and always rolls back. A database-level `SELECT`-only
+> account is still strongly recommended as independent defense in depth.
+
 ## Features
 - **Named connection profiles** for dev/test/staging/prod and multiple servers
 - Select a `connection` and `database` independently on every tool call
+- Database-to-profile routing hints without implicit cross-environment switching
 - **Strictly read-only SQL** with fail-closed validation, a MySQL read-only transaction, and unconditional rollback
 - Discover connections, databases, tables, schemas, and sample rows
 - Return-size protection (`MYSQL_MAX_ROWS`, hard maximum 1000)
@@ -20,44 +32,75 @@ A Model Context Protocol (MCP) implementation that enables secure interaction wi
 - **SSE/HTTP transport support** (`MCP_TRANSPORT=sse`)
 - Per-profile SSL/TLS and SSH tunneling
 - Passwords can stay in environment variables instead of the profiles file
-
+- Compatibility `query` alias for clients migrating from older MySQL MCP servers
+
 ## Installation
 
 ### npm / npx
 
-The npm package contains the matching Python wheel and exposes a cross-platform
-launcher:
+Requirements: Node.js 18+, npm 9+, and Python 3.11+ available on `PATH`.
+
+Run the current release without installing it globally:
 
 ```bash
 npx -y @yanzhang123/readonly-db-mcp
 ```
 
-Python 3.11 or newer is required. On first use, the launcher creates a
-versioned virtual environment in the user cache and installs the bundled wheel
-plus exact Python dependencies from a version-controlled SHA-256 lock file.
-Downloads use the configured pip index and the completed environment is cached
-by wheel-and-lock fingerprint. Override Python with `MYSQL_MCP_PYTHON` or the
-cache location with `MYSQL_MCP_NPM_CACHE_DIR`.
+For controlled production rollouts, pin the reviewed version:
+
+```bash
+npx -y @yanzhang123/readonly-db-mcp@0.7.3
+```
+
+On first use, the launcher creates a versioned virtual environment in the user
+cache and installs the bundled wheel plus exact Python dependencies from a
+version-controlled SHA-256 lock file. Downloads use the configured pip index
+and the completed environment is cached by wheel-and-lock fingerprint. Override
+Python with `MYSQL_MCP_PYTHON` or the cache location with
+`MYSQL_MCP_NPM_CACHE_DIR`.
 
 For MCP clients, use `npx` as the command and
 `["-y", "@yanzhang123/readonly-db-mcp"]` as its arguments.
 
-### Manual Installation
-```bash
-pip install mysql-mcp-server
-```
-
-### Installing via Smithery
-To install MySQL MCP Server for Claude Desktop automatically via [Smithery](https://smithery.ai/server/designcomputer/mysql-mcp-server):
-```bash
-npx -y @smithery/cli install designcomputer/mysql-mcp-server --client claude
-```
-
-### Installing via Claude Code CLI
-```bash
-claude mcp add --transport stdio designcomputer-mysql_mcp_server uvx mysql_mcp_server
-```
-
+### Minimal MCP client configuration
+
+Create `mysql-connections.toml` from
+[`mysql-connections.example.toml`](mysql-connections.example.toml), keep
+passwords in environment variables, and use an absolute path:
+
+```json
+{
+  "mcpServers": {
+    "mysql-readonly": {
+      "command": "npx",
+      "args": ["-y", "@yanzhang123/readonly-db-mcp@0.7.3"],
+      "env": {
+        "MYSQL_PROFILES_FILE": "C:/absolute/path/mysql-connections.toml",
+        "MYSQL_DEV_PASSWORD": "set-in-the-client-secret-store"
+      }
+    }
+  }
+}
+```
+
+On Windows clients that do not resolve npm command shims correctly, set
+`"command": "npx.cmd"`. Do not commit the populated profile, passwords, audit
+HMAC keys, connection strings, or client configuration containing secrets.
+
+After startup, call `validate_connections`, then `check_connection`, before
+running discovery queries. `check_connection` reports an irreversible account
+fingerprint and privilege classification without returning the username or raw
+grant statements.
+
+### Manual Python installation
+
+```bash
+pip install mysql-mcp-server
+```
+
+The Python package remains available for source-oriented deployments, but the
+scoped npm package is the documented distribution path for this fork.
+
 ## Configuration
 
 ### Recommended: named connections
@@ -163,8 +206,8 @@ MYSQL_PORT=3306         # Optional: Database port (defaults to 3306 if not speci
 MYSQL_USER=readonly_user
 MYSQL_PASSWORD=your_password
 MYSQL_DATABASE=your_database # Optional: Omit for multi-database mode
-
-# Advanced Configuration
+
+# Advanced Configuration
 MYSQL_SSL_MODE=REQUIRED  # DISABLED, REQUIRED, VERIFY_CA, VERIFY_IDENTITY
 MYSQL_SSL_CA=            # required for VERIFY_CA / VERIFY_IDENTITY
 MYSQL_CONNECT_TIMEOUT=10 # Timeout in seconds
@@ -183,18 +226,18 @@ MYSQL_AUDIT_REQUIRED_CONTEXT=actor,purpose,ticket_id
 MYSQL_AUDIT_FAIL_CLOSED=true
 MYSQL_AUDIT_FSYNC=true
 MYSQL_ALLOWED_DATABASES=your_database
-
-# Connection behaviour (Optional)
-MYSQL_SQL_MODE=TRADITIONAL           # SQL mode applied to the connection (default: TRADITIONAL)
-
-# Compatibility (Optional)
-MYSQL_CHARSET=utf8mb4
-MYSQL_COLLATION=utf8mb4_unicode_ci
-MYSQL_AUTH_PLUGIN=       # e.g., mysql_native_password for older MySQL versions
-MYSQL_USE_PURE=false     # Force the pure-Python connector (default: false)
-MYSQL_RAISE_ON_WARNINGS=false        # Raise on SQL warnings (default: false)
-
-# SSE Transport (Optional)
+
+# Connection behaviour (Optional)
+MYSQL_SQL_MODE=TRADITIONAL           # SQL mode applied to the connection (default: TRADITIONAL)
+
+# Compatibility (Optional)
+MYSQL_CHARSET=utf8mb4
+MYSQL_COLLATION=utf8mb4_unicode_ci
+MYSQL_AUTH_PLUGIN=       # e.g., mysql_native_password for older MySQL versions
+MYSQL_USE_PURE=false     # Force the pure-Python connector (default: false)
+MYSQL_RAISE_ON_WARNINGS=false        # Raise on SQL warnings (default: false)
+
+# SSE Transport (Optional)
 MCP_TRANSPORT=stdio      # stdio or sse
 MCP_SSE_HOST=127.0.0.1   # Safe default: loopback only
 PORT=8000                # HTTP port (fallback for MCP_SSE_PORT)
@@ -202,30 +245,30 @@ MCP_SSE_ALLOWED_HOSTS=   # Comma-separated allowed Host headers (default: localh
 MCP_SSE_BEARER_TOKEN=    # Optional; at least 32 characters
 # Set only when an authenticated reverse proxy is the sole network entry point:
 MCP_SSE_TRUST_PROXY_AUTH=false
-
-# SSH Tunneling (Optional)
-MYSQL_SSH_ENABLE=false   # Set to true to enable
-MYSQL_SSH_HOST=          # SSH jump host
-MYSQL_SSH_PORT=22        # SSH port
-MYSQL_SSH_USER=          # SSH username
-MYSQL_SSH_KEY_PATH=      # Path to SSH private key
-MYSQL_SSH_REMOTE_HOST=localhost # Host from the perspective of the jump host
-MYSQL_SSH_REMOTE_PORT=3306
+
+# SSH Tunneling (Optional)
+MYSQL_SSH_ENABLE=false   # Set to true to enable
+MYSQL_SSH_HOST=          # SSH jump host
+MYSQL_SSH_PORT=22        # SSH port
+MYSQL_SSH_USER=          # SSH username
+MYSQL_SSH_KEY_PATH=      # Path to SSH private key
+MYSQL_SSH_REMOTE_HOST=localhost # Host from the perspective of the jump host
+MYSQL_SSH_REMOTE_PORT=3306
 MYSQL_LOCAL_PORT=0       # 0 selects a free port; the tunnel is reused
 ```
-
-### `.env` file loading
-
-On startup the server automatically loads a `.env` file via `python-dotenv`, so for local use you can simply:
-
-```bash
-cp .env.example .env   # then edit with your credentials
-```
-
-The file is read from the **process working directory** (and parent directories), which works when you run the server yourself from the project folder.
-
-> ⚠️ **Claude Code / Claude Desktop:** these hosts launch the server from their own working directory, so the project's `.env` will **not** be found and you'll see `Missing required database configuration`. Put your `MYSQL_*` values in the `env` block of the MCP config (shown in the Usage section below) rather than relying on `.env`.
-
+
+### `.env` file loading
+
+On startup the server automatically loads a `.env` file via `python-dotenv`, so for local use you can simply:
+
+```bash
+cp .env.example .env   # then edit with your credentials
+```
+
+The file is read from the **process working directory** (and parent directories), which works when you run the server yourself from the project folder.
+
+> ⚠️ **Claude Code / Claude Desktop:** these hosts launch the server from their own working directory, so the project's `.env` will **not** be found and you'll see `Missing required database configuration`. Put your `MYSQL_*` values in the `env` block of the MCP config (shown in the Usage section below) rather than relying on `.env`.
+
 ### Multi-database mode
 
 When `MYSQL_DATABASE` is not set, the server operates in multi-database mode:
@@ -239,6 +282,9 @@ All tools are declared with `readOnlyHint=true` and `destructiveHint=false`.
 
 ### `list_connections`
 Lists named profiles, default database, policy limits and readiness. It never returns hosts, usernames, passwords, or SSH key paths.
+It also returns a `database_routes` index so clients can select the correct
+profile when one environment is split across several database-specific
+connections.
 
 ### `validate_connections`
 Forces a configuration reload and reports valid/invalid profiles plus missing
@@ -271,123 +317,134 @@ Executes exactly one read-only statement.
 - **Pagination:** JSON output includes `truncated` and `next_offset`; pass that value back as `offset`.
 - **Formats:** `json` preserves structured rows and metadata; `csv` uses RFC-style quoting and explicit `NULL`.
 - **Attribution:** `audit_context` supports `actor`, `purpose`, and `ticket_id`. A profile can require any of these fields before a connection is opened.
+- **Transient connector recovery:** client-side Connector/Python failures with
+  `errno=-1` are retried once. Persistent failures report only a safe exception
+  type and lifecycle phase; connector messages are not exposed.
+
+### `query`
+Compatibility alias for `execute_sql` with the same schema and all the same
+read-only, database allowlist, masking, timeout, pagination, and audit controls.
+Stateful legacy tools such as `use_connection` and `use_database` are
+intentionally not restored because process-global selection is unsafe with
+concurrent MCP clients.
 
 ### `get_schema_info`
 Provides detailed metadata about database structures.
 - **Arguments:** `table_name`, `connection`, `database` (all optional)
-- **Output:** Column names, types, nullability, default values, and comments.
-- **Cross-database:** Pass `database.table` to query a table outside `MYSQL_DATABASE`; bare names use the configured database.
-- **Identifier rules:** Names must contain only alphanumeric characters, underscores, and `$` (dots are allowed as a separator between database and table names).
-
+- **Output:** Column names, types, nullability, default values, and comments.
+- **Cross-database:** Pass `database.table` to query a table outside `MYSQL_DATABASE`; bare names use the configured database.
+- **Identifier rules:** Names must contain only alphanumeric characters, underscores, and `$` (dots are allowed as a separator between database and table names).
+
 ### `get_table_sample`
 Fetches a representative sample of data.
 - **Arguments:** `table_name` (required), `limit` (optional integer, max 100), `offset`, `connection`, `database`, `timeout_ms`, `result_format`
-- **Use Case:** Quickly understand data formats and content without fetching large result sets.
-- **Cross-database:** Pass `database.table` to sample a table outside `MYSQL_DATABASE`; bare names use the configured database.
-- **Identifier rules:** Names must contain only alphanumeric characters, underscores, and `$` (dots are allowed as a separator between database and table names).
-
-## Available Prompts
-
-In addition to tools, the server exposes **MCP prompts** — guided, multi-step workflows that a client can launch on demand. In Claude Code they appear as slash commands (`/mcp__<server>__<prompt>`); in Claude Desktop they appear in the prompts (`+`) menu.
-
-| Prompt | Arguments | Description |
-| --- | --- | --- |
+- **Use Case:** Quickly understand data formats and content without fetching large result sets.
+- **Cross-database:** Pass `database.table` to sample a table outside `MYSQL_DATABASE`; bare names use the configured database.
+- **Identifier rules:** Names must contain only alphanumeric characters, underscores, and `$` (dots are allowed as a separator between database and table names).
+- **Bounded execution:** Sampling applies `LIMIT limit+1 OFFSET offset` in
+  MySQL and fully consumes that small result. It does not open an unbounded
+  table scan merely to return a few rows.
+
+## Available Prompts
+
+In addition to tools, the server exposes **MCP prompts** — guided, multi-step workflows that a client can launch on demand. In Claude Code they appear as slash commands (`/mcp__<server>__<prompt>`); in Claude Desktop they appear in the prompts (`+`) menu.
+
+| Prompt | Arguments | Description |
+| --- | --- | --- |
 | `explore_database` | `connection`, `database` *(optional)* | Systematically explore the selected database: discover tables, inspect schemas, sample data, and summarize it. |
 | `analyze_table` | `table_name` *(required)*; `connection`, `database` *(optional)* | Deep-dive into a specific table. Accepts `database.table` notation. |
-
-**Example (Claude Code):**
-```
-/mcp__mysql__explore_database
-/mcp__mysql__analyze_table customers
-```
-
+
+**Example (Claude Code):**
+```
+/mcp__mysql__explore_database
+/mcp__mysql__analyze_table customers
+```
+
 Both prompts orchestrate the read-only discovery, schema, and sampling tools.
-
-## Usage
-### With Claude Desktop
-Add this to your `claude_desktop_config.json`:
-```json
-{
-  "mcpServers": {
-    "mysql": {
-      "command": "uv",
-      "args": [
-        "--directory",
-        "path/to/mysql_mcp_server",
-        "run",
-        "mysql_mcp_server"
-      ],
+
+## Usage
+### With Claude Desktop
+Add this to your `claude_desktop_config.json`:
+```json
+{
+  "mcpServers": {
+    "mysql-readonly": {
+      "command": "npx",
+      "args": ["-y", "@yanzhang123/readonly-db-mcp@0.7.3"],
       "env": {
         "MYSQL_PROFILES_FILE": "C:/absolute/path/mysql-connections.toml",
         "MYSQL_DEV_PASSWORD": "your_dev_password",
         "MYSQL_PROD_PASSWORD": "your_prod_password"
       }
-    }
-  }
-}
-```
-
-For more detailed examples and agent-specific guidance, see [MCP_USECASES.md](MCP_USECASES.md).
-
-### With Visual Studio Code
-Add this to your `mcp.json`:
-```json
-{
-  "mcpServers": {
-    "mysql": {
-      "type": "stdio",
-      "command": "uvx",
-      "args": [
-        "--from",
-        "mysql-mcp-server",
-        "mysql_mcp_server"
-      ],
+    }
+  }
+}
+```
+
+For more detailed examples and agent-specific guidance, see [MCP_USECASES.md](MCP_USECASES.md).
+
+### With Visual Studio Code
+Add this to your `mcp.json`:
+```json
+{
+  "mcpServers": {
+    "mysql-readonly": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "@yanzhang123/readonly-db-mcp@0.7.3"],
       "env": {
         "MYSQL_PROFILES_FILE": "C:/absolute/path/mysql-connections.toml",
         "MYSQL_DEV_PASSWORD": "your_dev_password",
         "MYSQL_PROD_PASSWORD": "your_prod_password"
       }
-    }
-  }
-}
-```
-Note: Will need to install uv for this to work
-
-### Debugging with MCP Inspector
-While MySQL MCP Server isn't intended to be run standalone or directly from the command line with Python, you can use the MCP Inspector to debug it.
-
-The MCP Inspector provides a convenient way to test and debug your MCP implementation:
-
-```bash
-# Install dependencies
-pip install -r requirements.txt
-# Use the MCP Inspector for debugging (do not run directly with Python)
-```
-
-The MySQL MCP Server is designed to be integrated with AI applications like Claude Desktop and should not be run directly as a standalone Python program.
-
-## Development
-```bash
-# Clone the repository
+    }
+  }
+}
+```
+
+Use `npx.cmd` instead of `npx` if required by your Windows MCP host.
+
+### Debugging with MCP Inspector
+While MySQL MCP Server isn't intended to be run standalone or directly from the command line with Python, you can use the MCP Inspector to debug it.
+
+The MCP Inspector provides a convenient way to test and debug your MCP implementation:
+
+```bash
+# Install dependencies
+pip install -r requirements.txt
+# Use the MCP Inspector for debugging (do not run directly with Python)
+```
+
+The MySQL MCP Server is designed to be integrated with AI applications like Claude Desktop and should not be run directly as a standalone Python program.
+
+## Development
+```bash
+# Clone the repository
 git clone https://github.com/12zhangyan/mysql_mcp_server.git
-cd mysql_mcp_server
-# Create virtual environment
-python -m venv venv
-source venv/bin/activate  # or `venv\Scripts\activate` on Windows
-# Install development dependencies
-pip install -r requirements-dev.txt
-# Copy the example config and edit with your credentials
-cp .env.example .env
-# Edit .env with your MySQL connection details
-# Run tests
-pytest
-```
-
+cd mysql_mcp_server
+# Create virtual environment
+python -m venv venv
+# Linux/macOS: source venv/bin/activate
+# Windows PowerShell: .\venv\Scripts\Activate.ps1
+# Install development dependencies
+pip install -r requirements-dev.txt
+# Copy the example config and edit with your credentials
+# Linux/macOS: cp .env.example .env
+# Windows PowerShell: Copy-Item .env.example .env
+# Edit .env with your MySQL connection details
+# Run tests
+pytest
+```
+
 ## Security Considerations
 - **Read-only SQL gate:** Only result-producing read statements are accepted; write/DDL/transaction/locking constructs are rejected before a connection is opened.
 - **Database enforcement:** Every exposed query runs with `autocommit=false` in a read-only transaction. Normal completion rolls back; cancellation or truncation closes the socket and forces server-side rollback.
 - **Write-capable credentials:** Read-only behavior does not depend on account grants. Unrecognized stored functions/UDFs, side-effecting functions, sequence advancement and locking reads are rejected because they can hide effects inside `SELECT`.
 - **Database allowlist:** `allowed_databases` is enforced with a MySQL AST parser for tools and resource URIs; system schemas are blocked by default.
+- **Controlled metadata:** User SQL cannot query `information_schema` by
+  default. Dedicated `list_tables` and `get_schema_info` operations use narrowly
+  scoped internal metadata queries, so catalog access does not become a general
+  system-schema bypass.
 - **Resource limits:** Calls have full-operation, socket and server statement timeouts; at most 1000 rows are returned and oversized cells are truncated.
 - **Cancellation:** Cancelling the MCP request closes the active connector socket. The worker does not continue silently after the response is abandoned.
 - **Enterprise audit:** Versioned UTC JSONL events include an event ID, MCP request ID, operation, caller-supplied attribution, policy decision, target database, literal-free query fingerprint, duration, result size and outcome. SQL text and result data are never logged. Optional rotation, fsync, HMAC signatures, required context and fail-closed behavior are supported.
@@ -401,50 +458,50 @@ pytest
 - **Diagnostic Privacy:** Connection diagnostics expose an account fingerprint and privilege summary, not raw usernames or `SHOW GRANTS`; configuration paths and database-supplied error text are redacted.
 - **Least Privilege:** A dedicated `SELECT` account is recommended as additional defense, but it is not assumed by the MCP read-only enforcement. `check_connection` warns about broader grants without disabling the profile.
 - **SSE is loopback-only by default.** Configure `MCP_SSE_BEARER_TOKEN` with at least 32 characters to enable built-in bearer authentication. A non-loopback bind is refused unless bearer authentication is enabled or `MCP_SSE_TRUST_PROXY_AUTH=true` explicitly confirms that an authenticated reverse proxy is the only network entry point. Example with nginx and HTTP Basic Auth:
-
-  ```nginx
-  location /sse {
-      auth_basic "MCP";
-      auth_basic_user_file /etc/nginx/.htpasswd;
-      proxy_pass http://127.0.0.1:8000;
-      proxy_set_header Host $host;
-      proxy_buffering off;
-  }
-  location /messages/ {
-      auth_basic "MCP";
-      auth_basic_user_file /etc/nginx/.htpasswd;
-      proxy_pass http://127.0.0.1:8000;
-      proxy_set_header Host $host;
-  }
-  ```
-
+
+  ```nginx
+  location /sse {
+      auth_basic "MCP";
+      auth_basic_user_file /etc/nginx/.htpasswd;
+      proxy_pass http://127.0.0.1:8000;
+      proxy_set_header Host $host;
+      proxy_buffering off;
+  }
+  location /messages/ {
+      auth_basic "MCP";
+      auth_basic_user_file /etc/nginx/.htpasswd;
+      proxy_pass http://127.0.0.1:8000;
+      proxy_set_header Host $host;
+  }
+  ```
+
   Keep `MCP_SSE_HOST=127.0.0.1` so the proxy is the sole public entry point. If a container requires `0.0.0.0`, set `MCP_SSE_TRUST_PROXY_AUTH=true` only after network policy prevents direct access. Set `MCP_SSE_ALLOWED_HOSTS` to the hostname forwarded by the proxy.
 
 See [SECURITY.md](SECURITY.md) and [ENTERPRISE_DEPLOYMENT.md](ENTERPRISE_DEPLOYMENT.md) for deployment and audit guidance.
 Maintainers should follow [RELEASING.md](RELEASING.md) for synchronized Python/npm version releases.
-
-## Security Best Practices
-This MCP implementation requires database access to function. For security:
-1. **Create a dedicated MySQL user** with `SELECT` only
-2. **Never use root credentials** or administrative accounts
-3. **Restrict database access** to only necessary operations
-4. **Enable logging** for audit purposes
-5. **Regular security reviews** of database access
-
+
+## Security Best Practices
+This MCP implementation requires database access to function. For security:
+1. **Prefer a dedicated MySQL user** with `SELECT` only as defense in depth; MCP enforcement remains read-only even when broader credentials are supplied
+2. **Never use root credentials** or administrative accounts
+3. **Restrict `allowed_databases`** to the schemas each profile needs
+4. **Require audit attribution** and protect the optional HMAC key in a secret manager
+5. **Review masking patterns, audit events, dependency updates, and account grants regularly**
+
 See [MySQL Security Configuration Guide](https://github.com/12zhangyan/mysql_mcp_server/blob/main/SECURITY.md) for detailed instructions on:
-- Creating a restricted MySQL user
-- Setting appropriate permissions
-- Monitoring database access
-- Security best practices
-
-⚠️ IMPORTANT: Always follow the principle of least privilege when configuring database access.
-
-## License
-MIT License - see LICENSE file for details.
-
-## Contributing
-1. Fork the repository
-2. Create your feature branch (`git checkout -b feature/amazing-feature`)
-3. Commit your changes (`git commit -m 'Add some amazing feature'`)
-4. Push to the branch (`git push origin feature/amazing-feature`)
-5. Open a Pull Request
+- Creating a restricted MySQL user
+- Setting appropriate permissions
+- Monitoring database access
+- Security best practices
+
+⚠️ IMPORTANT: Always follow the principle of least privilege when configuring database access.
+
+## License
+MIT License - see LICENSE file for details.
+
+## Contributing
+1. Fork the repository
+2. Create your feature branch (`git checkout -b feature/amazing-feature`)
+3. Commit your changes (`git commit -m 'Add some amazing feature'`)
+4. Push to the branch (`git push origin feature/amazing-feature`)
+5. Open a Pull Request

package/SECURITY.md

@@ -1,137 +1,137 @@
-## MySQL Security Configuration
-
-### Creating a Restricted MySQL User
-
-It's crucial to create a dedicated MySQL user with minimal permissions for the MCP server. Never use the root account or a user with full administrative privileges.
-
-#### 1. Create a new MySQL user
-
-```sql
--- Connect as root or administrator
-CREATE USER 'mcp_user'@'localhost' IDENTIFIED BY 'your_secure_password';
-```
-
-#### 2. Grant minimal required permissions
-
-Basic read-only access (recommended for exploration and analysis):
-```sql
--- Grant SELECT permission only
-GRANT SELECT ON your_database.* TO 'mcp_user'@'localhost';
-```
-
+## MySQL Security Configuration
+
+### Creating a Restricted MySQL User
+
+It's crucial to create a dedicated MySQL user with minimal permissions for the MCP server. Never use the root account or a user with full administrative privileges.
+
+#### 1. Create a new MySQL user
+
+```sql
+-- Connect as root or administrator
+CREATE USER 'mcp_user'@'localhost' IDENTIFIED BY 'your_secure_password';
+```
+
+#### 2. Grant minimal required permissions
+
+Basic read-only access (recommended for exploration and analysis):
+```sql
+-- Grant SELECT permission only
+GRANT SELECT ON your_database.* TO 'mcp_user'@'localhost';
+```
+
 Do not grant `INSERT`, `UPDATE`, `DELETE`, DDL, routine execution, file, lock, or
 temporary-table privileges to the MCP account. The server rejects those operations,
 and MySQL permissions provide the final security boundary.
-
-#### 3. Apply the permissions
-```sql
-FLUSH PRIVILEGES;
-```
-
-### Additional Security Measures
-
-1. **Network Access**
-   - Restrict the user to connecting only from localhost if the MCP server runs on the same machine
-   - If remote access is needed, specify exact IP addresses rather than using wildcards
-
-2. **Query Restrictions**
-   - Consider using VIEWs to further restrict data access
+
+#### 3. Apply the permissions
+```sql
+FLUSH PRIVILEGES;
+```
+
+### Additional Security Measures
+
+1. **Network Access**
+   - Restrict the user to connecting only from localhost if the MCP server runs on the same machine
+   - If remote access is needed, specify exact IP addresses rather than using wildcards
+
+2. **Query Restrictions**
+   - Consider using VIEWs to further restrict data access
    - Set an appropriate `max_queries_per_hour` limit:
-   ```sql
-   ALTER USER 'mcp_user'@'localhost' 
+   ```sql
+   ALTER USER 'mcp_user'@'localhost' 
    WITH MAX_QUERIES_PER_HOUR 1000;
-   ```
-
-3. **Data Access Control**
-   - Grant access only to specific tables when possible
-   - Use column-level permissions for sensitive data:
-   ```sql
-   GRANT SELECT (public_column1, public_column2) 
-   ON your_database.sensitive_table TO 'mcp_user'@'localhost';
-   ```
-
-4. **Regular Auditing**
-   - Enable MySQL audit logging for the MCP user
-   - Regularly review logs for unusual patterns
-   - Periodically review and adjust permissions
-
-### Environment Configuration
-
-When setting up the MCP server, use these restricted credentials in your environment:
-
-```bash
-MYSQL_USER=mcp_user
-MYSQL_PASSWORD=your_secure_password
-MYSQL_DATABASE=your_database
-MYSQL_HOST=localhost
-```
-
-### Monitoring Usage
-
-To monitor the MCP user's database usage:
-
-```sql
--- Check current connections
-SELECT * FROM information_schema.PROCESSLIST 
-WHERE user = 'mcp_user';
-
--- View user privileges
-SHOW GRANTS FOR 'mcp_user'@'localhost';
-
--- Check resource limits
-SELECT * FROM mysql.user 
-WHERE user = 'mcp_user' AND host = 'localhost';
-```
-
-### Best Practices
-
-1. **Regular Password Rotation**
-   - Change the MCP user's password periodically
-   - Use strong, randomly generated passwords
-   - Update application configurations after password changes
-
-2. **Permission Review**
-   - Regularly audit granted permissions
-   - Remove unnecessary privileges
-   - Keep permissions as restrictive as possible
-
-3. **Access Patterns**
-   - Monitor query patterns for potential issues
-   - Set up alerts for unusual activity
-   - Maintain detailed logs of database access
-
-4. **Data Protection**
-   - Consider encrypting sensitive columns
-   - Use SSL/TLS for database connections (see **SSL/TLS Support** below)
-   - Implement data masking where appropriate
-
-### Secure Remote Access (SSH Tunneling)
-
-If your MySQL server is not on the same network as the MCP server, **do not expose MySQL directly to the internet.** Instead, use the built-in SSH tunneling support:
-
-1. Enable SSH tunneling by setting `MYSQL_SSH_ENABLE=true`.
-2. Configure your SSH jump host credentials and private key path.
-3. The MCP server will establish a secure encrypted tunnel and connect to MySQL over `localhost`, keeping your database port closed to the outside world.
-
-### SSL/TLS Support
-
-For production environments, always encrypt the connection between the MCP server and MySQL.
-
+   ```
+
+3. **Data Access Control**
+   - Grant access only to specific tables when possible
+   - Use column-level permissions for sensitive data:
+   ```sql
+   GRANT SELECT (public_column1, public_column2) 
+   ON your_database.sensitive_table TO 'mcp_user'@'localhost';
+   ```
+
+4. **Regular Auditing**
+   - Enable MySQL audit logging for the MCP user
+   - Regularly review logs for unusual patterns
+   - Periodically review and adjust permissions
+
+### Environment Configuration
+
+When setting up the MCP server, use these restricted credentials in your environment:
+
+```bash
+MYSQL_USER=mcp_user
+MYSQL_PASSWORD=your_secure_password
+MYSQL_DATABASE=your_database
+MYSQL_HOST=localhost
+```
+
+### Monitoring Usage
+
+To monitor the MCP user's database usage:
+
+```sql
+-- Check current connections
+SELECT * FROM information_schema.PROCESSLIST 
+WHERE user = 'mcp_user';
+
+-- View user privileges
+SHOW GRANTS FOR 'mcp_user'@'localhost';
+
+-- Check resource limits
+SELECT * FROM mysql.user 
+WHERE user = 'mcp_user' AND host = 'localhost';
+```
+
+### Best Practices
+
+1. **Regular Password Rotation**
+   - Change the MCP user's password periodically
+   - Use strong, randomly generated passwords
+   - Update application configurations after password changes
+
+2. **Permission Review**
+   - Regularly audit granted permissions
+   - Remove unnecessary privileges
+   - Keep permissions as restrictive as possible
+
+3. **Access Patterns**
+   - Monitor query patterns for potential issues
+   - Set up alerts for unusual activity
+   - Maintain detailed logs of database access
+
+4. **Data Protection**
+   - Consider encrypting sensitive columns
+   - Use SSL/TLS for database connections (see **SSL/TLS Support** below)
+   - Implement data masking where appropriate
+
+### Secure Remote Access (SSH Tunneling)
+
+If your MySQL server is not on the same network as the MCP server, **do not expose MySQL directly to the internet.** Instead, use the built-in SSH tunneling support:
+
+1. Enable SSH tunneling by setting `MYSQL_SSH_ENABLE=true`.
+2. Configure your SSH jump host credentials and private key path.
+3. The MCP server will establish a secure encrypted tunnel and connect to MySQL over `localhost`, keeping your database port closed to the outside world.
+
+### SSL/TLS Support
+
+For production environments, always encrypt the connection between the MCP server and MySQL.
+
 Use the `MYSQL_SSL_MODE` environment variable to control encryption:
 - `DISABLED`: Allows plaintext only when explicitly selected; do not use in production.
 - `REQUIRED`: Ensures the connection is encrypted.
-- `VERIFY_CA`: Encrypts and verifies the server's certificate against a CA.
-- `VERIFY_IDENTITY`: Encrypts and verifies that the server's hostname matches the certificate.
-
+- `VERIFY_CA`: Encrypts and verifies the server's certificate against a CA.
+- `VERIFY_IDENTITY`: Encrypts and verifies that the server's hostname matches the certificate.
+
 `REQUIRED` is the default, and the MCP verifies after connection that the
 connector reports an encrypted session. Specify the CA certificate path using
 `MYSQL_SSL_CA` when using either verification mode.
-
+
 ### SQL Injection Protection
-
-The MCP server includes built-in protection against SQL injection for administrative operations:
-- All database and table identifiers provided via resources or tool arguments are strictly validated against a regex whitelist (`^[a-zA-Z0-9_$]+$`).
-- Identifiers are automatically quoted with backticks in internal queries.
+
+The MCP server includes built-in protection against SQL injection for administrative operations:
+- All database and table identifiers provided via resources or tool arguments are strictly validated against a regex whitelist (`^[a-zA-Z0-9_$]+$`).
+- Identifiers are automatically quoted with backticks in internal queries.
 - `execute_sql` uses a lexer-style guard that ignores ordinary strings and comments but rejects MySQL `/*!...*/` and MariaDB `/*M!...*/` executable comments, multiple statements, DML, DDL, locks, transactions, `SELECT INTO`, and session assignment.
 - Stored functions and UDFs are fail-closed unless sqlglot recognizes them as a
   built-in or their reviewed name is explicitly listed in `allowed_functions`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yanzhang123/readonly-db-mcp",
-  "version": "0.7.2",
+  "version": "0.7.4",
   "description": "Enterprise-auditable, strictly read-only MySQL MCP server with multi-environment profiles.",
   "license": "MIT",
   "type": "commonjs",