@yanzhang123/readonly-db-mcp 0.7.2

package/ENTERPRISE_DEPLOYMENT.md

@@ -0,0 +1,211 @@
+# Enterprise Deployment and Audit Guide
+
+This guide describes a defense-in-depth deployment of MySQL MCP Server. The MCP
+enforces its read-only contract even when the supplied database account has
+write privileges. Database least privilege remains a recommended independent
+containment layer rather than a correctness prerequisite.
+
+## Required Security Baseline
+
+1. Run the MCP as a dedicated operating-system identity.
+2. When organizational controls permit it, use one dedicated MySQL account per
+   environment with only `SELECT` and `SHOW VIEW`. Broader credentials remain
+   supported and are reported as a defense-in-depth warning.
+3. Configure `allowed_databases` for every profile.
+4. Require verified TLS (`VERIFY_CA` or `VERIFY_IDENTITY`) or an SSH tunnel.
+5. Store database passwords, bearer tokens and audit signing keys in a secret
+   manager and expose them only as process environment variables.
+6. Enable durable, signed, fail-closed audit logging for production profiles.
+7. Keep SSE on loopback behind an authenticated gateway, or configure the
+   built-in bearer token.
+8. Forward JSONL audit events to an append-only SIEM and alert on denials,
+   timeouts, repeated errors and privilege-assessment warnings.
+9. Review `mask_columns` against the organization's data classification catalog
+   and expose database views that omit sensitive fields where possible.
+
+## Database Account
+
+The MCP does not require a read-only account. Its SQL gate, AST policy, unknown
+function/UDF rejection and MySQL read-only transaction are applied regardless
+of grants. If a least-privilege account is available, the following is suggested
+DDL for a DBA to review and execute. The MCP server does not execute privilege
+changes:
+
+```sql
+CREATE USER 'mcp_reader'@'approved_source'
+  IDENTIFIED BY 'secret-manager-generated-password'
+  REQUIRE SSL;
+
+GRANT SELECT, SHOW VIEW ON `application_database`.*
+  TO 'mcp_reader'@'approved_source';
+```
+
+Prefer not to grant `INSERT`, `UPDATE`, `DELETE`, `CREATE`, `ALTER`, `DROP`, `FILE`,
+`PROCESS`, `EXECUTE`, `CREATE ROUTINE`, `EVENT`, `TRIGGER`, `LOCK TABLES` or
+global privileges. `check_connection` returns a `read_only_assessment`, reports
+any non-read privileges it finds, and continues operating in strict read-only
+mode.
+
+## Production Profile
+
+```toml
+[connections.prod]
+host = "prod-read.example.internal"
+port = 3306
+user = "mcp_reader"
+password_env = "MYSQL_PROD_PASSWORD"
+database = "application_database"
+allowed_databases = ["application_database"]
+# Unrecognized stored functions/UDFs are blocked. This list should normally
+# remain empty. Add only reviewed deterministic functions with no side effects.
+allowed_functions = []
+mask_columns = ["password", "passwd", "*secret*", "*token*", "*api_key*", "*private_key*", "ssn", "id_card", "phone", "email"]
+
+ssl_mode = "VERIFY_IDENTITY"
+ssl_ca = "/etc/mysql-mcp/company-ca.pem"
+query_timeout_ms = 15000
+max_rows = 200
+max_cell_length = 20000
+pool_size = 5
+result_format = "json"
+
+audit_enabled = true
+audit_log_file = "/var/log/mysql-mcp/audit.jsonl"
+audit_log_max_bytes = 10000000
+audit_log_backup_count = 20
+audit_hmac_key_env = "MYSQL_MCP_AUDIT_SIGNING_KEY"
+audit_required_context = ["actor", "purpose", "ticket_id"]
+audit_fail_closed = true
+audit_fsync = true
+```
+
+All database tools accept:
+
+```json
+{
+  "audit_context": {
+    "actor": "reporting-service",
+    "purpose": "monthly reconciliation",
+    "ticket_id": "FIN-2026-042"
+  }
+}
+```
+
+The server rejects a request missing a profile-required field before opening a
+database connection. Context values have length and control-character checks.
+Because MCP resource reads cannot carry tool arguments, profiles with required
+audit context must be accessed through the database tools; resource reads are
+intentionally denied instead of bypassing attribution policy.
+
+## Write-Capable Credential Model
+
+The account privilege assessment is advisory and never weakens query policy.
+With a write-capable or administrative account:
+
+- DML, DDL, transaction control, assignment, multiple statements, file output,
+  system-schema access and locking reads are still rejected before connection.
+- Every connector session uses `autocommit=false`, sets the transaction
+  read-only and starts `START TRANSACTION READ ONLY`.
+- Completion always rolls back; cancellation or truncated results close the
+  socket so the server rolls back.
+- Unknown stored functions and native UDFs are rejected because a function call
+  inside `SELECT` may write data or invoke external side effects.
+- Known lock, wait, file, sequence and session-mutating functions remain blocked.
+
+`allowed_functions` is an explicit escape hatch for a reviewed deterministic
+function. Adding a function moves that function into the organization's trusted
+computing boundary; do not allow a name whose implementation can be changed by
+the same write-capable account.
+
+## Audit Event
+
+Each line is canonical JSON containing:
+
+- `schema_version`, `timestamp`, `event_id`, `request_id`
+- `operation`, optional MCP client metadata and supplied audit context
+- `connection`, `database`, `query_type`, `query_id`
+- `policy`, `internal`, `read_only_enforced`
+- `status`, `duration_ms`, `row_count`, `truncated`, optional `error_type`
+- optional `signature_algorithm` and `signature`
+
+The query ID is a non-reversible fingerprint with literals removed. SQL text,
+result rows, credentials, hosts, usernames and private-key paths are excluded.
+Denied SQL receives an audit event even though it never reaches MySQL.
+In fail-closed mode, the server first persists and fsyncs a `started` event
+before opening the database connection, then writes a terminal outcome. Alert
+on unmatched started events and preserve them during incident review.
+
+Result masking is a final egress control, not an authorization boundary. Output
+names matching `mask_columns` are redacted, and any sensitive source column
+found through an alias, expression, subquery, or CTE causes conservative
+redaction. Validate patterns with representative queries and prefer restricted
+views or column grants for fields that must never be exposed.
+
+When HMAC signing is enabled, verify a line by removing `signature`, serializing
+the remaining object as UTF-8 JSON with sorted keys and compact separators, and
+computing HMAC-SHA256 with the signing key. Rotation protects disk usage; an
+external append-only log service is still required to detect deletion of whole
+files.
+
+`actor`, `purpose`, `ticket_id` and MCP client metadata are caller assertions.
+For strong human identity, an authenticated gateway must bind its verified
+principal to the MCP request and protect access to the MCP endpoint.
+
+## SSE Deployment
+
+The safe default is:
+
+```dotenv
+MCP_TRANSPORT=sse
+MCP_SSE_HOST=127.0.0.1
+MCP_SSE_PORT=8000
+```
+
+For built-in bearer authentication:
+
+```dotenv
+MCP_SSE_BEARER_TOKEN=<secret-manager-value-of-at-least-32-characters>
+```
+
+The token protects both `/sse` and `/messages/`; `/` remains a non-sensitive
+health endpoint. For a reverse proxy, keep the MCP on loopback. A container that
+must bind `0.0.0.0` may set `MCP_SSE_TRUST_PROXY_AUTH=true` only when network
+policy prevents direct access to the container port.
+
+## Monitoring
+
+Recommended alerts:
+
+- any `policy=denied`
+- any `status` of `timeout`, `cancelled`, or `error`
+- an audit sink/signing failure
+- `check_connection.read_only_assessment.account_select_only=false`
+- repeated queries approaching the timeout or row cap
+- unexpected profile, database, client, actor or ticket values
+
+Retain audit logs according to organizational and regulatory policy. Restrict
+file permissions to the MCP service account and log collector; keep HMAC keys
+outside the log host when possible.
+
+## Acceptance Evidence
+
+The 0.7.0 implementation was tested against a real external MySQL
+`8.0.46-0ubuntu0.22.04.3` instance whose account had non-read privileges. Only
+read-only operations were sent:
+
+- configuration validation, connection health and grants inspection
+- allowed-database discovery and system-schema filtering
+- table/schema metadata reads
+- normal query execution and pagination
+- pre-connection rejection of DML, DDL, multiple statements, locking reads and
+  system-schema access
+- durable JSONL events, required context, HMAC signatures and denial auditing
+- two-phase fail-closed audit records persisted before database connection
+- output/source-column masking, including alias and CTE cases
+- absence of SQL text, database host and credentials from audit records
+- encrypted transport verification (`TLS_AES_128_GCM_SHA256` on the tested
+  connection)
+
+No write or DDL statement was sent to the database during acceptance testing.
+Timeout/cancellation socket termination remains covered by deterministic
+automated tests rather than an intentionally expensive production query.

package/LICENSE

@@ -0,0 +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
+SOFTWARE.

package/README.md

@@ -0,0 +1,450 @@
+[![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.
+
+## Features
+- **Named connection profiles** for dev/test/staging/prod and multiple servers
+- Select a `connection` and `database` independently on every tool call
+- **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)
+- Legacy single-connection `MYSQL_*` configuration remains supported
+- **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
+
+## Installation
+
+### npm / npx
+
+The npm package contains the matching Python wheel and exposes a cross-platform
+launcher:
+
+```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 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
+```
+
+## Configuration
+
+### Recommended: named connections
+
+Copy [`mysql-connections.example.toml`](mysql-connections.example.toml) to an ignored local file named `mysql-connections.toml`, then define all environments in one place:
+
+```toml
+default = "dev"
+
+[connections.dev]
+description = "Local development"
+host = "127.0.0.1"
+port = 3306
+user = "readonly_user"
+password_env = "MYSQL_DEV_PASSWORD"
+database = "app_dev"
+allowed_databases = ["app_dev", "analytics_dev"]
+query_timeout_ms = 30000
+max_rows = 500
+max_cell_length = 20000
+result_format = "json"
+mask_columns = ["password", "passwd", "*secret*", "*token*", "*api_key*", "*private_key*", "ssn", "id_card", "phone", "email"]
+pool_size = 3
+audit_enabled = true
+
+[connections.prod]
+description = "Production read replica"
+host = "prod-read.example.internal"
+user = "readonly_user"
+password_env = "MYSQL_PROD_PASSWORD"
+database = "app"
+allowed_databases = ["app", "reporting"]
+allowed_functions = [] # reviewed deterministic UDF/stored-function names only
+query_timeout_ms = 15000
+max_rows = 200
+result_format = "json"
+mask_columns = ["password", "passwd", "*secret*", "*token*", "*api_key*", "*private_key*", "ssn", "id_card", "phone", "email"]
+pool_size = 5
+ssl_mode = "VERIFY_CA"
+ssl_ca = "C:/certs/company-ca.pem"
+
+# Enterprise audit controls
+audit_enabled = true
+audit_log_file = "C:/var/log/mysql-mcp/audit.jsonl"
+audit_log_max_bytes = 10000000
+audit_log_backup_count = 10
+audit_hmac_key_env = "MYSQL_MCP_AUDIT_SIGNING_KEY"
+audit_required_context = ["actor", "purpose", "ticket_id"]
+audit_fail_closed = true
+audit_fsync = true
+```
+
+Point the MCP process at that file and supply only the secrets through environment variables:
+
+```bash
+MYSQL_PROFILES_FILE=C:/absolute/path/mysql-connections.toml
+MYSQL_DEV_PASSWORD=...
+MYSQL_PROD_PASSWORD=...
+MYSQL_MCP_AUDIT_SIGNING_KEY=... # secret-manager supplied; never commit
+MYSQL_DEFAULT_CONNECTION=dev  # optional; overrides `default` in TOML
+MYSQL_MAX_ROWS=500             # optional; 1-1000, default 500
+MYSQL_QUERY_TIMEOUT_MS=30000   # full-call timeout, 100-300000 ms
+MYSQL_MAX_CELL_LENGTH=20000    # truncate oversized values
+MYSQL_RESULT_FORMAT=json       # csv or json
+MYSQL_MASK_COLUMNS=password,passwd,*secret*,*token*,*api_key*,*private_key*,ssn,id_card,phone,email
+MYSQL_POOL_SIZE=0              # legacy mode; named profiles default to 5
+MYSQL_ALLOWED_DATABASES=app,reporting
+MYSQL_ALLOWED_FUNCTIONS=              # optional reviewed function names
+```
+
+`password_env` is recommended. A `password` field is accepted for local-only setups, but `mysql-connections.toml` is gitignored because it may contain secrets. Use an absolute `MYSQL_PROFILES_FILE` path in desktop MCP clients because their working directory is not guaranteed.
+
+Each tool call can now target an environment without restarting the server:
+
+```json
+{
+  "connection": "prod",
+  "database": "app",
+  "query": "SELECT COUNT(*) FROM orders",
+  "audit_context": {
+    "actor": "reporting-service",
+    "purpose": "month-end reconciliation",
+    "ticket_id": "FIN-2026-042"
+  }
+}
+```
+
+There is deliberately no process-global “switch” tool: explicit per-call selection prevents one concurrent MCP client from silently changing another client's active environment.
+
+The profiles file is hot-reloaded when its size or modification time changes.
+One invalid profile is reported by `validate_connections` without disabling other
+valid profiles. Password environment variables are resolved only when their
+profile is used, so an unavailable production credential does not break local
+development.
+
+### Legacy single connection
+
+If `MYSQL_PROFILES_FILE` is not set, the original environment variables still work:
+
+```bash
+MYSQL_HOST=localhost     # Database host
+MYSQL_PORT=3306         # Optional: Database port (defaults to 3306 if not specified)
+MYSQL_USER=readonly_user
+MYSQL_PASSWORD=your_password
+MYSQL_DATABASE=your_database # Optional: Omit for multi-database mode
+
+# 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
+MYSQL_QUERY_TIMEOUT_MS=30000
+MYSQL_MAX_ROWS=500
+MYSQL_MAX_CELL_LENGTH=20000
+MYSQL_RESULT_FORMAT=json
+MYSQL_POOL_SIZE=0
+MYSQL_AUDIT_ENABLED=true
+MYSQL_AUDIT_LOG_FILE=C:/var/log/mysql-mcp/audit.jsonl
+MYSQL_AUDIT_LOG_MAX_BYTES=10000000
+MYSQL_AUDIT_LOG_BACKUP_COUNT=10
+MYSQL_AUDIT_HMAC_KEY_ENV=MYSQL_MCP_AUDIT_SIGNING_KEY
+MYSQL_MCP_AUDIT_SIGNING_KEY=replace-with-secret-manager-value
+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)
+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)
+MCP_SSE_ALLOWED_HOSTS=   # Comma-separated allowed Host headers (default: localhost:{port},127.0.0.1:{port})
+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
+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`.
+
+### Multi-database mode
+
+When `MYSQL_DATABASE` is not set, the server operates in multi-database mode:
+- `list_resources` returns all user databases (system databases are filtered out)
+- Pass `database` to any data tool, or use fully qualified names such as `mydb.mytable`
+- `USE` and multiple statements are intentionally blocked
+
+## Available Tools
+
+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.
+
+### `validate_connections`
+Forces a configuration reload and reports valid/invalid profiles plus missing
+password environment variables without opening database connections.
+
+### `check_connection`
+Runs `SELECT`/`SHOW GRANTS` health checks and returns MySQL version, current
+database, an irreversible account fingerprint, global read-only state, grant
+count, latency and active profile policy. Raw usernames and grant statements are
+not returned. It classifies non-read privileges and warns when the account does
+not provide read-only defense in depth.
+
+### `list_databases`
+Lists accessible non-system databases.
+- **Arguments:** `connection` (optional)
+
+### `list_tables`
+Lists tables and views in a database.
+- **Arguments:** `connection`, `database` (both optional)
+
+### `execute_sql`
+Executes exactly one read-only statement.
+- **Arguments:** `query` (required); `connection`, `database`, `max_rows`, `offset`, `timeout_ms`, `result_format`, `audit_context` (optional unless required by the profile)
+- **Allowed statement families:** `SELECT`, `WITH`, `SHOW`, `DESCRIBE`, `DESC`, `EXPLAIN`, `TABLE`
+- **Always blocked:** DML, DDL, `USE`, transaction control, locks, `SELECT ... INTO`, session-variable assignment, MySQL executable comments, and multiple statements
+- **Function policy:** unresolved stored functions/UDFs are blocked by default because `SELECT function(...)` can hide database or external side effects. `allowed_functions` is an explicit reviewed-function exception.
+- **Defense in depth:** validation occurs before connecting; MySQL then executes inside `START TRANSACTION READ ONLY`. Completed calls roll back; truncated/cancelled calls close the socket so MySQL rolls back and stops producing unread rows.
+- **Cross-database:** use the `database` argument or a qualified `database.table` name
+- **Timeout/cancellation:** profile timeout, Connector socket timeout and MySQL/MariaDB statement timeout are combined. MCP cancellation closes the active socket; no `KILL` privilege is required.
+- **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.
+
+### `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).
+
+### `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 |
+| --- | --- | --- |
+| `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
+```
+
+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"
+      ],
+      "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"
+      ],
+      "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
+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
+```
+
+## 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.
+- **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.
+- **Two-phase audit:** In fail-closed mode, an fsynced `started` event is persisted before opening a database connection, followed by the terminal outcome event.
+- **Result masking:** Sensitive output names are redacted by default. Queries whose expression tree references a sensitive source column are conservatively redacted even when aliases or CTEs hide the original name. Review `mask_columns` for each schema; setting it to an empty list explicitly disables masking.
+- **Encrypted by default:** Database TLS defaults to `REQUIRED` and the connected session is rejected if the connector reports plaintext. Production profiles should use `VERIFY_CA` or `VERIFY_IDENTITY` with `ssl_ca`.
+- **Parser hardening:** MySQL `/*!...*/` and MariaDB `/*M!...*/` executable comments are rejected, and server-wide `SHOW` variants are blocked unless they can be scoped to an allowed database.
+- **Identifier Validation:** Table and database names passed to `get_schema_info` and `get_table_sample` are validated against a strict whitelist (alphanumeric, underscore, and `$` only; a single dot is allowed as a `database.table` separator). Other special characters are rejected to prevent SQL injection.
+- **Encrypted Access:** Full support for SSL/TLS and SSH Tunneling for secure remote connections.
+- **Log Privacy:** SQL text, passwords, hosts, usernames and SSH private-key paths are not included in tool discovery or audit events.
+- **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;
+  }
+  ```
+
+  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
+
+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