fix: add actionable hints on ClickHouse connection failures

[sankalpsthakur]

Fixes #102

What

Improves failure messages when create_clickhouse_client() cannot connect to ClickHouse by appending short, actionable Hints for common misconfigurations:

1. Native TCP ports (9000 / 9440, or server messages like Port 9000 is for clickhouse-client program) — this server uses the HTTP interface (8123 / 8443).
2. TLS / scheme mismatches involving CLICKHOUSE_SECURE — clarifies that this flag is for the database HTTPS connection, not MCP or ingress TLS.
3. Opaque HTTP client errors with no stronger signal — reminds users to verify CLICKHOUSE_SECURE + HTTP interface port.

Also logs a warning before connecting when CLICKHOUSE_PORT is a known native protocol port.

Companion docs change: #211 (README env-var grouping) addresses the same setup confusion described in #172.

Why

Users frequently misconfigure ports and CLICKHOUSE_SECURE, then see low-context errors such as:

Failed to connect to ClickHouse: HTTP driver received HTTP status 400,
server response: Port 9000 is for clickhouse-client program

The original exception is re-raised unchanged and hints are added to the log message.

Changes

• mcp_clickhouse/mcp_server.py: _connection_error_hints, _format_connection_failure, native-port warning, richer raise path
• tests/test_connection_errors.py: unit coverage for hints, formatting, raise path, and native-port warning

Validation

uv sync --all-extras --dev
uv run ruff check .
CLICKHOUSE_HOST=localhost CLICKHOUSE_USER=default CLICKHOUSE_PASSWORD=test \
  CLICKHOUSE_SECURE=false CLICKHOUSE_PORT=8123 \
  uv run pytest -v tests/test_connection_errors.py tests/test_config_interface.py \
    tests/test_auth_config.py tests/test_context_config_override.py -k "not Integration"
# 32 passed
uv run pytest -v tests/test_optional_chdb.py tests/test_skills_advisor.py tests/test_middleware.py
# 16 passed

[CLAassistant]

All committers have signed the CLA.

[joe-clickhouse]

Hi @sankalpsthakur thanks for this work as well. I pushed a followup here too that separates an explicitly configured native port from the case where a cporrectly configured HTTP port is being misrouted to a native endpoint. It also preserves the original CH exception type, improves the generic connectivity guidance, and adds some tests around the scenario that #102 laid out and exception compatibility. Thanks again!

[Copilot]

Pull request overview

This PR improves the ClickHouse connection failure experience by adding targeted, actionable hints for common misconfigurations (native TCP vs HTTP ports, TLS/scheme mismatches, and opaque HTTP client errors), and by warning early when CLICKHOUSE_PORT is set to a known native protocol port.

Changes:

• Add _connection_error_hints() + _format_connection_failure() and a _NATIVE_PROTOCOL_PORTS constant to enrich connection-failure diagnostics.
• Emit a warning before connecting when CLICKHOUSE_PORT is set to a native TCP (clickhouse-client) port.
• Add unit tests covering hint selection, formatting, logging, and the native-port warning.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 2 comments.

File	Description
mcp_clickhouse/mcp_server.py	Adds hint generation/formatting for connection failures and warns on native TCP ports before connecting.
tests/test_connection_errors.py	Adds unit tests validating hint behavior, formatting, logging output, and the native-port warning.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[sankalpsthakur]

Same here — ready when you are.