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

mcp_hydrolix-0.1.5/.dockerignore

@@ -0,0 +1,13 @@
+__pycache__/
+*.pyc
+*.pyo
+*.pyd
+*.db
+*.sqlite3
+.env
+.venv/
+.envrc
+.DS_Store
+tests/
+.pytest_cache/
+.ruff_cache/

{mcp_hydrolix-0.1.3 → mcp_hydrolix-0.1.5}/.editorconfig

@@ -1,3 +1,3 @@
 [*]
 trim_trailing_whitespace = true
-end_of_line = lf
+end_of_line = lf

mcp_hydrolix-0.1.5/.github/pull_request_template.md

@@ -0,0 +1,26 @@
+What does this MR do?
+-----------------------
+
+Does this MR meet the acceptance criteria?
+--------------------------------------------
+
+* [ ] Documentation created/updated
+* [ ] Tests added for this feature/bug
+* [ ] Does this change request have any security impacts?
+
+Release Notes
+---------------------------------------------------
+
+* Major changes:
+    *
+* Minor changes:
+    *
+* Bugfixes:
+    *
+* Issues Closed:
+    *
+* Security impacts identified:
+    *
+
+Testing
+--------------------------------------------

mcp_hydrolix-0.1.5/.github/workflows/publish.yml

@@ -0,0 +1,67 @@
+on:
+  workflow_dispatch:
+    inputs:
+      publish_pypi:
+        description: "Include a pypi push in this publish"
+        required: true
+        type: boolean
+        default: true
+      publish_docker:
+        description: "Include a docker push in this publish"
+        required: true
+        type: boolean
+        default: true
+
+jobs:
+  publish:
+    name: Upload release to PyPI
+    runs-on: ubuntu-latest
+    if: ${{ inputs.publish_pypi }}
+    environment:
+      name: pypi
+      url: "https://pypi.org/p/mcp-hydrolix"
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/checkout@v5
+      - uses: astral-sh/setup-uv@v5
+      - run: uv python install
+      - run: uv build
+      - uses: pypa/gh-action-pypi-publish@release/v1
+  publish-docker:
+    name: Upload release to GAR
+    runs-on: ubuntu-latest
+    if: ${{ inputs.publish_docker }}
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v5
+      - name: Setup uv
+        uses: astral-sh/setup-uv@v5
+      - name: Authenticate GAR
+        uses: google-github-actions/auth@v3
+        with:
+          # Key ID: 98941823000cead5a61777398bd450e3e19539c3
+          credentials_json: ${{ secrets.GCP_GKE_CI_KEY }}
+      - name: "Set up GCP SDK" # needs to be done after google-github-actions/auth but before `gcloud auth configure-docker`
+        uses: google-github-actions/setup-gcloud@v3
+      - name: Configure GAR for docker
+        run: gcloud auth configure-docker us-docker.pkg.dev --quiet
+      - name: Get tag
+        id: get_tag
+        shell: bash
+        run: |
+          tag="v$(uv version --short)"
+          echo "::notice::Tag is $tag"
+          echo "tag=$tag" >> "$GITHUB_OUTPUT"
+      - name: Build docker image for MCP
+        shell: bash
+        run: |
+          docker buildx build \
+            -t us-docker.pkg.dev/hdx-art/t/mcp-hydrolix:${{ steps.get_tag.outputs.tag }} \
+            -t us-docker.pkg.dev/hdx-art/t/mcp-hydrolix:latest \
+            .
+      - name: Push docker image
+        shell: bash
+        run: |
+          docker push us-docker.pkg.dev/hdx-art/t/mcp-hydrolix:${{ steps.get_tag.outputs.tag }}
+          docker push us-docker.pkg.dev/hdx-art/t/mcp-hydrolix:latest

mcp_hydrolix-0.1.5/.github/workflows/tests.yaml

@@ -0,0 +1,40 @@
+name: Tests Pipeline
+
+on:
+  pull_request:
+    paths:
+      - '.github/workflows/tests.yml'
+      - 'mcp_hydrolix/**'
+      - 'mcp_hydrolix/tests/**'
+      - 'mcp_hydrolix/pyproject.toml'
+      - 'mcp_hydrolix/ruff.toml'
+      - 'mcp_hydrolix/uv.lock'
+      - 'mcp_hydrolix/Dockerfile'
+      - 'mcp_hydrolix/docker-compose.yaml'
+  workflow_dispatch:
+
+jobs:
+  core-test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+      - uses: actions/setup-python@v6
+        with:
+          python-version: '3.13'
+      - name: Pre-commit
+        uses: pre-commit/action@v3.0.1
+        with:
+          extra_args: --all-files
+      - name: Build and run Docker Compose services
+        run: docker compose up -d --wait --wait-timeout 300
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+      - name: Run tests
+        working-directory: .
+        run: |
+          uv sync --frozen --no-editable
+          uv pip install '.[dev]'
+          uv run pytest
+      - name: Stop Docker Compose services
+        if: always()
+        run: docker compose down

{mcp_hydrolix-0.1.3 → mcp_hydrolix-0.1.5}/.gitignore

@@ -168,7 +168,7 @@ cython_debug/
 #  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
 #  and can be added to the global gitignore or merged into this file.  For a more nuclear
 #  option (not recommended) you can uncomment the following to ignore the entire idea folder.
-#.idea/
+.idea/
 
 # PyPI configuration file
 .pypirc

mcp_hydrolix-0.1.5/.pre-commit-config.yaml

@@ -0,0 +1,20 @@
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v6.0.0
+    hooks:
+      - id: end-of-file-fixer
+      - id: trailing-whitespace
+        args: [--markdown-linebreak-ext=md]
+      - id: check-yaml
+      - id: check-json
+      - id: check-toml
+      - id: no-commit-to-branch
+
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.12.9
+    hooks:
+      - id: ruff
+        name: ruff lint
+        args: [--fix]
+      - id: ruff-format
+        name: ruff format

mcp_hydrolix-0.1.5/Dockerfile

@@ -0,0 +1,49 @@
+# use the official uv image (with matching python/alpine version) to construct the venv
+FROM ghcr.io/astral-sh/uv:0.9.4-python3.13-alpine AS builder
+# # Install `cc` (to build lz4 from source)
+RUN apk add build-base
+
+WORKDIR /app
+
+# dependencies specifications
+COPY pyproject.toml /app/
+COPY uv.lock /app/
+# And because uv sync likes to verify the README... for some reason...
+COPY README.md /app/
+
+# produce .venv
+RUN uv sync --locked
+
+# begin definition of runtime container, relying on the venv made in builder
+FROM python:3.13-alpine
+
+# don't buffer log streams (docker adds enough delay)
+ENV PYTHONUNBUFFERED=1
+
+# don't cache pyc bytecode, since the container fs isn't persisted across restarts anyways
+ENV PYTHONDONTWRITEBYTECODE=1
+
+# Bind HTTP transport to all interfaces
+ENV HYDROLIX_MCP_BIND_HOST=0.0.0.0
+ENV HYDROLIX_MCP_SERVER_TRANSPORT=http
+
+# declare that we expose port 8000
+EXPOSE 8000
+
+# Got a health check too
+HEALTHCHECK --interval=30s --timeout=30s --start-period=5s --retries=3 \
+  CMD [ "wget", "--no-verbose", "--tries=1", "--spider", "http://127.0.0.1:8000/health" ]
+
+RUN addgroup -g 1000 -S appgroup && \
+  adduser -u 1000 -S appuser -G appgroup -h /app -s /sbin/nologin
+USER appuser
+
+WORKDIR /app
+
+
+COPY --from=builder --chown=appuser:appgroup /app/.venv/ /app/.venv
+
+COPY --chown=appuser:appgroup mcp_hydrolix/ /app/mcp_hydrolix
+COPY --chown=appuser:appgroup pyproject.toml /app/
+
+ENTRYPOINT [".venv/bin/python", "-m", "mcp_hydrolix.main"]

{mcp_hydrolix-0.1.3 → mcp_hydrolix-0.1.5}/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.5/PKG-INFO

@@ -0,0 +1,314 @@
+Metadata-Version: 2.4
+Name: mcp-hydrolix
+Version: 0.1.5
+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.10.0
+Requires-Dist: fastmcp>=2.13.3
+Requires-Dist: gunicorn>=23.0.0
+Requires-Dist: pip-system-certs>=4.0
+Requires-Dist: pyjwt>=2.10.1
+Requires-Dist: python-dotenv>=1.0.1
+Provides-Extra: dev
+Requires-Dist: fastapi>=0.124.0; extra == 'dev'
+Requires-Dist: mcp-clickhouse>=0.1.12; extra == 'dev'
+Requires-Dist: pre-commit; extra == 'dev'
+Requires-Dist: pytest; extra == 'dev'
+Requires-Dist: pytest-asyncio; extra == 'dev'
+Requires-Dist: pytest-repeat; extra == 'dev'
+Requires-Dist: pytest-xdist; 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.
+
+### Authentication
+
+The server supports multiple authentication methods with the following precedence (highest to lowest):
+
+1. **Per-request Bearer token**: Service account token provided via `Authorization: Bearer <token>` header
+2. **Per-request GET parameter**: Service account token provided via `?token=<token>` query parameter
+3. **Environment-based credentials**: Credentials configured via environment variables
+   - Service account token (`HYDROLIX_TOKEN`), or
+   - Username and password (`HYDROLIX_USER` and `HYDROLIX_PASSWORD`)
+
+When multiple authentication methods are configured, the server will use the first available method in the precedence order above. Per-request authentication is only available when using HTTP or SSE transport modes.
+
+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.
+
+### Configuration Example (Claude Code)
+
+To configure the Hydrolix MCP server for Claude Code, run the following command:
+
+```bash
+claude mcp add --transport stdio hydrolix \
+  --env HYDROLIX_USER=<hydrolix-user> \
+  --env HYDROLIX_PASSWORD=<hydrolix-password> \
+  --env HYDROLIX_HOST=<hydrolix-host> \
+  --env HYDROLIX_MCP_SERVER_TRANSPORT=stdio \
+  -- uv run --with mcp-hydrolix --python 3.13 mcp-hydrolix
+```
+
+### 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
+
+#### Authentication Variables
+At least one authentication method must be configured when using the stdio transport:
+
+* `HYDROLIX_TOKEN`: Service account token for environment-based authentication
+* `HYDROLIX_USER` and `HYDROLIX_PASSWORD`: Username and password for environment-based authentication (both must be provided together)
+
+In summary:
+- For stdio, you MUST use HYDROLIX_TOKEN or HYDROLIX_USER+HYDROLIX_PASS (environmental credentials)
+- For http/sse, you MAY use HYDROLIX_TOKEN or HYDROLIX_USER+HYDROLIX_PASS (environmental credentials), but you may instead use per-request credentials.
+
+If no credentials are provided via the environment or the request, the request will fail.
+
+#### 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`
+
+#### Using Per-Request Authentication with HTTP Transport
+
+When using HTTP or SSE transport, you can omit environment-based credentials and instead provide authentication per-request. This is useful for multi-user scenarios or with clients that don't support running MCP servers locally.
+
+Example `mcpServers` configuration connecting to a remote HTTP server with per-request authentication:
+
+```json
+{
+  "mcpServers": {
+    "mcp-hydrolix-remote": {
+      "url": "http://my-hydrolix-mcp.example.com:8000/mcp?token=<service-account-token>"
+    }
+  }
+}
+```
+
+Example minimal `.env` configuration for running your own HTTP server without environment credentials:
+
+```env
+HYDROLIX_HOST=my-cluster.hydrolix.net
+HYDROLIX_MCP_SERVER_TRANSPORT=http
+```
+
+Though not part of the MCP specification, many MCP clients allow adding headers to MCP-issued requests. When this is possible, we recommend configuring the MCP client to pass a service account token via the `Authorization: Bearer <sa-token-here>` header instead of as a query parameter for greater security.
+
+Note: The bind host and port settings are only used when transport is set to "http" or "sse".