port latest code/refinement from mcp-clickhouse (#3)

* update the env config

* don't check env, since default values provided

* Update README.md

* Update test_tool.py

* Update test_tool.py

Author: Jove Zhong

.github/workflows/ci.yaml

@@ -35,6 +35,8 @@ jobs:
           TIMEPLUS_PORT: "8123"
           TIMEPLUS_USER: "default"
           TIMEPLUS_PASSWORD: ""
+          TIMEPLUS_SECURE: "false"
+          TIMEPLUS_VERIFY: "false"
         run: |
           uv run pytest tests
 

.gitignore

@@ -1,3 +1,4 @@
+.envrc
 .ruff_cache/
 
 # Byte-compiled / optimized / DLL files

README.md

@@ -3,7 +3,7 @@
 
 An MCP server for Timeplus.
 
-<a href="https://glama.ai/mcp/servers/yvjy4csvo1"><img width="380" height="200" src="https://glama.ai/mcp/servers/yvjy4csvo1/badge" alt="mcp-timeplus MCP server" /></a>
+<a href="https://glama.ai/mcp/servers/9aleefsq9s"><img width="380" height="200" src="https://glama.ai/mcp/servers/9aleefsq9s/badge" alt="mcp-timeplus MCP server" /></a>
 
 ## Features
 
@@ -25,8 +25,6 @@ An MCP server for Timeplus.
 
 First, ensure you have the `uv` executable installed. If not, you can install it by following the instructions [here](https://docs.astral.sh/uv/).
 
-This Python package is not published to PyPI yet. Please clone this repo and run `uv sync` to install the dependencies.
-
 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`
@@ -37,20 +35,17 @@ This Python package is not published to PyPI yet. Please clone this repo and run
 {
   "mcpServers": {
     "mcp-timeplus": {
-      "command": "/path/to/uv",
-      "args": [
-        "run",
-        "--project",
-        "/path/to/repo/mcp-timeplus",
-        "--python",
-        "3.13",
-        "mcp-timeplus"
-      ],
+      "command": "uvx",
+      "args": ["mcp-timeplus"],
       "env": {
         "TIMEPLUS_HOST": "<timeplus-host>",
         "TIMEPLUS_PORT": "<timeplus-port>",
         "TIMEPLUS_USER": "<timeplus-user>",
-        "TIMEPLUS_PASSWORD": "<timeplus-password>"
+        "TIMEPLUS_PASSWORD": "<timeplus-password>",
+        "TIMEPLUS_SECURE": "false",
+        "TIMEPLUS_VERIFY": "true",
+        "TIMEPLUS_CONNECT_TIMEOUT": "30",
+        "TIMEPLUS_SEND_RECEIVE_TIMEOUT": "30"
       }
     }
   }
@@ -59,33 +54,9 @@ This Python package is not published to PyPI yet. Please clone this repo and run
 
 Update the environment variables to point to your own Timeplus 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. Also point to the absolute path to the `mcp-timeplus` directory. A sample configuration:
+3. Restart Claude Desktop to apply the changes.
 
-```json
-{
-  "mcpServers": {
-    "mcp-timeplus": {
-      "command": "/opt/homebrew/bin/uv",
-      "args": [
-        "run",
-        "--project",
-        "/Users/jove/Dev/mcp-timeplus",
-        "--python",
-        "3.13",
-        "mcp-timeplus"
-      ],
-      "env": {
-        "TIMEPLUS_HOST": "localhost",
-        "TIMEPLUS_PORT": "8123",
-        "TIMEPLUS_USER": "default",
-        "TIMEPLUS_PASSWORD": ""
-      }
-    }
-  }
-}
-```
-
-4. Restart Claude Desktop to apply the changes.
+You can also try this MCP server with other MCP clients, such as [5ire](https://github.com/nanbingxyz/5ire).
 
 ## Development
 
@@ -98,8 +69,41 @@ TIMEPLUS_HOST=localhost
 TIMEPLUS_PORT=8123
 TIMEPLUS_USER=default
 TIMEPLUS_PASSWORD=
+TIMEPLUS_SECURE=false
+TIMEPLUS_VERIFY=true
+TIMEPLUS_CONNECT_TIMEOUT=30
+TIMEPLUS_SEND_RECEIVE_TIMEOUT=30
 ```
 
 3. Run `uv sync` to install the dependencies. Then do `source .venv/bin/activate`.
 
 4. For easy testing, you can run `fastmcp dev mcp_timeplus/mcp_server.py` to start the MCP server. Click the "Connect" button to connect the UI with the MCP server, then switch to the "Tools" tab to run the available tools: list_databases, list_tables, run_selected_query.
+
+### Environment Variables
+
+The following environment variables are used to configure the Timeplus connection:
+
+#### Required Variables
+* `TIMEPLUS_HOST`: The hostname of your Timeplus server
+* `TIMEPLUS_USER`: The username for authentication
+* `TIMEPLUS_PASSWORD`: The password for authentication
+
+#### Optional Variables
+* `TIMEPLUS_PORT`: The port number of your Timeplus server
+  - Default: `8443` if HTTPS is enabled, `8123` if disabled
+  - Usually doesn't need to be set unless using a non-standard port
+* `TIMEPLUS_SECURE`: Enable/disable HTTPS connection
+  - Default: `"false"`
+  - Set to `"true"` for secure connections
+* `TIMEPLUS_VERIFY`: Enable/disable SSL certificate verification
+  - Default: `"true"`
+  - Set to `"false"` to disable certificate verification (not recommended for production)
+* `TIMEPLUS_CONNECT_TIMEOUT`: Connection timeout in seconds
+  - Default: `"30"`
+  - Increase this value if you experience connection timeouts
+* `TIMEPLUS_SEND_RECEIVE_TIMEOUT`: Send/receive timeout in seconds
+  - Default: `"300"`
+  - Increase this value for long-running queries
+* `TIMEPLUS_DATABASE`: Default database to use
+  - Default: None (uses server default)
+  - Set this to automatically connect to a specific database

mcp_timeplus/mcp_env.py

@@ -0,0 +1,138 @@
+"""Environment configuration for the MCP Timeplus server.
+
+This module handles all environment variable configuration with sensible defaults
+and type conversion.
+"""
+
+from dataclasses import dataclass
+import os
+from typing import Optional
+
+
+@dataclass
+class TimeplusConfig:
+    """Configuration for Timeplus connection settings.
+
+    This class handles all environment variable configuration with sensible defaults
+    and type conversion. It provides typed methods for accessing each configuration value.
+
+    Required environment variables:
+        TIMEPLUS_HOST: The hostname of the Timeplus server
+        TIMEPLUS_USER: The username for authentication
+
+    Optional environment variables (with defaults):
+        TIMEPLUS_PASSWORD: The password for authentication (default: empty string)
+        TIMEPLUS_PORT: The port number (default: 8443 if secure=True, 8123 if secure=False)
+        TIMEPLUS_SECURE: Enable HTTPS (default: false)
+        TIMEPLUS_VERIFY: Verify SSL certificates (default: true)
+        TIMEPLUS_CONNECT_TIMEOUT: Connection timeout in seconds (default: 30)
+        TIMEPLUS_SEND_RECEIVE_TIMEOUT: Send/receive timeout in seconds (default: 300)
+        TIMEPLUS_DATABASE: Default database to use (default: default)
+    """
+
+    def __init__(self):
+        """Initialize the configuration from environment variables."""
+        self._validate_required_vars()
+
+    @property
+    def host(self) -> str:
+        """Get the Timeplus host."""
+        return os.getenv("TIMEPLUS_HOST", "localhost")
+
+    @property
+    def port(self) -> int:
+        """Get the Timeplus port.
+
+        Defaults to 8443 if secure=True, 8123 if secure=False.
+        Can be overridden by TIMEPLUS_PORT environment variable.
+        """
+        if "TIMEPLUS_PORT" in os.environ:
+            return int(os.environ["TIMEPLUS_PORT"])
+        return 8443 if self.secure else 8123
+
+    @property
+    def username(self) -> str:
+        """Get the Timeplus username."""
+        return os.getenv("TIMEPLUS_USER", "default")
+
+    @property
+    def password(self) -> str:
+        """Get the Timeplus password."""
+        return os.getenv("TIMEPLUS_PASSWORD", "")
+
+    @property
+    def database(self) -> Optional[str]:
+        """Get the default database name if set."""
+        return os.getenv("TIMEPLUS_DATABASE", "default")
+
+    @property
+    def secure(self) -> bool:
+        """Get whether HTTPS is enabled.
+
+        Default: False
+        """
+        return os.getenv("TIMEPLUS_SECURE", "false").lower() == "true"
+
+    @property
+    def verify(self) -> bool:
+        """Get whether SSL certificate verification is enabled.
+
+        Default: True
+        """
+        return os.getenv("TIMEPLUS_VERIFY", "true").lower() == "true"
+
+    @property
+    def connect_timeout(self) -> int:
+        """Get the connection timeout in seconds.
+
+        Default: 30
+        """
+        return int(os.getenv("TIMEPLUS_CONNECT_TIMEOUT", "30"))
+
+    @property
+    def send_receive_timeout(self) -> int:
+        """Get the send/receive timeout in seconds.
+
+        Default: 300 (Timeplus default)
+        """
+        return int(os.getenv("TIMEPLUS_SEND_RECEIVE_TIMEOUT", "300"))
+
+    def get_client_config(self) -> dict:
+        """Get the configuration dictionary for timeplus_connect client.
+
+        Returns:
+            dict: Configuration ready to be passed to timeplus_connect.get_client()
+        """
+        config = {
+            "host": self.host,
+            "port": self.port,
+            "username": self.username,
+            "password": self.password,
+            "secure": self.secure,
+            "verify": self.verify,
+            "connect_timeout": self.connect_timeout,
+            "send_receive_timeout": self.send_receive_timeout,
+        }
+
+        # Add optional database if set
+        if self.database:
+            config["database"] = self.database
+
+        return config
+
+    def _validate_required_vars(self) -> None:
+        """Validate that all required environment variables are set.
+
+        Raises:
+            ValueError: If any required environment variable is missing.
+        """
+        missing_vars = []
+
+        if missing_vars:
+            raise ValueError(
+                f"Missing required environment variables: {', '.join(missing_vars)}"
+            )
+
+
+# Global instance for easy access
+config = TimeplusConfig()

mcp_timeplus/mcp_server.py

@@ -1,12 +1,12 @@
 import logging
-import os
 from typing import Sequence
 
 import timeplus_connect
 from dotenv import load_dotenv
 from fastmcp import FastMCP
 
 MCP_SERVER_NAME = "mcp-timeplus"
+from mcp_timeplus.mcp_env import config
 
 # Configure logging
 logging.basicConfig(
@@ -102,13 +102,20 @@ def run_select_query(query: str):
 
 
 def create_timeplus_client():
-    host = os.getenv("TIMEPLUS_HOST")
-    port = os.getenv("TIMEPLUS_PORT")
-    username = os.getenv("TIMEPLUS_USER")
-    logger.info(f"Creating Timeplus client connection to {host}:{port} as {username}")
-    return timeplus_connect.get_client(
-        host=host,
-        port=port,
-        username=username,
-        password=os.getenv("TIMEPLUS_PASSWORD"),
-    )
+    client_config = config.get_client_config()
+    logger.info(
+        f"Creating Timeplus client connection to {client_config['host']}:{client_config['port']} "
+        f"as {client_config['username']} "
+        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)")
+
+    try:
+        client = timeplus_connect.get_client(**client_config)
+        # Test the connection
+        version = client.server_version
+        logger.info(f"Successfully connected to Timeplus server version {version}")
+        return client
+    except Exception as e:
+        logger.error(f"Failed to connect to Timeplus: {str(e)}")
+        raise

tests/test_tool.py

@@ -2,27 +2,26 @@
 
 from dotenv import load_dotenv
 
-from mcp_clickhouse import create_clickhouse_client, list_databases, list_tables, run_select_query
+from mcp_timeplus import create_timeplus_client, list_databases, list_tables, run_select_query
 
 load_dotenv()
 
 
-class TestClickhouseTools(unittest.TestCase):
+class TestTimeplusTools(unittest.TestCase):
     @classmethod
     def setUpClass(cls):
         """Set up the environment before tests."""
-        cls.client = create_clickhouse_client()
+        cls.client = create_timeplus_client()
 
         # Prepare test database and table
-        cls.test_db = "test_tool_db"
+        cls.test_db = "default"
         cls.test_table = "test_table"
         cls.client.command(f"CREATE DATABASE IF NOT EXISTS {cls.test_db}")
         cls.client.command(f"""
-            CREATE TABLE IF NOT EXISTS {cls.test_db}.{cls.test_table} (
-                id UInt32,
-                name String
-            ) ENGINE = MergeTree()
-            ORDER BY id
+            CREATE STREAM IF NOT EXISTS {cls.test_db}.{cls.test_table} (
+                id uint32,
+                name string
+            )
         """)
         cls.client.command(f"""
             INSERT INTO {cls.test_db}.{cls.test_table} (id, name) VALUES (1, 'Alice'), (2, 'Bob')