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

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

@@ -7,6 +7,12 @@ and this project aims to follow [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [0.2.6] - 2026-06-08
+
+### Fixed
+
+- Resolved the `psql` / `clickhouse-client` CLI binaries through an explicit lookup (env override → `PATH` → OS-aware fallback) instead of relying solely on `PATH`. Homebrew keg-only `libpq` installs on macOS, where `psql` is not symlinked onto `PATH`, now work without manual `PATH` setup. The resolved path can be pinned with `MCP_READ_ONLY_SQL_PSQL_PATH` / `MCP_READ_ONLY_SQL_CLICKHOUSE_CLIENT_PATH`, and is cached per connector.
+
 ## [0.2.5] - 2026-04-21
 
 ### Added

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mcp-read-only-sql
-Version: 0.2.5
+Version: 0.2.6
 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
@@ -86,6 +86,8 @@ See [READ_ONLY_ENFORCEMENT_MATRIX.md](READ_ONLY_ENFORCEMENT_MATRIX.md) for a sta
 
 Install the optional CLI binaries with your operating system's package manager or the official PostgreSQL / ClickHouse packages for your environment.
 
+The CLI binaries are located via the override environment variable (`MCP_READ_ONLY_SQL_PSQL_PATH` / `MCP_READ_ONLY_SQL_CLICKHOUSE_CLIENT_PATH`) if set, then `PATH`, then OS-specific fallback locations (e.g. Homebrew keg-only `libpq` on macOS, packaged PostgreSQL directories on Linux). If a binary is installed somewhere not on `PATH`, set the matching variable to its full path.
+
 The SQL package keeps both execution models first-class:
 
 - `implementation: cli` uses the official database client binaries you already trust in operations.

{mcp_read_only_sql-0.2.5 → mcp_read_only_sql-0.2.6}/README.md

@@ -51,6 +51,8 @@ See [READ_ONLY_ENFORCEMENT_MATRIX.md](READ_ONLY_ENFORCEMENT_MATRIX.md) for a sta
 
 Install the optional CLI binaries with your operating system's package manager or the official PostgreSQL / ClickHouse packages for your environment.
 
+The CLI binaries are located via the override environment variable (`MCP_READ_ONLY_SQL_PSQL_PATH` / `MCP_READ_ONLY_SQL_CLICKHOUSE_CLIENT_PATH`) if set, then `PATH`, then OS-specific fallback locations (e.g. Homebrew keg-only `libpq` on macOS, packaged PostgreSQL directories on Linux). If a binary is installed somewhere not on `PATH`, set the matching variable to its full path.
+
 The SQL package keeps both execution models first-class:
 
 - `implementation: cli` uses the official database client binaries you already trust in operations.

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

@@ -1,6 +1,6 @@
 [project]
 name = "mcp-read-only-sql"
-version = "0.2.5"
+version = "0.2.6"
 description = "MCP server for read-only SQL queries supporting PostgreSQL and ClickHouse"
 readme = "README.md"
 requires-python = ">=3.11"

mcp_read_only_sql-0.2.6/src/mcp_read_only_sql/cli_binaries.py

@@ -0,0 +1,158 @@
+"""Resolution of external CLI client binaries (psql, clickhouse-client).
+
+The CLI connectors shell out to a database client. Relying on a bare command
+name only works when the client happens to be on ``PATH``; a common failure is
+macOS Homebrew, where ``psql`` ships with the keg-only ``libpq`` formula and is
+not symlinked onto the default ``PATH`` (the server then fails with
+"psql: command not found").
+
+``resolve_cli_binary`` locates the client without hardcoding install locations
+as the primary mechanism. Resolution order:
+
+1. Explicit override via ``MCP_READ_ONLY_SQL_<BINARY>_PATH`` (matches the
+   project's existing ``MCP_READ_ONLY_SQL_*`` env convention).
+2. :func:`shutil.which` -- honors ``PATH`` (the normal case on Linux and any
+   correctly configured environment).
+3. OS-aware fallback directories, queried dynamically where possible:
+   - macOS: ask Homebrew (``brew --prefix``) where keg-only ``libpq`` / the
+     ``postgresql`` formulae live, plus the standard Homebrew opt dirs.
+   - Linux: standard packaged PostgreSQL layouts (Debian/Ubuntu, PGDG/RHEL).
+
+If every step fails, a :class:`FileNotFoundError` is raised naming the override
+env var so the user can point at the binary explicitly.
+"""
+
+from __future__ import annotations
+
+import glob
+import os
+import shutil
+import subprocess
+import sys
+
+from .runtime_paths import ENV_PREFIX
+
+# Upper bound on the optional `brew --prefix` probe so a misbehaving brew can
+# never hang query execution.
+_BREW_PROBE_TIMEOUT = 5  # seconds
+
+# Homebrew formulae that provide each client, in preference order.
+_BREW_FORMULAE: dict[str, list[str]] = {
+    "psql": ["libpq", "postgresql@18", "postgresql@17", "postgresql@16", "postgresql"],
+    "clickhouse-client": ["clickhouse"],
+}
+
+
+def env_var_for(binary: str) -> str:
+    """Return the override env var name for ``binary``.
+
+    ``psql`` -> ``MCP_READ_ONLY_SQL_PSQL_PATH``;
+    ``clickhouse-client`` -> ``MCP_READ_ONLY_SQL_CLICKHOUSE_CLIENT_PATH``.
+    """
+    slug = binary.upper().replace("-", "_")
+    return f"{ENV_PREFIX}_{slug}_PATH"
+
+
+def _is_executable(path: str) -> bool:
+    return bool(path) and os.path.isfile(path) and os.access(path, os.X_OK)
+
+
+def _brew_prefix(formula: str) -> str | None:
+    """Return the Homebrew prefix for ``formula``, or ``None`` if unavailable.
+
+    Note: this uses a blocking ``subprocess.run``. ``resolve_cli_binary`` is
+    synchronous but is called from within the connectors' async ``_run_query``,
+    so this probe blocks the event loop for its duration (bounded by
+    ``_BREW_PROBE_TIMEOUT`` per call). It only runs on the fallback path (binary
+    not pinned and not on PATH, macOS only) and ``BaseCLIConnector`` caches the
+    resolved path per connector, so in practice it runs at most once per
+    connector rather than per query. If that ever becomes a problem (e.g. many
+    connectors resolving concurrently), move the call onto a thread via
+    ``asyncio.to_thread`` or lower ``_BREW_PROBE_TIMEOUT``.
+    """
+    brew = shutil.which("brew")
+    if not brew:
+        return None
+    try:
+        result = subprocess.run(
+            [brew, "--prefix", formula],
+            capture_output=True,
+            text=True,
+            timeout=_BREW_PROBE_TIMEOUT,
+        )
+    except (OSError, subprocess.SubprocessError):
+        return None
+    if result.returncode != 0:
+        return None
+    prefix = result.stdout.strip()
+    return prefix or None
+
+
+def _candidate_dirs(binary: str) -> list[str]:
+    """OS-aware fallback directories to search for ``binary``.
+
+    Evaluated only when the binary is neither pinned via env var nor found on
+    ``PATH``. Homebrew prefixes are resolved dynamically; the static entries are
+    last-resort best effort.
+    """
+    dirs: list[str] = []
+
+    if sys.platform == "darwin":
+        for formula in _BREW_FORMULAE.get(binary, []):
+            prefix = _brew_prefix(formula)
+            if prefix:
+                dirs.append(os.path.join(prefix, "bin"))
+        if binary == "psql":
+            # Standard Homebrew keg-only libpq locations (Apple Silicon, Intel).
+            dirs += ["/opt/homebrew/opt/libpq/bin", "/usr/local/opt/libpq/bin"]
+    elif sys.platform.startswith("linux"):
+        if binary == "psql":
+            # Debian/Ubuntu (postgresql-client-NN) and PGDG/RHEL layouts;
+            # newest version dir first. clickhouse-client has no equivalent
+            # fallback: its distro package installs onto PATH, so which() above
+            # already covers it.
+            dirs += sorted(glob.glob("/usr/lib/postgresql/*/bin"), reverse=True)
+            dirs += sorted(glob.glob("/usr/pgsql-*/bin"), reverse=True)
+
+    return dirs
+
+
+def resolve_cli_binary(binary: str) -> str:
+    """Resolve the absolute path to a CLI client binary.
+
+    Args:
+        binary: The client command name, e.g. ``"psql"`` or
+            ``"clickhouse-client"``.
+
+    Returns:
+        Absolute path to an executable.
+
+    Raises:
+        FileNotFoundError: If the binary cannot be located. The message names
+            the override env var.
+    """
+    env_var = env_var_for(binary)
+
+    override = os.environ.get(env_var)
+    if override:
+        expanded = os.path.expanduser(override)
+        if _is_executable(expanded):
+            return expanded
+        raise FileNotFoundError(
+            f"{binary}: {env_var} is set to '{override}', but that is not an "
+            f"executable file."
+        )
+
+    found = shutil.which(binary)
+    if found:
+        return found
+
+    for directory in _candidate_dirs(binary):
+        candidate = os.path.join(directory, binary)
+        if _is_executable(candidate):
+            return candidate
+
+    raise FileNotFoundError(
+        f"{binary}: command not found. Install the client tools, add them to "
+        f"PATH, or set {env_var} to the full path of the {binary} executable."
+    )

{mcp_read_only_sql-0.2.5 → mcp_read_only_sql-0.2.6}/src/mcp_read_only_sql/connectors/base_cli.py

@@ -8,6 +8,7 @@ import logging
 
 from .base import BaseConnector
 from ..config import Connection
+from ..cli_binaries import resolve_cli_binary
 from ..utils.ssh_tunnel_cli import CLISSHTunnel
 
 logger = logging.getLogger(__name__)
@@ -19,6 +20,26 @@ class BaseCLIConnector(BaseConnector):
     def __init__(self, connection: Connection):
         super().__init__(connection)
         self._ssh_tunnel = None
+        # Resolved CLI client paths, cached per connector instance. Connectors
+        # are rebuilt on config reload, so this re-resolves after a reload while
+        # avoiding a lookup (and a possible `brew --prefix` probe) per query.
+        self._binary_cache: dict[str, str] = {}
+
+    def _resolve_binary(self, name: str) -> str:
+        """Resolve and cache the absolute path to a CLI client binary.
+
+        Called synchronously from the async ``_run_query``. On the macOS
+        fallback path resolution may run a blocking ``brew --prefix`` probe (see
+        ``cli_binaries._brew_prefix``); caching the result here keeps that to at
+        most once per connector instead of once per query. Failures are not
+        cached, so resolution retries on the next query (e.g. if the client is
+        installed mid-session).
+        """
+        cached = self._binary_cache.get(name)
+        if cached is None:
+            cached = resolve_cli_binary(name)
+            self._binary_cache[name] = cached
+        return cached
 
     @asynccontextmanager
     async def _get_ssh_tunnel(self, server: Optional[str] = None):

{mcp_read_only_sql-0.2.5 → mcp_read_only_sql-0.2.6}/src/mcp_read_only_sql/connectors/clickhouse/cli.py

@@ -110,9 +110,11 @@ class ClickHouseCLIConnector(BaseCLIConnector):
             # Use specified database or configured database (validated)
             db_name = self._resolve_database(database)
 
-            # Build clickhouse-client command with read-only enforcement
+            # Build clickhouse-client command with read-only enforcement.
+            # Resolve the client binary explicitly so installs that are not on
+            # PATH still work (mirrors the psql connector).
             cmd = [
-                "clickhouse-client",
+                self._resolve_binary("clickhouse-client"),
                 "--host",
                 host,
                 "--port",

{mcp_read_only_sql-0.2.5 → mcp_read_only_sql-0.2.6}/src/mcp_read_only_sql/connectors/postgresql/cli.py

@@ -75,9 +75,11 @@ class PostgreSQLCLIConnector(BaseCLIConnector):
                 COMMIT;
             """
 
-            # Build psql command with individual parameters
+            # Build psql command with individual parameters.
+            # Resolve the client binary explicitly so installs that are not on
+            # PATH (e.g. Homebrew keg-only libpq on macOS) still work.
             cmd = [
-                "psql",
+                self._resolve_binary("psql"),
                 "--single-transaction",
                 "-v",
                 "ON_ERROR_STOP=1",

mcp_read_only_sql-0.2.6/tests/test_cli_binaries.py

@@ -0,0 +1,93 @@
+import stat
+
+import pytest
+
+from mcp_read_only_sql import cli_binaries
+from mcp_read_only_sql.cli_binaries import env_var_for, resolve_cli_binary
+
+
+def _make_executable(path):
+    path.write_text("#!/bin/sh\n")
+    path.chmod(path.stat().st_mode | stat.S_IXUSR | stat.S_IXGRP | stat.S_IXOTH)
+    return str(path)
+
+
+def test_env_var_for_naming():
+    assert env_var_for("psql") == "MCP_READ_ONLY_SQL_PSQL_PATH"
+    assert (
+        env_var_for("clickhouse-client") == "MCP_READ_ONLY_SQL_CLICKHOUSE_CLIENT_PATH"
+    )
+
+
+def test_env_override_returns_pinned_path(monkeypatch, tmp_path):
+    binary = _make_executable(tmp_path / "psql")
+    monkeypatch.setenv("MCP_READ_ONLY_SQL_PSQL_PATH", binary)
+
+    assert resolve_cli_binary("psql") == binary
+
+
+def test_env_override_expands_user(monkeypatch, tmp_path):
+    binary = _make_executable(tmp_path / "psql")
+    monkeypatch.setenv("HOME", str(tmp_path))
+    monkeypatch.setenv("MCP_READ_ONLY_SQL_PSQL_PATH", "~/psql")
+
+    assert resolve_cli_binary("psql") == binary
+
+
+def test_env_override_non_executable_raises(monkeypatch, tmp_path):
+    bogus = tmp_path / "not-exec"
+    bogus.write_text("")
+    monkeypatch.setenv("MCP_READ_ONLY_SQL_PSQL_PATH", str(bogus))
+
+    with pytest.raises(FileNotFoundError) as exc:
+        resolve_cli_binary("psql")
+    assert "MCP_READ_ONLY_SQL_PSQL_PATH" in str(exc.value)
+
+
+def test_resolves_via_which(monkeypatch):
+    monkeypatch.delenv("MCP_READ_ONLY_SQL_PSQL_PATH", raising=False)
+    monkeypatch.setattr(
+        cli_binaries.shutil,
+        "which",
+        lambda name: "/usr/bin/psql" if name == "psql" else None,
+    )
+
+    assert resolve_cli_binary("psql") == "/usr/bin/psql"
+
+
+def test_falls_back_to_candidate_dir(monkeypatch, tmp_path):
+    binary = _make_executable(tmp_path / "psql")
+    monkeypatch.delenv("MCP_READ_ONLY_SQL_PSQL_PATH", raising=False)
+    monkeypatch.setattr(cli_binaries.shutil, "which", lambda name: None)
+    monkeypatch.setattr(cli_binaries, "_candidate_dirs", lambda b: [str(tmp_path)])
+
+    assert resolve_cli_binary("psql") == binary
+
+
+def test_not_found_raises_with_env_hint(monkeypatch):
+    monkeypatch.delenv("MCP_READ_ONLY_SQL_PSQL_PATH", raising=False)
+    monkeypatch.setattr(cli_binaries.shutil, "which", lambda name: None)
+    monkeypatch.setattr(cli_binaries, "_candidate_dirs", lambda b: [])
+
+    with pytest.raises(FileNotFoundError) as exc:
+        resolve_cli_binary("psql")
+    message = str(exc.value)
+    assert "psql: command not found" in message
+    assert "MCP_READ_ONLY_SQL_PSQL_PATH" in message
+
+
+def test_brew_prefix_used_for_candidate_dirs(monkeypatch, tmp_path):
+    """On macOS the libpq Homebrew prefix should be probed for psql."""
+    prefix_bin = tmp_path / "opt" / "libpq" / "bin"
+    prefix_bin.mkdir(parents=True)
+    _make_executable(prefix_bin / "psql")
+
+    monkeypatch.setattr(cli_binaries.sys, "platform", "darwin")
+    monkeypatch.setattr(
+        cli_binaries,
+        "_brew_prefix",
+        lambda formula: str(tmp_path / "opt" / "libpq") if formula == "libpq" else None,
+    )
+
+    dirs = cli_binaries._candidate_dirs("psql")
+    assert str(prefix_bin) in dirs