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

mcp_hydrolix/utils.py

@@ -0,0 +1,70 @@
+import inspect
+import ipaddress
+import json
+from datetime import datetime, time
+from decimal import Decimal
+from functools import wraps
+
+import fastmcp.utilities.types
+from fastmcp.tools.tool import ToolResult
+
+
+class ExtendedEncoder(json.JSONEncoder):
+    """Extends JSONEncoder to apply custom serialization of CH data types."""
+
+    def default(self, obj):
+        if isinstance(obj, ipaddress.IPv4Address):
+            return str(obj)
+        if isinstance(obj, datetime):
+            return obj.time()
+        if isinstance(obj, time):
+            return obj.hour * 3600 + obj.minute * 60 + obj.second + obj.microsecond / 1_000_000
+        if isinstance(obj, bytes):
+            return obj.decode()
+        if isinstance(obj, Decimal):
+            return str(obj)
+        return super().default(obj)
+
+
+def with_serializer(fn):
+    """
+    Decorator to apply custom serialization to CH query tool result.
+    Should be applied as a first decorator of the tool function.
+
+    :returns: sync/async wrapper of mcp tool function
+    """
+
+    @wraps(fn)
+    def wrapper(*args, **kwargs):
+        """
+        Sync wrapper of mcpt tool `fn` function.
+        Function should return a dict or None.
+
+        :returns: ToolResult object with text-serialized and structured content.
+        """
+        result = fn(*args, **kwargs)
+        if not isinstance(result, dict):
+            result = {"result": result}
+        enc = json.dumps(result, cls=ExtendedEncoder)
+        return ToolResult(content=enc, structured_content=json.loads(enc))
+
+    @wraps(fn)
+    async def async_wrapper(*args, **kwargs):
+        """
+        Async wrapper of mcp tool `fn` function.
+        Function should return a dict or None.
+
+        :returns: ToolResult object with text-serialized and structured content.
+        """
+        result = await fn(*args, **kwargs)
+        if not isinstance(result, dict):
+            result = {"result": result}
+        enc = json.dumps(result, cls=ExtendedEncoder)
+        return ToolResult(content=enc, structured_content=json.loads(enc))
+
+    # TODO: remove next signature fix code when a new fastmcp released (https://github.com/jlowin/fastmcp/issues/2524)
+    new_fn = fastmcp.utilities.types.create_function_without_params(fn, ["ctx"])
+    sig = inspect.signature(new_fn)
+    async_wrapper.__signature__ = sig
+    wrapper.__signature__ = sig
+    return async_wrapper if inspect.iscoroutinefunction(fn) else wrapper

{mcp_hydrolix-0.1.4.dist-info → mcp_hydrolix-0.1.5.dist-info}/METADATA

@@ -1,19 +1,25 @@
 Metadata-Version: 2.4
 Name: mcp-hydrolix
-Version: 0.1.4
+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.8.16
-Requires-Dist: fastmcp>=2.0.0
+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
 
@@ -64,6 +70,18 @@ The Hydrolix MCP server is configured using a standard MCP server entry. Consult
 
 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
@@ -199,17 +217,37 @@ To leverage service account use the following config block:
 
 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
-* `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.
+#### 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
@@ -248,4 +286,29 @@ When using HTTP transport, the server will run on the configured port (default 8
 - 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".

mcp_hydrolix-0.1.5.dist-info/RECORD

@@ -0,0 +1,17 @@
+mcp_hydrolix/__init__.py,sha256=DnAQkvoFf_QhrDNFLOmn-nHlldPUgtdN33k3xJWthgc,225
+mcp_hydrolix/main.py,sha256=Q58yz9ykx0bilptGALXW_Lli0pR7wDNOPib34l1z8Sg,2760
+mcp_hydrolix/mcp_env.py,sha256=CM8LG1ce1-LyM_CUm3Fg8hCoVi3ef5Lv-kLUVji7Jj0,11521
+mcp_hydrolix/mcp_server.py,sha256=CyOozGeu0MYX3m2UdaFAECyXA7Zk2fM_5pwh6mxI-Ng,12475
+mcp_hydrolix/utils.py,sha256=fMGCsRa2DqlS2PMfIpD5VaHTbaxUkW7mvgArgVViXbs,2433
+mcp_hydrolix/auth/__init__.py,sha256=uWF8v7ooLEcgBctxgyf4E4gtM_-PQM3xYTljA-Pbgnk,622
+mcp_hydrolix/auth/credentials.py,sha256=IK8w6TjNxS1K0LCKBt3xXOOI-0ogWCVAkiJuOzEJuJY,1915
+mcp_hydrolix/auth/mcp_providers.py,sha256=LSijw3RxC_BB9NnWXUSfWOSBjHwAk-vK41zYVM4CbFU,5177
+mcp_hydrolix/log/__init__.py,sha256=n7S4B06C1B6ZrOyz_15BbQ72D3lmmVNfOcc2qYiKans,103
+mcp_hydrolix/log/log.py,sha256=6KX0oSz-BbCWUoPxbJED4sZBmbgCHa3KDrc5nYtdks4,1838
+mcp_hydrolix/log/log.yaml,sha256=ldw66lGkQjqyJ92gJqOtdP63T_3MSD_ndKU1p8Xegvs,978
+mcp_hydrolix/log/utils.py,sha256=iwiFB331RzlWndhL8fbzPUmNlWS0e4qCV8n6W2Hpi5s,2088
+mcp_hydrolix-0.1.5.dist-info/METADATA,sha256=UVLw_p_jxkng-iKuDe-UffCWIcP7ci2OIAJ1UWlQ-VE,11074
+mcp_hydrolix-0.1.5.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+mcp_hydrolix-0.1.5.dist-info/entry_points.txt,sha256=vHa7F2rOCVu8lpsqR8BYbE1w8ugJSOYwX95w802Y5qE,56
+mcp_hydrolix-0.1.5.dist-info/licenses/LICENSE,sha256=xx0jnfkXJvxRnG63LTGOxlggYnIysveWIZ6H3PNdCrQ,11357
+mcp_hydrolix-0.1.5.dist-info/RECORD,,

{mcp_hydrolix-0.1.4.dist-info → mcp_hydrolix-0.1.5.dist-info}/WHEEL

@@ -1,4 +1,4 @@
 Wheel-Version: 1.0
-Generator: hatchling 1.27.0
+Generator: hatchling 1.28.0
 Root-Is-Purelib: true
 Tag: py3-none-any

mcp_hydrolix-0.1.4.dist-info/RECORD

@@ -1,9 +0,0 @@
-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,,