sql-safe-mcp 1.3.0__tar.gz → 1.4.0__tar.gz

{sql_safe_mcp-1.3.0 → sql_safe_mcp-1.4.0}/CHANGELOG.md

@@ -7,6 +7,24 @@ categories `Added`, `Changed`, `Deprecated`, `Removed`, `Fixed`, and `Security`.
 
 ## [Unreleased]
 
+## [1.4.0] - 2026-09-22
+
+### Added
+
+- `sql-safe-mcp --gen-pii-key [N]` generates one base64-encoded 32-byte PII key by default, or
+  `N` keys as one value per line, without loading configuration or connecting to a database.
+- PII table rules now accept case-insensitive full shell-glob patterns, and `pii_rules` can define
+  shared unnamed defaults or named sets explicitly included by `pii_safe` aliases. Shared rules are
+  flattened at startup in deterministic default, include, and local order.
+
+## [1.3.1] - 2026-09-21
+
+### Changed
+
+- A `${NAME}` placeholder embedded in `connection_url` whose value puts an encoded character into
+  the host, such as a `host:port` value whose `:` becomes `%3A`, is now a startup error that names
+  the cause. Before, the server started and every call failed after the driver's login timeout.
+
 ## [1.3.0] - 2026-09-21
 
 ### Added

{sql_safe_mcp-1.3.0 → sql_safe_mcp-1.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: sql-safe-mcp
-Version: 1.3.0
+Version: 1.4.0
 Summary: Minimal, read-only, PII-safe MCP server for SQL databases.
 License: MIT License
         
@@ -40,7 +40,9 @@ Description-Content-Type: text/markdown
 
 # sql-safe-mcp
 
-A read-only, PII-safe SQL Server, MySQL and MariaDB MCP server for coding agents: schema knowledge and safe queries, with no way to change or leak data.
+A PII-safe, read-only MCP server for coding agents working with SQL Server, MySQL and MariaDB:
+schema knowledge and safe queries without write-capable tools or plaintext exposure of configured
+PII columns.
 
 [![CI](https://github.com/proprock/sql-safe-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/proprock/sql-safe-mcp/actions/workflows/ci.yml)
 [![Release](https://img.shields.io/github/v/release/proprock/sql-safe-mcp)](https://github.com/proprock/sql-safe-mcp/releases)
@@ -59,31 +61,32 @@ A read-only, PII-safe SQL Server, MySQL and MariaDB MCP server for coding agents
 
 <!-- mcp-name: io.github.proprock/sql-safe-mcp -->
 
-General-purpose database MCP servers hand the agent a raw SQL prompt and dozens of tools. This
-server gives a coding agent the schema knowledge it needs to write correct code - servers,
-databases, tables, columns, keys, indexes, stored procedures - and, on servers you mark
-`pii_safe`, a way to look at real rows without ever seeing the personal data in them.
+Give a coding agent the schema knowledge it needs to write correct code - servers, databases,
+tables, columns, keys, indexes, and stored procedures. On aliases you mark `pii_safe`, it can also
+query real rows while configured personal data stays hidden behind authenticated tokens.
 
-## Read-only by design. PII-safe by default
+## PII-safe by default. Read-only by design.
 
-- **Read-only by construction** - seven tools, all annotated read-only. No tool writes data, and
-  the server never executes SQL an agent wrote: metadata comes from SQLAlchemy Inspector and fixed
-  catalog queries, and `execute_sql` runs only a validated, regenerated `SELECT`.
 - **PII-safe by default** - on a `pii_safe` server, the columns you configure come back as
   alias-bound, authenticated tokens (`pii:v1:...`), never as plaintext. An agent can still
   project, count, and filter on them with `=` and `IN` using tokens it was given, so it can follow
   a record without reading it. Tokens do not work on another server alias or with another key.
+- **Read-only by construction** - seven tools, all annotated read-only. No tool writes data, and
+  the server never executes SQL an agent wrote: metadata comes from SQLAlchemy Inspector and fixed
+  catalog queries, and `execute_sql` runs only a validated, regenerated `SELECT`.
+- **Multiple servers, isolated policies** - one MCP process can expose multiple named SQL Server,
+  MySQL, and MariaDB instances. Each alias has its own connection, access level, and, when enabled,
+  PII key and protection rules. Every database operation targets an explicit alias; there is no
+  network discovery.
+
+## Operational safeguards
+
 - **Fails closed** - SQL validation is an allowlist. Unknown syntax, unresolved lineage, and
   unsupported protected-value types are refused, not guessed at. The verification evidence is in
   the [security model](SECURITY-MODEL.md).
 - **Least access first** - `access_level: metadata` (the default) exposes schema only;
   `execute_sql` needs an explicit `pii_safe` alias with its own key. Database permissions stay the
   primary control, so use a least-privilege login.
-
-## Also
-
-- **Your aliases, not your network** - the agent sees only the server aliases you configure. There
-  is no network discovery, and the catalog is not published as MCP resources.
 - **Secrets stay out of sight** - connection URLs live in YAML with `${NAME}` placeholders resolved
   from the environment. They never appear in logs or model-visible errors.
 - **Compact, predictable output** - object-rooted results with stable sorting, literal
@@ -98,7 +101,6 @@ databases, tables, columns, keys, indexes, stored procedures - and, on servers y
 - **Diagnosable failures** - a timeout or connection error carries a `Reference`, and the stderr
   log records the connection stage, elapsed time, and driver error for the same reference, with
   credentials removed. See [Logging](docs/configuration.md#logging).
-- **On PyPI** - `uvx sql-safe-mcp`, no repo clone required.
 
 | Tool | Access | Purpose |
 |---|---|---|
@@ -116,16 +118,9 @@ databases, tables, columns, keys, indexes, stored procedures - and, on servers y
 > database is the catalog, and `execute_sql` uses `LIMIT` instead of `TOP`. See
 > [ARCHITECTURE.md](ARCHITECTURE.md).
 
-- [Install](#install)
-- [Configure](#configure)
-- [PII-safe queries](#pii-safe-queries)
-- [Security](#security)
-- [Contributing](#contributing)
+## Quick start
 
-More detail lives in [`docs/`](docs): the [configuration reference](docs/configuration.md),
-[what the tools return](docs/tools.md), and the [security model](SECURITY-MODEL.md).
-
-## Install
+### Install
 
 ```bash
 uvx sql-safe-mcp
@@ -137,7 +132,7 @@ or
 pip install sql-safe-mcp
 ```
 
-Pin a version when you want a fixed surface: `uvx sql-safe-mcp==1.3.0`.
+Pin a version when you want a fixed surface: `uvx sql-safe-mcp==1.4.0`.
 
 Requires Python 3.12+, [uv](https://docs.astral.sh/uv/) (or `pip`), and
 [Microsoft ODBC Driver 18 for SQL Server](https://learn.microsoft.com/sql/connect/odbc/download-odbc-driver-for-sql-server)
@@ -146,10 +141,10 @@ else.
 
 Verified against SQL Server 2022, MySQL 8.4, and MariaDB 11.4 (see [CHECKS.md](CHECKS.md)).
 
-## Configure
+### Configure multiple servers
 
-Copy [sql-safe-mcp.example.yaml](sql-safe-mcp.example.yaml) to `sql-safe-mcp.yaml`, list your
-servers, and keep credentials in environment variables:
+Copy [sql-safe-mcp.example.yaml](sql-safe-mcp.example.yaml) to `sql-safe-mcp.yaml`. Add each
+database server under a named alias and keep credentials in environment variables:
 
 ```yaml
 version: 1
@@ -158,36 +153,50 @@ servers:
     engine: sqlserver
     access_level: metadata
     connection_url: "${REPORTING_SQL_URL}"
-```
-
-`connection_url` is a SQLAlchemy URL whose dialect must match `engine`. It is a secret, so keep the
-credentials in environment variables and reference them with `${NAME}`:
-
-```yaml
-servers:
-  # The whole URL comes from one variable (it may hold any valid URL).
-  reporting:
-    engine: sqlserver
-    connection_url: "${REPORTING_SQL_URL}"
 
-  # SQL Server (mssql+pyodbc), URL assembled from parts. Embedded placeholders are
-  # URL-encoded, so a password containing @ or / is safe.
   billing:
     engine: sqlserver
-    connection_url: >-
-      mssql+pyodbc://${BILLING_USER}:${BILLING_PASSWORD}@${BILLING_HOST}/master
-      ?driver=ODBC+Driver+18+for+SQL+Server&Encrypt=yes
+    access_level: pii_safe
+    connection_url: "${BILLING_SQL_URL}"
+    pii_key_env: BILLING_PII_KEY
+    pii:
+      rules:
+        - database: Billing
+          schema: dbo
+          table: Customers
+          columns: [Email, FullName]
 
-  # MySQL or MariaDB (mysql+pymysql). Use engine: mariadb for MariaDB.
   shop:
     engine: mysql
+    access_level: metadata
     connection_url: "mysql+pymysql://${SHOP_USER}:${SHOP_PASSWORD}@db.internal/shop"
 ```
 
-A missing variable, or an `engine` that does not match the URL dialect, stops the server at startup.
+Here `reporting`, `billing`, and `shop` are the values an agent passes as `server`. Their
+credentials and access policies are independent. A missing variable, or an `engine` that does not
+match the URL dialect, stops the MCP server at startup.
+
+### Ask an agent to install it
+
+Give a coding agent the following prompt when you want it to perform the setup in its own MCP
+host:
+
+```text
+Install and configure sql-safe-mcp as a stdio MCP server for this workspace. First inspect the
+host's existing MCP configuration convention and preserve all unrelated server entries. Create or
+update a non-secret YAML configuration using environment-variable placeholders only. Never put
+connection URLs, passwords, PII keys, tokens, bind values, or query results in tracked files, chat
+output, or logs. If the database aliases, engines, access levels, PII rules, configuration path,
+or secret-storage mechanism are not specified, ask me before choosing them. Configure the host to
+run `uvx sql-safe-mcp` with `SQL_SAFE_MCP_CONFIG` and the required variables supplied through the
+host's secret or environment mechanism. Run `sql-safe-mcp --check-config` after the variables are
+available, then report only the configured aliases and the validation result.
+```
+
+### Check the configuration
 
-Point the server at the file with `SQL_SAFE_MCP_CONFIG` (or `--config`), and check it without
-connecting to any database:
+After defining every environment variable referenced by the YAML file, point the server at it with
+`SQL_SAFE_MCP_CONFIG` (or `--config`) and check it without connecting to any database:
 
 ```bash
 SQL_SAFE_MCP_CONFIG=sql-safe-mcp.yaml uvx sql-safe-mcp --check-config
@@ -196,8 +205,13 @@ SQL_SAFE_MCP_CONFIG=sql-safe-mcp.yaml uvx sql-safe-mcp --check-config
 Configuration is validated at startup, and an error names the problem without printing a URL or
 secret. Keep credentials in the host's own configuration and never commit them. The server acts
 with the database account's permissions, so use a dedicated login with the least access the job
-needs. Every setting, including the runtime limits, is in
-[configuration.md](docs/configuration.md).
+needs.
+
+### Connect an MCP client
+
+Every client configuration needs `SQL_SAFE_MCP_CONFIG` plus the environment variables referenced
+by your YAML file. Keep connection URLs and PII keys in the MCP host's environment or
+configuration, never in the YAML file or other tracked files.
 
 <details>
 <summary><b>Claude Code</b></summary>
@@ -206,15 +220,15 @@ needs. Every setting, including the runtime limits, is in
 claude mcp add --env SQL_SAFE_MCP_CONFIG=/path/to/sql-safe-mcp.yaml --env REPORTING_SQL_URL=mssql+pyodbc://... --transport stdio sql-safe -- uvx sql-safe-mcp
 ```
 
-Put at least one other option between the last `--env` and the server name, as above - the CLI
-otherwise reads the name as another `KEY=value` pair.
+Put at least one other option between the last `--env` and the server name, as above. Otherwise,
+the CLI reads the name as another `KEY=value` pair.
 
 </details>
 
 <details>
 <summary><b>Claude Desktop</b></summary>
 
-In `claude_desktop_config.json`:
+Add the server to `claude_desktop_config.json`:
 
 ```json
 {
@@ -245,42 +259,43 @@ codex mcp add sql-safe --env SQL_SAFE_MCP_CONFIG=/path/to/sql-safe-mcp.yaml --en
 <details>
 <summary><b>Any other stdio host</b></summary>
 
-Command `uvx`, argument `sql-safe-mcp`, and the environment variables your configuration
-references, plus `SQL_SAFE_MCP_CONFIG`. The server speaks MCP over stdio and logs only to stderr.
+Use command `uvx`, argument `sql-safe-mcp`, and set `SQL_SAFE_MCP_CONFIG` plus every environment
+variable referenced by the configuration file. The server writes MCP messages to stdout and logs
+only to stderr.
 
 </details>
 
 ## PII-safe queries
 
-Mark an alias `access_level: pii_safe`, give it its own key, and list the protected columns:
+`execute_sql` on the `billing` alias allows one restricted `SELECT`. For example, these arguments:
 
-```yaml
-servers:
-  legacy_prod:
-    engine: sqlserver
-    access_level: pii_safe
-    connection_url: "${LEGACY_PROD_SQL_URL}"
-    pii_key_env: LEGACY_PROD_PII_KEY
-    pii:
-      rules:
-        - database: "*"
-          schema: dbo
-          table: Users
-          columns: [Email, FirstName, LastName]
+```json
+{
+  "server": "billing",
+  "database": "Billing",
+  "sql": "SELECT CustomerId, Email FROM dbo.Customers"
+}
 ```
 
-`execute_sql` then accepts one restricted `SELECT`. Protected cells come back as tokens, and a
-token is accepted only in `=` and `IN` predicates on the same alias. Protection covers the columns
-you list, so list every column that holds personal data. The rule format, key generation, and the
-accepted SQL are in [configuration.md](docs/configuration.md) and [tools.md](docs/tools.md).
+can return a row such as `[42, "pii:v1:..."]`: the agent can follow the customer without reading
+the email address. A token is accepted only in `=` and `IN` predicates on the same protected column
+and server alias. Protection covers the columns you list, so list every column that holds personal
+data.
+
+## Documentation
+
+- [Configuration reference](docs/configuration.md) - aliases, connection URLs, PII rules, runtime
+  limits, and logging.
+- [Tool reference](docs/tools.md) - arguments, responses, errors, and the accepted SQL subset.
+- [Security model](SECURITY-MODEL.md) - trust boundaries, guarantees, limitations, and verification.
+- [Checks](CHECKS.md) - local, integration, and security verification commands.
 
 ## Security
 
-The MCP caller, SQL input, database metadata, rows, and tokens are untrusted; the operator, the
-process environment, and the database credentials are the trusted boundary. Database permissions
-remain the primary authorization control - this server never widens them. The full model and its
-verification are in [SECURITY-MODEL.md](SECURITY-MODEL.md). To report a vulnerability,
-use the private channel in [SECURITY.md](SECURITY.md).
+The MCP caller, SQL input, database metadata, rows, and tokens are untrusted. Database permissions
+remain the primary authorization control - this server never widens them. Read the full
+[security model](SECURITY-MODEL.md), including its limitations and verification evidence. To report
+a vulnerability, use the private channel in [SECURITY.md](SECURITY.md).
 
 ## Contributing
 

{sql_safe_mcp-1.3.0 → sql_safe_mcp-1.4.0}/README.md

@@ -2,7 +2,9 @@
 
 # sql-safe-mcp
 
-A read-only, PII-safe SQL Server, MySQL and MariaDB MCP server for coding agents: schema knowledge and safe queries, with no way to change or leak data.
+A PII-safe, read-only MCP server for coding agents working with SQL Server, MySQL and MariaDB:
+schema knowledge and safe queries without write-capable tools or plaintext exposure of configured
+PII columns.
 
 [![CI](https://github.com/proprock/sql-safe-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/proprock/sql-safe-mcp/actions/workflows/ci.yml)
 [![Release](https://img.shields.io/github/v/release/proprock/sql-safe-mcp)](https://github.com/proprock/sql-safe-mcp/releases)
@@ -21,31 +23,32 @@ A read-only, PII-safe SQL Server, MySQL and MariaDB MCP server for coding agents
 
 <!-- mcp-name: io.github.proprock/sql-safe-mcp -->
 
-General-purpose database MCP servers hand the agent a raw SQL prompt and dozens of tools. This
-server gives a coding agent the schema knowledge it needs to write correct code - servers,
-databases, tables, columns, keys, indexes, stored procedures - and, on servers you mark
-`pii_safe`, a way to look at real rows without ever seeing the personal data in them.
+Give a coding agent the schema knowledge it needs to write correct code - servers, databases,
+tables, columns, keys, indexes, and stored procedures. On aliases you mark `pii_safe`, it can also
+query real rows while configured personal data stays hidden behind authenticated tokens.
 
-## Read-only by design. PII-safe by default
+## PII-safe by default. Read-only by design.
 
-- **Read-only by construction** - seven tools, all annotated read-only. No tool writes data, and
-  the server never executes SQL an agent wrote: metadata comes from SQLAlchemy Inspector and fixed
-  catalog queries, and `execute_sql` runs only a validated, regenerated `SELECT`.
 - **PII-safe by default** - on a `pii_safe` server, the columns you configure come back as
   alias-bound, authenticated tokens (`pii:v1:...`), never as plaintext. An agent can still
   project, count, and filter on them with `=` and `IN` using tokens it was given, so it can follow
   a record without reading it. Tokens do not work on another server alias or with another key.
+- **Read-only by construction** - seven tools, all annotated read-only. No tool writes data, and
+  the server never executes SQL an agent wrote: metadata comes from SQLAlchemy Inspector and fixed
+  catalog queries, and `execute_sql` runs only a validated, regenerated `SELECT`.
+- **Multiple servers, isolated policies** - one MCP process can expose multiple named SQL Server,
+  MySQL, and MariaDB instances. Each alias has its own connection, access level, and, when enabled,
+  PII key and protection rules. Every database operation targets an explicit alias; there is no
+  network discovery.
+
+## Operational safeguards
+
 - **Fails closed** - SQL validation is an allowlist. Unknown syntax, unresolved lineage, and
   unsupported protected-value types are refused, not guessed at. The verification evidence is in
   the [security model](SECURITY-MODEL.md).
 - **Least access first** - `access_level: metadata` (the default) exposes schema only;
   `execute_sql` needs an explicit `pii_safe` alias with its own key. Database permissions stay the
   primary control, so use a least-privilege login.
-
-## Also
-
-- **Your aliases, not your network** - the agent sees only the server aliases you configure. There
-  is no network discovery, and the catalog is not published as MCP resources.
 - **Secrets stay out of sight** - connection URLs live in YAML with `${NAME}` placeholders resolved
   from the environment. They never appear in logs or model-visible errors.
 - **Compact, predictable output** - object-rooted results with stable sorting, literal
@@ -60,7 +63,6 @@ databases, tables, columns, keys, indexes, stored procedures - and, on servers y
 - **Diagnosable failures** - a timeout or connection error carries a `Reference`, and the stderr
   log records the connection stage, elapsed time, and driver error for the same reference, with
   credentials removed. See [Logging](docs/configuration.md#logging).
-- **On PyPI** - `uvx sql-safe-mcp`, no repo clone required.
 
 | Tool | Access | Purpose |
 |---|---|---|
@@ -78,16 +80,9 @@ databases, tables, columns, keys, indexes, stored procedures - and, on servers y
 > database is the catalog, and `execute_sql` uses `LIMIT` instead of `TOP`. See
 > [ARCHITECTURE.md](ARCHITECTURE.md).
 
-- [Install](#install)
-- [Configure](#configure)
-- [PII-safe queries](#pii-safe-queries)
-- [Security](#security)
-- [Contributing](#contributing)
+## Quick start
 
-More detail lives in [`docs/`](docs): the [configuration reference](docs/configuration.md),
-[what the tools return](docs/tools.md), and the [security model](SECURITY-MODEL.md).
-
-## Install
+### Install
 
 ```bash
 uvx sql-safe-mcp
@@ -99,7 +94,7 @@ or
 pip install sql-safe-mcp
 ```
 
-Pin a version when you want a fixed surface: `uvx sql-safe-mcp==1.3.0`.
+Pin a version when you want a fixed surface: `uvx sql-safe-mcp==1.4.0`.
 
 Requires Python 3.12+, [uv](https://docs.astral.sh/uv/) (or `pip`), and
 [Microsoft ODBC Driver 18 for SQL Server](https://learn.microsoft.com/sql/connect/odbc/download-odbc-driver-for-sql-server)
@@ -108,10 +103,10 @@ else.
 
 Verified against SQL Server 2022, MySQL 8.4, and MariaDB 11.4 (see [CHECKS.md](CHECKS.md)).
 
-## Configure
+### Configure multiple servers
 
-Copy [sql-safe-mcp.example.yaml](sql-safe-mcp.example.yaml) to `sql-safe-mcp.yaml`, list your
-servers, and keep credentials in environment variables:
+Copy [sql-safe-mcp.example.yaml](sql-safe-mcp.example.yaml) to `sql-safe-mcp.yaml`. Add each
+database server under a named alias and keep credentials in environment variables:
 
 ```yaml
 version: 1
@@ -120,36 +115,50 @@ servers:
     engine: sqlserver
     access_level: metadata
     connection_url: "${REPORTING_SQL_URL}"
-```
-
-`connection_url` is a SQLAlchemy URL whose dialect must match `engine`. It is a secret, so keep the
-credentials in environment variables and reference them with `${NAME}`:
-
-```yaml
-servers:
-  # The whole URL comes from one variable (it may hold any valid URL).
-  reporting:
-    engine: sqlserver
-    connection_url: "${REPORTING_SQL_URL}"
 
-  # SQL Server (mssql+pyodbc), URL assembled from parts. Embedded placeholders are
-  # URL-encoded, so a password containing @ or / is safe.
   billing:
     engine: sqlserver
-    connection_url: >-
-      mssql+pyodbc://${BILLING_USER}:${BILLING_PASSWORD}@${BILLING_HOST}/master
-      ?driver=ODBC+Driver+18+for+SQL+Server&Encrypt=yes
+    access_level: pii_safe
+    connection_url: "${BILLING_SQL_URL}"
+    pii_key_env: BILLING_PII_KEY
+    pii:
+      rules:
+        - database: Billing
+          schema: dbo
+          table: Customers
+          columns: [Email, FullName]
 
-  # MySQL or MariaDB (mysql+pymysql). Use engine: mariadb for MariaDB.
   shop:
     engine: mysql
+    access_level: metadata
     connection_url: "mysql+pymysql://${SHOP_USER}:${SHOP_PASSWORD}@db.internal/shop"
 ```
 
-A missing variable, or an `engine` that does not match the URL dialect, stops the server at startup.
+Here `reporting`, `billing`, and `shop` are the values an agent passes as `server`. Their
+credentials and access policies are independent. A missing variable, or an `engine` that does not
+match the URL dialect, stops the MCP server at startup.
+
+### Ask an agent to install it
+
+Give a coding agent the following prompt when you want it to perform the setup in its own MCP
+host:
+
+```text
+Install and configure sql-safe-mcp as a stdio MCP server for this workspace. First inspect the
+host's existing MCP configuration convention and preserve all unrelated server entries. Create or
+update a non-secret YAML configuration using environment-variable placeholders only. Never put
+connection URLs, passwords, PII keys, tokens, bind values, or query results in tracked files, chat
+output, or logs. If the database aliases, engines, access levels, PII rules, configuration path,
+or secret-storage mechanism are not specified, ask me before choosing them. Configure the host to
+run `uvx sql-safe-mcp` with `SQL_SAFE_MCP_CONFIG` and the required variables supplied through the
+host's secret or environment mechanism. Run `sql-safe-mcp --check-config` after the variables are
+available, then report only the configured aliases and the validation result.
+```
+
+### Check the configuration
 
-Point the server at the file with `SQL_SAFE_MCP_CONFIG` (or `--config`), and check it without
-connecting to any database:
+After defining every environment variable referenced by the YAML file, point the server at it with
+`SQL_SAFE_MCP_CONFIG` (or `--config`) and check it without connecting to any database:
 
 ```bash
 SQL_SAFE_MCP_CONFIG=sql-safe-mcp.yaml uvx sql-safe-mcp --check-config
@@ -158,8 +167,13 @@ SQL_SAFE_MCP_CONFIG=sql-safe-mcp.yaml uvx sql-safe-mcp --check-config
 Configuration is validated at startup, and an error names the problem without printing a URL or
 secret. Keep credentials in the host's own configuration and never commit them. The server acts
 with the database account's permissions, so use a dedicated login with the least access the job
-needs. Every setting, including the runtime limits, is in
-[configuration.md](docs/configuration.md).
+needs.
+
+### Connect an MCP client
+
+Every client configuration needs `SQL_SAFE_MCP_CONFIG` plus the environment variables referenced
+by your YAML file. Keep connection URLs and PII keys in the MCP host's environment or
+configuration, never in the YAML file or other tracked files.
 
 <details>
 <summary><b>Claude Code</b></summary>
@@ -168,15 +182,15 @@ needs. Every setting, including the runtime limits, is in
 claude mcp add --env SQL_SAFE_MCP_CONFIG=/path/to/sql-safe-mcp.yaml --env REPORTING_SQL_URL=mssql+pyodbc://... --transport stdio sql-safe -- uvx sql-safe-mcp
 ```
 
-Put at least one other option between the last `--env` and the server name, as above - the CLI
-otherwise reads the name as another `KEY=value` pair.
+Put at least one other option between the last `--env` and the server name, as above. Otherwise,
+the CLI reads the name as another `KEY=value` pair.
 
 </details>
 
 <details>
 <summary><b>Claude Desktop</b></summary>
 
-In `claude_desktop_config.json`:
+Add the server to `claude_desktop_config.json`:
 
 ```json
 {
@@ -207,42 +221,43 @@ codex mcp add sql-safe --env SQL_SAFE_MCP_CONFIG=/path/to/sql-safe-mcp.yaml --en
 <details>
 <summary><b>Any other stdio host</b></summary>
 
-Command `uvx`, argument `sql-safe-mcp`, and the environment variables your configuration
-references, plus `SQL_SAFE_MCP_CONFIG`. The server speaks MCP over stdio and logs only to stderr.
+Use command `uvx`, argument `sql-safe-mcp`, and set `SQL_SAFE_MCP_CONFIG` plus every environment
+variable referenced by the configuration file. The server writes MCP messages to stdout and logs
+only to stderr.
 
 </details>
 
 ## PII-safe queries
 
-Mark an alias `access_level: pii_safe`, give it its own key, and list the protected columns:
+`execute_sql` on the `billing` alias allows one restricted `SELECT`. For example, these arguments:
 
-```yaml
-servers:
-  legacy_prod:
-    engine: sqlserver
-    access_level: pii_safe
-    connection_url: "${LEGACY_PROD_SQL_URL}"
-    pii_key_env: LEGACY_PROD_PII_KEY
-    pii:
-      rules:
-        - database: "*"
-          schema: dbo
-          table: Users
-          columns: [Email, FirstName, LastName]
+```json
+{
+  "server": "billing",
+  "database": "Billing",
+  "sql": "SELECT CustomerId, Email FROM dbo.Customers"
+}
 ```
 
-`execute_sql` then accepts one restricted `SELECT`. Protected cells come back as tokens, and a
-token is accepted only in `=` and `IN` predicates on the same alias. Protection covers the columns
-you list, so list every column that holds personal data. The rule format, key generation, and the
-accepted SQL are in [configuration.md](docs/configuration.md) and [tools.md](docs/tools.md).
+can return a row such as `[42, "pii:v1:..."]`: the agent can follow the customer without reading
+the email address. A token is accepted only in `=` and `IN` predicates on the same protected column
+and server alias. Protection covers the columns you list, so list every column that holds personal
+data.
+
+## Documentation
+
+- [Configuration reference](docs/configuration.md) - aliases, connection URLs, PII rules, runtime
+  limits, and logging.
+- [Tool reference](docs/tools.md) - arguments, responses, errors, and the accepted SQL subset.
+- [Security model](SECURITY-MODEL.md) - trust boundaries, guarantees, limitations, and verification.
+- [Checks](CHECKS.md) - local, integration, and security verification commands.
 
 ## Security
 
-The MCP caller, SQL input, database metadata, rows, and tokens are untrusted; the operator, the
-process environment, and the database credentials are the trusted boundary. Database permissions
-remain the primary authorization control - this server never widens them. The full model and its
-verification are in [SECURITY-MODEL.md](SECURITY-MODEL.md). To report a vulnerability,
-use the private channel in [SECURITY.md](SECURITY.md).
+The MCP caller, SQL input, database metadata, rows, and tokens are untrusted. Database permissions
+remain the primary authorization control - this server never widens them. Read the full
+[security model](SECURITY-MODEL.md), including its limitations and verification evidence. To report
+a vulnerability, use the private channel in [SECURITY.md](SECURITY.md).
 
 ## Contributing
 

{sql_safe_mcp-1.3.0 → sql_safe_mcp-1.4.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "sql-safe-mcp"
-version = "1.3.0"
+version = "1.4.0"
 description = "Minimal, read-only, PII-safe MCP server for SQL databases."
 readme = "README.md"
 requires-python = ">=3.12,<3.15"

{sql_safe_mcp-1.3.0 → sql_safe_mcp-1.4.0}/server.json

@@ -7,12 +7,12 @@
     "url": "https://github.com/proprock/sql-safe-mcp",
     "source": "github"
   },
-  "version": "1.3.0",
+  "version": "1.4.0",
   "packages": [
     {
       "registryType": "pypi",
       "identifier": "sql-safe-mcp",
-      "version": "1.3.0",
+      "version": "1.4.0",
       "transport": {
         "type": "stdio"
       }

{sql_safe_mcp-1.3.0 → sql_safe_mcp-1.4.0}/sql-safe-mcp.example.yaml

@@ -13,6 +13,18 @@ runtime:
   default_max_rows: 200
   hard_max_rows: 1000
 
+pii_rules:
+  - rules: # optional unnamed default: every pii_safe alias receives this rule
+      - database: "*"
+        table: "Audit*"
+        columns: [IpAddress]
+  - name: users_pii
+    rules:
+      - database: "*"
+        schema: dbo
+        table: "Users[0-9]?"
+        columns: [Email, FirstName, LastName]
+
 servers:
   legacy-prod:
     engine: sqlserver
@@ -23,11 +35,12 @@ servers:
       ?driver=ODBC+Driver+18+for+SQL+Server&Encrypt=yes
     pii_key_env: LEGACY_PROD_PII_KEY
     pii:
+      include: [users_pii]
       rules:
-        - database: "*"
+        - database: Billing
           schema: dbo
-          table: Users
-          columns: [Email, FirstName, LastName]
+          table: Cards
+          columns: [HolderName]
 
   reporting-metadata:
     engine: sqlserver

{sql_safe_mcp-1.3.0 → sql_safe_mcp-1.4.0}/src/sql_safe_mcp/__init__.py

@@ -1,3 +1,3 @@
 """Minimal, PII-safe MCP server for relational databases."""
 
-__version__ = "1.3.0"
+__version__ = "1.4.0"

{sql_safe_mcp-1.3.0 → sql_safe_mcp-1.4.0}/src/sql_safe_mcp/__main__.py

@@ -1,7 +1,9 @@
 from __future__ import annotations
 
 import argparse
+import base64
 import os
+import secrets
 import sys
 from pathlib import Path
 
@@ -10,6 +12,13 @@ from sql_safe_mcp.errors import DomainError
 from sql_safe_mcp.mcp_server import create_server
 
 
+def _positive_int(value: str) -> int:
+    count = int(value)
+    if count < 1:
+        raise argparse.ArgumentTypeError("must be a positive integer")
+    return count
+
+
 def _parser() -> argparse.ArgumentParser:
     parser = argparse.ArgumentParser(description="Run the sql-safe-mcp stdio server.")
     parser.add_argument(
@@ -18,16 +27,29 @@ def _parser() -> argparse.ArgumentParser:
         default=os.environ.get("SQL_SAFE_MCP_CONFIG", "sql-safe-mcp.yaml"),
         help="YAML configuration path (default: SQL_SAFE_MCP_CONFIG or sql-safe-mcp.yaml)",
     )
-    parser.add_argument(
+    actions = parser.add_mutually_exclusive_group()
+    actions.add_argument(
         "--check-config",
         action="store_true",
         help="Validate configuration and secrets without connecting to databases.",
     )
+    actions.add_argument(
+        "--gen-pii-key",
+        nargs="?",
+        type=_positive_int,
+        const=1,
+        metavar="N",
+        help="Print N base64-encoded 32-byte PII keys (default: 1) and exit.",
+    )
     return parser
 
 
 def main() -> None:
     args = _parser().parse_args()
+    if args.gen_pii_key is not None:
+        for _ in range(args.gen_pii_key):
+            print(base64.b64encode(secrets.token_bytes(32)).decode("ascii"))
+        return
     try:
         config = load_config(args.config)
     except DomainError as exc:

{sql_safe_mcp-1.3.0 → sql_safe_mcp-1.4.0}/src/sql_safe_mcp/config.py

@@ -5,6 +5,7 @@ import binascii
 import os
 import re
 from collections.abc import Mapping
+from copy import deepcopy
 from pathlib import Path
 from typing import Literal
 from urllib.parse import quote
@@ -17,6 +18,7 @@ from sql_safe_mcp.errors import DomainError, ErrorCode
 
 _ENV_PATTERN = re.compile(r"\$\{([A-Z_][A-Z0-9_]*)\}")
 _FULL_ENV_PATTERN = re.compile(r"^\$\{([A-Z_][A-Z0-9_]*)\}$")
+_SERVER_ALIAS_PATTERN = r"[A-Za-z0-9][A-Za-z0-9._-]*"
 
 
 class RuntimeConfig(BaseModel):
@@ -59,8 +61,8 @@ class PiiRule(BaseModel):
 
     @model_validator(mode="after")
     def validate_wildcards(self) -> PiiRule:
-        if "*" in self.table or (self.schema_ and "*" in self.schema_):
-            raise ValueError("wildcards are allowed only in pii rule database")
+        if self.schema_ and "*" in self.schema_:
+            raise ValueError("wildcards are allowed only in pii rule table or database")
         if self.database != "*" and "*" in self.database:
             raise ValueError("database must be an exact name or '*'")
         folded = [column.casefold() for column in self.columns]
@@ -75,6 +77,24 @@ class PiiConfig(BaseModel):
     rules: list[PiiRule] = Field(min_length=1)
 
 
+class PiiConfigInput(BaseModel):
+    """The YAML-only PII shape before shared rules are resolved."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    include: list[str] = Field(default_factory=list)
+    rules: list[PiiRule] = Field(default_factory=list)
+
+
+class PiiRuleSet(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    name: str | None = Field(default=None, pattern=rf"^{_SERVER_ALIAS_PATTERN}$")
+    rules: list[PiiRule] = Field(min_length=1)
+
+
+_PERCENT_ESCAPE = re.compile(r"%[0-9A-Fa-f]{2}")
+
 _DRIVERNAMES = {
     "sqlserver": "mssql+pyodbc",
     "mysql": "mysql+pymysql",
@@ -82,16 +102,39 @@ _DRIVERNAMES = {
 }
 
 
-class ServerConfig(BaseModel):
+class ServerConfigBase(BaseModel):
     model_config = ConfigDict(extra="forbid")
 
     engine: Literal["sqlserver", "mysql", "mariadb"]
     access_level: Literal["metadata", "pii_safe"] = "metadata"
     connection_url: SecretStr
     pii_key_env: str | None = Field(default=None, pattern=r"^[A-Z_][A-Z0-9_]*$")
-    pii: PiiConfig | None = None
     pii_key: SecretStr | None = Field(default=None, exclude=True)
 
+    @model_validator(mode="after")
+    def validate_connection_url(self) -> ServerConfigBase:
+        url = make_url(self.connection_url.get_secret_value())
+        if url.host and _PERCENT_ESCAPE.search(url.host):
+            raise ValueError(
+                "connection_url host contains an encoded character; a ${NAME} placeholder inside "
+                "a URL is URL-encoded, so a 'host:port' value breaks. "
+                "Use separate ${HOST} and ${PORT} variables"
+            )
+        driver = url.drivername
+        expected = _DRIVERNAMES[self.engine]
+        if driver != expected:
+            raise ValueError(f"engine {self.engine!r} requires SQLAlchemy dialect {expected!r}")
+        return self
+
+    def key_bytes(self) -> bytes | None:
+        if self.pii_key is None:
+            return None
+        return base64.b64decode(self.pii_key.get_secret_value(), validate=True)
+
+
+class ServerConfig(ServerConfigBase):
+    pii: PiiConfig | None = None
+
     @model_validator(mode="after")
     def validate_security_shape(self) -> ServerConfig:
         if self.access_level == "pii_safe":
@@ -101,17 +144,11 @@ class ServerConfig(BaseModel):
                 raise ValueError(f"pii rules for engine {self.engine!r} cannot set schema")
         elif self.pii_key_env is not None or self.pii is not None:
             raise ValueError("metadata servers cannot configure pii_key_env or pii rules")
-
-        driver = make_url(self.connection_url.get_secret_value()).drivername
-        expected = _DRIVERNAMES[self.engine]
-        if driver != expected:
-            raise ValueError(f"engine {self.engine!r} requires SQLAlchemy dialect {expected!r}")
         return self
 
-    def key_bytes(self) -> bytes | None:
-        if self.pii_key is None:
-            return None
-        return base64.b64decode(self.pii_key.get_secret_value(), validate=True)
+
+class ServerConfigInput(ServerConfigBase):
+    pii: PiiConfigInput | None = None
 
 
 class AppConfig(BaseModel):
@@ -126,7 +163,7 @@ class AppConfig(BaseModel):
     def validate_aliases_and_keys(self) -> AppConfig:
         seen_keys: dict[bytes, str] = {}
         for alias, server in self.servers.items():
-            if not re.fullmatch(r"[A-Za-z0-9][A-Za-z0-9._-]*", alias):
+            if not re.fullmatch(_SERVER_ALIAS_PATTERN, alias):
                 raise ValueError(f"invalid server alias {alias!r}")
             key = server.key_bytes()
             if key is None:
@@ -141,6 +178,18 @@ class AppConfig(BaseModel):
         return self
 
 
+class AppConfigInput(BaseModel):
+    """Strict top-level YAML shape, including shared PII rule declarations."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    version: Literal[1]
+    runtime: RuntimeConfig = Field(default_factory=RuntimeConfig)
+    logging: LoggingConfig = Field(default_factory=LoggingConfig)
+    pii_rules: list[PiiRuleSet] | None = Field(default=None, min_length=1)
+    servers: dict[str, ServerConfigInput] = Field(min_length=1)
+
+
 def _expand_connection_url(template: str, environ: Mapping[str, str]) -> str:
     full_match = _FULL_ENV_PATTERN.fullmatch(template)
     if full_match:
@@ -169,6 +218,54 @@ def _validation_summary(error: ValidationError) -> str:
     return "; ".join(issues)
 
 
+def _resolve_pii_rules(raw: dict[object, object], config: AppConfigInput) -> dict[object, object]:
+    """Flatten shared PII rules before runtime configuration is constructed."""
+
+    default_rules: list[PiiRule] = []
+    named_rules: dict[str, list[PiiRule]] = {}
+    for rule_set in config.pii_rules or []:
+        if rule_set.name is None:
+            if default_rules:
+                raise ValueError("at most one unnamed pii rule set is allowed")
+            default_rules = rule_set.rules
+            continue
+        if rule_set.name in named_rules:
+            raise ValueError(f"duplicate pii rule set name {rule_set.name!r}")
+        named_rules[rule_set.name] = rule_set.rules
+
+    resolved = deepcopy(raw)
+    resolved.pop("pii_rules", None)
+    servers = resolved["servers"]
+    assert isinstance(servers, dict)
+    for alias, server in config.servers.items():
+        server_data = servers[alias]
+        assert isinstance(server_data, dict)
+        if server.access_level == "metadata":
+            if server.pii is not None:
+                raise ValueError("metadata servers cannot configure pii_key_env or pii rules")
+            continue
+
+        effective_rules = list(default_rules)
+        if server.pii is not None:
+            included: set[str] = set()
+            for name in server.pii.include:
+                if name not in named_rules:
+                    raise ValueError(f"server {alias!r} includes unknown pii rule set {name!r}")
+                if name in included:
+                    raise ValueError(
+                        f"server {alias!r} includes pii rule set {name!r} more than once"
+                    )
+                included.add(name)
+                effective_rules.extend(named_rules[name])
+            effective_rules.extend(server.pii.rules)
+        server_data["pii"] = (
+            {"rules": [rule.model_dump(by_alias=True) for rule in effective_rules]}
+            if effective_rules
+            else None
+        )
+    return resolved
+
+
 def load_config(path: str | Path, environ: Mapping[str, str] | None = None) -> AppConfig:
     env = os.environ if environ is None else environ
     try:
@@ -196,7 +293,8 @@ def load_config(path: str | Path, environ: Mapping[str, str] | None = None) -> A
                 if len(decoded) != 32:
                     raise ValueError(f"PII key for server {alias!r} must decode to 32 bytes")
                 value["pii_key"] = env[key_env]
-        return AppConfig.model_validate(raw)
+        input_config = AppConfigInput.model_validate(raw)
+        return AppConfig.model_validate(_resolve_pii_rules(raw, input_config))
     except ValidationError as exc:
         raise DomainError(
             ErrorCode.CONFIG_ERROR,

{sql_safe_mcp-1.3.0 → sql_safe_mcp-1.4.0}/src/sql_safe_mcp/mcp_server.py

@@ -52,7 +52,7 @@ def create_server(config: AppConfig) -> MCPServer[AppContext]:
     server: MCPServer[AppContext] = MCPServer(
         "sql-safe-mcp",
         description="Minimal, read-only, PII-safe SQL database navigation.",
-        version="1.3.0",
+        version="1.4.0",
         lifespan=lifespan,
         log_level=config.logging.level,
     )

{sql_safe_mcp-1.3.0 → sql_safe_mcp-1.4.0}/src/sql_safe_mcp/security/policy.py

@@ -1,6 +1,7 @@
 from __future__ import annotations
 
 from dataclasses import dataclass, field
+from fnmatch import fnmatchcase
 
 from sqlglot import exp
 
@@ -42,7 +43,9 @@ class PiiPolicy:
                 continue
             if rule.schema_ is not None and rule.schema_.casefold() != schema:
                 continue
-            if rule.table.casefold() == table and column in {c.casefold() for c in rule.columns}:
+            if fnmatchcase(table, rule.table.casefold()) and column in {
+                item.casefold() for item in rule.columns
+            }:
                 return True
         return False