mcp-hydrolix 0.1.0__py3-none-any.whl → 0.1.3__py3-none-any.whl

mcp_hydrolix/mcp_env.py

@@ -127,5 +127,17 @@ class HydrolixConfig:
             raise ValueError(f"Missing required environment variables: {', '.join(missing_vars)}")
 
 
-# Global instance for easy access
-config = HydrolixConfig()
+# Global instance placeholder for the singleton pattern
+_CONFIG_INSTANCE = None
+
+
+def get_config():
+    """
+    Gets the singleton instance of HydrolixConfig.
+    Instantiates it on the first call.
+    """
+    global _CONFIG_INSTANCE
+    if _CONFIG_INSTANCE is None:
+        # Instantiate the config object here, ensuring load_dotenv() has likely run
+        _CONFIG_INSTANCE = HydrolixConfig()
+    return _CONFIG_INSTANCE

mcp_hydrolix/mcp_server.py

@@ -8,7 +8,7 @@ from clickhouse_connect.driver.binding import quote_identifier, format_query_val
 from dotenv import load_dotenv
 from mcp.server.fastmcp import FastMCP
 
-from mcp_hydrolix.mcp_env import config
+from mcp_hydrolix.mcp_env import get_config
 
 MCP_SERVER_NAME = "mcp-hydrolix"
 
@@ -56,10 +56,11 @@ def list_tables(database: str, like: str = None):
 
     # Get all table comments in one query
     table_comments_query = (
-        f"SELECT name, comment FROM system.tables WHERE database = {format_query_value(database)}"
+        f"SELECT name, comment, primary_key FROM system.tables WHERE database = {format_query_value(database)} and engine = 'TurbineStorage' and total_rows > 0"
     )
     table_comments_result = client.query(table_comments_query)
     table_comments = {row[0]: row[1] for row in table_comments_result.result_rows}
+    primary_keys = {row[0]: row[2] 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)}"
@@ -98,6 +99,7 @@ def list_tables(database: str, like: str = None):
             "comment": table_comments.get(table),
             "columns": columns,
             "create_table_query": create_table_result,
+            "primary_key": primary_keys.get(table)
         }
 
     tables = []
@@ -212,7 +214,7 @@ def run_select_query(query: str):
 
 
 def create_hydrolix_client():
-    client_config = config.get_client_config()
+    client_config = get_config().get_client_config()
     logger.info(
         f"Creating Hydrolix client connection to {client_config['host']}:{client_config['port']} "
         f"as {client_config['username']} "

mcp_hydrolix-0.1.3.dist-info/METADATA

@@ -0,0 +1,146 @@
+Metadata-Version: 2.4
+Name: mcp-hydrolix
+Version: 0.1.3
+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.3.dist-info/RECORD

@@ -0,0 +1,9 @@
+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=xzEILclKF88KE8OZljiaAHwPcfiyt5DE_amPnqVyMFQ,10017
+mcp_hydrolix-0.1.3.dist-info/METADATA,sha256=EEc9-0SGJc6AGmSQHvrbki6unzxV7c1m2IoLJhMWBuo,5152
+mcp_hydrolix-0.1.3.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+mcp_hydrolix-0.1.3.dist-info/entry_points.txt,sha256=vHa7F2rOCVu8lpsqR8BYbE1w8ugJSOYwX95w802Y5qE,56
+mcp_hydrolix-0.1.3.dist-info/licenses/LICENSE,sha256=QwcOLU5TJoTeUhuIXzhdCEEDDvorGiC6-3YTOl4TecE,11356
+mcp_hydrolix-0.1.3.dist-info/RECORD,,

mcp_hydrolix-0.1.0.dist-info/METADATA

@@ -1,106 +0,0 @@
-Metadata-Version: 2.4
-Name: mcp-hydrolix
-Version: 0.1.0
-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.0
-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.
-
-## Features
-
-### 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.
-
-## Configuration
-
-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 the following:
-
-```json
-{
-  "mcpServers": {
-    "mcp-hydrolix": {
-      "command": "uv",
-      "args": [
-        "run",
-        "--with",
-        "mcp-hydrolix",
-        "--python",
-        "3.13",
-        "mcp-hydrolix"
-      ],
-      "env": {
-        "HYDROLIX_HOST": "<hydrolix-host>",
-        "HYDROLIX_PORT": "<hydrolix-port>",
-        "HYDROLIX_USER": "<hydrolix-user>",
-        "HYDROLIX_PASSWORD": "<hydrolix-password>",
-        "HYDROLIX_SECURE": "true",
-        "HYDROLIX_VERIFY": "true",
-        "HYDROLIX_CONNECT_TIMEOUT": "30",
-        "HYDROLIX_SEND_RECEIVE_TIMEOUT": "30"
-      }
-    }
-  }
-}
-```
-
-Update the environment variables to point to your own Hydrolix service.
-
-3. 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. On a mac, you can find this path using `which uv`.
-
-4. Restart Claude Desktop to apply the changes.
-
-### Environment Variables
-
-The following environment variables are used to configure the Hydrolix connection:
-
-#### 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_CONNECT_TIMEOUT`: Connection timeout in seconds
-  - Default: `"30"`
-  - Increase this value if you experience connection timeouts
-* `HYDROLIX_SEND_RECEIVE_TIMEOUT`: Send/receive timeout in seconds
-  - Default: `"300"`
-  - Increase this value for long-running queries
-* `HYDROLIX_DATABASE`: Default database to use
-  - Default: None (uses server default)
-  - Set this to automatically connect to a specific database

mcp_hydrolix-0.1.0.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=PIMxbhImiSGs4PaqrvEFXjA7wkr2AwEMkjCnKPyMEZg,4091
-mcp_hydrolix/mcp_server.py,sha256=EFkFy0658H0Fspo0e7oHiQNsWzBcP7tAcU0fo11iHz8,9813
-mcp_hydrolix-0.1.0.dist-info/METADATA,sha256=KZRd6hGV42Hcx_DIM6TGbbzkEaSLP2ovHtHpuyO-0aY,3368
-mcp_hydrolix-0.1.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-mcp_hydrolix-0.1.0.dist-info/entry_points.txt,sha256=vHa7F2rOCVu8lpsqR8BYbE1w8ugJSOYwX95w802Y5qE,56
-mcp_hydrolix-0.1.0.dist-info/licenses/LICENSE,sha256=QwcOLU5TJoTeUhuIXzhdCEEDDvorGiC6-3YTOl4TecE,11356
-mcp_hydrolix-0.1.0.dist-info/RECORD,,