@yanzhang123/readonly-db-mcp 0.9.14 → 0.9.15

package/README.md

@@ -41,13 +41,22 @@
 npx -y @yanzhang123/readonly-db-mcp
 ```
 
-生产环境建议固定经过审核的版本：
+生产环境建议固定经过审核的版本，在包名后加 `@<版本>`，版本号见 [npm 页面](https://www.npmjs.com/package/@yanzhang123/readonly-db-mcp?activeTab=versions)。
+
+首次运行时，启动器会在用户缓存目录创建版本化虚拟环境，并安装包内 wheel 与带 SHA-256 锁定的 Python 依赖。完成后的环境按 wheel 和依赖锁指纹复用。可通过 `MYSQL_MCP_PYTHON` 指定 Python，通过 `MYSQL_MCP_NPM_CACHE_DIR` 修改缓存位置。
+
+### Claude Code 一行安装
+
+先复制 [`mysql-connections.example.toml`](mysql-connections.example.toml) 为本地配置文件，再把配置文件的绝对路径和密码环境变量交给 Claude Code：
 
 ```bash
-npx -y @yanzhang123/readonly-db-mcp@0.9.1
+claude mcp add mysql-readonly \
+  -e MYSQL_PROFILES_FILE=/absolute/path/mysql-connections.toml \
+  -e MYSQL_DEV_PASSWORD=由密钥存储提供 \
+  -- npx -y @yanzhang123/readonly-db-mcp
 ```
 
-首次运行时，启动器会在用户缓存目录创建版本化虚拟环境，并安装包内 wheel 与带 SHA-256 锁定的 Python 依赖。完成后的环境按 wheel 和依赖锁指纹复用。可通过 `MYSQL_MCP_PYTHON` 指定 Python，通过 `MYSQL_MCP_NPM_CACHE_DIR` 修改缓存位置。
+Windows 上无法启动 `npx` 时改用 `npx.cmd`。其他客户端的配置见 [客户端配置](https://github.com/12zhangyan/mysql_mcp_server/blob/main/docs/CONFIGURATION.md#mcp-客户端配置)。
 
 ### 最小 MCP 配置
 
@@ -58,7 +67,7 @@ npx -y @yanzhang123/readonly-db-mcp@0.9.1
   "mcpServers": {
     "mysql-readonly": {
       "command": "npx",
-      "args": ["-y", "@yanzhang123/readonly-db-mcp@0.9.1"],
+      "args": ["-y", "@yanzhang123/readonly-db-mcp"],
       "env": {
         "MYSQL_PROFILES_FILE": "C:/absolute/path/mysql-connections.toml",
         "MYSQL_DEV_PASSWORD": "由客户端密钥存储提供"
@@ -82,529 +91,26 @@ cd mysql_mcp_server
 pip install ".[http]"   # 只用 STDIO 时可省略 [http]
 ```
 
-## 配置
-
-### 结果脱敏配置
-
-**默认不脱敏。** 代码不再内置敏感字段名单；省略配置或配置为空时，所有结果字段（包括密码、Token、联系方式及 JSON 内键）均按查询结果返回，`masked_columns` 为空。
-
-命名连接通过 `mask_columns` 指定要隐藏的字段。配置属于各自连接，支持大小写不敏感的字段名和通配符：
-
-```toml
-[connections.dev]
-# 其他连接参数见下方完整示例。
-mask_columns = [] # 默认全部放开；省略此项效果相同。
-# 如需脱敏，将上面一行改为自己的字段列表，例如：
-# mask_columns = ["password", "access_token", "users.phone"]
-```
-
-旧单连接模式通过 `MYSQL_MASK_COLUMNS` 配置，以逗号分隔；未设置或设为空字符串均不脱敏。例如 `MYSQL_MASK_COLUMNS=password,access_token` 只按这两个规则处理。使用命名连接文件时，以各连接自己的 `mask_columns` 为准。
-
-显式配置会把每个结果列追溯到底层表的字段：别名、表达式、函数与类型转换、窗口函数、标量子查询与关联子查询、派生表、CTE（含列清单）、`UNION`、`LATERAL`、`JSON_TABLE`、`TABLE` 语句和 `*` 都会继续追踪，并对 JSON 内匹配的键递归处理。按路径从 JSON 文档读取的值也会检查路径中的键：`JSON_EXTRACT`、`->`、`->>`、`JSON_VALUE` 和 `JSON_TABLE` 列的路径只要经过匹配不带点规则的键（例如 `$.contact.phone` 匹配 `phone`），读出的值就会隐藏；路径含通配符、递归 `**` 或不是常量时按敏感处理。派生表或 CTE 中名称匹配规则的列也视为敏感来源；只有最外层的别名不算。不带点的模式只匹配字段名，例如 `password`；带点的模式按限定路径匹配，例如 `users.phone` 或 `app.users.phone`，表别名会解析回真实表名，未写库名的表按当前库匹配。`COUNT` / `COUNT(DISTINCT ...)` 统计值可以正常读取，同一查询中匹配规则的原始值和拼接值仍会隐藏；`WHERE`、`HAVING`、`EXISTS`、`IN` 子查询里的值不会出现在结果中，不会让其他列被遮蔽。
-
-脱敏按 fail-closed 设计：某个结果列的来源无法确定时（例如无法解析的列名、子查询中可能来自外层查询的列，或 MySQL 自动生成、与表达式文本对不上的列名），只要它可能来自匹配规则的字段，就按敏感处理；SQL 分析失败时同样按保守规则处理。因此少数复杂查询可能多遮几列。
-
-脱敏是结果出口的辅助控制，不是访问授权边界：它基于 SQL 静态分析，无法看到视图定义、存储函数内部或数据库中实际的表结构，也不能排除尚未覆盖的 SQL 写法。绝不能暴露的字段，应在数据库层用只包含安全字段的视图或列级权限隔离，再让本服务使用该账号。
-
-脱敏只替换返回值，不改变 MySQL 的 `WHERE` / `JOIN` 条件或删除结果行。`[REDACTED]` 表示值被隐藏，JSON/compact 的 `masked_columns` 可定位受影响列。已有的非空配置仍会生效；需要全部放开时，把它改成空列表（单连接模式清空环境变量），或删除该配置项。
-
-### 推荐：命名连接
-
-将 [`mysql-connections.example.toml`](mysql-connections.example.toml) 复制为已被 Git 忽略的 `mysql-connections.toml`，然后集中声明各环境：
-
-```toml
-default = "dev"
-
-[connections.dev]
-description = "本地开发环境"
-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 = []
-pool_size = 3
-audit_enabled = true
-
-[connections.prod]
-description = "生产只读副本"
-host = "prod-read.example.internal"
-user = "readonly_user"
-password_env = "MYSQL_PROD_PASSWORD"
-database = "app"
-allowed_databases = ["app", "reporting"]
-allowed_functions = [] # 仅填写已经审核、确定无副作用的 UDF/存储函数
-query_timeout_ms = 15000
-max_rows = 200
-result_format = "json"
-pool_size = 5
-ssl_mode = "VERIFY_CA"
-ssl_ca = "C:/certs/company-ca.pem"
-
-# 企业审计配置
-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
-```
-
-通过环境变量提供配置路径和密钥：
-
-```bash
-MYSQL_PROFILES_FILE=C:/absolute/path/mysql-connections.toml
-MYSQL_DEV_PASSWORD=...
-MYSQL_PROD_PASSWORD=...
-MYSQL_MCP_AUDIT_SIGNING_KEY=... # 由密钥管理系统提供，禁止提交
-MYSQL_DEFAULT_CONNECTION=dev    # 可选，覆盖 TOML 中的 default
-MYSQL_MAX_ROWS=500              # 可选，1-1000，默认 500
-MYSQL_QUERY_TIMEOUT_MS=30000    # 整次调用超时，100-300000 毫秒
-MYSQL_MAX_CELL_LENGTH=20000     # 超长单元格截断长度
-MYSQL_RESULT_FORMAT=json        # json 或 csv
-MYSQL_POOL_SIZE=0               # 旧单连接模式；命名配置默认 5
-MYSQL_ALLOWED_DATABASES=app,reporting
-MYSQL_ALLOWED_FUNCTIONS=        # 可选，经过审核的函数名
-```
-
-推荐使用 `password_env`。本地环境也支持 `password` 字段，但 `mysql-connections.toml` 已加入 `.gitignore`，因为它可能包含敏感信息。桌面 MCP 客户端的工作目录不固定，因此 `MYSQL_PROFILES_FILE` 必须使用绝对路径。
+## 文档
 
-### 使用操作系统凭据库
-
-用户级 MCP 配置可使用系统凭据库，让密码不出现在 MCP JSON 或 TOML 中：
-
-```toml
-[connections.dev]
-host = "127.0.0.1"
-user = "readonly_user"
-credential_provider = "keyring"
-credential_ref = "dev"
-database = "app_dev"
-allowed_databases = ["app_dev"]
-```
-
-使用遮罩输入在本机管理凭据：
-
-```powershell
-readonly-db-mcp credentials --profiles-file C:/absolute/path/mysql-connections.toml set dev
-readonly-db-mcp credentials --profiles-file C:/absolute/path/mysql-connections.toml status dev
-readonly-db-mcp credentials --profiles-file C:/absolute/path/mysql-connections.toml delete dev
-```
-
-Windows 下 `keyring` 使用 Windows 凭据管理器。无桌面的服务环境可设置 `credential_provider = "command"`，并通过 `credential_command = ["executable", "arg1"]` 调用经过批准的密钥管理 CLI。程序不会通过 shell 执行命令；stderr 会被丢弃，输出长度受限，且只接受一行非空 UTF-8 文本。失败信息不会包含密钥、命令参数或凭据引用。
-
-每次请求最多读取一次凭据（含连接重试）。`keyring` 或 `command` 较慢时，可设置 `credential_cache_seconds = 30`（0–300，默认 0 即不缓存）在进程内存中短期复用密码：轮换后的新密码最晚在该时长后生效；服务端返回认证失败（1045/1698）、调用 `validate_connections` 或进程退出时立即丢弃缓存。该项只对 `keyring` 和 `command` 有效。
-
-### 逻辑环境路由
-
-一个逻辑环境分布在多个物理实例时，可声明精确别名：
-
-```toml
-[routes.shared-test]
-ubp = { connection = "test-ubp", database = "ubp" }
-gts = { connection = "test-gts", database = "gts" }
-eam = { connection = "test-eam", database = "eam" }
-```
-
-调用 `connection="shared-test", database="eam"` 时，只会解析到声明的目标。未知别名会明确失败，服务不会搜索或猜测其他环境。JSON 结果和审计记录会同时保留请求目标与实际目标。
-
-每次调用都可以选择环境，无需重启：
-
-```json
-{
-  "connection": "prod",
-  "database": "app",
-  "query": "SELECT COUNT(*) FROM orders",
-  "audit_context": {
-    "actor": "reporting-service",
-    "purpose": "月末对账",
-    "ticket_id": "FIN-2026-042"
-  }
-}
-```
-
-服务刻意不提供进程级“切换连接/数据库”工具。显式逐次选择可防止一个并发客户端悄悄改变另一个客户端的活动环境。
-
-配置文件的大小或修改时间变化后会自动热加载。单个配置无效时，`validate_connections` 会报告该配置，但不会停用其他有效配置。密码环境变量只在使用对应连接时解析，因此生产凭据暂时不可用不会影响本地开发环境。
-
-### 旧版单连接环境变量
-
-未设置 `MYSQL_PROFILES_FILE` 时，仍可使用原有环境变量：
-
-```bash
-MYSQL_HOST=localhost
-MYSQL_PORT=3306
-MYSQL_USER=readonly_user
-MYSQL_PASSWORD=your_password
-MYSQL_DATABASE=your_database
-MYSQL_ALLOWED_DATABASES=your_database
-
-MYSQL_SSL_MODE=REQUIRED          # DISABLED、REQUIRED、VERIFY_CA、VERIFY_IDENTITY
-MYSQL_SSL_CA=                   # VERIFY_CA / VERIFY_IDENTITY 必填
-MYSQL_CONNECT_TIMEOUT=10
-MYSQL_QUERY_TIMEOUT_MS=30000
-MYSQL_MAX_ROWS=500
-MYSQL_MAX_CELL_LENGTH=20000
-MYSQL_RESULT_FORMAT=json
-MYSQL_POOL_SIZE=0
-MYSQL_SQL_MODE=TRADITIONAL
-MYSQL_CHARSET=utf8mb4
-MYSQL_COLLATION=utf8mb4_unicode_ci
-# MYSQL_USE_PURE=true            # 默认不设置
-MYSQL_RAISE_ON_WARNINGS=false
-```
-
-`MYSQL_USE_PURE`（命名配置中为 `use_pure`）默认不设置：Connector/Python 优先使用 C 扩展，加载失败时自动退回纯 Python 实现。只有明确需要时才设置；设为 `false` 会强制要求 C 扩展，扩展不可用时连接直接失败。
-
-`MYSQL_SQL_MODE` 与命名配置的 `sql_mode` 会在每次查询的会话中显式设置（空值即设为空模式）。会改变引号或反斜杠语义的模式会被拒绝：`ANSI_QUOTES`、`NO_BACKSLASH_ESCAPES`，以及包含它们的组合模式 `ANSI`、`DB2`、`MAXDB`、`MSSQL`、`ORACLE`、`POSTGRESQL`，因为只读 SQL 闸门按 MySQL 默认规则识别字符串边界。
-
-### Streamable HTTP 传输（推荐）
-
-DeepSeek Harness 等新客户端可直接连接标准 MCP Streamable HTTP 端点：
-
-```bash
-MCP_TRANSPORT=streamable-http
-MCP_HTTP_HOST=127.0.0.1
-MCP_HTTP_PORT=8000
-MCP_HTTP_PATH=/mcp
-MCP_HTTP_ALLOWED_HOSTS=localhost:8000,127.0.0.1:8000
-MCP_HTTP_BEARER_TOKEN=          # 可选，至少 32 个字符
-MCP_HTTP_TRUST_PROXY_AUTH=false # 仅在认证反向代理是唯一入口时启用
-MCP_HTTP_SESSION_IDLE_TIMEOUT_SECONDS=1800
-```
-
-`MCP_TRANSPORT` 支持 `stdio`、`sse`、`streamable-http`（及别名 `http`）；
-未知值会在启动时直接报错，避免配置拼写错误被静默降级为 STDIO。
-HTTP/SSE 端口必须在 `1-65535` 范围内；会话空闲超时必须为正有限数。
-
-默认端点是 `http://127.0.0.1:8000/mcp`。非回环地址只有在启用 Bearer
-认证，或显式确认由认证反向代理保护时才允许启动。
-
-### 旧版 SSE 传输
-
-```bash
-MCP_TRANSPORT=sse
-MCP_SSE_HOST=127.0.0.1          # 默认仅监听回环地址
-PORT=8000                       # MCP_SSE_PORT 的后备值
-MCP_SSE_ALLOWED_HOSTS=          # 允许的 Host，逗号分隔
-MCP_SSE_BEARER_TOKEN=           # 可选，至少 32 个字符
-MCP_SSE_TRUST_PROXY_AUTH=false  # 仅在认证反向代理是唯一入口时启用
-```
-
-旧版端点为 `/sse` 和 `/messages/`，仅用于兼容现有客户端。部署细节见
-[`ENTERPRISE_DEPLOYMENT.md`](ENTERPRISE_DEPLOYMENT.md)。
-
-### SSH 隧道
-
-```bash
-MYSQL_SSH_ENABLE=false
-MYSQL_SSH_HOST=
-MYSQL_SSH_PORT=22
-MYSQL_SSH_USER=
-MYSQL_SSH_KEY_PATH=
-MYSQL_SSH_REMOTE_HOST=localhost
-MYSQL_SSH_REMOTE_PORT=3306
-MYSQL_LOCAL_PORT=0              # 0 表示自动选择端口，隧道会复用
-```
-
-### `.env` 文件
-
-服务启动时会通过 `python-dotenv` 从进程工作目录及父目录加载 `.env`：
-
-```bash
-cp .env.example .env
-```
-
-Claude Desktop、Codex 等宿主通常从自己的目录启动 MCP 服务，未必能找到项目内 `.env`。这类场景应将 `MYSQL_*` 配置放入 MCP 配置的 `env` 节点，或使用命名配置文件和凭据库。
-
-### 多数据库模式
-
-未设置 `MYSQL_DATABASE` 时，服务进入多数据库模式：
-
-- `list_resources` 返回过滤系统库后的可访问数据库
-- 数据工具通过 `database` 参数或 `database.table` 全限定名选择数据库
-- `USE` 和多语句始终被拦截
+- [配置](https://github.com/12zhangyan/mysql_mcp_server/blob/main/docs/CONFIGURATION.md)：命名连接、结果脱敏、凭据库、逻辑环境路由、传输、SSH 隧道和各客户端配置
+- [工具与提示词](https://github.com/12zhangyan/mysql_mcp_server/blob/main/docs/TOOLS.md)：12 个工具的参数、响应预算、并发控制和可纠正的错误码
+- [常见问题与排障](https://github.com/12zhangyan/mysql_mcp_server/blob/main/docs/TROUBLESHOOTING.md)
+- [开发与测试](https://github.com/12zhangyan/mysql_mcp_server/blob/main/docs/TESTING.md)
+- [企业部署](ENTERPRISE_DEPLOYMENT.md) · [安全说明](SECURITY.md) · [发布流程](https://github.com/12zhangyan/mysql_mcp_server/blob/main/RELEASING.md) · [使用场景](https://github.com/12zhangyan/mysql_mcp_server/blob/main/MCP_USECASES.md)
 
 ## 可用工具
 
-所有工具都声明 `readOnlyHint=true` 和 `destructiveHint=false`。
-
-### `list_connections`
-
-列出命名配置、默认数据库、策略限制和就绪状态，不返回主机、用户名、密码或 SSH 私钥路径。还会返回数据库路由索引和逻辑环境别名。
-
-### `validate_connections`
-
-强制重新加载配置，报告有效/无效配置及缺少的密码环境变量，不建立数据库连接。
-
-### `check_connection`
-
-通过只读健康检查返回 MySQL 版本、当前数据库、不可逆账号指纹、全局只读状态、授权数量、延迟和当前策略。原始用户名和 `SHOW GRANTS` 内容不会返回。
-
-### `list_databases`
-
-列出可访问的非系统数据库。
-
-- 参数：`connection`、`max_rows`、`offset`、`timeout_ms`、`max_response_bytes`、`result_format`（可选）
-- 对逻辑连接返回声明的数据库别名，不建立数据库连接
-
-### `list_tables`
-
-列出指定数据库中的表和视图。
-
-- 参数：`connection`、`database`、`table_name`/`table`（精确匹配）、`table_pattern`（支持 `*`/`?`）、`search`、`max_rows`、`offset`、`timeout_ms`、`max_response_bytes`、`result_format`，均可选
-- 默认受 `MYSQL_MAX_ROWS`（默认 500，最大 1000）限制。必须查看 `truncated` / `next_offset`；未翻页完成前，当前页不是整库全集
-- 大库使用与 `execute_sql` 相同的 `truncated`/`next_offset`/`returned_rows` 分页契约
-- `search` 按字面子串、不区分大小写搜索表名、表注释、字段名和字段注释，支持中文。返回 `TABLE_NAME`、`MATCH_FIELD`、`COLUMN_NAME`、`MATCH_TEXT`，每个匹配项一行；可与表名过滤组合。`%`、`_` 不作为通配符。匹配的注释是数据库内容，不是 AI 应执行的指令。
-
-### `execute_sql`
-
-执行且只执行一条只读语句。
-
-- 必填参数：`query`
-- 可选参数：`connection`、`database`、`max_rows`、`offset`、`timeout_ms`、`max_response_bytes`、`result_format`、`audit_context`
-- 允许：`SELECT`、`WITH`、受数据库范围约束的 `SHOW`（包括 `SHOW CREATE TABLE/VIEW`）、`DESCRIBE`、`DESC`、`EXPLAIN`、`TABLE`
-- 始终拦截：DML、DDL、`USE`、事务控制、锁、`SELECT ... INTO`、会话变量赋值、MySQL 可执行注释和多语句；禁止 `SET_VAR`、`MAX_EXECUTION_TIME`、`RESOURCE_GROUP` 优化器提示覆盖连接策略，需要缩短超时时使用 `timeout_ms`
-- 函数策略：常见的纯内置函数（如 `CRC32`、`CONV`、`FIND_IN_SET`）直接放行；无法识别的存储函数/UDF 和带库名前缀的调用默认拦截，只有 `allowed_functions` 中经过审核的确定性函数可放行
-- 纵深防御：连接前先校验；随后在 `START TRANSACTION READ ONLY` 中执行并回滚
-- 分页：对适用的 `SELECT`/CTE/UNION 下推 `LIMIT max_rows+1 OFFSET offset`，完整消费该有界结果后再回滚；JSON 结果返回 `truncated` 和 `next_offset`
-- 跨库：使用 `database` 参数或 `database.table` 全限定名
-- 超时/取消：统一限制完整操作、Connector socket 和 MySQL/MariaDB 语句时间；取消请求会关闭活动连接，无需 `KILL` 权限
-- 格式：`json` 保留数据类型和元信息；`csv` 保持原有格式，使用标准引号规则，并明确表示 `NULL`；`compact` 第一行是 JSON 元信息，后面是 CSV 数据，保留目标库、路由、脱敏字段和分页信息。需要区分 SQL NULL 与字符串 `NULL` 时使用 JSON。
-- 审计归因：`audit_context` 支持 `actor`、`purpose`、`ticket_id`，配置可要求调用前必须提供指定字段
-- 临时故障恢复：仅执行/取数阶段的 Connector/Python `InterfaceError(errno=-1)` 保留一次兼容重试。`ReadTimeoutError` / `WriteTimeoutError` 不重放，统一返回 `QUERY_TIMEOUT` 并丢弃活动连接；其他未知 `errno=-1`、表不存在、字段不存在、语法和权限错误不会自动重试。
-- 首次查询或结构不确定时先用 `list_tables` / `get_schema_info` 确认真实名称；每次传入一致的 `connection`、`database`。收到确定性 SQL 错误后核对元数据再改 SQL，不自动换库或改表名执行。
-
-### `explain_sql`
-
-对原始 `SELECT` / `WITH`（含 UNION）生成普通 `EXPLAIN` 执行计划，便于先检查索引、连接顺序和预估扫描行数。
-
-- 必填 `query`，传入原 SQL；不要添加 `EXPLAIN` 前缀。拒绝写语句、多语句和 `EXPLAIN ANALYZE`。
-- 可选参数与 `execute_sql` 一致，复用数据库白名单、函数策略、只读事务、审计、脱敏、超时和响应预算。
-- 保留原 SQL 中的 `LIMIT/OFFSET`；工具参数 `max_rows/offset` 只分页执行计划，避免为诊断修改原查询。
-- 默认 `plan_output=rows` 返回数据库的计划结果，格式取决于服务器设置。保留完整计划单元格，不再受普通数据的 `max_cell_length` 截断；首行超响应预算时明确返回 `RESULT_TOO_LARGE` 并提示切换分片，不交付残缺计划。
-- `plan_output=chunks` 显式请求 `EXPLAIN FORMAT=JSON`；先按原规则脱敏，再把计划文本拆成固定长度的 `part/text` 行。此时 `offset/max_rows` 针对分片，响应仍受 UTF-8 字节预算限制。默认使用 `json`，也可选 `compact`；不接受缺少计划元信息的 `csv`。
-- 第一页保留 `plan.id`。续页传 `offset=next_offset` 和 `expected_plan_id=plan.id`，按 `part` 顺序拼接 `text`，直到 `truncated=false`。分片长度、总字符数和总片数在 `plan` 中。每页重新生成计划；计划、目标或分片上下文变化时返回 `PLAN_CHANGED`，需丢弃旧片段并从 0 重取，避免混合版本。
-- 计划是估算信息，不代表实际执行耗时；工具不会自动建索引、更新统计信息或运行 ANALYZE。分片模式需要服务器支持 `EXPLAIN FORMAT=JSON`，不会自动切换到 ANALYZE 或其他数据库。
-
-```json
-{"query":"SELECT id FROM orders WHERE status = 'open' ORDER BY id LIMIT 20","connection":"dev","database":"app_dev","result_format":"json"}
-```
-
-### `query`
-
-`execute_sql` 的兼容别名，使用相同的只读、白名单、脱敏、超时、分页和审计策略。不会恢复不安全的进程级 `use_connection` 或 `use_database`。
-
-### `get_schema_info`
-
-返回数据库结构详情，包括字段名、类型、可空性、默认值和注释。
-
-- 参数：`table_name` 或兼容别名 `table`，以及 `connection`、`database`
-- 支持 `table_pattern`（与 `list_tables` 相同的 `*`/`?` glob）或 `table_names` 批量指定 1–100 张当前库的表；与 `table_name`/`table` 三者互斥。超过 100 张表会报错，不会静默截断名单。
-- 整库或批量模式也支持 `max_rows`、`offset`、`max_response_bytes`、`timeout_ms`、`result_format`。默认页大小为连接的 `MYSQL_MAX_ROWS`。必须查看 `truncated` / `next_offset`；未把 `truncated` 翻到 `false` 前，不得把当前页当作整库列全集。
-- `detail=true` 一次返回表注释、字段完整类型/默认值/可空性/附加属性/注释、索引（含 PRIMARY、列顺序、前缀长度、唯一性）及已声明的外键。结果按 `KIND` 区分 `table`、`column`、`index`、`foreign_key`；每个索引列或外键列独立成行，不用字符串聚合，避免结构信息被静默截断。不会猜测未声明的业务关联。
-- 可用 `database.table` 访问允许列表中的其他数据库
-- 同时传 `database` 和限定表名时，两者必须一致。保留相同参数并递增 `offset=next_offset`，直到 `truncated=false`。
-- 标识符只允许字母、数字、下划线、`$`，数据库与表之间允许一个点
-
-### `get_table_sample`
-
-返回具有代表性的少量样例数据。
-
-- `table_name` 或兼容别名 `table` 必须提供一个
-- 可选参数：`limit`（最大 100）、`offset`、`connection`、`database`、`timeout_ms`、`max_response_bytes`、`result_format`
-- 采样会在 MySQL 中应用 `LIMIT limit+1 OFFSET offset` 并完整消费小结果集，不会为了返回几行数据而开启无界扫描结果
-
-### `inspect_catalog`
-
-返回 `tables`、`columns`、`indexes`、`constraints`、`foreign_keys` 或 `views` 的固定元数据投影。该工具不会开放任意 `information_schema` SQL。
-
-- 过滤：`table_name`/`table` 精确匹配，或 `table_pattern`，或最多 100 个 `table_names`，三者互斥。不传表过滤时，对该 database 的 `kind` 投影做稳定排序后分页。列排序为 `TABLE_NAME, ORDINAL_POSITION, COLUMN_NAME`。
-- 分页：`max_rows`（1..连接上限，默认 `MYSQL_MAX_ROWS`）和 `offset`（默认 0）。JSON/`compact` 返回 `truncated`、`next_offset`（无下一页为 `null`）、`returned_rows`。`offset` 会下推为 SQL `LIMIT`/`OFFSET`。
-- 指定单表时仍尊重 `max_rows`/`offset`。旧调用不传这些参数时等价于 `offset=0`，仍可能 `truncated=true`。
-- 未翻页完成前，不得把当前页当作整库全集。续查时保持 `kind` 和过滤条件不变，只把 `offset` 换成上一页的 `next_offset`。
-
-### `dump_schema`
-
-按表分组返回允许列表内的表/列元数据，便于用少量调用拉完 600+ 张表的列结构。
-
-- 参数：`connection`、`database`、`kinds`（仅 `tables` 和/或 `columns`，默认两者都要）、以及与 `inspect_catalog` 相同的表过滤和分页参数
-- 出参为 JSON：`tables[].table_name`、可选表级字段、`columns[]`（`name`/`type`/`nullable`/`default`/`comment`/`ordinal`/`extra`），外加 `truncated`/`next_offset`/`returned_rows`
-- 分页作用在底层列（或仅 `tables` 时的表）行上；单表列可能跨页出现，合并时按 `(table_name, ordinal/name)` 去重。响应过大时会继续截断并设置 `truncated=true`，不会静默丢列
-- `indexes`/`constraints`/`foreign_keys`/`views` 请继续用 `inspect_catalog` 分页拉取
-
-### 查询响应预算与并发控制
-
-以下参数可写在命名连接中，也可使用对应的环境变量：
-
-| 配置 | 环境变量 | 默认值 | 范围 |
-| --- | --- | --- | --- |
-| `max_response_bytes` | `MYSQL_MAX_RESPONSE_BYTES` | 262144 | 4096–4194304 |
-| `max_concurrent_queries` | `MYSQL_MAX_CONCURRENT_QUERIES` | 5 | 1–32 |
-| `max_queued_queries` | `MYSQL_MAX_QUEUED_QUERIES` | 16 | 0–128 |
-| `queue_timeout_ms` | `MYSQL_QUEUE_TIMEOUT_MS` | 1000 | 1–300000 |
-
-查询数据响应按最终文本的 UTF-8 字节数（含结果元信息）控制；预算不包含 MCP/HTTP 外层封装，不是数据库扫描量或进程内存上限。单次 `max_response_bytes` 只能降低连接配置的预算。按完整行截断后，`next_offset` 指向下一条尚未交付的记录；表头或首行超预算时返回 `RESULT_TOO_LARGE`，需要减少列或用 `SUBSTRING` 分段取内容，不跳过该行。
-
-`truncated` 表示还有未交付的行；`content_truncated` 表示有单元格被 `max_cell_length` 截断。`truncation_reasons` 区分 `row_limit`、`response_bytes` 和 `cell_length`。单元格内容截断不能靠翻到下一行恢复。分页 SQL 应使用稳定、唯一的 `ORDER BY`；各页是独立只读事务，并发数据变化时不保证跨页快照一致。
-
-并发按实际连接别名隔离；启用连接池时并发上限不超过池大小。队列满或等候超过 `queue_timeout_ms` 返回 `CONNECTION_BUSY`，建议降低并行度后短暂等待再调用。`timeout_ms` 包含排队与执行，JSON/compact 返回 `queue_wait_ms`。取消请求会关闭活动 socket，工作线程完成清理前继续占用并发名额。
-
-### 可纠正的查询错误
-
-数据库错误通过 MCP `isError=true` 返回，文本为 JSON，同时提供 `structuredContent`。字段包含 `code`、`message`、`retryable`、`next_action`、安全的错误码/阶段、实际连接/库、请求的连接/库、`route_applied` 和 `query_id`。不透传驱动原始错误、SQL 文本、密码或主机连接信息。
-
-- `SQL_PARSE_ERROR`：连接前解析失败；只返回固定消息、可用的数字行列位置和查询指纹，不回显 SQL、字面量、解析器上下文或 ANSI 高亮。
-- `TABLE_NOT_FOUND`：1146/1109，先核对目标库并发现真实表名。
-- `COLUMN_NOT_FOUND`：1054，检查字段和别名。
-- `SQL_SYNTAX_ERROR`：1064，核对 MySQL 语法。
-- `DATABASE_NOT_FOUND`、`AUTHENTICATION_FAILED`、`ACCESS_DENIED`：核对配置和只读权限。
-- `QUERY_TIMEOUT`：MySQL 3024、MariaDB 1969、驱动读写超时或本地完整调用截止时间；先缩小查询范围或用 `explain_sql` 检查计划，不直接重复昂贵查询。本地截止时间使用 `phase=deadline` 并携带 `timeout_ms`。
-- `LOCK_WAIT_TIMEOUT` / `DEADLOCK`：1205 / 1213，检查并发事务或 DDL，在阻塞缓解后有限退避重试。
-- `CONNECTION_FAILED` / `CONNECTION_LOST`：连接建立失败或结果接收中断；先核对网络和目标连接，中断结果不得当作完整结果。
-- `QUERY_INTERRUPTED`：1317，先确认取消原因，不自动重新执行。
-- `CONNECTION_BUSY`：本地队列拥塞，或 MySQL 1040/1203 连接数超限；降低并发后有限退避重试，不会自动切换环境。
-- `retryable=true` 表示恢复后可由调用方有限重试，不会触发本服务新增自动重放；未知主机 2005、查询超时及主动中断均为 `false`。
-- `RESULT_TOO_LARGE`：普通查询缩小字段投影后从原 offset 重查；执行计划改用 `plan_output=chunks` 从 0 获取。
-- `PLAN_CHANGED`：计划续页指纹不一致，丢弃已收集分片并从 0 重取；`PLAN_FORMAT_UNSUPPORTED` 表示服务器没有返回预期的单行 JSON 计划。
-
-示例调用：
-
-```json
-{"connection":"dev","database":"app_dev","search":"调拨","max_rows":20,"result_format":"compact"}
-```
-
-上例用于 `list_tables`；取得真实表名后，可用 `get_schema_info` 的 `table_names` 和 `detail=true` 批量查看结构。
-
-### 常见问题
-
-- 提示 `auto mode classifier gave no verdict`：来自 Claude Code 的权限分类器，不是 SQL 错误，也不是本服务返回的。原样重试即可；常用的只读工具可在客户端权限设置里放行。
-- 查询 `information_schema` 被拒：设计如此，请改用 `get_schema_info`、`inspect_catalog` 或 `list_tables`。
-- `timeout_ms` 被拒：它不能超过该连接的 `query_timeout_ms`（`list_connections` 可查，配置上限 300000）。需要更长时间时由部署方调整对应连接。
-- 某个库查不到：先看 `list_connections` 的 `allowed_databases` 和 `database_routes`，库不在连接的范围内就不能访问。
-- 函数被拒：内置的纯函数已放行；被拒的多为存储函数、UDF 或带库名前缀的调用，审核确认无副作用后加入该连接的 `allowed_functions`。
-- 字段注释显示乱码：先在 MySQL 客户端对照同一列；若客户端也乱码，是库里存储的编码问题，与本服务的读取无关。
-- 其他 MCP 服务（如 `ssh-mcp-server`）连接失败：与本服务无关，检查它自己的启动配置。
-
-## 可用提示词
-
-| 提示词 | 参数 | 说明 |
-| --- | --- | --- |
-| `explore_database` | `connection`、`database`（可选） | 依次发现表、检查结构、采样并总结数据库 |
-| `analyze_table` | `table_name`（必填）、`connection`、`database`（可选） | 深入分析指定表，支持 `database.table` |
-
-这些提示词只编排只读的发现、结构检查和采样工具。
-
-## MCP 客户端配置
-
-### Claude Desktop
-
-在 `claude_desktop_config.json` 中加入：
-
-```json
-{
-  "mcpServers": {
-    "mysql-readonly": {
-      "command": "npx",
-      "args": ["-y", "@yanzhang123/readonly-db-mcp@0.9.1"],
-      "env": {
-        "MYSQL_PROFILES_FILE": "C:/absolute/path/mysql-connections.toml",
-        "MYSQL_DEV_PASSWORD": "your_dev_password"
-      }
-    }
-  }
-}
-```
-
-### Visual Studio Code / Codex
-
-在 `mcp.json` 或对应 MCP 配置中加入：
-
-```json
-{
-  "mcpServers": {
-    "mysql-readonly": {
-      "type": "stdio",
-      "command": "npx",
-      "args": ["-y", "@yanzhang123/readonly-db-mcp@0.9.1"],
-      "env": {
-        "MYSQL_PROFILES_FILE": "C:/absolute/path/mysql-connections.toml",
-        "MYSQL_DEV_PASSWORD": "your_dev_password"
-      }
-    }
-  }
-}
-```
-
-Windows 宿主如无法解析 `npx`，改用 `npx.cmd`。更多调用场景见 [`MCP_USECASES.md`](MCP_USECASES.md)。
-
-### DeepSeek Harness
-
-Harness 自带 `@deepseek-ai/dsh-mcp-client`。本地使用推荐挂载 npm 包的
-STDIO 入口；在 Windows 上使用 `npx.cmd`：
-
-```yaml
-- insert:
-    - id: mcp-mysql-readonly
-      name: '@deepseek-ai/dsh-mcp-client'
-      config:
-        serverName: mysql-readonly
-        transport: stdio
-        command: npx.cmd
-        args: ['-y', '@yanzhang123/readonly-db-mcp@0.9.1']
-        env:
-          MYSQL_PROFILES_FILE: 'C:/absolute/path/mysql-connections.toml'
-        toolCallTimeoutMs: 60000
-        failOnStartupError: true
-```
-
-远程或集中部署时使用 Streamable HTTP。先按上文启动服务，然后在 Harness
-配置中挂载端点；`MYSQL_MCP_AUTHORIZATION` 的值应为 `Bearer <token>`，并
-从进程环境或密钥管理系统注入，不要提交到仓库：
-
-```yaml
-- insert:
-    - id: mcp-mysql-readonly
-      name: '@deepseek-ai/dsh-mcp-client'
-      config:
-        serverName: mysql-readonly
-        transport: streamable-http
-        url: 'https://mcp.example.com/mcp'
-        headers:
-          Authorization: !!js process.env.MYSQL_MCP_AUTHORIZATION
-        toolCallTimeoutMs: 60000
-        failOnStartupError: true
-```
-
-## 开发与测试
-
-```bash
-git clone https://github.com/12zhangyan/mysql_mcp_server.git
-cd mysql_mcp_server
-python -m venv .venv
-
-# Linux/macOS
-source .venv/bin/activate
-
-# Windows PowerShell
-.\.venv\Scripts\Activate.ps1
-
-pip install -r requirements-dev.txt
-pytest
-npm test
-```
-
-调试 MCP 协议交互时可使用 MCP Inspector，不建议直接把 Python 进程当作普通命令行程序交互。
+所有工具都声明 `readOnlyHint=true` 和 `destructiveHint=false`。参数和行为详见 [工具与提示词](https://github.com/12zhangyan/mysql_mcp_server/blob/main/docs/TOOLS.md)。
 
-`tests/test_local_readonly.py` 是显式启用的本机验收测试。仅在进程环境设置 `MYSQL_MCP_LOCAL_TESTS=1`、`MYSQL_USER`、`MYSQL_PASSWORD` 后运行 `python -m pytest tests/test_local_readonly.py -q`；固定连接 `127.0.0.1:3306`，不使用远程配置或 SSH。测试使用 CTE 构造数据并读取已有元数据，不创建或修改表。覆盖 MySQL 8 的 CTE/UNION/嵌套查询/已有分页/窗口函数改写对照、中文注释搜索、响应预算续查和真实数据库错误。未显式启用时跳过；凭据不要写入文件。
+| 工具 | 用途 |
+| --- | --- |
+| `list_connections` / `validate_connections` / `check_connection` | 列出命名连接、重载并校验配置、只读健康检查 |
+| `list_databases` / `list_tables` | 列出可访问的数据库、表和视图 |
+| `execute_sql` / `query` | 执行单条只读语句（`query` 是兼容别名） |
+| `explain_sql` | 对 `SELECT` / `WITH` 生成执行计划 |
+| `get_schema_info` / `inspect_catalog` / `dump_schema` | 字段、索引、约束、视图等元数据，支持分页和整库导出 |
+| `get_table_sample` | 返回少量样例数据 |
 
 ## 安全设计
 

package/package.json

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