mcp-dbutils 0.9.0__tar.gz → 0.10.0__tar.gz

{mcp_dbutils-0.9.0 → mcp_dbutils-0.10.0}/CHANGELOG.md

@@ -1,6 +1,31 @@
 # CHANGELOG
 
 
+## v0.10.0 (2025-03-12)
+
+### Features
+
+- Enhance database configuration with SSL support
+  ([#22](https://github.com/donghao1393/mcp-dbutils/pull/22),
+  [`4ea4d0b`](https://github.com/donghao1393/mcp-dbutils/commit/4ea4d0b5deb51b8e9202839bd7a8cd5f71463c88))
+
+* feat: enhance database configuration with SSL support
+
+- Replace jdbc_url with url for better clarity - Add dedicated SSL configuration support - Update
+  documentation and examples - Update test cases
+
+BREAKING CHANGE: Remove jdbc_url support as it was just added and not yet in production use
+
+* docs: update documentation for SSL support and URL configuration
+
+- Add SSL configuration examples - Update configuration format examples - Add configuration
+  documentation in both English and Chinese - Remove JDBC related content
+
+### Breaking Changes
+
+- Remove jdbc_url support as it was just added and not yet in production use
+
+
 ## v0.9.0 (2025-03-09)
 
 ### Documentation

mcp_dbutils-0.10.0/PKG-INFO

@@ -0,0 +1,227 @@
+Metadata-Version: 2.4
+Name: mcp-dbutils
+Version: 0.10.0
+Summary: MCP Database Utilities Service
+Author: Dong Hao
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.10
+Requires-Dist: mcp>=1.2.1
+Requires-Dist: psycopg2-binary>=2.9.10
+Requires-Dist: python-dotenv>=1.0.1
+Requires-Dist: pyyaml>=6.0.2
+Provides-Extra: test
+Requires-Dist: aiosqlite>=0.19.0; extra == 'test'
+Requires-Dist: docker>=7.0.0; extra == 'test'
+Requires-Dist: pytest-asyncio>=0.23.0; extra == 'test'
+Requires-Dist: pytest-cov>=4.1.0; extra == 'test'
+Requires-Dist: pytest-docker>=2.0.0; extra == 'test'
+Requires-Dist: pytest>=7.0.0; extra == 'test'
+Requires-Dist: testcontainers>=3.7.0; extra == 'test'
+Description-Content-Type: text/markdown
+
+# MCP Database Utilities
+
+![GitHub Repo stars](https://img.shields.io/github/stars/donghao1393/mcp-dbutils)
+![PyPI version](https://img.shields.io/pypi/v/mcp-dbutils)
+[![Coverage](https://img.shields.io/endpoint?url=https://gist.githubusercontent.com/donghao1393/bdd0a63ec2a816539ff8c136ceb41e48/raw/coverage.json)](https://github.com/donghao1393/mcp-dbutils/actions)
+![Python](https://img.shields.io/badge/Python-3.10%2B-blue)
+![License](https://img.shields.io/github/license/donghao1393/mcp-dbutils)
+[![smithery badge](https://smithery.ai/badge/@donghao1393/mcp-dbutils)](https://smithery.ai/server/@donghao1393/mcp-dbutils)
+
+[中文文档](README_CN.md)
+
+## Overview
+MCP Database Utilities is a unified database access service that supports multiple database types (PostgreSQL and SQLite). Through its abstraction layer design, it provides a simple and unified database operation interface for MCP servers.
+
+## Features
+- Unified database access interface
+- Support for multiple database configurations
+- Secure read-only query execution
+- Table structure and schema information retrieval
+- Database tables listing via MCP tools
+- Intelligent connection management and resource cleanup
+- Debug mode support
+- SSL/TLS connection support for PostgreSQL
+
+## Installation and Configuration
+
+### Installation Methods
+#### Installing via Smithery
+
+To install Database Utilities for Claude Desktop automatically via [Smithery](https://smithery.ai/server/@donghao1393/mcp-dbutils):
+
+```bash
+npx -y @smithery/cli install @donghao1393/mcp-dbutils --client claude
+```
+
+#### Using uvx (Recommended)
+No installation required, run directly using `uvx`:
+```bash
+uvx mcp-dbutils --config /path/to/config.yaml
+```
+
+Add to Claude configuration:
+```json
+"mcpServers": {
+  "mcp-dbutils": {
+    "command": "uvx",
+    "args": [
+      "mcp-dbutils",
+      "--config",
+      "/path/to/config.yaml"
+    ],
+    "env": {
+      "MCP_DEBUG": "1"  // Optional: Enable debug mode
+    }
+  }
+}
+```
+
+#### Using pip
+```bash
+pip install mcp-dbutils
+```
+
+Add to Claude configuration:
+```json
+"mcpServers": {
+  "mcp-dbutils": {
+    "command": "python",
+    "args": [
+      "-m",
+      "mcp_dbutils",
+      "--config",
+      "/path/to/config.yaml"
+    ],
+    "env": {
+      "MCP_DEBUG": "1"  // Optional: Enable debug mode
+    }
+  }
+}
+```
+
+#### Using Docker
+```bash
+docker run -i --rm \
+  -v /path/to/config.yaml:/app/config.yaml \
+  -v /path/to/sqlite.db:/app/sqlite.db \  # Optional: for SQLite database
+  -e MCP_DEBUG=1 \  # Optional: Enable debug mode
+  mcp/dbutils --config /app/config.yaml
+```
+
+Add to Claude configuration:
+```json
+"mcpServers": {
+  "mcp-dbutils": {
+    "command": "docker",
+    "args": [
+      "run",
+      "-i",
+      "--rm",
+      "-v",
+      "/path/to/config.yaml:/app/config.yaml",
+      "-v",
+      "/path/to/sqlite.db:/app/sqlite.db",  // Optional: for SQLite database
+      "mcp/dbutils",
+      "--config",
+      "/app/config.yaml"
+    ],
+    "env": {
+      "MCP_DEBUG": "1"  // Optional: Enable debug mode
+    }
+  }
+}
+```
+
+> **Note for Docker database connections:**
+> - For SQLite: Mount your database file using `-v /path/to/sqlite.db:/app/sqlite.db`
+> - For PostgreSQL running on host:
+>   - On Mac/Windows: Use `host.docker.internal` as host in config
+>   - On Linux: Use `172.17.0.1` (docker0 IP) or run with `--network="host"`
+
+### Requirements
+- Python 3.10+
+- PostgreSQL (optional)
+- SQLite3 (optional)
+
+### Configuration File
+The project requires a YAML configuration file, specified via the `--config` parameter. Configuration examples:
+
+```yaml
+connections:
+  # SQLite configuration examples
+  dev-db:
+    type: sqlite
+    path: /path/to/dev.db
+    # Password is optional
+    password: 
+
+  # PostgreSQL standard configuration
+  test-db:
+    type: postgres
+    host: postgres.example.com
+    port: 5432
+    dbname: test_db
+    user: test_user
+    password: test_pass
+
+  # PostgreSQL URL configuration with SSL
+  prod-db:
+    type: postgres
+    url: postgresql://postgres.example.com:5432/prod-db?sslmode=verify-full
+    user: prod_user
+    password: prod_pass
+    
+  # PostgreSQL full SSL configuration example
+  secure-db:
+    type: postgres
+    host: secure-db.example.com
+    port: 5432
+    dbname: secure_db
+    user: secure_user
+    password: secure_pass
+    ssl:
+      mode: verify-full  # disable/require/verify-ca/verify-full
+      cert: /path/to/client-cert.pem
+      key: /path/to/client-key.pem
+      root: /path/to/root.crt
+```
+
+PostgreSQL SSL Configuration Options:
+1. Using URL parameters:
+   ```
+   postgresql://host:port/dbname?sslmode=verify-full&sslcert=/path/to/cert.pem
+   ```
+2. Using dedicated SSL configuration section:
+   ```yaml
+   ssl:
+     mode: verify-full  # SSL verification mode
+     cert: /path/to/cert.pem      # Client certificate
+     key: /path/to/key.pem        # Client private key
+     root: /path/to/root.crt      # CA certificate
+   ```
+
+SSL Modes:
+- disable: No SSL
+- require: Use SSL but no certificate verification
+- verify-ca: Verify server certificate is signed by trusted CA
+- verify-full: Verify server certificate and hostname match
+
+SQLite Configuration Options:
+1. Basic configuration with path:
+   ```yaml
+   type: sqlite
+   path: /path/to/db.sqlite
+   password: optional_password  # Optional encryption
+   ```
+2. Using URI parameters:
+   ```yaml
+   type: sqlite
+   path: /path/to/db.sqlite?mode=ro&cache=shared
+   ```
+
+### Debug Mode
+Set environment variable `MCP_DEBUG=1` to enable debug mode for detailed logging output.
+
+[Rest of the README content remains unchanged...]

mcp_dbutils-0.10.0/README.md

@@ -0,0 +1,205 @@
+# MCP Database Utilities
+
+![GitHub Repo stars](https://img.shields.io/github/stars/donghao1393/mcp-dbutils)
+![PyPI version](https://img.shields.io/pypi/v/mcp-dbutils)
+[![Coverage](https://img.shields.io/endpoint?url=https://gist.githubusercontent.com/donghao1393/bdd0a63ec2a816539ff8c136ceb41e48/raw/coverage.json)](https://github.com/donghao1393/mcp-dbutils/actions)
+![Python](https://img.shields.io/badge/Python-3.10%2B-blue)
+![License](https://img.shields.io/github/license/donghao1393/mcp-dbutils)
+[![smithery badge](https://smithery.ai/badge/@donghao1393/mcp-dbutils)](https://smithery.ai/server/@donghao1393/mcp-dbutils)
+
+[中文文档](README_CN.md)
+
+## Overview
+MCP Database Utilities is a unified database access service that supports multiple database types (PostgreSQL and SQLite). Through its abstraction layer design, it provides a simple and unified database operation interface for MCP servers.
+
+## Features
+- Unified database access interface
+- Support for multiple database configurations
+- Secure read-only query execution
+- Table structure and schema information retrieval
+- Database tables listing via MCP tools
+- Intelligent connection management and resource cleanup
+- Debug mode support
+- SSL/TLS connection support for PostgreSQL
+
+## Installation and Configuration
+
+### Installation Methods
+#### Installing via Smithery
+
+To install Database Utilities for Claude Desktop automatically via [Smithery](https://smithery.ai/server/@donghao1393/mcp-dbutils):
+
+```bash
+npx -y @smithery/cli install @donghao1393/mcp-dbutils --client claude
+```
+
+#### Using uvx (Recommended)
+No installation required, run directly using `uvx`:
+```bash
+uvx mcp-dbutils --config /path/to/config.yaml
+```
+
+Add to Claude configuration:
+```json
+"mcpServers": {
+  "mcp-dbutils": {
+    "command": "uvx",
+    "args": [
+      "mcp-dbutils",
+      "--config",
+      "/path/to/config.yaml"
+    ],
+    "env": {
+      "MCP_DEBUG": "1"  // Optional: Enable debug mode
+    }
+  }
+}
+```
+
+#### Using pip
+```bash
+pip install mcp-dbutils
+```
+
+Add to Claude configuration:
+```json
+"mcpServers": {
+  "mcp-dbutils": {
+    "command": "python",
+    "args": [
+      "-m",
+      "mcp_dbutils",
+      "--config",
+      "/path/to/config.yaml"
+    ],
+    "env": {
+      "MCP_DEBUG": "1"  // Optional: Enable debug mode
+    }
+  }
+}
+```
+
+#### Using Docker
+```bash
+docker run -i --rm \
+  -v /path/to/config.yaml:/app/config.yaml \
+  -v /path/to/sqlite.db:/app/sqlite.db \  # Optional: for SQLite database
+  -e MCP_DEBUG=1 \  # Optional: Enable debug mode
+  mcp/dbutils --config /app/config.yaml
+```
+
+Add to Claude configuration:
+```json
+"mcpServers": {
+  "mcp-dbutils": {
+    "command": "docker",
+    "args": [
+      "run",
+      "-i",
+      "--rm",
+      "-v",
+      "/path/to/config.yaml:/app/config.yaml",
+      "-v",
+      "/path/to/sqlite.db:/app/sqlite.db",  // Optional: for SQLite database
+      "mcp/dbutils",
+      "--config",
+      "/app/config.yaml"
+    ],
+    "env": {
+      "MCP_DEBUG": "1"  // Optional: Enable debug mode
+    }
+  }
+}
+```
+
+> **Note for Docker database connections:**
+> - For SQLite: Mount your database file using `-v /path/to/sqlite.db:/app/sqlite.db`
+> - For PostgreSQL running on host:
+>   - On Mac/Windows: Use `host.docker.internal` as host in config
+>   - On Linux: Use `172.17.0.1` (docker0 IP) or run with `--network="host"`
+
+### Requirements
+- Python 3.10+
+- PostgreSQL (optional)
+- SQLite3 (optional)
+
+### Configuration File
+The project requires a YAML configuration file, specified via the `--config` parameter. Configuration examples:
+
+```yaml
+connections:
+  # SQLite configuration examples
+  dev-db:
+    type: sqlite
+    path: /path/to/dev.db
+    # Password is optional
+    password: 
+
+  # PostgreSQL standard configuration
+  test-db:
+    type: postgres
+    host: postgres.example.com
+    port: 5432
+    dbname: test_db
+    user: test_user
+    password: test_pass
+
+  # PostgreSQL URL configuration with SSL
+  prod-db:
+    type: postgres
+    url: postgresql://postgres.example.com:5432/prod-db?sslmode=verify-full
+    user: prod_user
+    password: prod_pass
+    
+  # PostgreSQL full SSL configuration example
+  secure-db:
+    type: postgres
+    host: secure-db.example.com
+    port: 5432
+    dbname: secure_db
+    user: secure_user
+    password: secure_pass
+    ssl:
+      mode: verify-full  # disable/require/verify-ca/verify-full
+      cert: /path/to/client-cert.pem
+      key: /path/to/client-key.pem
+      root: /path/to/root.crt
+```
+
+PostgreSQL SSL Configuration Options:
+1. Using URL parameters:
+   ```
+   postgresql://host:port/dbname?sslmode=verify-full&sslcert=/path/to/cert.pem
+   ```
+2. Using dedicated SSL configuration section:
+   ```yaml
+   ssl:
+     mode: verify-full  # SSL verification mode
+     cert: /path/to/cert.pem      # Client certificate
+     key: /path/to/key.pem        # Client private key
+     root: /path/to/root.crt      # CA certificate
+   ```
+
+SSL Modes:
+- disable: No SSL
+- require: Use SSL but no certificate verification
+- verify-ca: Verify server certificate is signed by trusted CA
+- verify-full: Verify server certificate and hostname match
+
+SQLite Configuration Options:
+1. Basic configuration with path:
+   ```yaml
+   type: sqlite
+   path: /path/to/db.sqlite
+   password: optional_password  # Optional encryption
+   ```
+2. Using URI parameters:
+   ```yaml
+   type: sqlite
+   path: /path/to/db.sqlite?mode=ro&cache=shared
+   ```
+
+### Debug Mode
+Set environment variable `MCP_DEBUG=1` to enable debug mode for detailed logging output.
+
+[Rest of the README content remains unchanged...]

mcp_dbutils-0.10.0/README_CN.md

@@ -0,0 +1,189 @@
+# MCP 数据库服务
+
+## 项目简介
+MCP数据库服务是一个统一的数据库访问服务，支持多种数据库类型（PostgreSQL和SQLite）。它通过抽象层设计，为MCP服务器提供了简单、统一的数据库操作接口。
+
+## 功能特性
+- 统一的数据库访问接口
+- 支持多个数据库配置
+- 安全的只读查询执行
+- 表结构和模式信息查询
+- 通过MCP工具列出数据库表
+- 智能的连接管理和资源清理
+- 支持调试模式
+- PostgreSQL的SSL/TLS连接支持
+
+## 安装与配置
+
+### 安装方式
+
+#### 使用 uvx 安装（推荐）
+不需要专门安装，直接使用 `uvx` 运行：
+```bash
+uvx mcp-dbutils --config /path/to/config.yaml
+```
+
+添加到 Claude 配置：
+```json
+"mcpServers": {
+  "mcp-dbutils": {
+    "command": "uvx",
+    "args": [
+      "mcp-dbutils",
+      "--config",
+      "/path/to/config.yaml"
+    ],
+    "env": {
+      "MCP_DEBUG": "1"  // 可选：启用调试模式
+    }
+  }
+}
+```
+
+#### 使用 pip 安装
+```bash
+pip install mcp-dbutils
+```
+
+添加到 Claude 配置：
+```json
+"mcpServers": {
+  "mcp-dbutils": {
+    "command": "python",
+    "args": [
+      "-m",
+      "mcp_dbutils",
+      "--config",
+      "/path/to/config.yaml"
+    ],
+    "env": {
+      "MCP_DEBUG": "1"  // 可选：启用调试模式
+    }
+  }
+}
+```
+
+#### 使用 Docker 安装
+```bash
+docker run -i --rm \
+  -v /path/to/config.yaml:/app/config.yaml \
+  -v /path/to/sqlite.db:/app/sqlite.db \  # 可选：用于SQLite数据库
+  -e MCP_DEBUG=1 \  # 可选：启用调试模式
+  mcp/dbutils --config /app/config.yaml
+```
+
+添加到 Claude 配置：
+```json
+"mcpServers": {
+  "mcp-dbutils": {
+    "command": "docker",
+    "args": [
+      "run",
+      "-i",
+      "--rm",
+      "-v",
+      "/path/to/config.yaml:/app/config.yaml",
+      "-v",
+      "/path/to/sqlite.db:/app/sqlite.db",  // 可选：用于SQLite数据库
+      "mcp/dbutils",
+      "--config",
+      "/app/config.yaml"
+    ],
+    "env": {
+      "MCP_DEBUG": "1"  // 可选：启用调试模式
+    }
+  }
+}
+```
+
+> **Docker数据库连接说明：**
+> - SQLite数据库：使用 `-v /path/to/sqlite.db:/app/sqlite.db` 映射数据库文件
+> - 主机上运行的PostgreSQL：
+>   - Mac/Windows：配置中使用 `host.docker.internal`
+>   - Linux：使用 `172.17.0.1`（docker0网络IP）或使用 `--network="host"` 运行
+
+### 环境要求
+- Python 3.10+
+- PostgreSQL (可选)
+- SQLite3 (可选)
+
+### 配置文件
+项目运行需要一个YAML格式的配置文件，通过 `--config` 参数指定路径。配置示例：
+
+```yaml
+connections:
+  # SQLite配置示例
+  dev-db:
+    type: sqlite
+    path: /path/to/dev.db
+    # 密码是可选的
+    password: 
+
+  # PostgreSQL标准配置
+  test-db:
+    type: postgres
+    host: postgres.example.com
+    port: 5432
+    dbname: test_db
+    user: test_user
+    password: test_pass
+
+  # PostgreSQL URL配置（带SSL）
+  prod-db:
+    type: postgres
+    url: postgresql://postgres.example.com:5432/prod-db?sslmode=verify-full
+    user: prod_user
+    password: prod_pass
+    
+  # PostgreSQL完整SSL配置示例
+  secure-db:
+    type: postgres
+    host: secure-db.example.com
+    port: 5432
+    dbname: secure_db
+    user: secure_user
+    password: secure_pass
+    ssl:
+      mode: verify-full  # disable/require/verify-ca/verify-full
+      cert: /path/to/client-cert.pem
+      key: /path/to/client-key.pem
+      root: /path/to/root.crt
+```
+
+PostgreSQL SSL配置选项：
+1. 使用URL参数：
+   ```
+   postgresql://host:port/dbname?sslmode=verify-full&sslcert=/path/to/cert.pem
+   ```
+2. 使用专门的SSL配置部分：
+   ```yaml
+   ssl:
+     mode: verify-full  # SSL验证模式
+     cert: /path/to/cert.pem      # 客户端证书
+     key: /path/to/key.pem        # 客户端私钥
+     root: /path/to/root.crt      # CA证书
+   ```
+
+SSL模式：
+- disable: 不使用SSL
+- require: 使用SSL但不验证证书
+- verify-ca: 验证服务器证书是由受信任的CA签名
+- verify-full: 验证服务器证书和主机名匹配
+
+SQLite配置选项：
+1. 基本路径配置：
+   ```yaml
+   type: sqlite
+   path: /path/to/db.sqlite
+   password: optional_password  # 可选的加密密码
+   ```
+2. 使用URI参数：
+   ```yaml
+   type: sqlite
+   path: /path/to/db.sqlite?mode=ro&cache=shared
+   ```
+
+### 调试模式
+设置环境变量 `MCP_DEBUG=1` 启用调试模式，可以看到详细的日志输出。
+
+[剩余的README内容保持不变...]

mcp_dbutils-0.10.0/config.yaml.example

@@ -0,0 +1,44 @@
+connections:
+  # SQLite configuration examples
+  dev-db:
+    type: sqlite
+    path: /path/to/dev.db
+    # Password is optional
+    password: 
+
+  prod-sqlite:
+    type: sqlite
+    path: /path/to/prod.db
+    password: optional_password    # Optional
+
+  # PostgreSQL configuration examples
+  # Standard configuration
+  test-db:
+    type: postgres
+    host: postgres.example.com
+    port: 5432
+    dbname: test_db
+    user: test_user
+    password: test_pass
+
+  # URL configuration
+  # Use postgresql://host:port/dbname?sslmode=verify-full&sslcert=/path/to/cert.pem
+  prod-db:
+    type: postgres
+    url: postgresql://postgres.example.com:5432/prod-db?sslmode=verify-full
+    user: prod_user
+    password: prod_pass
+    
+  # Full SSL configuration example
+  secure-db:
+    type: postgres
+    host: secure-db.example.com
+    port: 5432
+    dbname: secure_db
+    user: secure_user
+    password: secure_pass
+    ssl:
+      mode: verify-full
+      cert: /path/to/client-cert.pem
+      key: /path/to/client-key.pem
+      root: /path/to/ca.crt

{mcp_dbutils-0.9.0 → mcp_dbutils-0.10.0}/pyproject.toml

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