mcp-dbutils 0.2.3__tar.gz

mcp_dbutils-0.2.3/.github/workflows/publish.yml

@@ -0,0 +1,33 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  publish:
+    name: Build and Publish to PyPI
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write  # Required for trusted publishing
+
+    steps:
+      - uses: actions/checkout@v4
+      
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+        with:
+          enable-cache: false
+      
+      - name: Set up Python
+        run: uv python install
+      
+      - name: Install build dependencies
+        run: uv sync --all-extras
+      
+      - name: Build package
+        run: uv build
+      
+      - name: Publish to PyPI
+        run: uv publish

mcp_dbutils-0.2.3/.gitignore

@@ -0,0 +1,43 @@
+# Python
+docs/
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+uv.lock
+
+# Virtual Environment
+.env
+.venv
+env/
+venv/
+ENV/
+.python-version
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# OS
+.DS_Store
+Thumbs.db

mcp_dbutils-0.2.3/CHANGELOG.md

@@ -0,0 +1,69 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## [0.2.3] - 2025-02-09
+
+### Added
+- Added comprehensive installation guides for uvx, pip, and Docker
+- Added GitHub Actions workflow for automated PyPI releases
+- Added both English and Chinese documentation
+- Added project badges and repository information
+
+### Changed
+- Internationalized all code messages and docstrings
+- Updated Python version requirement to 3.10+
+- Improved documentation structure and examples
+- Unified project naming to mcp-dbutils across all references
+
+## [0.2.2] - 2025-02-09
+
+### Added
+- Added explicit database type declaration in configs
+- Improved database type awareness in query results
+- Standardized field naming across different database types
+
+### Changed
+- Unified response format for normal results and error messages
+- Enhanced error reporting with database-specific details
+
+## [0.2.1] - 2025-02-09
+
+### Added
+- SQLite database support with basic CRUD operations
+- Password protection for SQLite databases
+- Table schema inspection for SQLite
+- URI connection string support for SQLite
+
+### Fixed
+- Automatic database type detection from config
+- Connection handling improvements
+
+## [0.2.0] - 2025-02-09
+
+### Changed
+- Renamed project from mcp-postgres to mcp-dbutils
+- Restructured project for multi-database support
+- Added base classes for database handling
+- Improved configuration management
+- Enhanced error handling and logging
+
+## [0.1.1] - 2025-02-08
+
+### Added
+- Enhanced PostgreSQL error logging with error codes
+- Improved error details with pgcode and pgerror
+- Better error differentiation between PostgreSQL-specific and general errors
+
+### Changed
+- Maintained backwards compatibility while improving error flow
+
+## [0.1.0] - 2025-02-08
+
+### Added
+- Initial PostgreSQL implementation
+- YAML configuration for multiple databases
+- Connection pool management
+- Table structure querying
+- Read-only SQL query execution
+- Basic error handling and logging

mcp_dbutils-0.2.3/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Dong Hao
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

mcp_dbutils-0.2.3/PKG-INFO

@@ -0,0 +1,218 @@
+Metadata-Version: 2.4
+Name: mcp-dbutils
+Version: 0.2.3
+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
+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)
+![Python versions](https://img.shields.io/pypi/pyversions/mcp-dbutils)
+![License](https://img.shields.io/github/license/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
+- Intelligent connection management and resource cleanup
+- Debug mode support
+
+## Installation and Configuration
+
+### Installation Methods
+
+#### 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": {
+  "database": {
+    "command": "uvx",
+    "args": ["mcp-dbutils", "--config", "/path/to/config.yaml"]
+  }
+}
+```
+
+#### Using pip
+```bash
+pip install mcp-dbutils
+```
+
+Add to Claude configuration:
+```json
+"mcpServers": {
+  "database": {
+    "command": "python",
+    "args": ["-m", "mcp_dbutils", "--config", "/path/to/config.yaml"]
+  }
+}
+```
+
+#### Using Docker
+```bash
+docker run -i --rm \
+  -v /path/to/config.yaml:/app/config.yaml \
+  mcp/dbutils --config /app/config.yaml
+```
+
+Add to Claude configuration:
+```json
+"mcpServers": {
+  "database": {
+    "command": "docker",
+    "args": ["run", "-i", "--rm", "-v", "/path/to/config.yaml:/app/config.yaml", 
+             "mcp/dbutils", "--config", "/app/config.yaml"]
+  }
+}
+```
+
+### Requirements
+- Python 3.10+
+- PostgreSQL (optional)
+- SQLite3 (optional)
+
+### Configuration File
+The project requires a YAML configuration file, specified via the `--config` parameter. Configuration example:
+
+```yaml
+databases:
+  # PostgreSQL example
+  my_postgres:
+    type: postgres
+    dbname: test_db
+    user: postgres
+    password: secret
+    host: localhost
+    port: 5432
+
+  # SQLite example
+  my_sqlite:
+    type: sqlite
+    path: /path/to/database.db
+    password: optional_password  # optional
+```
+
+### Debug Mode
+Set environment variable `MCP_DEBUG=1` to enable debug mode for detailed logging output.
+
+## Architecture Design
+
+### Core Concept: Abstraction Layer
+The abstraction layer design is the core architectural concept in MCP Database Utilities. Just like a universal remote control that works with different devices, users only need to know the basic operations without understanding the underlying complexities.
+
+#### 1. Simplified User Interaction
+- Users only need to know the database configuration name (e.g., "my_postgres")
+- No need to deal with connection parameters and implementation details
+- MCP server automatically handles database connections and queries
+
+#### 2. Unified Interface Design
+- DatabaseHandler abstract class defines unified operation interfaces
+- All specific database implementations (PostgreSQL/SQLite) follow the same interface
+- Users interact with different databases in the same way
+
+#### 3. Configuration and Implementation Separation
+- Complex database configuration parameters are encapsulated in configuration files
+- Runtime access through simple database names
+- Easy management and modification of database configurations without affecting business code
+
+### System Components
+1. DatabaseServer
+   - Core component of the MCP server
+   - Handles resource and tool requests
+   - Manages database connection lifecycle
+
+2. DatabaseHandler
+   - Abstract base class defining unified interface
+   - Includes get_tables(), get_schema(), execute_query(), etc.
+   - Implemented by PostgreSQL and SQLite handlers
+
+3. Configuration System
+   - YAML-based configuration file
+   - Support for multiple database configurations
+   - Type-safe configuration validation
+
+4. Error Handling and Logging
+   - Unified error handling mechanism
+   - Detailed logging output
+   - Sensitive information masking
+
+## Usage Examples
+
+### Basic Query
+```python
+# Access through database name
+async with server.get_handler("my_postgres") as handler:
+    # Execute SQL query
+    result = await handler.execute_query("SELECT * FROM users")
+```
+
+### View Table Structure
+```python
+# Get all tables
+tables = await handler.get_tables()
+
+# Get specific table schema
+schema = await handler.get_schema("users")
+```
+
+### Error Handling
+```python
+try:
+    async with server.get_handler("my_db") as handler:
+        result = await handler.execute_query("SELECT * FROM users")
+except ValueError as e:
+    print(f"Configuration error: {e}")
+except Exception as e:
+    print(f"Query error: {e}")
+```
+
+## Security Notes
+- Supports SELECT queries only to protect database security
+- Automatically masks sensitive information (like passwords) in logs
+- Executes queries in read-only transactions
+
+## API Documentation
+
+### DatabaseServer
+Core server class providing:
+- Resource list retrieval
+- Tool call handling
+- Database handler management
+
+### DatabaseHandler
+Abstract base class defining interfaces:
+- get_tables(): Get table resource list
+- get_schema(): Get table structure
+- execute_query(): Execute SQL query
+- cleanup(): Resource cleanup
+
+### PostgreSQL Implementation
+Provides PostgreSQL-specific features:
+- Remote connection support
+- Table description information
+- Constraint queries
+
+### SQLite Implementation
+Provides SQLite-specific features:
+- File path handling
+- URI scheme support
+- Password protection support (optional)

mcp_dbutils-0.2.3/README.md

@@ -0,0 +1,204 @@
+# 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)
+![Python versions](https://img.shields.io/pypi/pyversions/mcp-dbutils)
+![License](https://img.shields.io/github/license/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
+- Intelligent connection management and resource cleanup
+- Debug mode support
+
+## Installation and Configuration
+
+### Installation Methods
+
+#### 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": {
+  "database": {
+    "command": "uvx",
+    "args": ["mcp-dbutils", "--config", "/path/to/config.yaml"]
+  }
+}
+```
+
+#### Using pip
+```bash
+pip install mcp-dbutils
+```
+
+Add to Claude configuration:
+```json
+"mcpServers": {
+  "database": {
+    "command": "python",
+    "args": ["-m", "mcp_dbutils", "--config", "/path/to/config.yaml"]
+  }
+}
+```
+
+#### Using Docker
+```bash
+docker run -i --rm \
+  -v /path/to/config.yaml:/app/config.yaml \
+  mcp/dbutils --config /app/config.yaml
+```
+
+Add to Claude configuration:
+```json
+"mcpServers": {
+  "database": {
+    "command": "docker",
+    "args": ["run", "-i", "--rm", "-v", "/path/to/config.yaml:/app/config.yaml", 
+             "mcp/dbutils", "--config", "/app/config.yaml"]
+  }
+}
+```
+
+### Requirements
+- Python 3.10+
+- PostgreSQL (optional)
+- SQLite3 (optional)
+
+### Configuration File
+The project requires a YAML configuration file, specified via the `--config` parameter. Configuration example:
+
+```yaml
+databases:
+  # PostgreSQL example
+  my_postgres:
+    type: postgres
+    dbname: test_db
+    user: postgres
+    password: secret
+    host: localhost
+    port: 5432
+
+  # SQLite example
+  my_sqlite:
+    type: sqlite
+    path: /path/to/database.db
+    password: optional_password  # optional
+```
+
+### Debug Mode
+Set environment variable `MCP_DEBUG=1` to enable debug mode for detailed logging output.
+
+## Architecture Design
+
+### Core Concept: Abstraction Layer
+The abstraction layer design is the core architectural concept in MCP Database Utilities. Just like a universal remote control that works with different devices, users only need to know the basic operations without understanding the underlying complexities.
+
+#### 1. Simplified User Interaction
+- Users only need to know the database configuration name (e.g., "my_postgres")
+- No need to deal with connection parameters and implementation details
+- MCP server automatically handles database connections and queries
+
+#### 2. Unified Interface Design
+- DatabaseHandler abstract class defines unified operation interfaces
+- All specific database implementations (PostgreSQL/SQLite) follow the same interface
+- Users interact with different databases in the same way
+
+#### 3. Configuration and Implementation Separation
+- Complex database configuration parameters are encapsulated in configuration files
+- Runtime access through simple database names
+- Easy management and modification of database configurations without affecting business code
+
+### System Components
+1. DatabaseServer
+   - Core component of the MCP server
+   - Handles resource and tool requests
+   - Manages database connection lifecycle
+
+2. DatabaseHandler
+   - Abstract base class defining unified interface
+   - Includes get_tables(), get_schema(), execute_query(), etc.
+   - Implemented by PostgreSQL and SQLite handlers
+
+3. Configuration System
+   - YAML-based configuration file
+   - Support for multiple database configurations
+   - Type-safe configuration validation
+
+4. Error Handling and Logging
+   - Unified error handling mechanism
+   - Detailed logging output
+   - Sensitive information masking
+
+## Usage Examples
+
+### Basic Query
+```python
+# Access through database name
+async with server.get_handler("my_postgres") as handler:
+    # Execute SQL query
+    result = await handler.execute_query("SELECT * FROM users")
+```
+
+### View Table Structure
+```python
+# Get all tables
+tables = await handler.get_tables()
+
+# Get specific table schema
+schema = await handler.get_schema("users")
+```
+
+### Error Handling
+```python
+try:
+    async with server.get_handler("my_db") as handler:
+        result = await handler.execute_query("SELECT * FROM users")
+except ValueError as e:
+    print(f"Configuration error: {e}")
+except Exception as e:
+    print(f"Query error: {e}")
+```
+
+## Security Notes
+- Supports SELECT queries only to protect database security
+- Automatically masks sensitive information (like passwords) in logs
+- Executes queries in read-only transactions
+
+## API Documentation
+
+### DatabaseServer
+Core server class providing:
+- Resource list retrieval
+- Tool call handling
+- Database handler management
+
+### DatabaseHandler
+Abstract base class defining interfaces:
+- get_tables(): Get table resource list
+- get_schema(): Get table structure
+- execute_query(): Execute SQL query
+- cleanup(): Resource cleanup
+
+### PostgreSQL Implementation
+Provides PostgreSQL-specific features:
+- Remote connection support
+- Table description information
+- Constraint queries
+
+### SQLite Implementation
+Provides SQLite-specific features:
+- File path handling
+- URI scheme support
+- Password protection support (optional)