mcp-dbutils 0.2.3__tar.gz → 0.2.8__tar.gz

mcp_dbutils-0.2.8/.coveragerc

@@ -0,0 +1,17 @@
+[run]
+source = src/mcp_dbutils
+omit = 
+    tests/*
+    **/__init__.py
+
+[report]
+exclude_lines =
+    pragma: no cover
+    def __repr__
+    raise NotImplementedError
+    if __name__ == .__main__.:
+    pass
+    raise ImportError
+
+[html]
+directory = coverage_html

mcp_dbutils-0.2.8/.github/workflows/test.yml

@@ -0,0 +1,77 @@
+name: Tests
+
+on:
+  push:
+    branches: [ main ]
+  pull_request:
+    branches: [ main ]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+
+    services:
+      postgres:
+        image: postgres:15-alpine
+        env:
+          POSTGRES_PASSWORD: postgres
+        ports:
+          - 5432:5432
+        options: >-
+          --health-cmd pg_isready
+          --health-interval 10s
+          --health-timeout 5s
+          --health-retries 5
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+
+      - name: Set up Python
+        run: uv python install
+
+      - name: Create and activate venv
+        run: |
+          uv venv
+          . .venv/bin/activate
+
+      - name: Install dependencies
+        run: uv pip install -e ".[test]"
+
+      - name: Run tests with coverage
+        id: tests
+        run: |
+          uv run pytest \
+            -v \
+            --cov=src/mcp_dbutils \
+            --cov-report=html \
+            --cov-report=term-missing \
+            --cov-report=json:coverage.json \
+            tests/
+            
+      - name: Calculate coverage percentage
+        id: calc_coverage
+        run: |
+          COVERAGE=$(jq -r '.totals.percent_covered' coverage.json)
+          echo "Coverage: $COVERAGE"
+          echo "percentage=${COVERAGE%.*}" >> $GITHUB_OUTPUT
+          if (( $(echo "$COVERAGE >= 90" | bc -l) )); then
+            echo "color=green" >> $GITHUB_OUTPUT
+          elif (( $(echo "$COVERAGE >= 80" | bc -l) )); then
+            echo "color=yellow" >> $GITHUB_OUTPUT
+          else
+            echo "color=red" >> $GITHUB_OUTPUT
+          fi
+
+      - name: Create Coverage Badge
+        uses: schneegans/dynamic-badges-action@v1.7.0
+        with:
+          auth: ${{ secrets.GIST_SECRET }}
+          gistID: bdd0a63ec2a816539ff8c136ceb41e48
+          filename: coverage.json
+          label: "coverage"
+          message: "${{ steps.calc_coverage.outputs.percentage }}%"
+          color: "${{ steps.calc_coverage.outputs.color }}"
+          namedLogo: python

{mcp_dbutils-0.2.3 → mcp_dbutils-0.2.8}/.gitignore

@@ -6,6 +6,8 @@ __pycache__/
 *.so
 .Python
 build/
+.coverage
+coverage_html/
 develop-eggs/
 dist/
 downloads/
@@ -37,6 +39,7 @@ ENV/
 .vscode/
 *.swp
 *.swo
+memory-bank/
 
 # OS
 .DS_Store

mcp_dbutils-0.2.8/CHANGELOG.md

@@ -0,0 +1,158 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## [0.2.11] - 2025-02-15
+
+### Added
+- Added basic prompts support
+  - Implemented empty prompts/list handler
+  - Added prompts capability configuration
+  - Added integration tests for prompts
+
+## [0.2.10] - 2025-02-15
+
+### Added
+- Resource monitoring system
+  - Added ResourceStats for resource usage tracking
+  - Implemented connection lifecycle monitoring
+  - Added error pattern analysis
+  - Added memory usage estimation
+
+### Changed
+- Enhanced database handlers
+  - Improved error tracking and reporting
+  - Added resource cleanup logging
+  - Standardized monitoring output format
+  - Implemented template method pattern for queries
+
+### Fixed
+- Unified resource monitoring across all database types
+- Added proper cleanup for monitoring resources
+
+## [0.2.9] - 2025-02-15
+
+### Changed
+- Optimized database type handling
+  - Removed redundant type detection based on path/dbname
+  - Now using explicit 'type' field from configuration
+  - Added custom exception classes for better error handling
+  - Enhanced logging for handler lifecycle
+
+### Added
+- New exception hierarchy for better error handling
+  - DatabaseError as base exception
+  - ConfigurationError for configuration issues
+  - ConnectionError for connection problems
+- Improved debug logging
+  - Added handler creation logs
+  - Added cleanup operation logs
+  - Enhanced error messages with more context
+
+## [0.2.8] - 2025-02-15
+
+### Changed
+- Improved test configuration and stability
+  - Removed custom event_loop fixture in favor of pytest-asyncio's default
+  - Configured asyncio_mode to strict for better async test behavior
+  - Set asyncio_default_fixture_loop_scope to function level
+  - Fixed all pytest-asyncio deprecation warnings
+
+## [0.2.7] - 2025-02-15
+
+### Added
+- Added GitHub Actions workflow for automated testing
+- Added PostgreSQL service in CI environment
+- Added detailed test reporting with coverage in CI
+- Added coverage badge to README using dynamic-badges-action
+
+## [0.2.6] - 2025-02-12
+
+### Added
+- Added test coverage reporting with pytest-cov
+- Added coverage configuration and HTML report generation
+- Added test coverage tracking for all source code
+
+## [0.2.5] - 2025-02-12
+
+### Added
+- Comprehensive automated tests for both PostgreSQL and SQLite handlers
+- Integration tests for database operations
+- Unit tests for configuration
+- Test fixtures and Docker-based test environments
+
+## [0.2.4] - 2025-02-09
+
+### Changed
+- Unified server configuration name to "dbutils"
+- Improved documentation formatting and readability
+- Added architecture diagrams
+- Added contribution guidelines
+- Enhanced installation instructions with environment variables
+- Added acknowledgments section
+
+## [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.8/Dockerfile

@@ -0,0 +1,17 @@
+# Generated by https://smithery.ai. See: https://smithery.ai/docs/config#dockerfile
+# Use a base Python image
+FROM python:3.10-slim AS base
+
+# Set the working directory in the container
+WORKDIR /app
+
+# Copy the project file
+COPY pyproject.toml README.md src /app/
+
+# Install dependencies and the package
+RUN pip install hatchling && \
+    hatchling build && \
+    pip install dist/*.whl
+
+# Set the entry point to run the server
+ENTRYPOINT ["mcp-dbutils", "--config", "/app/config.yaml"]

mcp_dbutils-0.2.3/README.md → mcp_dbutils-0.2.8/PKG-INFO

@@ -1,9 +1,33 @@
+Metadata-Version: 2.4
+Name: mcp-dbutils
+Version: 0.2.8
+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)
-![Python versions](https://img.shields.io/pypi/pyversions/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)
 
@@ -21,6 +45,13 @@ MCP Database Utilities is a unified database access service that supports multip
 ## 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`:
@@ -31,9 +62,16 @@ uvx mcp-dbutils --config /path/to/config.yaml
 Add to Claude configuration:
 ```json
 "mcpServers": {
-  "database": {
+  "dbutils": {
     "command": "uvx",
-    "args": ["mcp-dbutils", "--config", "/path/to/config.yaml"]
+    "args": [
+      "mcp-dbutils",
+      "--config",
+      "/path/to/config.yaml"
+    ],
+    "env": {
+      "MCP_DEBUG": "1"  // Optional: Enable debug mode
+    }
   }
 }
 ```
@@ -46,9 +84,17 @@ pip install mcp-dbutils
 Add to Claude configuration:
 ```json
 "mcpServers": {
-  "database": {
+  "dbutils": {
     "command": "python",
-    "args": ["-m", "mcp_dbutils", "--config", "/path/to/config.yaml"]
+    "args": [
+      "-m",
+      "mcp_dbutils",
+      "--config",
+      "/path/to/config.yaml"
+    ],
+    "env": {
+      "MCP_DEBUG": "1"  // Optional: Enable debug mode
+    }
   }
 }
 ```
@@ -57,20 +103,41 @@ Add to Claude configuration:
 ```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": {
-  "database": {
+  "dbutils": {
     "command": "docker",
-    "args": ["run", "-i", "--rm", "-v", "/path/to/config.yaml:/app/config.yaml", 
-             "mcp/dbutils", "--config", "/app/config.yaml"]
+    "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)
@@ -81,20 +148,21 @@ The project requires a YAML configuration file, specified via the `--config` par
 
 ```yaml
 databases:
-  # PostgreSQL example
+  # PostgreSQL example (when using Docker)
   my_postgres:
     type: postgres
     dbname: test_db
     user: postgres
     password: secret
-    host: localhost
+    host: host.docker.internal  # For Mac/Windows
+    # host: 172.17.0.1         # For Linux (docker0 IP)
     port: 5432
 
-  # SQLite example
+  # SQLite example (when using Docker)
   my_sqlite:
     type: sqlite
-    path: /path/to/database.db
-    password: optional_password  # optional
+    path: /app/sqlite.db       # Mapped path inside container
+    password: optional_password # optional
 ```
 
 ### Debug Mode
@@ -103,6 +171,23 @@ Set environment variable `MCP_DEBUG=1` to enable debug mode for detailed logging
 ## Architecture Design
 
 ### Core Concept: Abstraction Layer
+
+```mermaid
+graph TD
+  Client[Client] --> DatabaseServer[Database Server]
+  subgraph MCP Server
+    DatabaseServer
+    DatabaseHandler[Database Handler]
+    PostgresHandler[PostgreSQL Handler]
+    SQLiteHandler[SQLite Handler]
+    DatabaseServer --> DatabaseHandler
+    DatabaseHandler --> PostgresHandler
+    DatabaseHandler --> SQLiteHandler
+  end
+  PostgresHandler --> PostgreSQL[(PostgreSQL)]
+  SQLiteHandler --> SQLite[(SQLite)]
+```
+
 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
@@ -202,3 +287,30 @@ Provides SQLite-specific features:
 - File path handling
 - URI scheme support
 - Password protection support (optional)
+
+## Contributing
+Contributions are welcome! Here's how you can help:
+
+1. 🐛 Report bugs: Open an issue describing the bug and how to reproduce it
+2. 💡 Suggest features: Open an issue to propose new features
+3. 🛠️ Submit PRs: Fork the repo and create a pull request with your changes
+
+### Development Setup
+1. Clone the repository
+2. Create a virtual environment using `uv venv`
+3. Install dependencies with `uv sync --all-extras`
+4. Run tests with `pytest`
+
+For detailed guidelines, see [CONTRIBUTING.md](.github/CONTRIBUTING.md)
+
+## Acknowledgments
+- [MCP Servers](https://github.com/modelcontextprotocol/servers) for inspiration and demonstration
+- AI Editors:
+  * [Claude Desktop](https://claude.ai/download)
+  * [5ire](https://5ire.app/)
+  * [Cline](https://cline.bot)
+- [Model Context Protocol](https://modelcontextprotocol.io/) for comprehensive interfaces
+
+## Star History
+
+[![Star History Chart](https://api.star-history.com/svg?repos=donghao1393/mcp-dbutils&type=Date)](https://star-history.com/#donghao1393/mcp-dbutils&Date)