sql-safe-mcp 1.5.0__tar.gz → 1.5.2__tar.gz

{sql_safe_mcp-1.5.0 → sql_safe_mcp-1.5.2}/CHANGELOG.md

@@ -7,6 +7,28 @@ categories `Added`, `Changed`, `Deprecated`, `Removed`, `Fixed`, and `Security`.
 
 ## [Unreleased]
 
+## [1.5.2] - 2026-10-05
+
+### Security
+
+- `execute_sql` now rejects a projection whose alias names anything other than a direct column,
+  a literal, or `COUNT(*)`, such as `SELECT (Email) AS e FROM Users`. Before, the expression was
+  classified as a literal, so a protected column wrapped in parentheses was returned in clear,
+  and on MySQL/MariaDB a projected comparison such as `(Email > 'm') AS x` acted as an oracle on
+  the protected value. The lineage stage also fails closed on any untraceable projection.
+
+## [1.5.1] - 2026-09-23
+
+### Fixed
+
+- Malformed `connection_url` values now return a sanitized `CONFIG_ERROR` instead of an unhandled
+  traceback. DBAPI errors now prefer supported SQLSTATE and native error codes over driver text.
+
+### Security
+
+- The Bash and PowerShell demo seeding scripts reject reader-password characters unsafe for their
+  SQL command boundary.
+
 ## [1.5.0] - 2026-09-22
 
 ### Changed

{sql_safe_mcp-1.5.0 → sql_safe_mcp-1.5.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: sql-safe-mcp
-Version: 1.5.0
+Version: 1.5.2
 Summary: Minimal, read-only, PII-safe MCP server for SQL databases.
 License: MIT License
         
@@ -83,7 +83,7 @@ query real rows while configured personal data stays hidden behind authenticated
 
 - **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).
+  the [security model](docs/security-model.md).
 - **Least access first** - `access_level: metadata` (the default) exposes database navigation and
   table structure; `meta_and_code` additionally exposes stored procedures; `execute_sql` needs an
   explicit `all_pii_safe` alias with its own key. Database permissions stay the primary control,
@@ -98,7 +98,7 @@ query real rows while configured personal data stays hidden behind authenticated
   adversarial corpus of hostile statements, property-based tests (token isolation, tamper
   resistance), a live attack run against a really writable login with before/after snapshots, and
   mutation testing. Results are in
-  [Verification of the SQL boundary](SECURITY-MODEL.md#verification-of-the-sql-boundary).
+  [Verification of the SQL boundary](docs/security-model.md#verification-of-the-sql-boundary).
 - **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).
@@ -117,7 +117,7 @@ query real rows while configured personal data stays hidden behind authenticated
 > **Status:** SQL Server supports every tool. MySQL and MariaDB (`engine: mysql` or `mariadb`,
 > `mysql+pymysql` URLs) support every tool too. `schema` is always `null` there because the
 > database is the catalog, and `execute_sql` uses `LIMIT` instead of `TOP`. See
-> [ARCHITECTURE.md](ARCHITECTURE.md).
+> [architecture.md](docs/architecture.md).
 
 ## Quick start
 
@@ -133,14 +133,14 @@ or
 pip install sql-safe-mcp
 ```
 
-Pin a version when you want a fixed surface: `uvx sql-safe-mcp==1.5.0`.
+Pin a version when you want a fixed surface: `uvx sql-safe-mcp==1.5.2`.
 
-Requires Python 3.12+, [uv](https://docs.astral.sh/uv/) (or `pip`), and
+Requires Python 3.12–3.14, [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)
 when you connect to SQL Server. MySQL and MariaDB use the bundled PyMySQL driver and need nothing
 else.
 
-Verified against SQL Server 2022, MySQL 8.4, and MariaDB 11.4 (see [CHECKS.md](CHECKS.md)).
+Verified against SQL Server 2022, MySQL 8.4, and MariaDB 11.4 (see [checks.md](docs/checks.md)).
 
 <details>
 <summary><b>Or you can even ask an agent to install it</b></summary>
@@ -265,23 +265,26 @@ only to stderr.
 ```
 
 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.
+the email address. A token is accepted only in `=` and `IN` predicates on the same server alias.
+If `FirstName` is protected, `SELECT FirstName FROM Users WHERE FirstName = 'Alice'` is rejected
+before it reaches the database. Filter protected columns only with authentic `pii:v1:...` tokens
+returned by `execute_sql` for the same alias; a matching prefix alone is not enough. Each token is
+authenticated and alias-bound, then validated and converted to a bound database value.
+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 model](docs/security-model.md) - trust boundaries, guarantees, limitations, and verification.
+- [Checks](docs/checks.md) - local, integration, and security verification commands.
 
 ## Security
 
 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
+[security model](docs/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.5.0 → sql_safe_mcp-1.5.2}/README.md

@@ -45,7 +45,7 @@ query real rows while configured personal data stays hidden behind authenticated
 
 - **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).
+  the [security model](docs/security-model.md).
 - **Least access first** - `access_level: metadata` (the default) exposes database navigation and
   table structure; `meta_and_code` additionally exposes stored procedures; `execute_sql` needs an
   explicit `all_pii_safe` alias with its own key. Database permissions stay the primary control,
@@ -60,7 +60,7 @@ query real rows while configured personal data stays hidden behind authenticated
   adversarial corpus of hostile statements, property-based tests (token isolation, tamper
   resistance), a live attack run against a really writable login with before/after snapshots, and
   mutation testing. Results are in
-  [Verification of the SQL boundary](SECURITY-MODEL.md#verification-of-the-sql-boundary).
+  [Verification of the SQL boundary](docs/security-model.md#verification-of-the-sql-boundary).
 - **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).
@@ -79,7 +79,7 @@ query real rows while configured personal data stays hidden behind authenticated
 > **Status:** SQL Server supports every tool. MySQL and MariaDB (`engine: mysql` or `mariadb`,
 > `mysql+pymysql` URLs) support every tool too. `schema` is always `null` there because the
 > database is the catalog, and `execute_sql` uses `LIMIT` instead of `TOP`. See
-> [ARCHITECTURE.md](ARCHITECTURE.md).
+> [architecture.md](docs/architecture.md).
 
 ## Quick start
 
@@ -95,14 +95,14 @@ or
 pip install sql-safe-mcp
 ```
 
-Pin a version when you want a fixed surface: `uvx sql-safe-mcp==1.5.0`.
+Pin a version when you want a fixed surface: `uvx sql-safe-mcp==1.5.2`.
 
-Requires Python 3.12+, [uv](https://docs.astral.sh/uv/) (or `pip`), and
+Requires Python 3.12–3.14, [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)
 when you connect to SQL Server. MySQL and MariaDB use the bundled PyMySQL driver and need nothing
 else.
 
-Verified against SQL Server 2022, MySQL 8.4, and MariaDB 11.4 (see [CHECKS.md](CHECKS.md)).
+Verified against SQL Server 2022, MySQL 8.4, and MariaDB 11.4 (see [checks.md](docs/checks.md)).
 
 <details>
 <summary><b>Or you can even ask an agent to install it</b></summary>
@@ -227,23 +227,26 @@ only to stderr.
 ```
 
 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.
+the email address. A token is accepted only in `=` and `IN` predicates on the same server alias.
+If `FirstName` is protected, `SELECT FirstName FROM Users WHERE FirstName = 'Alice'` is rejected
+before it reaches the database. Filter protected columns only with authentic `pii:v1:...` tokens
+returned by `execute_sql` for the same alias; a matching prefix alone is not enough. Each token is
+authenticated and alias-bound, then validated and converted to a bound database value.
+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 model](docs/security-model.md) - trust boundaries, guarantees, limitations, and verification.
+- [Checks](docs/checks.md) - local, integration, and security verification commands.
 
 ## Security
 
 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
+[security model](docs/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.5.0 → sql_safe_mcp-1.5.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "sql-safe-mcp"
-version = "1.5.0"
+version = "1.5.2"
 description = "Minimal, read-only, PII-safe MCP server for SQL databases."
 readme = "README.md"
 requires-python = ">=3.12,<3.15"
@@ -62,7 +62,7 @@ markers = [
 
 [tool.mutmut]
 source_paths = ["src/sql_safe_mcp"]
-also_copy = ["server.json", "README.md"]
+also_copy = ["server.json", "README.md", "tools", "scripts", "compose.sqlserver.yml", "compose.mysql.yml"]
 only_mutate = ["*security/*.py", "*config.py"]
 mutate_only_covered_lines = true
 pytest_add_cli_args = ["-q", "-m", "not integration and not deep", "-p", "no:cacheprovider"]

{sql_safe_mcp-1.5.0 → sql_safe_mcp-1.5.2}/server.json

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

{sql_safe_mcp-1.5.0 → sql_safe_mcp-1.5.2}/src/sql_safe_mcp/__init__.py

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

{sql_safe_mcp-1.5.0 → sql_safe_mcp-1.5.2}/src/sql_safe_mcp/config.py

@@ -13,6 +13,7 @@ from urllib.parse import quote
 import yaml
 from pydantic import BaseModel, ConfigDict, Field, SecretStr, ValidationError, model_validator
 from sqlalchemy.engine import make_url
+from sqlalchemy.exc import ArgumentError
 
 from sql_safe_mcp.errors import DomainError, ErrorCode
 
@@ -113,7 +114,10 @@ class ServerConfigBase(BaseModel):
 
     @model_validator(mode="after")
     def validate_connection_url(self) -> ServerConfigBase:
-        url = make_url(self.connection_url.get_secret_value())
+        try:
+            url = make_url(self.connection_url.get_secret_value())
+        except ArgumentError as exc:
+            raise ValueError("connection_url must be a valid SQLAlchemy URL") from exc
         if url.host and _PERCENT_ESCAPE.search(url.host):
             raise ValueError(
                 "connection_url host contains an encoded character; a ${NAME} placeholder inside "

{sql_safe_mcp-1.5.0 → sql_safe_mcp-1.5.2}/src/sql_safe_mcp/mcp_server.py

@@ -8,6 +8,7 @@ from mcp.server.mcpserver import Context, MCPServer
 from mcp.server.mcpserver.exceptions import ToolError
 from mcp_types import ToolAnnotations
 
+from sql_safe_mcp import __version__
 from sql_safe_mcp.config import AppConfig
 from sql_safe_mcp.db.registry import EngineRegistry
 from sql_safe_mcp.diagnostics import configure_logging
@@ -29,7 +30,6 @@ READ_ONLY = ToolAnnotations(read_only_hint=True, open_world_hint=False)
 @dataclass(slots=True)
 class AppContext:
     service: DatabaseService
-    registry: EngineRegistry
 
 
 async def _domain_call[T](operation: Callable[[], Awaitable[T]]) -> T:
@@ -44,7 +44,7 @@ def create_server(config: AppConfig) -> MCPServer[AppContext]:
     async def lifespan(_server: MCPServer[AppContext]) -> AsyncIterator[AppContext]:
         registry = EngineRegistry(config)
         try:
-            yield AppContext(service=DatabaseService(config, registry), registry=registry)
+            yield AppContext(service=DatabaseService(config, registry))
         finally:
             registry.dispose()
 
@@ -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.5.0",
+        version=__version__,
         lifespan=lifespan,
         log_level=config.logging.level,
     )

{sql_safe_mcp-1.5.0 → sql_safe_mcp-1.5.2}/src/sql_safe_mcp/security/lineage.py

@@ -142,8 +142,11 @@ def _analyze_projections(
             outputs.append(OutputColumn(alias or canonical, "column", source, binding.name))
         elif isinstance(value, exp.Count):
             outputs.append(OutputColumn(alias or f"column_{index}", "count", None))
-        else:
+        elif isinstance(value, exp.Literal | exp.Null | exp.Neg):
             outputs.append(OutputColumn(alias or f"column_{index}", "literal", None))
+        else:
+            # Fail closed: a projection whose source cannot be traced is never a "literal".
+            raise reject(Reason.PROJECTION_UNSUPPORTED)
     return outputs
 
 

{sql_safe_mcp-1.5.0 → sql_safe_mcp-1.5.2}/src/sql_safe_mcp/security/parser.py

@@ -80,6 +80,10 @@ _ALLOWED_ARGS: dict[type[exp.Expr], frozenset[str]] = {
     **{comparison: frozenset({"this", "expression"}) for comparison in _COMPARISONS},
 }
 _PLACEHOLDER_ARGS = frozenset({"this"})
+# What an alias may name: a direct column, a literal, or COUNT(*). Anything else (a Paren, a
+# comparison, ...) would be invisible to lineage and could project a protected column in clear.
+# A Star under an alias is still rejected by the Star branch below with its own reason.
+_ALIASED = (exp.Column, exp.Star, exp.Literal, exp.Null, exp.Neg, exp.Count)
 _PROJECTIONS = (exp.Column, exp.Star, exp.Literal, exp.Null, exp.Neg, exp.Alias, exp.Count)
 
 
@@ -110,6 +114,9 @@ def _check_node(node: exp.Expr, allow_placeholders: bool) -> None:
     elif isinstance(node, exp.Column):
         if not isinstance(node.this, (exp.Identifier, exp.Star)):
             raise reject(Reason.COLUMN_REFERENCE_UNSUPPORTED)
+    elif isinstance(node, exp.Alias):
+        if not isinstance(node.this, _ALIASED):
+            raise reject(Reason.PROJECTION_UNSUPPORTED)
     elif isinstance(node, exp.Count):
         if not isinstance(node.this, exp.Star):
             raise reject(Reason.COUNT_STAR_ONLY)

{sql_safe_mcp-1.5.0 → sql_safe_mcp-1.5.2}/src/sql_safe_mcp/service.py

@@ -1,6 +1,7 @@
 from __future__ import annotations
 
 import logging
+import re
 import time
 from collections.abc import Callable
 from typing import TypeVar
@@ -42,6 +43,12 @@ logger = logging.getLogger(__name__)
 CatalogFactory = Callable[[Connection, str, str], TableCatalog]
 _SCHEMA_CACHE_ENTRIES = 1024
 _SCHEMA_CACHE_TTL_SECONDS = 300.0
+_TIMEOUT_SQLSTATES = frozenset({"HYT00", "HYT01"})
+_CONNECTION_SQLSTATES = frozenset({"08001", "08004"})
+_ACCESS_DENIED_SQLSTATES = frozenset({"28000"})
+_TIMEOUT_NATIVE_CODES = frozenset({-2})
+_CONNECTION_NATIVE_CODES = frozenset({1049, 2003, 4060})
+_ACCESS_DENIED_NATIVE_CODES = frozenset({229, 1044, 1045, 18456})
 T = TypeVar("T")
 
 
@@ -63,6 +70,48 @@ def _connection_error() -> DomainError:
     )
 
 
+def _driver_codes(exc: DBAPIError) -> tuple[frozenset[str], frozenset[int]]:
+    sqlstates: set[str] = set()
+    native_codes: set[int] = set()
+    for value in getattr(exc.orig, "args", ()):
+        if isinstance(value, str):
+            if re.fullmatch(r"[A-Za-z0-9]{5}", value):
+                sqlstates.add(value.upper())
+            native_codes.update(int(code) for code in re.findall(r"\((-?\d+)\)", value))
+        elif isinstance(value, int) and not isinstance(value, bool):
+            native_codes.add(value)
+    return frozenset(sqlstates), frozenset(native_codes)
+
+
+def _classify_dbapi_error(exc: DBAPIError) -> DomainError | None:
+    sqlstates, native_codes = _driver_codes(exc)
+    if sqlstates & _TIMEOUT_SQLSTATES or native_codes & _TIMEOUT_NATIVE_CODES:
+        return _timeout_error()
+    if sqlstates & _CONNECTION_SQLSTATES or native_codes & _CONNECTION_NATIVE_CODES:
+        return _connection_error()
+    if sqlstates & _ACCESS_DENIED_SQLSTATES or native_codes & _ACCESS_DENIED_NATIVE_CODES:
+        return DomainError(ErrorCode.ACCESS_DENIED, "The database denied this operation.")
+
+    message = str(exc.orig).casefold()
+    if any(value in message for value in ("timeout", "timed out", "hyt00", "hyt01")):
+        return _timeout_error()
+    if any(
+        value in message
+        for value in (
+            "permission denied",
+            "permission was denied",
+            "access denied",
+            "not authorized",
+        )
+    ):
+        return DomainError(ErrorCode.ACCESS_DENIED, "The database denied this operation.")
+    if any(
+        value in message for value in ("cannot open database", "(4060)", "08001", "08004")
+    ) or isinstance(exc, OperationalError):
+        return _connection_error()
+    return None
+
+
 def _contains(value: str, needle: str | None) -> bool:
     return needle is None or needle.casefold() in value.casefold()
 
@@ -158,25 +207,8 @@ class DatabaseService:
         except SQLAlchemyTimeoutError as exc:
             raise self._classified(alias, database, operation_name, _timeout_error(), exc) from exc
         except DBAPIError as exc:
-            message = str(exc.orig).casefold()
-            if any(value in message for value in ("timeout", "timed out", "hyt00", "hyt01")):
-                raise self._classified(
-                    alias, database, operation_name, _timeout_error(), exc
-                ) from exc
-            if any(value in message for value in ("permission", "denied", "not authorized")):
-                raise self._classified(
-                    alias,
-                    database,
-                    operation_name,
-                    DomainError(ErrorCode.ACCESS_DENIED, "The database denied this operation."),
-                    exc,
-                ) from exc
-            if any(
-                value in message for value in ("cannot open database", "(4060)", "08001", "08004")
-            ) or isinstance(exc, OperationalError):
-                raise self._classified(
-                    alias, database, operation_name, _connection_error(), exc
-                ) from exc
+            if error := _classify_dbapi_error(exc):
+                raise self._classified(alias, database, operation_name, error, exc) from exc
             raise self._unexpected(
                 "Database operation failed", alias, database, operation_name, exc
             ) from exc