mcp-hydrolix 0.1.1__py3-none-any.whl → 0.1.4__py3-none-any.whl

mcp_hydrolix/main.py

@@ -1,8 +1,20 @@
 from .mcp_server import mcp
+from .mcp_env import get_config, TransportType
 
 
 def main():
-    mcp.run()
+    config = get_config()
+    transport = config.mcp_server_transport
+
+    # For HTTP and SSE transports, we need to specify host and port
+    http_transports = [TransportType.HTTP.value, TransportType.SSE.value]
+    if transport in http_transports:
+        # Use the configured bind host (defaults to 127.0.0.1, can be set to 0.0.0.0)
+        # and bind port (defaults to 8000)
+        mcp.run(transport=transport, host=config.mcp_bind_host, port=config.mcp_bind_port)
+    else:
+        # For stdio transport, no host or port is needed
+        mcp.run(transport=transport)
 
 
 if __name__ == "__main__":

mcp_hydrolix/mcp_env.py

@@ -7,6 +7,20 @@ and type conversion.
 from dataclasses import dataclass
 import os
 from typing import Optional
+from enum import Enum
+
+
+class TransportType(str, Enum):
+    """Supported MCP server transport types."""
+
+    STDIO = "stdio"
+    HTTP = "http"
+    SSE = "sse"
+
+    @classmethod
+    def values(cls) -> list[str]:
+        """Get all valid transport values."""
+        return [transport.value for transport in cls]
 
 
 @dataclass
@@ -18,15 +32,20 @@ class HydrolixConfig:
 
     Required environment variables:
         HYDROLIX_HOST: The hostname of the Hydrolix server
-        HYDROLIX_USER: The username for authentication
-        HYDROLIX_PASSWORD: The password for authentication
 
     Optional environment variables (with defaults):
+        HYDROLIX_TOKEN: Service account token to the Hydrolix Server (this or user+password is required)
+        HYDROLIX_USER: The username for authentication (this or token is required)
+        HYDROLIX_PASSWORD: The password for authentication (this or token is required)
         HYDROLIX_PORT: The port number (default: 8088)
         HYDROLIX_VERIFY: Verify SSL certificates (default: true)
         HYDROLIX_CONNECT_TIMEOUT: Connection timeout in seconds (default: 30)
         HYDROLIX_SEND_RECEIVE_TIMEOUT: Send/receive timeout in seconds (default: 300)
         HYDROLIX_DATABASE: Default database to use (default: None)
+        HYDROLIX_PROXY_PATH: Path to be added to the host URL. For instance, for servers behind an HTTP proxy (default: None)
+        HYDROLIX_MCP_SERVER_TRANSPORT: MCP server transport method - "stdio", "http", or "sse" (default: stdio)
+        HYDROLIX_MCP_BIND_HOST: Host to bind the MCP server to when using HTTP or SSE transport (default: 127.0.0.1)
+        HYDROLIX_MCP_BIND_PORT: Port to bind the MCP server to when using HTTP or SSE transport (default: 8000)
     """
 
     def __init__(self):
@@ -49,15 +68,39 @@ class HydrolixConfig:
             return int(os.environ["HYDROLIX_PORT"])
         return 8088
 
+    @property
+    def service_account(self) -> bool:
+        """Determine if service account is enabled
+
+        Defaults to false.
+        Can be overridden if HYDROLIX_TOKEN environment variable.
+        """
+        return "HYDROLIX_TOKEN" in os.environ
+
+    @property
+    def service_account_token(self) -> str:
+        """Get the service account token
+
+        Defaults to None.
+        Can be overridden if HYDROLIX_TOKEN environment variable.
+        """
+        if "HYDROLIX_TOKEN" in os.environ:
+            return os.environ["HYDROLIX_TOKEN"]
+        return None
+
     @property
     def username(self) -> str:
         """Get the Hydrolix username."""
-        return os.environ["HYDROLIX_USER"]
+        if "HYDROLIX_USER" in os.environ:
+            return os.environ["HYDROLIX_USER"]
+        return None
 
     @property
     def password(self) -> str:
         """Get the Hydrolix password."""
-        return os.environ["HYDROLIX_PASSWORD"]
+        if "HYDROLIX_PASSWORD" in os.environ:
+            return os.environ["HYDROLIX_PASSWORD"]
+        return None
 
     @property
     def database(self) -> Optional[str]:
@@ -88,6 +131,43 @@ class HydrolixConfig:
         """
         return int(os.getenv("HYDROLIX_SEND_RECEIVE_TIMEOUT", "300"))
 
+    @property
+    def proxy_path(self) -> str:
+        return os.getenv("HYDROLIX_PROXY_PATH")
+
+    @property
+    def mcp_server_transport(self) -> str:
+        """Get the MCP server transport method.
+
+        Valid options: "stdio", "http", "sse"
+        Default: "stdio"
+        """
+        transport = os.getenv("HYDROLIX_MCP_SERVER_TRANSPORT", TransportType.STDIO.value).lower()
+
+        # Validate transport type
+        if transport not in TransportType.values():
+            valid_options = ", ".join(f'"{t}"' for t in TransportType.values())
+            raise ValueError(f"Invalid transport '{transport}'. Valid options: {valid_options}")
+        return transport
+
+    @property
+    def mcp_bind_host(self) -> str:
+        """Get the host to bind the MCP server to.
+
+        Only used when transport is "http" or "sse".
+        Default: "127.0.0.1"
+        """
+        return os.getenv("HYDROLIX_MCP_BIND_HOST", "127.0.0.1")
+
+    @property
+    def mcp_bind_port(self) -> int:
+        """Get the port to bind the MCP server to.
+
+        Only used when transport is "http" or "sse".
+        Default: 8000
+        """
+        return int(os.getenv("HYDROLIX_MCP_BIND_PORT", "8000"))
+
     def get_client_config(self) -> dict:
         """Get the configuration dictionary for clickhouse_connect client.
 
@@ -97,8 +177,6 @@ class HydrolixConfig:
         config = {
             "host": self.host,
             "port": self.port,
-            "username": self.username,
-            "password": self.password,
             "secure": True,
             "verify": self.verify,
             "connect_timeout": self.connect_timeout,
@@ -110,6 +188,15 @@ class HydrolixConfig:
         if self.database:
             config["database"] = self.database
 
+        if self.proxy_path:
+            config["proxy_path"] = self.proxy_path
+
+        if self.service_account:
+            config["access_token"] = self.service_account_token
+        else:
+            config["username"] = self.username
+            config["password"] = self.password
+
         return config
 
     def _validate_required_vars(self) -> None:
@@ -119,7 +206,11 @@ class HydrolixConfig:
             ValueError: If any required environment variable is missing.
         """
         missing_vars = []
-        for var in ["HYDROLIX_HOST", "HYDROLIX_USER", "HYDROLIX_PASSWORD"]:
+        if self.service_account:
+            required_vars = ["HYDROLIX_HOST", "HYDROLIX_TOKEN"]
+        else:
+            required_vars = ["HYDROLIX_HOST", "HYDROLIX_USER", "HYDROLIX_PASSWORD"]
+        for var in required_vars:
             if var not in os.environ:
                 missing_vars.append(var)
 

mcp_hydrolix/mcp_server.py

@@ -1,15 +1,53 @@
 import logging
-from typing import Sequence
+import json
+from typing import Optional, List, Any
 import concurrent.futures
 import atexit
 
 import clickhouse_connect
-from clickhouse_connect.driver.binding import quote_identifier, format_query_value
+from clickhouse_connect.driver.binding import format_query_value
 from dotenv import load_dotenv
-from mcp.server.fastmcp import FastMCP
+from fastmcp import FastMCP
+from fastmcp.exceptions import ToolError
+from dataclasses import dataclass, field, asdict, is_dataclass
+from starlette.requests import Request
+from starlette.responses import PlainTextResponse
 
 from mcp_hydrolix.mcp_env import get_config
 
+
+@dataclass
+class Column:
+    database: str
+    table: str
+    name: str
+    column_type: str
+    default_kind: Optional[str]
+    default_expression: Optional[str]
+    comment: Optional[str]
+
+
+@dataclass
+class Table:
+    database: str
+    name: str
+    engine: str
+    create_table_query: str
+    dependencies_database: str
+    dependencies_table: str
+    engine_full: str
+    sorting_key: str
+    primary_key: str
+    total_rows: int
+    total_bytes: int
+    total_bytes_uncompressed: int
+    parts: int
+    active_parts: int
+    total_marks: int
+    comment: Optional[str] = None
+    columns: List[Column] = field(default_factory=list)
+
+
 MCP_SERVER_NAME = "mcp-hydrolix"
 
 # Configure logging
@@ -24,14 +62,48 @@ SELECT_QUERY_TIMEOUT_SECS = 30
 
 load_dotenv()
 
-deps = [
-    "clickhouse-connect",
-    "python-dotenv",
-    "uvicorn",
-    "pip-system-certs",
-]
+mcp = FastMCP(
+    name=MCP_SERVER_NAME,
+    dependencies=[
+        "clickhouse-connect",
+        "python-dotenv",
+        "pip-system-certs",
+    ],
+)
+
+
+@mcp.custom_route("/health", methods=["GET"])
+async def health_check(request: Request) -> PlainTextResponse:
+    """Health check endpoint for monitoring server status.
+
+    Returns OK if the server is running and can connect to Hydrolix.
+    """
+    try:
+        # Try to create a client connection to verify query-head connectivity
+        client = create_hydrolix_client()
+        version = client.server_version
+        return PlainTextResponse(f"OK - Connected to Hydrolix compatible with ClickHouse {version}")
+    except Exception as e:
+        # Return 503 Service Unavailable if we can't connect to Hydrolix
+        return PlainTextResponse(f"ERROR - Cannot connect to Hydrolix: {str(e)}", status_code=503)
+
+
+def result_to_table(query_columns, result) -> List[Table]:
+    return [Table(**dict(zip(query_columns, row))) for row in result]
 
-mcp = FastMCP(MCP_SERVER_NAME, dependencies=deps)
+
+def result_to_column(query_columns, result) -> List[Column]:
+    return [Column(**dict(zip(query_columns, row))) for row in result]
+
+
+def to_json(obj: Any) -> str:
+    if is_dataclass(obj):
+        return json.dumps(asdict(obj), default=to_json)
+    elif isinstance(obj, list):
+        return [to_json(item) for item in obj]
+    elif isinstance(obj, dict):
+        return {key: to_json(value) for key, value in obj.items()}
+    return obj
 
 
 @mcp.tool()
@@ -40,79 +112,48 @@ def list_databases():
     logger.info("Listing all databases")
     client = create_hydrolix_client()
     result = client.command("SHOW DATABASES")
-    logger.info(f"Found {len(result) if isinstance(result, list) else 1} databases")
-    return result
+
+    # Convert newline-separated string to list and trim whitespace
+    if isinstance(result, str):
+        databases = [db.strip() for db in result.strip().split("\n")]
+    else:
+        databases = [result]
+
+    logger.info(f"Found {len(databases)} databases")
+    return json.dumps(databases)
 
 
 @mcp.tool()
-def list_tables(database: str, like: str = None):
-    """List available Hydrolix tables in a database"""
+def list_tables(database: str, like: Optional[str] = None, not_like: Optional[str] = None):
+    """List available Hydrolix tables in a database, including schema, comment,
+    row count, and column count."""
     logger.info(f"Listing tables in database '{database}'")
     client = create_hydrolix_client()
-    query = f"SHOW TABLES FROM {quote_identifier(database)}"
+    query = f"SELECT database, name, engine, create_table_query, dependencies_database, dependencies_table, engine_full, sorting_key, primary_key, total_rows, total_bytes, total_bytes_uncompressed, parts, active_parts, total_marks, comment FROM system.tables WHERE database = {format_query_value(database)}"
     if like:
-        query += f" LIKE {format_query_value(like)}"
-    result = client.command(query)
+        query += f" AND name LIKE {format_query_value(like)}"
 
-    # Get all table comments in one query
-    table_comments_query = (
-        f"SELECT name, comment FROM system.tables WHERE database = {format_query_value(database)}"
-    )
-    table_comments_result = client.query(table_comments_query)
-    table_comments = {row[0]: row[1] for row in table_comments_result.result_rows}
-
-    # Get all column comments in one query
-    column_comments_query = f"SELECT table, name, comment FROM system.columns WHERE database = {format_query_value(database)}"
-    column_comments_result = client.query(column_comments_query)
-    column_comments = {}
-    for row in column_comments_result.result_rows:
-        table, col_name, comment = row
-        if table not in column_comments:
-            column_comments[table] = {}
-        column_comments[table][col_name] = comment
-
-    def get_table_info(table):
-        logger.info(f"Getting schema info for table {database}.{table}")
-        schema_query = f"DESCRIBE TABLE {quote_identifier(database)}.{quote_identifier(table)}"
-        schema_result = client.query(schema_query)
-
-        columns = []
-        column_names = schema_result.column_names
-        for row in schema_result.result_rows:
-            column_dict = {}
-            for i, col_name in enumerate(column_names):
-                column_dict[col_name] = row[i]
-            # Add comment from our pre-fetched comments
-            if table in column_comments and column_dict["name"] in column_comments[table]:
-                column_dict["comment"] = column_comments[table][column_dict["name"]]
-            else:
-                column_dict["comment"] = None
-            columns.append(column_dict)
-
-        create_table_query = f"SHOW CREATE TABLE {database}.`{table}`"
-        create_table_result = client.command(create_table_query)
-
-        return {
-            "database": database,
-            "name": table,
-            "comment": table_comments.get(table),
-            "columns": columns,
-            "create_table_query": create_table_result,
-        }
-
-    tables = []
-    if isinstance(result, str):
-        # Single table result
-        for table in (t.strip() for t in result.split()):
-            if table:
-                tables.append(get_table_info(table))
-    elif isinstance(result, Sequence):
-        # Multiple table results
-        for table in result:
-            tables.append(get_table_info(table))
+    if not_like:
+        query += f" AND name NOT LIKE {format_query_value(not_like)}"
+
+    result = client.query(query)
+
+    # Deserialize result as Table dataclass instances
+    tables = result_to_table(result.column_names, result.result_rows)
+
+    for table in tables:
+        column_data_query = f"SELECT database, table, name, type AS column_type, default_kind, default_expression, comment FROM system.columns WHERE database = {format_query_value(database)} AND table = {format_query_value(table.name)}"
+        column_data_query_result = client.query(column_data_query)
+        table.columns = [
+            c
+            for c in result_to_column(
+                column_data_query_result.column_names,
+                column_data_query_result.result_rows,
+            )
+        ]
 
     logger.info(f"Found {len(tables)} tables")
-    return tables
+    return [asdict(table) for table in tables]
 
 
 def execute_query(query: str):
@@ -129,20 +170,11 @@ def execute_query(query: str):
                 "hdx_query_admin_comment": f"User: {MCP_SERVER_NAME}",
             },
         )
-        column_names = res.column_names
-        rows = []
-        for row in res.result_rows:
-            row_dict = {}
-            for i, col_name in enumerate(column_names):
-                row_dict[col_name] = row[i]
-            rows.append(row_dict)
-        logger.info(f"Query returned {len(rows)} rows")
-        return rows
+        logger.info(f"Query returned {len(res.result_rows)} rows")
+        return {"columns": res.column_names, "rows": res.result_rows}
     except Exception as err:
         logger.error(f"Error executing query: {err}")
-        # Return a structured dictionary rather than a string to ensure proper serialization
-        # by the MCP protocol. String responses for errors can cause BrokenResourceError.
-        return {"error": str(err)}
+        raise ToolError(f"Query execution failed: {str(err)}")
 
 
 @mcp.tool()
@@ -194,28 +226,32 @@ def run_select_query(query: str):
                 logger.warning(f"Query failed: {result['error']}")
                 # MCP requires structured responses; string error messages can cause
                 # serialization issues leading to BrokenResourceError
-                return {"status": "error", "message": f"Query failed: {result['error']}"}
+                return {
+                    "status": "error",
+                    "message": f"Query failed: {result['error']}",
+                }
             return result
         except concurrent.futures.TimeoutError:
             logger.warning(f"Query timed out after {SELECT_QUERY_TIMEOUT_SECS} seconds: {query}")
             future.cancel()
-            # Return a properly structured response for timeout errors
-            return {
-                "status": "error",
-                "message": f"Query timed out after {SELECT_QUERY_TIMEOUT_SECS} seconds",
-            }
+            raise ToolError(f"Query timed out after {SELECT_QUERY_TIMEOUT_SECS} seconds")
+    except ToolError:
+        raise
     except Exception as e:
         logger.error(f"Unexpected error in run_select_query: {str(e)}")
-        # Catch all other exceptions and return them in a structured format
-        # to prevent MCP serialization failures
-        return {"status": "error", "message": f"Unexpected error: {str(e)}"}
+        raise RuntimeError(f"Unexpected error during query execution: {str(e)}")
 
 
 def create_hydrolix_client():
     client_config = get_config().get_client_config()
+    auth_info = (
+        f"as {client_config['username']}"
+        if "username" in client_config
+        else "using service account token"
+    )
     logger.info(
         f"Creating Hydrolix client connection to {client_config['host']}:{client_config['port']} "
-        f"as {client_config['username']} "
+        f"{auth_info} "
         f"(secure={client_config['secure']}, verify={client_config['verify']}, "
         f"connect_timeout={client_config['connect_timeout']}s, "
         f"send_receive_timeout={client_config['send_receive_timeout']}s)"
@@ -225,7 +261,7 @@ def create_hydrolix_client():
         client = clickhouse_connect.get_client(**client_config)
         # Test the connection
         version = client.server_version
-        logger.info(f"Successfully connected to Hydrolix server version {version}")
+        logger.info(f"Successfully connected to Hydrolix compatible with ClickHouse {version}")
         return client
     except Exception as e:
         logger.error(f"Failed to connect to Hydrolix: {str(e)}")

mcp_hydrolix-0.1.4.dist-info/METADATA

@@ -0,0 +1,251 @@
+Metadata-Version: 2.4
+Name: mcp-hydrolix
+Version: 0.1.4
+Summary: An MCP server for Hydrolix.
+Project-URL: Home, https://github.com/hydrolix/mcp-hydrolix
+License-Expression: Apache-2.0
+License-File: LICENSE
+Requires-Python: >=3.13
+Requires-Dist: clickhouse-connect>=0.8.16
+Requires-Dist: fastmcp>=2.0.0
+Requires-Dist: pip-system-certs>=4.0
+Requires-Dist: python-dotenv>=1.0.1
+Provides-Extra: dev
+Requires-Dist: pre-commit; extra == 'dev'
+Requires-Dist: pytest; extra == 'dev'
+Requires-Dist: pytest-asyncio; extra == 'dev'
+Requires-Dist: ruff; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Hydrolix MCP Server
+
+[![PyPI - Version](https://img.shields.io/pypi/v/mcp-hydrolix)](https://pypi.org/project/mcp-hydrolix)
+
+An MCP server for Hydrolix.
+
+## Tools
+
+* `run_select_query`
+  * Execute SQL queries on your Hydrolix cluster.
+  * Input: `sql` (string): The SQL query to execute.
+  * All Hydrolix queries are run with `readonly = 1` to ensure they are safe.
+
+* `list_databases`
+  * List all databases on your Hydrolix cluster.
+
+* `list_tables`
+  * List all tables in a database.
+  * Input: `database` (string): The name of the database.
+
+## Effective Usage
+
+Due to the wide variety in LLM architectures, not all models will proactively use the tools above, and few will use them effectively without guidance, even with the carefully-constructed tool descriptions provided to the model. To get the best results out of your model while using the Hydrolix MCP server, we recommend the following:
+
+* Refer to your Hydrolix database by name and request tool usage in your prompts (e.g., "Using MCP tools to access my Hydrolix database, please ...")
+  - This encourages the model to use the MCP tools available and minimizes hallucinations.
+* Include time ranges in your prompts (e.g., "Between December 5 2023 and January 18 2024, ...") and specifically request that the output be ordered by timestamp.
+  - This prompts the model to write more efficient queries that take advantage of [primary key optimizations](https://hydrolix.io/blog/optimizing-latest-n-row-queries/)
+
+### Health Check Endpoint
+
+When running with HTTP or SSE transport, a health check endpoint is available at `/health`. This endpoint:
+- Returns `200 OK` with the Hydrolix query-head's Clickhouse version if the server is healthy and can connect to Hydrolix
+- Returns `503 Service Unavailable` if the server cannot connect to the Hydrolix query-head
+
+Example:
+```bash
+curl http://localhost:8000/health
+# Response: OK - Connected to Hydrolix compatible with ClickHouse 24.3.1
+```
+
+## Configuration
+
+The Hydrolix MCP server is configured using a standard MCP server entry. Consult your client's documentation for specific instructions on where to find or declare MCP servers. An example setup using Claude Desktop is documented below.
+
+The recommended way to launch the Hydrolix MCP server is via the [`uv` project manager](https://github.com/astral-sh/uv), which will manage installing all other dependencies in an isolated environment.
+
+MCP Server definition using username and password (JSON):
+
+```json
+{
+  "command": "uv",
+  "args": [
+    "run",
+    "--with",
+    "mcp-hydrolix",
+    "--python",
+    "3.13",
+    "mcp-hydrolix"
+  ],
+  "env": {
+    "HYDROLIX_HOST": "<hydrolix-host>",
+    "HYDROLIX_USER": "<hydrolix-user>",
+    "HYDROLIX_PASSWORD": "<hydrolix-password>"
+  }
+}
+```
+
+MCP Server definition using service account token (JSON):
+
+```json
+{
+  "command": "uv",
+  "args": [
+    "run",
+    "--with",
+    "mcp-hydrolix",
+    "--python",
+    "3.13",
+    "mcp-hydrolix"
+  ],
+  "env": {
+    "HYDROLIX_HOST": "<hydrolix-host>",
+    "HYDROLIX_TOKEN": "<hydrolix-service-account-token>"
+  }
+}
+```
+
+MCP Server definition using username and password (YAML):
+
+```yaml
+command: uv
+args:
+- run
+- --with
+- mcp-hydrolix
+- --python
+- "3.13"
+- mcp-hydrolix
+env:
+  HYDROLIX_HOST: <hydrolix-host>
+  HYDROLIX_USER: <hydrolix-user>
+  HYDROLIX_PASSWORD: <hydrolix-password>
+```
+
+MCP Server definition using service account token (YAML):
+
+```yaml
+command: uv
+args:
+- run
+- --with
+- mcp-hydrolix
+- --python
+- "3.13"
+- mcp-hydrolix
+env:
+  HYDROLIX_HOST: <hydrolix-host>
+  HYDROLIX_TOKEN: <hydrolix-service-account-token>
+```
+
+### Configuration Example (Claude Desktop)
+
+1. Open the Claude Desktop configuration file located at:
+   - On macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
+   - On Windows: `%APPDATA%/Claude/claude_desktop_config.json`
+
+2. Add a `mcp-hydrolix` server entry to the `mcpServers` config block to use username and password:
+
+```json
+{
+  "mcpServers": {
+    "mcp-hydrolix": {
+      "command": "uv",
+      "args": [
+        "run",
+        "--with",
+        "mcp-hydrolix",
+        "--python",
+        "3.13",
+        "mcp-hydrolix"
+      ],
+      "env": {
+        "HYDROLIX_HOST": "<hydrolix-host>",
+        "HYDROLIX_USER": "<hydrolix-user>",
+        "HYDROLIX_PASSWORD": "<hydrolix-password>"
+      }
+    }
+  }
+}
+```
+
+To leverage service account use the following config block:
+
+```json
+{
+  "mcpServers": {
+    "mcp-hydrolix": {
+      "command": "uv",
+      "args": [
+        "run",
+        "--with",
+        "mcp-hydrolix",
+        "--python",
+        "3.13",
+        "mcp-hydrolix"
+      ],
+      "env": {
+        "HYDROLIX_HOST": "<hydrolix-host>",
+        "HYDROLIX_TOKEN": "<hydrolix-service-account-token>"
+      }
+    }
+  }
+}
+```
+
+3. Update the environment variable definitions to point to your Hydrolix cluster.
+
+4. (Recommended) Locate the command entry for `uv` and replace it with the absolute path to the `uv` executable. This ensures that the correct version of `uv` is used when starting the server. You can find this path using `which uv` or `where.exe uv`.
+
+5. Restart Claude Desktop to apply the changes. If you are using Windows, ensure Claude is stopped completely by closing the client using the system tray icon.
+
+### Environment Variables
+
+The following variables are used to configure the Hydrolix connection. These variables may be provided via the MCP config block (as shown above), a `.env` file, or traditional environment variables.
+
+#### Required Variables
+* `HYDROLIX_HOST`: The hostname of your Hydrolix server
+* `HYDROLIX_TOKEN`: The Hydrolix service account token (omit if using username/password)
+* `HYDROLIX_USER`: The username for authentication (omit if using service account)
+* `HYDROLIX_PASSWORD`: The password for authentication (omit if using service account)
+
+**Authentication precedence:** If both `HYDROLIX_TOKEN` and `HYDROLIX_USER`/`HYDROLIX_PASSWORD` are provided, the service account token takes precedence and username/password authentication will be ignored.
+
+#### Optional Variables
+* `HYDROLIX_PORT`: The port number of your Hydrolix server
+  * Default: `8088`
+  * Usually doesn't need to be set unless using a non-standard port
+* `HYDROLIX_VERIFY`: Enable/disable SSL certificate verification
+  * Default: `"true"`
+  * Set to `"false"` to disable certificate verification (not recommended for production)
+* `HYDROLIX_DATABASE`: Default database to use
+  *Default: None (uses server default)
+  * Set this to automatically connect to a specific database
+* `HYDROLIX_MCP_SERVER_TRANSPORT`: Sets the transport method for the MCP server.
+  * Default: `"stdio"`
+  * Valid options: `"stdio"`, `"http"`, `"sse"`. This is useful for local development with tools like MCP Inspector.
+* `HYDROLIX_MCP_BIND_HOST`: Host to bind the MCP server to when using HTTP or SSE transport
+  * Default: `"127.0.0.1"`
+  * Set to `"0.0.0.0"` to bind to all network interfaces (useful for Docker or remote access)
+  * Only used when transport is `"http"` or `"sse"`
+* `HYDROLIX_MCP_BIND_PORT`: Port to bind the MCP server to when using HTTP or SSE transport
+  * Default: `"8000"`
+  * Only used when transport is `"http"` or `"sse"`
+
+
+For MCP Inspector or remote access with HTTP transport:
+
+```env
+HYDROLIX_HOST=localhost
+HYDROLIX_USER=default
+HYDROLIX_PASSWORD=myPassword
+HYDROLIX_MCP_SERVER_TRANSPORT=http
+HYDROLIX_MCP_BIND_HOST=0.0.0.0  # Bind to all interfaces
+HYDROLIX_MCP_BIND_PORT=4200  # Custom port (default: 8000)
+```
+
+When using HTTP transport, the server will run on the configured port (default 8000). For example, with the above configuration:
+- MCP endpoint: `http://localhost:4200/mcp`
+- Health check: `http://localhost:4200/health`
+
+Note: The bind host and port settings are only used when transport is set to "http" or "sse".

mcp_hydrolix-0.1.4.dist-info/RECORD

@@ -0,0 +1,9 @@
+mcp_hydrolix/__init__.py,sha256=DnAQkvoFf_QhrDNFLOmn-nHlldPUgtdN33k3xJWthgc,225
+mcp_hydrolix/main.py,sha256=9cNwIVNE0fCbPuwde-VjcwyZwNb07i9zFRxzEE1yLus,703
+mcp_hydrolix/mcp_env.py,sha256=3NyjHiMyhodB9D7QpPxtFtXFzHbw-FzrqlsmGPElqwc,7651
+mcp_hydrolix/mcp_server.py,sha256=i0qPwXv-s6-kxMh1FeuPNAItk5u17sSjY8GGu1SiyB8,10537
+mcp_hydrolix-0.1.4.dist-info/METADATA,sha256=13PY5b6HeuurxPMYOysJ29FwJ8wc2xPnKUNvGSWuqxA,8376
+mcp_hydrolix-0.1.4.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+mcp_hydrolix-0.1.4.dist-info/entry_points.txt,sha256=vHa7F2rOCVu8lpsqR8BYbE1w8ugJSOYwX95w802Y5qE,56
+mcp_hydrolix-0.1.4.dist-info/licenses/LICENSE,sha256=xx0jnfkXJvxRnG63LTGOxlggYnIysveWIZ6H3PNdCrQ,11357
+mcp_hydrolix-0.1.4.dist-info/RECORD,,

{mcp_hydrolix-0.1.1.dist-info → mcp_hydrolix-0.1.4.dist-info}/licenses/LICENSE

@@ -198,4 +198,4 @@
    distributed under the License is distributed on an "AS IS" BASIS,
    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    See the License for the specific language governing permissions and
-   limitations under the License.
+   limitations under the License.

mcp_hydrolix-0.1.1.dist-info/METADATA

@@ -1,146 +0,0 @@
-Metadata-Version: 2.4
-Name: mcp-hydrolix
-Version: 0.1.1
-Summary: An MCP server for Hydrolix.
-Project-URL: Home, https://github.com/hydrolix/mcp-hydrolix
-License-Expression: Apache-2.0
-License-File: LICENSE
-Requires-Python: >=3.13
-Requires-Dist: clickhouse-connect>=0.8.16
-Requires-Dist: mcp[cli]>=1.3.0
-Requires-Dist: pip-system-certs>=4.0
-Requires-Dist: python-dotenv>=1.0.1
-Requires-Dist: uvicorn>=0.34.0
-Provides-Extra: dev
-Requires-Dist: pytest; extra == 'dev'
-Requires-Dist: ruff; extra == 'dev'
-Description-Content-Type: text/markdown
-
-# Hydrolix MCP Server
-[![PyPI - Version](https://img.shields.io/pypi/v/mcp-hydrolix)](https://pypi.org/project/mcp-hydrolix)
-
-An MCP server for Hydrolix.
-
-## Tools
-
-* `run_select_query`
-  - Execute SQL queries on your Hydrolix cluster.
-  - Input: `sql` (string): The SQL query to execute.
-  - All Hydrolix queries are run with `readonly = 1` to ensure they are safe.
-
-* `list_databases`
-  - List all databases on your Hydrolix cluster.
-
-* `list_tables`
-  - List all tables in a database.
-  - Input: `database` (string): The name of the database.
-
-## Effective Usage
-
-Due to the wide variety in LLM architectures, not all models will proactively use the tools above, and few will use them effectively without guidance, even with the carefully-constructed tool descriptions provided to the model. To get the best results out of your model while using the Hydrolix MCP server, we recommend the following:
-
-* Refer to your Hydrolix database by name and request tool usage in your prompts (e.g., "Using MCP tools to access my Hydrolix database, please ...")
-  - This encourages the model to use the MCP tools available and minimizes hallucinations.
-* Include time ranges in your prompts (e.g., "Between December 5 2023 and January 18 2024, ...") and specifically request that the output be ordered by timestamp.
-  - This prompts the model to write more efficient queries that take advantage of [primary key optimizations](https://hydrolix.io/blog/optimizing-latest-n-row-queries/)
-
-## Configuration
-
-The Hydrolix MCP server is configured using a standard MCP server entry. Consult your client's documentation for specific instructions on where to find or declare MCP servers. An example setup using Claude Desktop is documented below.
-
-The recommended way to launch the Hydrolix MCP server is via the [`uv` project manager](https://github.com/astral-sh/uv), which will manage installing all other dependencies in an isolated environment.
-
-MCP Server definition (JSON):
-
-```json
-{
-  "command": "uv",
-  "args": [
-    "run",
-    "--with",
-    "mcp-hydrolix",
-    "--python",
-    "3.13",
-    "mcp-hydrolix"
-  ],
-  "env": {
-    "HYDROLIX_HOST": "<hydrolix-host>",
-    "HYDROLIX_USER": "<hydrolix-user>",
-    "HYDROLIX_PASSWORD": "<hydrolix-password>",
-  }
-}
-```
-
-MCP Server definition (YAML):
-
-```yaml
-command: uv
-args:
-- run
-- --with
-- mcp-hydrolix
-- --python
-- "3.13"
-- mcp-hydrolix
-env:
-  HYDROLIX_HOST: <hydrolix-host>
-  HYDROLIX_USER: <hydrolix-user>
-  HYDROLIX_PASSWORD: <hydrolix-password>
-```
-
-## Configuration Example (Claude Desktop)
-
-1. Open the Claude Desktop configuration file located at:
-   - On macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
-   - On Windows: `%APPDATA%/Claude/claude_desktop_config.json`
-
-2. Add a `mcp-hydrolix` server entry to the `mcpServers` config block:
-
-```json
-{
-  "mcpServers": {
-    "mcp-hydrolix": {
-      "command": "uv",
-      "args": [
-        "run",
-        "--with",
-        "mcp-hydrolix",
-        "--python",
-        "3.13",
-        "mcp-hydrolix"
-      ],
-      "env": {
-        "HYDROLIX_HOST": "<hydrolix-host>",
-        "HYDROLIX_USER": "<hydrolix-user>",
-        "HYDROLIX_PASSWORD": "<hydrolix-password>",
-      }
-    }
-  }
-}
-```
-
-3. Update the environment variable definitions to point to your Hydrolix cluster.
-
-4. (Recommended) Locate the command entry for `uv` and replace it with the absolute path to the `uv` executable. This ensures that the correct version of `uv` is used when starting the server. You can find this path using `which uv` or `where.exe uv`.
-
-5. Restart Claude Desktop to apply the changes. If you are using Windows, ensure Claude is stopped completely by closing the client using the system tray icon.
-
-### Environment Variables
-
-The following variables are used to configure the Hydrolix connection. These variables may be provided via the MCP config block (as shown above), a `.env` file, or traditional environment variables.
-
-#### Required Variables
-* `HYDROLIX_HOST`: The hostname of your Hydrolix server
-* `HYDROLIX_USER`: The username for authentication
-* `HYDROLIX_PASSWORD`: The password for authentication
-
-#### Optional Variables
-* `HYDROLIX_PORT`: The port number of your Hydrolix server
-  - Default: `8088`
-  - Usually doesn't need to be set unless using a non-standard port
-* `HYDROLIX_VERIFY`: Enable/disable SSL certificate verification
-  - Default: `"true"`
-  - Set to `"false"` to disable certificate verification (not recommended for production)
-* `HYDROLIX_DATABASE`: Default database to use
-  - Default: None (uses server default)
-  - Set this to automatically connect to a specific database

mcp_hydrolix-0.1.1.dist-info/RECORD

@@ -1,9 +0,0 @@
-mcp_hydrolix/__init__.py,sha256=DnAQkvoFf_QhrDNFLOmn-nHlldPUgtdN33k3xJWthgc,225
-mcp_hydrolix/main.py,sha256=WTZcvpIas2mIjNd_em7KWlXI_6IXZAdtdlQ7czmX1cs,96
-mcp_hydrolix/mcp_env.py,sha256=HPOPRdPm-YAxU3ygdZPoNT8Oc4CE-VWXF6mmton5mnU,4454
-mcp_hydrolix/mcp_server.py,sha256=L5ahWFqNXXiQLNbpONo1jTsGFoZFtrd1pln5iHTsMOM,9823
-mcp_hydrolix-0.1.1.dist-info/METADATA,sha256=k_CVCad12xZLwzYKsFvsXPoN9vMb489qpVg2H6xkSKc,5153
-mcp_hydrolix-0.1.1.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-mcp_hydrolix-0.1.1.dist-info/entry_points.txt,sha256=vHa7F2rOCVu8lpsqR8BYbE1w8ugJSOYwX95w802Y5qE,56
-mcp_hydrolix-0.1.1.dist-info/licenses/LICENSE,sha256=QwcOLU5TJoTeUhuIXzhdCEEDDvorGiC6-3YTOl4TecE,11356
-mcp_hydrolix-0.1.1.dist-info/RECORD,,