mcp-dbutils 0.4.0__tar.gz → 0.5.0__tar.gz

{mcp_dbutils-0.4.0 → mcp_dbutils-0.5.0}/CHANGELOG.md

@@ -1,6 +1,30 @@
 # CHANGELOG
 
 
+## v0.5.0 (2025-03-02)
+
+### Documentation
+
+- Add JDBC URL configuration documentation
+  ([`a1b5f4b`](https://github.com/donghao1393/mcp-dbutils/commit/a1b5f4b424cec0df239bed65705aaac7c3e9072a))
+
+- Add JDBC URL configuration examples to English and Chinese docs - Document secure credential
+  handling approach - Update configuration format descriptions
+
+Part of feature #2
+
+### Features
+
+- **config**: Add JDBC URL support for SQLite
+  ([#5](https://github.com/donghao1393/mcp-dbutils/pull/5),
+  [`9feb1e8`](https://github.com/donghao1393/mcp-dbutils/commit/9feb1e8c7e38a8e4e3c0f63c81a72f4a4edd05b5))
+
+- Add JDBC URL parsing for SQLite configuration - Support SQLite specific URL format and parameters
+  - Keep credentials separate from URL - Complete test coverage for new functionality
+
+Part of #4
+
+
 ## v0.4.0 (2025-03-01)
 
 ### Features

{mcp_dbutils-0.4.0 → mcp_dbutils-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mcp-dbutils
-Version: 0.4.0
+Version: 0.5.0
 Summary: MCP Database Utilities Service
 Author: Dong Hao
 License-Expression: MIT
@@ -148,7 +148,7 @@ The project requires a YAML configuration file, specified via the `--config` par
 
 ```yaml
 databases:
-  # PostgreSQL example (when using Docker)
+  # Standard PostgreSQL configuration example
   my_postgres:
     type: postgres
     dbname: test_db
@@ -158,6 +158,13 @@ databases:
     # host: 172.17.0.1         # For Linux (docker0 IP)
     port: 5432
 
+  # PostgreSQL with JDBC URL example
+  my_postgres_jdbc:
+    type: postgres
+    jdbc_url: jdbc:postgresql://host.docker.internal:5432/test_db
+    user: postgres            # Credentials must be provided separately
+    password: secret          # Not included in JDBC URL for security
+
   # SQLite example (when using Docker)
   my_sqlite:
     type: sqlite
@@ -165,6 +172,10 @@ databases:
     password: optional_password # optional
 ```
 
+The configuration supports two formats for PostgreSQL:
+1. Standard configuration with individual parameters
+2. JDBC URL configuration with separate credentials (recommended for better compatibility)
+
 ### Debug Mode
 Set environment variable `MCP_DEBUG=1` to enable debug mode for detailed logging output.
 

{mcp_dbutils-0.4.0 → mcp_dbutils-0.5.0}/README.md

@@ -126,7 +126,7 @@ The project requires a YAML configuration file, specified via the `--config` par
 
 ```yaml
 databases:
-  # PostgreSQL example (when using Docker)
+  # Standard PostgreSQL configuration example
   my_postgres:
     type: postgres
     dbname: test_db
@@ -136,6 +136,13 @@ databases:
     # host: 172.17.0.1         # For Linux (docker0 IP)
     port: 5432
 
+  # PostgreSQL with JDBC URL example
+  my_postgres_jdbc:
+    type: postgres
+    jdbc_url: jdbc:postgresql://host.docker.internal:5432/test_db
+    user: postgres            # Credentials must be provided separately
+    password: secret          # Not included in JDBC URL for security
+
   # SQLite example (when using Docker)
   my_sqlite:
     type: sqlite
@@ -143,6 +150,10 @@ databases:
     password: optional_password # optional
 ```
 
+The configuration supports two formats for PostgreSQL:
+1. Standard configuration with individual parameters
+2. JDBC URL configuration with separate credentials (recommended for better compatibility)
+
 ### Debug Mode
 Set environment variable `MCP_DEBUG=1` to enable debug mode for detailed logging output.
 

{mcp_dbutils-0.4.0 → mcp_dbutils-0.5.0}/README_CN.md

@@ -110,7 +110,7 @@ docker run -i --rm \
 
 ```yaml
 databases:
-  # PostgreSQL配置示例（使用Docker）
+  # PostgreSQL标准配置示例
   my_postgres:
     type: postgres
     dbname: test_db
@@ -120,6 +120,13 @@ databases:
     # host: 172.17.0.1         # Linux系统使用（docker0网络IP）
     port: 5432
 
+  # PostgreSQL JDBC URL配置示例
+  my_postgres_jdbc:
+    type: postgres
+    jdbc_url: jdbc:postgresql://host.docker.internal:5432/test_db
+    user: postgres            # 认证信息必须单独提供
+    password: secret          # 出于安全考虑，不包含在JDBC URL中
+
   # SQLite配置示例（使用Docker）
   my_sqlite:
     type: sqlite
@@ -127,6 +134,10 @@ databases:
     password: optional_password # 可选
 ```
 
+PostgreSQL配置支持两种格式：
+1. 标准配置：使用独立的参数配置
+2. JDBC URL配置：使用JDBC URL并单独提供认证信息（推荐，兼容性更好）
+
 ### 调试模式
 设置环境变量 `MCP_DEBUG=1` 启用调试模式，可以看到详细的日志输出。
 

{mcp_dbutils-0.4.0 → mcp_dbutils-0.5.0}/config.yaml.example

@@ -1,10 +1,21 @@
 databases:
   # SQLite configuration examples
+  # SQLite with standard configuration
   dev-db:
     type: sqlite
     path: /path/to/dev.db
     password: 
 
+  # SQLite with JDBC URL configuration
+  # jdbc:sqlite: URL supports query parameters:
+  # - mode=ro: Read-only mode
+  # - cache=shared: Shared cache mode
+  # Note: Password must be provided separately
+  prod-sqlite:
+    type: sqlite
+    jdbc_url: jdbc:sqlite:/path/to/prod.db?mode=ro
+    password: optional_password    # Provided separately for security
+
   # PostgreSQL configuration examples
   # Standard configuration
   test-db:

{mcp_dbutils-0.4.0 → mcp_dbutils-0.5.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "mcp-dbutils"
-version = "0.4.0"
+version = "0.5.0"
 description = "MCP Database Utilities Service"
 readme = "README.md"
 license = "MIT"

mcp_dbutils-0.5.0/src/mcp_dbutils/sqlite/config.py

@@ -0,0 +1,150 @@
+"""SQLite configuration module"""
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Dict, Any, Optional, Literal
+from urllib.parse import urlparse, parse_qs
+from ..config import DatabaseConfig
+
+def parse_jdbc_url(jdbc_url: str) -> Dict[str, str]:
+    """Parse JDBC URL into connection parameters
+
+    Args:
+        jdbc_url: JDBC URL (e.g. jdbc:sqlite:file:/path/to/database.db or jdbc:sqlite:/path/to/database.db)
+
+    Returns:
+        Dictionary of connection parameters
+
+    Raises:
+        ValueError: If URL format is invalid
+    """
+    if not jdbc_url.startswith('jdbc:sqlite:'):
+        raise ValueError("Invalid SQLite JDBC URL format")
+
+    # Remove jdbc:sqlite: prefix
+    url = jdbc_url[12:]
+
+    # Handle file: prefix
+    if url.startswith('file:'):
+        url = url[5:]
+
+    # Parse URL
+    parsed = urlparse(url)
+    path = parsed.path
+
+    # Extract query parameters
+    params = {}
+    if parsed.query:
+        query_params = parse_qs(parsed.query)
+        for key, values in query_params.items():
+            params[key] = values[0]
+
+    if not path:
+        raise ValueError("Database path must be specified in URL")
+
+    return {
+        'path': path,
+        'parameters': params
+    }
+
+@dataclass
+class SqliteConfig(DatabaseConfig):
+    path: str
+    password: Optional[str] = None
+    uri: bool = True  # Enable URI mode to support parameters like password
+    type: Literal['sqlite'] = 'sqlite'
+
+    @classmethod
+    def from_jdbc_url(cls, jdbc_url: str, password: Optional[str] = None) -> 'SqliteConfig':
+        """Create configuration from JDBC URL
+
+        Args:
+            jdbc_url: JDBC URL (e.g. jdbc:sqlite:file:/path/to/database.db)
+            password: Optional password for database encryption
+
+        Returns:
+            SqliteConfig instance
+
+        Raises:
+            ValueError: If URL format is invalid
+        """
+        params = parse_jdbc_url(jdbc_url)
+
+        config = cls(
+            path=params['path'],
+            password=password,
+            uri=True
+        )
+        config.debug = cls.get_debug_mode()
+        return config
+
+    @property
+    def absolute_path(self) -> str:
+        """Return absolute path to database file"""
+        return str(Path(self.path).expanduser().resolve())
+
+    def get_connection_params(self) -> Dict[str, Any]:
+        """Get sqlite3 connection parameters"""
+        if not self.password:
+            return {'database': self.absolute_path, 'uri': self.uri}
+
+        # Use URI format if password is provided
+        uri = f"file:{self.absolute_path}?mode=rw"
+        if self.password:
+            uri += f"&password={self.password}"
+
+        return {
+            'database': uri,
+            'uri': True
+        }
+
+    def get_masked_connection_info(self) -> Dict[str, Any]:
+        """Return connection information for logging"""
+        info = {
+            'database': self.absolute_path,
+            'uri': self.uri
+        }
+        if self.password:
+            info['password'] = '******'
+        return info
+
+    @classmethod
+    def from_yaml(cls, yaml_path: str, db_name: str, **kwargs) -> 'SqliteConfig':
+        """Create SQLite configuration from YAML
+
+        Args:
+            yaml_path: Path to YAML configuration file
+            db_name: Database configuration name
+        """
+        configs = cls.load_yaml_config(yaml_path)
+
+        if db_name not in configs:
+            available_dbs = list(configs.keys())
+            raise ValueError(f"Database configuration not found: {db_name}. Available configurations: {available_dbs}")
+
+        db_config = configs[db_name]
+
+        if 'type' not in db_config:
+            raise ValueError("Database configuration must include 'type' field")
+        if db_config['type'] != 'sqlite':
+            raise ValueError(f"Configuration is not SQLite type: {db_config['type']}")
+
+        # Check if using JDBC URL configuration
+        if 'jdbc_url' in db_config:
+            params = parse_jdbc_url(db_config['jdbc_url'])
+            config = cls(
+                path=params['path'],
+                password=db_config.get('password'),
+                uri=True
+            )
+        else:
+            if 'path' not in db_config:
+                raise ValueError("SQLite configuration must include 'path' field")
+            config = cls(
+                path=db_config['path'],
+                password=db_config.get('password'),
+                uri=True
+            )
+
+        config.debug = cls.get_debug_mode()
+        return config

mcp_dbutils-0.5.0/tests/integration/test_sqlite_config.py

@@ -0,0 +1,109 @@
+"""Test SQLite configuration functionality"""
+import pytest
+import tempfile
+import yaml
+from pathlib import Path
+from mcp_dbutils.sqlite.config import SqliteConfig, parse_jdbc_url
+
+def test_parse_jdbc_url():
+    """Test JDBC URL parsing"""
+    # Test basic URL
+    url = "jdbc:sqlite:/path/to/test.db"
+    params = parse_jdbc_url(url)
+    assert params["path"] == "/path/to/test.db"
+    assert params["parameters"] == {}
+
+    # Test URL with file: prefix
+    url = "jdbc:sqlite:file:/path/to/test.db"
+    params = parse_jdbc_url(url)
+    assert params["path"] == "/path/to/test.db"
+    assert params["parameters"] == {}
+
+    # Test URL with parameters
+    url = "jdbc:sqlite:/path/to/test.db?mode=ro&cache=shared"
+    params = parse_jdbc_url(url)
+    assert params["path"] == "/path/to/test.db"
+    assert params["parameters"] == {"mode": "ro", "cache": "shared"}
+
+    # Test invalid format
+    with pytest.raises(ValueError, match="Invalid SQLite JDBC URL format"):
+        parse_jdbc_url("sqlite:/path/to/test.db")
+
+    # Test missing path
+    with pytest.raises(ValueError, match="Database path must be specified"):
+        parse_jdbc_url("jdbc:sqlite:")
+
+def test_from_jdbc_url():
+    """Test SqliteConfig creation from JDBC URL"""
+    url = "jdbc:sqlite:/path/to/test.db"
+    config = SqliteConfig.from_jdbc_url(url)
+    
+    assert str(Path(config.path)) == str(Path("/path/to/test.db"))
+    assert config.password is None
+    assert config.uri is True
+    assert config.type == "sqlite"
+
+    # Test with password
+    config = SqliteConfig.from_jdbc_url(url, password="test_pass")
+    assert config.password == "test_pass"
+    assert config.uri is True
+
+def test_from_yaml_with_jdbc_url(tmp_path):
+    """Test SqliteConfig creation from YAML with JDBC URL"""
+    config_data = {
+        "databases": {
+            "test_db": {
+                "type": "sqlite",
+                "jdbc_url": "jdbc:sqlite:/path/to/test.db",
+                "password": "test_pass"
+            }
+        }
+    }
+
+    config_file = tmp_path / "config.yaml"
+    with open(config_file, "w") as f:
+        yaml.dump(config_data, f)
+
+    config = SqliteConfig.from_yaml(str(config_file), "test_db")
+    assert str(Path(config.path)) == str(Path("/path/to/test.db"))
+    assert config.password == "test_pass"
+    assert config.uri is True
+    assert config.type == "sqlite"
+
+def test_required_fields_validation(tmp_path):
+    """Test validation of required configuration fields"""
+    # Missing type
+    config_data = {
+        "databases": {
+            "test_db": {
+                "jdbc_url": "jdbc:sqlite:/path/to/test.db"
+            }
+        }
+    }
+    
+    config_file = tmp_path / "config.yaml"
+    with open(config_file, "w") as f:
+        yaml.dump(config_data, f)
+
+    with pytest.raises(ValueError, match="missing required 'type' field"):
+        SqliteConfig.from_yaml(str(config_file), "test_db")
+
+    # Wrong type
+    config_data["databases"]["test_db"]["type"] = "postgres"
+    
+    with open(config_file, "w") as f:
+        yaml.dump(config_data, f)
+
+    with pytest.raises(ValueError, match="Configuration is not SQLite type"):
+        SqliteConfig.from_yaml(str(config_file), "test_db")
+
+    # Standard config (non-JDBC) missing path
+    config_data["databases"]["test_db"] = {
+        "type": "sqlite"
+    }
+    
+    with open(config_file, "w") as f:
+        yaml.dump(config_data, f)
+
+    with pytest.raises(ValueError, match="must include 'path' field"):
+        SqliteConfig.from_yaml(str(config_file), "test_db")

mcp_dbutils-0.4.0/src/mcp_dbutils/sqlite/config.py

@@ -1,74 +0,0 @@
-"""SQLite configuration module"""
-
-from dataclasses import dataclass
-from pathlib import Path
-from typing import Dict, Any, Optional, Literal
-from ..config import DatabaseConfig
-
-@dataclass
-class SqliteConfig(DatabaseConfig):
-    path: str
-    password: Optional[str] = None
-    uri: bool = True  # Enable URI mode to support parameters like password
-    type: Literal['sqlite'] = 'sqlite'
-
-    @property
-    def absolute_path(self) -> str:
-        """Return absolute path to database file"""
-        return str(Path(self.path).expanduser().resolve())
-
-    def get_connection_params(self) -> Dict[str, Any]:
-        """Get sqlite3 connection parameters"""
-        if not self.password:
-            return {'database': self.absolute_path, 'uri': self.uri}
-
-        # Use URI format if password is provided
-        uri = f"file:{self.absolute_path}?mode=rw"
-        if self.password:
-            uri += f"&password={self.password}"
-
-        return {
-            'database': uri,
-            'uri': True
-        }
-
-    def get_masked_connection_info(self) -> Dict[str, Any]:
-        """Return connection information for logging"""
-        info = {
-            'database': self.absolute_path,
-            'uri': self.uri
-        }
-        if self.password:
-            info['password'] = '******'
-        return info
-
-    @classmethod
-    def from_yaml(cls, yaml_path: str, db_name: str, **kwargs) -> 'SqliteConfig':
-        """Create SQLite configuration from YAML
-
-        Args:
-            yaml_path: Path to YAML configuration file
-            db_name: Database configuration name
-        """
-        configs = cls.load_yaml_config(yaml_path)
-
-        if db_name not in configs:
-            available_dbs = list(configs.keys())
-            raise ValueError(f"Database configuration not found: {db_name}. Available configurations: {available_dbs}")
-
-        db_config = configs[db_name]
-
-        if 'type' not in db_config:
-            raise ValueError("Database configuration must include 'type' field")
-        if db_config['type'] != 'sqlite':
-            raise ValueError(f"Configuration is not SQLite type: {db_config['type']}")
-        if 'path' not in db_config:
-            raise ValueError("SQLite configuration must include 'path' field")
-
-        config = cls(
-            path=db_config['path'],
-            password=db_config.get('password'),
-            uri=True
-        )
-        config.debug = cls.get_debug_mode()
-        return config