@yanzhang123/readonly-db-mcp 0.7.6 → 0.8.0

package/ENTERPRISE_DEPLOYMENT.md

@@ -79,6 +79,26 @@ audit_fail_closed = true
 audit_fsync = true
 ```
 
+For desktop deployments, replace `password_env` with an OS keyring reference so
+user-level MCP configuration contains no database password:
+
+```toml
+credential_provider = "keyring"
+credential_ref = "prod"
+```
+
+Provision it interactively with `readonly-db-mcp credentials --profiles-file
+C:/absolute/path/mysql-connections.toml set prod`. The tool never prints the
+credential. For non-interactive services, the `command` provider accepts a
+reviewed argv array for a secret-manager CLI and executes it without a shell.
+Restrict the profiles file because command names and non-secret arguments can
+still reveal infrastructure topology.
+
+If an environment spans physical profiles, use `[routes.ENVIRONMENT]` with
+exact database aliases. Each audit event records `requested_connection`,
+`requested_database`, the resolved physical `connection`/`database`, and
+`route_applied`; unknown aliases fail rather than being guessed.
+
 All database tools accept:
 
 ```json
@@ -196,6 +216,10 @@ read-only operations were sent:
 - configuration validation, connection health and grants inspection
 - allowed-database discovery and system-schema filtering
 - table/schema metadata reads
+- controlled catalog projections for tables, columns, indexes, constraints,
+  foreign keys and views while arbitrary system-schema SQL remains denied
+- deterministic keyring, command-provider and explicit-route tests with no
+  production credential material
 - normal query execution and pagination
 - pre-connection rejection of DML, DDL, multiple statements, locking reads and
   system-schema access

package/README.md

@@ -176,6 +176,49 @@ 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.
 
+For user-level `mcp.json` files, prefer the OS credential store so the password
+does not appear in either MCP configuration or 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"]
+```
+
+Store or manage it locally with a masked prompt:
+
+```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
+```
+
+The keyring backend uses the platform credential service (Windows Credential
+Manager on Windows). Headless services can instead set
+`credential_provider = "command"` and a `credential_command = ["executable",
+"arg1"]` array for an approved secret-manager CLI. It is executed directly,
+never through a shell; stderr is discarded, output is bounded, and exactly one
+non-empty UTF-8 line is accepted. Provider failures are explicit but never
+include the secret, command arguments, or keyring reference.
+
+When one logical environment is physically split, declare exact aliases:
+
+```toml
+[routes.shared-test]
+ubp = { connection = "test-ubp", database = "ubp" }
+gts = { connection = "test-gts", database = "gts" }
+eam = { connection = "test-eam", database = "eam" }
+```
+
+A call with `connection="shared-test", database="eam"` resolves only that
+declared route. Unknown aliases fail with the configured choices; the server
+does not search or guess another environment. JSON results and audit records
+contain both requested and resolved targets.
+
 Each tool call can now target an environment without restarting the server:
 
 ```json
@@ -287,7 +330,7 @@ All tools are declared with `readOnlyHint=true` and `destructiveHint=false`.
 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.
+connections, plus `logical_routes` for exact configured environment aliases.
 
 ### `validate_connections`
 Forces a configuration reload and reports valid/invalid profiles plus missing
@@ -303,6 +346,8 @@ not provide read-only defense in depth.
 ### `list_databases`
 Lists accessible non-system databases.
 - **Arguments:** `connection` (optional)
+- For a configured logical connection, returns its declared database aliases
+  without opening a database connection.
 
 ### `list_tables`
 Lists tables and views in a database.
@@ -348,6 +393,12 @@ Fetches a representative sample of data.
   MySQL and fully consumes that small result. It does not open an unbounded
   table scan merely to return a few rows.
 
+### `inspect_catalog`
+Returns one fixed metadata projection for `tables`, `columns`, `indexes`,
+`constraints`, `foreign_keys`, or `views`, optionally filtered by a validated
+bare table name. `connection` and `database` follow the same explicit routing
+rules as other tools. This does not permit arbitrary `information_schema` SQL.
+
 ## 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.
@@ -445,9 +496,12 @@ pytest
 - **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.
+  default. Dedicated `list_tables`, `get_schema_info`, and `inspect_catalog`
+  operations use narrowly scoped internal metadata queries, so catalog access
+  does not become a general system-schema bypass.
+- **Credential isolation:** Named profiles can resolve passwords from an OS
+  keyring or an approved no-shell command. Discovery, logs, errors and audit
+  events omit credential values and keyring references.
 - **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.

package/SECURITY.md

@@ -59,6 +59,13 @@ FLUSH PRIVILEGES;
 
 When setting up the MCP server, use these restricted credentials in your environment:
 
+Prefer `credential_provider = "keyring"` for desktop MCP clients so passwords
+do not appear in user-level MCP JSON or TOML. The local credentials command uses
+a masked prompt and never returns stored values. Enterprise secret-manager
+commands must be configured as an argv array; they run with `shell=false`, no
+stdin, discarded stderr, a bounded timeout/output size, and a one-line output
+contract. Do not embed secrets in command arguments.
+
 ```bash
 MYSQL_USER=mcp_user
 MYSQL_PASSWORD=your_secure_password

package/npm/requirements.lock

@@ -18,6 +18,10 @@ attrs==26.1.0 \
     # via
     #   jsonschema
     #   referencing
+backports-tarfile==1.2.0 ; python_full_version < '3.12' \
+    --hash=sha256:77e284d754527b01fb1e6fa8a1afe577858ebe4e9dad8919e34c862cb399bc34 \
+    --hash=sha256:d75e02c268746e1b8144c278978b6e98e85de6ad16f8e4b0844a154557eca991
+    # via jaraco-context
 certifi==2026.5.20 \
     --hash=sha256:3c52e209ba0a4ad7aebe60436a4ab349c39e1e602e8c134221e546902ad25897 \
     --hash=sha256:69dea482ab64caa7b9f6aba1c6bf48bb6a5448d1c0f1b17ab42ad8c763a5344d
@@ -144,7 +148,9 @@ cryptography==48.0.0 \
     --hash=sha256:ecde28a596bead48b0cfd2a1b4416c3d43074c2d785e3a398d7ec1fc4d0f7fbb \
     --hash=sha256:f5333311663ea94f75dd408665686aaf426563556bb5283554a3539177e03b8c \
     --hash=sha256:fdfef35d751d510fcef5252703621574364fec16418c4a1e5e1055248401054b
-    # via pyjwt
+    # via
+    #   pyjwt
+    #   secretstorage
 h11==0.16.0 \
     --hash=sha256:4e35b956cf45792e4caa5885e69fba00bdbc6ffafbfa020300e549b208ee5ff1 \
     --hash=sha256:63cf8bbe7522de3bf65932fda1d9c2772064ffb3dae62d55932da54b31cb6c86
@@ -169,6 +175,28 @@ idna==3.18 \
     # via
     #   anyio
     #   httpx
+importlib-metadata==9.0.0 ; python_full_version < '3.12' \
+    --hash=sha256:2d21d1cc5a017bd0559e36150c21c830ab1dc304dedd1b7ea85d20f45ef3edd7 \
+    --hash=sha256:a4f57ab599e6a2e3016d7595cfd72eb4661a5106e787a95bcc90c7105b831efc
+    # via keyring
+jaraco-classes==3.4.0 \
+    --hash=sha256:47a024b51d0239c0dd8c8540c6c7f484be3b8fcf0b2d85c13825780d3b3f3acd \
+    --hash=sha256:f662826b6bed8cace05e7ff873ce0f9283b5c924470fe664fff1c2f00f581790
+    # via keyring
+jaraco-context==6.1.2 \
+    --hash=sha256:bf8150b79a2d5d91ae48629d8b427a8f7ba0e1097dd6202a9059f29a36379535 \
+    --hash=sha256:f1a6c9d391e661cc5b8d39861ff077a7dc24dc23833ccee564b234b81c82dfe3
+    # via keyring
+jaraco-functools==4.6.0 \
+    --hash=sha256:880c577ec9720b3a052d5bc611fb9f2269b3d87902ef42440df443b88e443280 \
+    --hash=sha256:99e3dc0060c5cbe8fcd1cdb36258e2a65ca40f1566b2033b12abb1bb44dd3c30
+    # via keyring
+jeepney==0.9.0 ; sys_platform == 'linux' \
+    --hash=sha256:97e5714520c16fc0a45695e5365a2e11b81ea79bba796e26f9f1d178cb182683 \
+    --hash=sha256:cf0e9e845622b81e4a28df94c40345400256ec608d0e55bb8a3feaa9163f5732
+    # via
+    #   keyring
+    #   secretstorage
 jsonschema==4.26.0 \
     --hash=sha256:0c26707e2efad8aa1bfc5b7ce170f3fccc2e4918ff85989ba9ffa9facb2be326 \
     --hash=sha256:d489f15263b8d200f8387e64b4c3a75f06629559fb73deb8fdfb525f2dab50ce
@@ -177,10 +205,20 @@ jsonschema-specifications==2025.9.1 \
     --hash=sha256:98802fee3a11ee76ecaca44429fda8a41bff98b00a0f2838151b113f210cc6fe \
     --hash=sha256:b540987f239e745613c7a9176f3edb72b832a4ac465cf02712288397832b5e8d
     # via jsonschema
+keyring==25.7.0 \
+    --hash=sha256:be4a0b195f149690c166e850609a477c532ddbfbaed96a404d4e43f8d5e2689f \
+    --hash=sha256:fe01bd85eb3f8fb3dd0405defdeac9a5b4f6f0439edbb3149577f244a2e8245b
+    # via mysql-mcp-server
 mcp==1.27.2 \
     --hash=sha256:8e02db104096d1c25b28e64bde29a5c32b31bc241710213e12fd4d84985bdfef \
     --hash=sha256:d6ff5160c6ca65d93013626efb3fc249de683c30b2d8570755ceddd490344de5
     # via mysql-mcp-server
+more-itertools==11.1.0 \
+    --hash=sha256:48e8f4d9e7e5878571ecf6f2b4e57634f93cd474cc8cfbd2376f2d11b396e30d \
+    --hash=sha256:4b65538ae22f6fed0ce4874efd317463a7489796a0939fa66824dd542125a192
+    # via
+    #   jaraco-classes
+    #   jaraco-functools
 mysql-connector-python==9.7.0 \
     --hash=sha256:079ce68d617250ef5cefffd5243056dc9f87c6034c804235fd6f45a0daf5a6ae \
     --hash=sha256:15106ed73d74487f86de6b1859ff7f362efca7c7f9c494497ccb7439d3139fe6 \
@@ -343,6 +381,10 @@ pywin32==312 ; sys_platform == 'win32' \
     --hash=sha256:d11417d84412f859b722fad0841b3614459ed0047f7542d8362e77884f6b6e8a \
     --hash=sha256:dab4f65ac9c4e48400a2a0530c46c3c579cd5905ecd11b80692373915269208b
     # via mcp
+pywin32-ctypes==0.2.3 ; sys_platform == 'win32' \
+    --hash=sha256:8a1513379d709975552d202d942d9837758905c8d01eb82b8bcc30918929e7b8 \
+    --hash=sha256:d162dc04946d704503b2edc4d55f3dba5c1d539ead017afa00142c38b9885755
+    # via keyring
 referencing==0.37.0 \
     --hash=sha256:381329a9f99628c9069361716891d34ad94af76e461dcb0335825aecc7692231 \
     --hash=sha256:44aefc3142c5b842538163acb373e24cce6632bd54bdb01b21ad5863489f50d8
@@ -483,6 +525,10 @@ rpds-py==2026.5.1 \
     # via
     #   jsonschema
     #   referencing
+secretstorage==3.5.0 ; sys_platform == 'linux' \
+    --hash=sha256:0ce65888c0725fcb2c5bc0fdb8e5438eece02c523557ea40ce0703c266248137 \
+    --hash=sha256:f04b8e4689cbce351744d5537bf6b1329c6fc68f91fa666f60a380edddcd11be
+    # via keyring
 sqlglot==30.14.0 \
     --hash=sha256:df2ef5d2b8ca814313781f4ff35bf63e58f821ef517eeddbd523c19a61fa9bb9 \
     --hash=sha256:fc768e24889d63a5e1237dea7ad305e5ffb4356a98b0bed828f89591ebcd3636
@@ -519,3 +565,7 @@ uvicorn==0.49.0 ; sys_platform != 'emscripten' \
     --hash=sha256:ba3d14c3ee7e41c6c654c46c9eb489d33213cdd30aa1696eab1374337c13f68f \
     --hash=sha256:ebf4271aa580d9de97f93192d4595176df6e91f9aae919ca73e4fc07df1e66a3
     # via mcp
+zipp==4.1.0 ; python_full_version < '3.12' \
+    --hash=sha256:25ad4e16390cd314347dd8f1de67a2ac538ae658ed4ab9db16029c07c188e97f \
+    --hash=sha256:4cb57381f544315db7688e976e922a2b18cdb513d21cc194eb42232ba2a3e602
+    # via importlib-metadata

package/package.json

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