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

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

@@ -1,12 +1,116 @@
 # 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
+
+- Update README files to include new tools
+  ([`eb796d5`](https://github.com/donghao1393/mcp-dbutils/commit/eb796d54ca517c173e26b8a535bfeb00545fbab0))
+
+Added documentation for new tools: - dbutils-get-stats - dbutils-list-constraints -
+  dbutils-explain-query
+
+Both English and Chinese READMEs updated
+
+- Update README files with new monitoring tools
+  ([#18](https://github.com/donghao1393/mcp-dbutils/pull/18),
+  [`4b919fe`](https://github.com/donghao1393/mcp-dbutils/commit/4b919fe348e2f6ed35ea1f16b64a2706a5d875f4))
+
+- Add dbutils-get-performance tool documentation - Add dbutils-analyze-query tool documentation -
+  Update both English and Chinese READMEs
+
+- Update tool names with dbutils prefix
+  ([`4731021`](https://github.com/donghao1393/mcp-dbutils/commit/4731021ab981ecca305414f34f72c1f8f0577b8e))
+
+Renamed basic tools in README files: - list_tables -> dbutils-list-tables - query -> dbutils-query
+
+Both English and Chinese READMEs updated
+
+### Features
+
+- Add advanced database tools ([#15](https://github.com/donghao1393/mcp-dbutils/pull/15),
+  [`2c85dc8`](https://github.com/donghao1393/mcp-dbutils/commit/2c85dc8c026bca93571ab8ed5b837518553087d5))
+
+* Added three new tools:
+
+1. dbutils-get-stats - Table statistics information - Column level statistics - Adapted for
+  PostgreSQL and SQLite
+
+2. dbutils-list-constraints - Primary key, foreign key, unique constraints - Constraint definitions
+  and properties - Constraint comments support
+
+3. dbutils-explain-query - EXPLAIN and EXPLAIN ANALYZE support - Detailed cost and timing estimates
+  - Database-specific optimizations
+
+Implementation: - Added abstract methods to DatabaseHandler - Implemented in PostgreSQL and SQLite -
+  Added dedicated integration tests - Fixed SQL syntax and parameter issues
+
+Refs #14
+
+* fix: check non-SELECT statements in SQLite handler
+
+- Add more database tools ([#13](https://github.com/donghao1393/mcp-dbutils/pull/13),
+  [`8b8bd1e`](https://github.com/donghao1393/mcp-dbutils/commit/8b8bd1ea04d63e7828c81dc25a9c0cb70df73867))
+
+* 添加更多数据库工具
+
+添加三个新的数据库工具： - dbutils-describe-table：获取表的详细信息 - dbutils-get-ddl：获取表的DDL语句 -
+  dbutils-list-indexes：获取表的索引信息
+
+实现内容： - DatabaseHandler新增三个抽象方法 - PostgreSQL和SQLite分别实现这些方法 - 添加新工具的集成测试 - 所有测试通过
+
+Fixes #12
+
+* test: 拆分表信息工具测试
+
+将test_table_info_tools拆分为三个独立的测试函数： - test_describe_table_tool - test_get_ddl_tool -
+  test_list_indexes_tool
+
+这样可以更清晰地展示每个工具的测试状态，便于定位问题。
+
+- Enhance monitoring system with LLM dialog support
+  ([#17](https://github.com/donghao1393/mcp-dbutils/pull/17),
+  [`50d8df1`](https://github.com/donghao1393/mcp-dbutils/commit/50d8df1fabbf6513718582e6efe0d3832de9ce5d))
+
+- Add query duration tracking - Add query type statistics - Add slow query detection - Add memory
+  usage tracking - Add performance statistics formatting - Add new MCP tools:
+  dbutils-get-performance and dbutils-analyze-query - Add tests for new features
+
+Closes #16
+
+
 ## v0.8.0 (2025-03-09)
 
 ### Features
 
 - Unify tool names with dbutils prefix ([#11](https://github.com/donghao1393/mcp-dbutils/pull/11),
-  [`30ebbc2`](https://github.com/donghao1393/mcp-dbutils/commit/30ebbc251be55f7d18fc9873021151b82c3f0fde))
+  [`aa57995`](https://github.com/donghao1393/mcp-dbutils/commit/aa57995dc6cf3ffd33909162d831dffbbbf19bfc))
 
 给工具名称添加dbutils前缀，使所有工具名称规范统一： - query -> dbutils-run-query - list_tables -> dbutils-list-tables
 

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...]