mcp-read-only-sql 0.2.1__tar.gz → 0.2.5__tar.gz

{mcp_read_only_sql-0.2.1 → mcp_read_only_sql-0.2.5}/AGENTS.md

@@ -1,7 +1,7 @@
 # Repository Guidelines
 
 ## Project Structure & Module Organization
-`src/mcp_read_only_sql/server.py` exposes the MCP entry point, while `src/mcp_read_only_sql/connectors/` hosts the PostgreSQL and ClickHouse adapters. Cross-cutting helpers (`ssh_tunnel.py`, `sql_guard.py`, TSV formatting) live in `src/mcp_read_only_sql/utils/`. Configuration tooling, including DBeaver import and manifest validation, sits in `src/mcp_read_only_sql/config/` and `src/mcp_read_only_sql/tools/`. Tests are grouped in `tests/`, and Docker fixtures for integration runs reside in `docker/`. The package ships a sample `connections.yaml`, and runtime config lives under `~/.config/lukleh/mcp-read-only-sql/`.
+`src/mcp_read_only_sql/server.py` exposes the MCP entry point, while `src/mcp_read_only_sql/connectors/` hosts the PostgreSQL and ClickHouse adapters for both CLI and Python implementations. Cross-cutting helpers (`ssh_tunnel.py`, `ssh_tunnel_cli.py`, `sql_guard.py`, TSV formatting, timeout handling) live in `src/mcp_read_only_sql/utils/`. Configuration tooling, including DBeaver import and manifest validation, sits in `src/mcp_read_only_sql/config/` and `src/mcp_read_only_sql/tools/`. Tests are grouped in `tests/`, and Docker fixtures for integration runs reside in `docker/`. The package ships a sample `connections.yaml`, and runtime config lives under `~/.config/lukleh/mcp-read-only-sql/`.
 
 ## Build, Test, and Development Commands
 - `uv sync --extra dev` — install runtime and development dependencies.
@@ -11,9 +11,11 @@
 - `just validate` — lint `connections.yaml` against the schema and safety checks.
 - `just test` — spin up Dockerized fixtures and execute the full pytest suite via `./run_tests.sh`.
 - `uv run python -m pytest tests/test_sql_guard.py` — run an individual module when iterating quickly.
+- `uv run ruff check .` and `uv run black .` — run linting and formatting for the Python tree.
+- `uv run ty check` — type-check the full `src/` tree; there are no remaining package excludes.
 
 ## Coding Style & Naming Conventions
-Target Python 3.11+, four-space indentation, and Unix newlines. Format with `uv run black .` and lint via `uv run ruff check .`; CI mirrors these checks. Modules and callables use snake_case, classes PascalCase (e.g., `TestReadOnlyGuards`), and immutable settings uppercase (`DEFAULT_QUERY_TIMEOUT`). Apply type hints on public surfaces and keep docstrings brief, emphasising read-only guarantees.
+Target Python 3.11+, four-space indentation, and Unix newlines. Format with `uv run black .`, lint via `uv run ruff check .`, and keep `uv run ty check` passing for `src/`. Modules and callables use snake_case, classes PascalCase (e.g., `TestReadOnlyGuards`), and immutable settings uppercase (`DEFAULT_QUERY_TIMEOUT`). Apply type hints on public surfaces and keep docstrings brief, emphasizing read-only guarantees and connector behavior.
 
 ## Testing Guidelines
 Pytest discovers `test_*.py` modules, `Test*` classes, and `test_*` functions per `pytest.ini`. Use the built-in markers (`security`, `cli`, `python`, `ssh`, `slow`) to scope runs, e.g. `pytest -m "security and not slow"`. A 30s default timeout applies, so tear down tunnels and subprocesses explicitly. `just test` emits JUnit XML at `test-results/pytest.xml` for CI uploads.
@@ -22,4 +24,4 @@ Pytest discovers `test_*.py` modules, `Test*` classes, and `test_*` functions pe
 Recent commits favour imperative, concise subjects (“Refactor PostgreSQL read-only guard into shared utility”). Keep changes focused and explain security or connector impacts in the body when needed. Pull requests should describe motivation, list affected modules or scripts, link issues, and attach logs or screenshots for operational updates.
 
 ## Security & Configuration Tips
-Do not relax safeguards in `src/mcp_read_only_sql/utils/sql_guard.py` or connector factories without matching tests. Treat `connections.yaml` as sensitive; the server stores database and SSH passwords directly in that file, so keep it private and user-readable only. Use the SSH tunnel helpers instead of bespoke subprocesses to preserve timeout and read-only enforcement.
+Do not relax safeguards in `src/mcp_read_only_sql/utils/sql_guard.py` or connector factories without matching tests. Treat `connections.yaml` as sensitive; the server stores database and SSH passwords directly in that file, so keep it private and user-readable only. Use the shared SSH tunnel and timeout helpers instead of bespoke subprocesses so read-only enforcement, cleanup, and managed result-file behavior stay consistent.

{mcp_read_only_sql-0.2.1 → mcp_read_only_sql-0.2.5}/CHANGELOG.md

@@ -7,6 +7,34 @@ and this project aims to follow [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [0.2.5] - 2026-04-21
+
+### Added
+
+- Added hot-reload regression tests covering connection add/change/remove flows, invalid live edits, and config changes that happen during a reload attempt.
+
+### Fixed
+
+- Reloaded `connections.yaml` automatically before both `list_connections` and `run_query_read_only`, without requiring an MCP server restart.
+- Kept hot-reload state atomic by building connectors from a single file snapshot and only storing a config marker for the exact snapshot that was actually loaded.
+- Preserved the last known good connections when live config edits are invalid or the config file is temporarily missing, while continuing to retry reloads on later tool calls.
+
+## [0.2.2] - 2026-04-03
+
+### Added
+
+- Added `ty` as a supported development check for the full packaged `src/` tree.
+
+### Changed
+
+- Added repo-specific `AGENTS.md` guidance covering connector layout, shared timeout and SSH helpers, and the typed development workflow.
+- Reworked `RELEASING.md` into an evergreen release checklist with explicit validation, tagging, and publish steps.
+
+### Fixed
+
+- Flushed the final buffered TSV line when PostgreSQL and ClickHouse CLI queries stream results to an output file.
+- Hardened DBeaver credential import so missing or non-dictionary decrypted sections are ignored cleanly instead of being treated as valid connection data.
+
 ## [0.2.1] - 2026-04-02
 
 ### Added

{mcp_read_only_sql-0.2.1 → mcp_read_only_sql-0.2.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mcp-read-only-sql
-Version: 0.2.1
+Version: 0.2.5
 Summary: MCP server for read-only SQL queries supporting PostgreSQL and ClickHouse
 Project-URL: Homepage, https://github.com/lukleh/mcp-read-only-sql
 Project-URL: Repository, https://github.com/lukleh/mcp-read-only-sql
@@ -29,6 +29,8 @@ Requires-Dist: black>=23.0.0; extra == 'dev'
 Requires-Dist: pytest-timeout>=2.2.0; extra == 'dev'
 Requires-Dist: pytest>=7.0.0; extra == 'dev'
 Requires-Dist: ruff>=0.1.0; extra == 'dev'
+Requires-Dist: ty>=0.0.28; extra == 'dev'
+Requires-Dist: vulture>=2.16; extra == 'dev'
 Description-Content-Type: text/markdown
 
 # MCP Read-Only SQL Server

mcp_read_only_sql-0.2.5/RELEASING.md

@@ -0,0 +1,76 @@
+# Releasing `mcp-read-only-sql`
+
+This repository publishes to PyPI from Git tags through GitHub Actions.
+
+Release automation lives in:
+- `.github/workflows/publish.yml`
+- `.github/workflows/test.yml`
+- the GitHub environment named `pypi`
+- the PyPI trusted publisher for `lukleh/mcp-read-only-sql`
+
+## What To Change For A Release
+
+Update these files in the release commit:
+
+1. `CHANGELOG.md`
+   Move the user-visible items from `## [Unreleased]` into a new section:
+   `## [X.Y.Z] - YYYY-MM-DD`
+2. `pyproject.toml`
+   Update `[project].version` to `X.Y.Z`
+
+Do not expect a tracked `uv.lock` change in this repository. `uv.lock` is
+gitignored here, so it is not part of the release diff.
+
+`RELEASING.md` should stay evergreen. It should explain the process, not carry a
+release-specific version number.
+
+## How To Update The Version
+
+1. Edit `pyproject.toml`
+2. Refresh the local environment if needed:
+
+```bash
+uv sync --extra dev
+```
+
+3. Confirm the installed package metadata and CLI version output match:
+
+```bash
+uv run --extra dev pytest tests/test_server.py tests/test_cli_versions.py -q -k 'package_version_matches_distribution_metadata or support_version'
+```
+
+## Pre-Release Validation
+
+Run the normal local checks before tagging:
+
+```bash
+uv run --extra dev ruff check .
+uv run --extra dev ty check
+./run_tests.sh
+```
+
+If you are iterating on release metadata only, the focused version tests above
+are the minimum sanity check.
+
+## How To Publish
+
+1. Make the release commit on `main`
+2. Create and push the matching tag:
+
+```bash
+git tag vX.Y.Z
+git push origin main
+git push origin vX.Y.Z
+```
+
+3. GitHub Actions starts `.github/workflows/publish.yml`
+4. The workflow runs the test matrix, builds the wheel and sdist, and smoke-tests the built artifacts
+5. The final publish job pauses on the GitHub `pypi` environment
+6. Approve the deployment in GitHub Actions
+7. GitHub publishes the package to PyPI
+
+## Notes
+
+- Keep both `implementation: cli` and `implementation: python` clearly supported in release notes and docs
+- `uvx` installs the Python package only; it does not install `psql`, `clickhouse-client`, or `sshpass`
+- If the public CLI or result-file behavior changes, keep the package smoke tests and README aligned with `mcp-read-only-sql`

{mcp_read_only_sql-0.2.1 → mcp_read_only_sql-0.2.5}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "mcp-read-only-sql"
-version = "0.2.1"
+version = "0.2.5"
 description = "MCP server for read-only SQL queries supporting PostgreSQL and ClickHouse"
 readme = "README.md"
 requires-python = ">=3.11"
@@ -39,6 +39,8 @@ dev = [
     "pytest-timeout>=2.2.0",
     "black>=23.0.0",
     "ruff>=0.1.0",
+    "ty>=0.0.28",
+    "vulture>=2.16",
 ]
 
 [build-system]
@@ -50,3 +52,13 @@ mcp-read-only-sql = "mcp_read_only_sql.server:main"
 
 [tool.hatch.build.targets.wheel]
 packages = ["src/mcp_read_only_sql"]
+
+[tool.ty.src]
+include = ["src"]
+
+[tool.vulture]
+paths = ["src", "tests"]
+exclude = [".venv", "venv", "build", "dist", "node_modules", "__pycache__", "site-packages"]
+ignore_decorators = ["@*.tool*", "@pytest.fixture"]
+ignore_names = ["pytest_*"]
+min_confidence = 80

mcp_read_only_sql-0.2.5/src/mcp_read_only_sql/config/__init__.py

@@ -0,0 +1,14 @@
+"""
+Configuration module for connection management
+"""
+
+from .connection import Connection, Server, SSHTunnelConfig
+from .loader import load_connections, load_connections_from_text
+
+__all__ = [
+    "Connection",
+    "Server",
+    "SSHTunnelConfig",
+    "load_connections",
+    "load_connections_from_text",
+]

{mcp_read_only_sql-0.2.1 → mcp_read_only_sql-0.2.5}/src/mcp_read_only_sql/config/connection.py

@@ -109,7 +109,7 @@ class SSHTunnelConfig:
                 raise ValueError("SSH tunnel timeout must be a positive integer")
 
     @classmethod
-    def from_dict(cls, data: Dict[str, Any]) -> "SSHTunnelConfig":
+    def from_dict(cls, data: Dict[str, Any]) -> Optional["SSHTunnelConfig"]:
         """Create SSHTunnelConfig from dict with validation."""
         if not data.get("enabled", True):
             return None

{mcp_read_only_sql-0.2.1 → mcp_read_only_sql-0.2.5}/src/mcp_read_only_sql/config/dbeaver_import.py

@@ -31,10 +31,12 @@ class DBeaverImporter:
         self.last_requested_names: List[str] = []
         self.last_seen_names: List[str] = []
 
-    def _decrypt_credentials(self) -> Dict[str, Any]:
+    def _decrypt_credentials(
+        self,
+    ) -> tuple[dict[str, dict[str, Any]], dict[str, dict[str, Any]]]:
         """Decrypt DBeaver credentials file using OpenSSL with default AES key"""
         if not self.credentials_path.exists():
-            return {}
+            return {}, {}
 
         # DBeaver's default AES key and IV
         key = "babb4a9f774ab853c96c2d653dfe544a"
@@ -60,21 +62,23 @@ class DBeaverImporter:
                 logger.warning(
                     f"Could not decrypt credentials: {result.stderr.decode()}"
                 )
-                return {}
+                return {}, {}
 
             # Skip the first 16 bytes (padding) and parse JSON
             decrypted = result.stdout[16:]
             credentials_data = json.loads(decrypted)
 
             # Extract both connection and SSH credentials
-            credentials = {}
-            ssh_credentials = {}
+            credentials: dict[str, dict[str, Any]] = {}
+            ssh_credentials: dict[str, dict[str, Any]] = {}
             for conn_id, conn_data in credentials_data.items():
                 if isinstance(conn_data, dict):
-                    if "#connection" in conn_data:
-                        credentials[conn_id] = conn_data["#connection"]
-                    if "network/ssh_tunnel" in conn_data:
-                        ssh_credentials[conn_id] = conn_data["network/ssh_tunnel"]
+                    db_connection = conn_data.get("#connection")
+                    if isinstance(db_connection, dict):
+                        credentials[conn_id] = db_connection
+                    ssh_connection = conn_data.get("network/ssh_tunnel")
+                    if isinstance(ssh_connection, dict):
+                        ssh_credentials[conn_id] = ssh_connection
 
             logger.info(
                 f"Successfully decrypted credentials for {len(credentials)} connections"
@@ -83,7 +87,7 @@ class DBeaverImporter:
 
         except (subprocess.SubprocessError, json.JSONDecodeError) as e:
             logger.warning(f"Could not decrypt credentials file: {e}")
-            return {}
+            return {}, {}
 
     def import_connections(
         self, merge_clusters: bool = True, only_names: Optional[List[str]] = None
@@ -98,21 +102,20 @@ class DBeaverImporter:
             data_sources = json.load(handle)
 
         # Try to decrypt credentials
-        decrypt_result = self._decrypt_credentials()
-        if isinstance(decrypt_result, tuple):
-            credentials, ssh_credentials = decrypt_result
-        else:
-            credentials = decrypt_result or {}
-            ssh_credentials = {}
+        credentials, ssh_credentials = self._decrypt_credentials()
 
         if not credentials and self.credentials_path.exists():
             # Fallback: try to read as plaintext JSON (some DBeaver versions don't encrypt)
             try:
                 with self.credentials_path.open("r", encoding="utf-8") as handle:
                     cred_data = json.load(handle)
-                    for conn_id, conn_creds in cred_data.items():
-                        if isinstance(conn_creds, dict) and "#connection" in conn_creds:
-                            credentials[conn_id] = conn_creds["#connection"]
+                    if isinstance(cred_data, dict):
+                        for conn_id, conn_creds in cred_data.items():
+                            if not isinstance(conn_creds, dict):
+                                continue
+                            db_connection = conn_creds.get("#connection")
+                            if isinstance(db_connection, dict):
+                                credentials[conn_id] = db_connection
                     logger.info("Credentials file was not encrypted")
             except (json.JSONDecodeError, UnicodeDecodeError):
                 logger.warning(
@@ -125,10 +128,16 @@ class DBeaverImporter:
             print(f"Filtering: only {len(only_set)} requested connection(s)")
         self.last_requested_names = requested
 
-        connections = []
+        connections: list[dict[str, Any]] = []
         imported_names: List[str] = []
         seen_names: List[str] = []
-        for conn_id, conn_data in data_sources.get("connections", {}).items():
+        connections_data = data_sources.get("connections", {})
+        if not isinstance(connections_data, dict):
+            connections_data = {}
+
+        for conn_id, conn_data in connections_data.items():
+            if not isinstance(conn_data, dict):
+                continue
             original_name = conn_data.get("name", conn_id)
             if only_set and original_name not in only_set:
                 continue
@@ -136,9 +145,7 @@ class DBeaverImporter:
                 seen_names.append(original_name)
             # Pass both DB and SSH credentials
             db_creds = credentials.get(conn_id)
-            ssh_creds = (
-                ssh_credentials.get(conn_id) if "ssh_credentials" in locals() else None
-            )
+            ssh_creds = ssh_credentials.get(conn_id)
             converted = self._convert_connection(
                 conn_id, conn_data, db_creds, ssh_creds
             )
@@ -157,12 +164,14 @@ class DBeaverImporter:
         self,
         conn_id: str,
         conn_data: Dict[str, Any],
-        creds: Dict[str, Any] = None,
-        ssh_creds: Dict[str, Any] = None,
-    ) -> Dict[str, Any]:
+        creds: Optional[Dict[str, Any]] = None,
+        ssh_creds: Optional[Dict[str, Any]] = None,
+    ) -> Optional[Dict[str, Any]]:
         """Convert a DBeaver connection to our format"""
         provider = conn_data.get("provider", "")
         config = conn_data.get("configuration", {})
+        if not isinstance(config, dict):
+            config = {}
         conn_name = conn_data.get("name", conn_id)
 
         print(f"  Processing: {conn_name}...")
@@ -213,8 +222,14 @@ class DBeaverImporter:
 
         # Check for SSH tunnel configuration
         handlers = config.get("handlers", {})  # handlers is inside configuration
+        if not isinstance(handlers, dict):
+            handlers = {}
         ssh_handler = handlers.get("ssh_tunnel", {})
+        if not isinstance(ssh_handler, dict):
+            ssh_handler = {}
         ssh_props = ssh_handler.get("properties", {}) if ssh_handler else {}
+        if not isinstance(ssh_props, dict):
+            ssh_props = {}
 
         if ssh_handler and ssh_handler.get("enabled"):
             # Get SSH username from credentials or properties
@@ -368,9 +383,13 @@ class DBeaverImporter:
                         )
 
             # Add servers from this connection to the group
+            group_servers = group.get("servers")
+            if not isinstance(group_servers, list):
+                group_servers = []
+                group["servers"] = group_servers
             for server in servers:
-                if server not in group["servers"]:
-                    group["servers"].append(server)
+                if server not in group_servers:
+                    group_servers.append(server)
 
             # Track original DBeaver name
             if (
@@ -381,8 +400,12 @@ class DBeaverImporter:
                 import_part = (
                     conn["description"].split("(imported from DBeaver:")[-1].rstrip(")")
                 )
-                if import_part not in group["original_names"]:
-                    group["original_names"].append(import_part)
+                group_original_names = group.get("original_names")
+                if not isinstance(group_original_names, list):
+                    group_original_names = []
+                    group["original_names"] = group_original_names
+                if import_part not in group_original_names:
+                    group_original_names.append(import_part)
 
         # Return merged groups in original order with updated descriptions
         merged = []

{mcp_read_only_sql-0.2.1 → mcp_read_only_sql-0.2.5}/src/mcp_read_only_sql/config/loader.py

@@ -1,50 +1,36 @@
 """Connection configuration loader."""
 
 from pathlib import Path
-from typing import Dict
+from typing import Any, Dict, cast
 
 import yaml
 
 from .connection import Connection
 
 
-def load_connections(yaml_path: str | Path) -> Dict[str, Connection]:
-    """
-    Load and validate all connections from YAML configuration file.
-
-    Args:
-        yaml_path: Path to connections.yaml file
-
-    Returns:
-        Dictionary mapping connection name to Connection object
-
-    Raises:
-        FileNotFoundError: If YAML file doesn't exist
-        ValueError: If configuration is invalid (includes all validation errors)
-    """
-    yaml_file = Path(yaml_path).expanduser()
-    if not yaml_file.exists():
-        raise FileNotFoundError(f"Configuration file not found: {yaml_path}")
-
-    with open(yaml_file, encoding="utf-8") as f:
-        raw_configs = yaml.safe_load(f)
-
+def _build_connections_from_raw_configs(
+    raw_configs: Any, source: str | Path
+) -> Dict[str, Connection]:
+    """Validate parsed YAML data and return Connection objects."""
+    source_name = str(source)
     if not raw_configs:
-        raise ValueError(f"Configuration file is empty: {yaml_path}")
+        raise ValueError(f"Configuration file is empty: {source_name}")
 
     if not isinstance(raw_configs, list):
         raise ValueError("Configuration file must contain a list of connections")
 
-    connections = {}
-    errors = []
+    connections: Dict[str, Connection] = {}
+    errors: list[str] = []
 
     for idx, config in enumerate(raw_configs):
         if not isinstance(config, dict):
             errors.append(f"Connection #{idx+1}: must be a dictionary")
             continue
 
+        config_dict = cast(Dict[str, Any], config)
+
         try:
-            conn = Connection(config)
+            conn = Connection(config_dict)
 
             # Check for duplicate names
             if conn.name in connections:
@@ -54,7 +40,7 @@ def load_connections(yaml_path: str | Path) -> Dict[str, Connection]:
 
         except Exception as e:
             # Get connection name if available for better error messages
-            name = config.get("connection_name", f"#{idx+1}")
+            name = config_dict.get("connection_name", f"#{idx+1}")
             errors.append(f"Connection '{name}': {e}")
 
     if errors:
@@ -62,3 +48,41 @@ def load_connections(yaml_path: str | Path) -> Dict[str, Connection]:
         raise ValueError(error_msg)
 
     return connections
+
+
+def load_connections_from_text(
+    yaml_text: str, source: str | Path = "<memory>"
+) -> Dict[str, Connection]:
+    """
+    Load and validate connections from a YAML text snapshot.
+
+    Args:
+        yaml_text: Raw YAML document content
+        source: Source label used in validation errors
+    """
+    raw_configs = yaml.safe_load(yaml_text)
+    return _build_connections_from_raw_configs(raw_configs, source)
+
+
+def load_connections(yaml_path: str | Path) -> Dict[str, Connection]:
+    """
+    Load and validate all connections from YAML configuration file.
+
+    Args:
+        yaml_path: Path to connections.yaml file
+
+    Returns:
+        Dictionary mapping connection name to Connection object
+
+    Raises:
+        FileNotFoundError: If YAML file doesn't exist
+        ValueError: If configuration is invalid (includes all validation errors)
+    """
+    yaml_file = Path(yaml_path).expanduser()
+    if not yaml_file.exists():
+        raise FileNotFoundError(f"Configuration file not found: {yaml_path}")
+
+    with open(yaml_file, encoding="utf-8") as f:
+        yaml_text = f.read()
+
+    return load_connections_from_text(yaml_text, yaml_file)