mcp-dbutils 0.2.3__py3-none-any.whl

mcp_dbutils-0.2.3.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,17 @@
+mcp_dbutils/__init__.py,sha256=_zVdjN2P_G5qEye7f5vQxiXAd6EwX2gyTL1wpFpqKck,1718
+mcp_dbutils/base.py,sha256=BQ6lEduhnR0pZnc-YY_OsO-w4XM06dzCJRU1uWnL-5M,6810
+mcp_dbutils/config.py,sha256=EwnPNuQVCBKd5WOXQfROyDTM-YpM_Odp0GhCPRg8YwE,1863
+mcp_dbutils/log.py,sha256=RJwWtHyZnJA2YRcyCK-WgnFadNuwtJeYKSxPbE-DCG0,991
+mcp_dbutils/postgres/__init__.py,sha256=Y6v_RsI79pqAfpKM3SrT1T1I9r5yWuKT0GUUNmHD3DE,146
+mcp_dbutils/postgres/config.py,sha256=ipjskdlv3u949R9rC2AKPCINRrtEAiKDjeogpFfM6aE,2401
+mcp_dbutils/postgres/handler.py,sha256=e-E03JST5t_YBgjRs3EmIEbKzym40WhGyScFerP3ueg,5811
+mcp_dbutils/postgres/server.py,sha256=3AdQyQfgrClkCmWOZ-xFXTeI9t3tpFkrY3qmyOR0b-U,8586
+mcp_dbutils/sqlite/__init__.py,sha256=QV4th2ywzUmCCa3GHCcBf8blJ_E8OYy0dJ2fSf1TfSU,134
+mcp_dbutils/sqlite/config.py,sha256=QK1JlY-ZBB5VyhydbiU-aAKNESTWMtyBfawbv2DAVCQ,2452
+mcp_dbutils/sqlite/handler.py,sha256=v2fFHxepNSUuK65UPo4fwyeBCDG6fit5IuLdBRIKUsY,4220
+mcp_dbutils/sqlite/server.py,sha256=Q29O2YOW4kqDGc3z1hMXVv4M0KSkuZbqvVDMgZE8Fd8,7593
+mcp_dbutils-0.2.3.dist-info/METADATA,sha256=TqDZw19V4rPsI5zS89McSFqHBSk73KOWTiaS3tE3dzw,6051
+mcp_dbutils-0.2.3.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+mcp_dbutils-0.2.3.dist-info/entry_points.txt,sha256=XTjt0QmYRgKOJQT6skR9bp1EMUfIrgpHeZJPZ3CJffs,49
+mcp_dbutils-0.2.3.dist-info/licenses/LICENSE,sha256=1A_CwpWVlbjrKdVEYO77vYfnXlW7oxcilZ8FpA_BzCI,1065
+mcp_dbutils-0.2.3.dist-info/RECORD,,

mcp_dbutils-0.2.3.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.27.0
+Root-Is-Purelib: true
+Tag: py3-none-any

mcp_dbutils-0.2.3.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+mcp-dbutils = mcp_dbutils:main

mcp_dbutils-0.2.3.dist-info/licenses/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.