mcp-hydrolix 0.1.0__tar.gz → 0.1.3__tar.gz

mcp_hydrolix-0.1.3/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,128 @@
+# 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/glama.json

@@ -0,0 +1,8 @@
+{
+  "$schema": "https://glama.ai/mcp/schemas/server.json",
+  "maintainers": [
+    "aggarwaa",
+    "dsztykman",
+    "emanb29"
+  ]
+}

{mcp_hydrolix-0.1.0 → mcp_hydrolix-0.1.3}/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-0.1.0 → mcp_hydrolix-0.1.3}/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.0 → mcp_hydrolix-0.1.3}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "mcp-hydrolix"
-version = "0.1.0"
+version = "0.1.3"
 description = "An MCP server for Hydrolix."
 readme = "README.md"
 license = "Apache-2.0"
@@ -10,7 +10,7 @@ dependencies = [
      "mcp[cli]>=1.3.0",
      "python-dotenv>=1.0.1",
      "uvicorn>=0.34.0",
-     "clickhouse-connect>=0.8.0",
+     "clickhouse-connect>=0.8.16",
      "pip-system-certs>=4.0",
 ]