mcp-dbutils 0.8.0__py3-none-any.whl → 0.10.0__py3-none-any.whl

mcp_dbutils/sqlite/server.py

@@ -7,15 +7,15 @@ from typing import Optional, List
 import mcp.types as types
 from importlib.metadata import metadata
 
-from ..base import DatabaseServer
+from ..base import ConnectionServer
 from ..log import create_logger
-from .config import SqliteConfig
+from .config import SQLiteConfig
 
 # 获取包信息用于日志命名
 pkg_meta = metadata("mcp-dbutils")
 
-class SqliteServer(DatabaseServer):
-    def __init__(self, config: SqliteConfig, config_path: Optional[str] = None):
+class SQLiteServer(ConnectionServer):
+    def __init__(self, config: SQLiteConfig, config_path: Optional[str] = None):
         """初始化 SQLite 服务器
 
         Args:
@@ -32,13 +32,13 @@ class SqliteServer(DatabaseServer):
 
         # 测试连接
         try:
-            self.log("debug", f"正在连接数据库: {self.config.get_masked_connection_info()}")
+            self.log("debug", f"正在连接: {self.config.get_masked_connection_info()}")
             connection_params = self.config.get_connection_params()
             with closing(sqlite3.connect(**connection_params)) as conn:
                 conn.row_factory = sqlite3.Row
-            self.log("info", "数据库连接测试成功")
+            self.log("info", "连接测试成功")
         except sqlite3.Error as e:
-            self.log("error", f"数据库连接失败: {str(e)}")
+            self.log("error", f"连接失败: {str(e)}")
             raise
 
     def _get_connection(self):
@@ -53,13 +53,13 @@ class SqliteServer(DatabaseServer):
         use_default = True
         conn = None
         try:
-            database = arguments.get("database")
-            if database and self.config_path:
-                # 使用指定的数据库配置
-                config = SqliteConfig.from_yaml(self.config_path, database)
+            connection = arguments.get("connection")
+            if connection and self.config_path:
+                # 使用指定的数据库连接
+                config = SQLiteConfig.from_yaml(self.config_path, connection)
                 connection_params = config.get_connection_params()
                 masked_params = config.get_masked_connection_info()
-                self.log("info", f"使用配置 {database} 连接数据库: {masked_params}")
+                self.log("info", f"使用配置 {connection} 连接: {masked_params}")
                 conn = sqlite3.connect(**connection_params)
                 conn.row_factory = sqlite3.Row
                 use_default = False
@@ -126,9 +126,9 @@ class SqliteServer(DatabaseServer):
                 inputSchema={
                     "type": "object",
                     "properties": {
-                        "database": {
+                        "connection": {
                             "type": "string",
-                            "description": "数据库配置名称（可选）"
+                            "description": "数据库连接名称（可选）"
                         },
                         "sql": {
                             "type": "string",
@@ -156,13 +156,13 @@ class SqliteServer(DatabaseServer):
         use_default = True
         conn = None
         try:
-            database = arguments.get("database")
-            if database and self.config_path:
-                # 使用指定的数据库配置
-                config = SqliteConfig.from_yaml(self.config_path, database)
+            connection = arguments.get("connection")
+            if connection and self.config_path:
+                # 使用指定的数据库连接
+                config = SQLiteConfig.from_yaml(self.config_path, connection)
                 connection_params = config.get_connection_params()
                 masked_params = config.get_masked_connection_info()
-                self.log("info", f"使用配置 {database} 连接数据库: {masked_params}")
+                self.log("info", f"使用配置 {connection} 连接: {masked_params}")
                 conn = sqlite3.connect(**connection_params)
                 conn.row_factory = sqlite3.Row
                 use_default = False
@@ -180,7 +180,7 @@ class SqliteServer(DatabaseServer):
 
                 result_text = str({
                     'type': 'sqlite',
-                    'config_name': database or 'default',
+                    'config_name': connection or 'default',
                     'query_result': {
                         'columns': columns,
                         'rows': formatted_results,
@@ -194,7 +194,7 @@ class SqliteServer(DatabaseServer):
         except sqlite3.Error as e:
             error_msg = str({
                 'type': 'sqlite',
-                'config_name': database or 'default',
+                'config_name': connection or 'default',
                 'error': f"查询执行失败: {str(e)}"
             })
             self.log("error", error_msg)

mcp_dbutils/stats.py

@@ -2,8 +2,9 @@
 
 from dataclasses import dataclass
 from datetime import datetime
-from typing import Optional
+from typing import Optional, List, Tuple
 import sys
+import statistics
 
 @dataclass
 class ResourceStats:
@@ -24,11 +25,23 @@ class ResourceStats:
 
     # Resource stats
     estimated_memory: int = 0
+    
+    # Performance monitoring
+    query_durations: List[float] = None  # 查询执行时间列表 (秒)
+    query_types: dict[str, int] = None   # 查询类型统计 (SELECT, EXPLAIN等)
+    slow_queries: List[Tuple[str, float]] = None  # 慢查询记录 (SQL, 时间)
+    peak_memory: int = 0  # 峰值内存使用
 
     def __post_init__(self):
         """Initialize mutable defaults"""
         if self.error_types is None:
             self.error_types = {}
+        if self.query_durations is None:
+            self.query_durations = []
+        if self.query_types is None:
+            self.query_types = {}
+        if self.slow_queries is None:
+            self.slow_queries = []
 
     def record_connection_start(self):
         """Record new connection start"""
@@ -45,6 +58,26 @@ class ResourceStats:
         self.query_count += 1
         self.last_query_time = datetime.now()
 
+    def record_query_duration(self, sql: str, duration: float):
+        """Record query execution time and type
+
+        Args:
+            sql: SQL query text
+            duration: Execution time in seconds
+        """
+        self.query_durations.append(duration)
+        
+        # Record query type
+        query_type = sql.strip().split()[0].upper()
+        self.query_types[query_type] = self.query_types.get(query_type, 0) + 1
+        
+        # Record slow queries (over 100ms)
+        if duration > 0.1:  # 100ms
+            # Keep at most 10 slow queries
+            if len(self.slow_queries) >= 10:
+                self.slow_queries.pop(0)
+            self.slow_queries.append((sql[:100], duration))  # Truncate SQL to avoid excessive length
+
     def record_error(self, error_type: str):
         """Record error occurrence
 
@@ -61,7 +94,73 @@ class ResourceStats:
         Args:
             obj: Object to estimate size for
         """
-        self.estimated_memory = sys.getsizeof(obj)
+        current_memory = sys.getsizeof(obj)
+        self.estimated_memory = current_memory
+        self.peak_memory = max(self.peak_memory, current_memory)
+
+    def get_query_time_stats(self) -> dict:
+        """Get query time statistics
+
+        Returns:
+            Dictionary with min, max, avg, median query times
+        """
+        if not self.query_durations:
+            return {
+                "min": 0,
+                "max": 0,
+                "avg": 0,
+                "median": 0
+            }
+        
+        return {
+            "min": min(self.query_durations),
+            "max": max(self.query_durations),
+            "avg": sum(self.query_durations) / len(self.query_durations),
+            "median": statistics.median(self.query_durations) if len(self.query_durations) > 0 else 0
+        }
+
+    def get_performance_stats(self) -> str:
+        """Get formatted performance statistics
+
+        Returns:
+            Formatted string with performance statistics
+        """
+        stats = []
+        stats.append(f"Database Performance Statistics")
+        stats.append(f"-----------------------------")
+        stats.append(f"Query Count: {self.query_count}")
+        
+        # Query time statistics
+        if self.query_durations:
+            time_stats = self.get_query_time_stats()
+            stats.append(f"Query Times: avg={time_stats['avg']*1000:.2f}ms, min={time_stats['min']*1000:.2f}ms, max={time_stats['max']*1000:.2f}ms, median={time_stats['median']*1000:.2f}ms")
+        
+        # Query type distribution
+        if self.query_types:
+            stats.append(f"Query Types:")
+            for qtype, count in self.query_types.items():
+                percentage = (count / self.query_count) * 100 if self.query_count else 0
+                stats.append(f"  - {qtype}: {count} ({percentage:.1f}%)")
+        
+        # Slow queries
+        if self.slow_queries:
+            stats.append(f"Slow Queries:")
+            for sql, duration in self.slow_queries:
+                stats.append(f"  - {duration*1000:.2f}ms: {sql}...")
+        
+        # Error statistics
+        if self.error_count > 0:
+            error_rate = (self.error_count / self.query_count) * 100 if self.query_count else 0
+            stats.append(f"Error Rate: {error_rate:.2f}% ({self.error_count} errors)")
+            stats.append(f"Error Types:")
+            for etype, count in self.error_types.items():
+                stats.append(f"  - {etype}: {count}")
+        
+        # Resource usage
+        stats.append(f"Memory Usage: current={self.estimated_memory/1024:.2f}KB, peak={self.peak_memory/1024:.2f}KB")
+        stats.append(f"Connections: active={self.active_connections}, total={self.total_connections}")
+        
+        return "\n".join(stats)
 
     def to_dict(self) -> dict:
         """Convert stats to dictionary for logging
@@ -74,12 +173,22 @@ class ResourceStats:
         if self.connection_start_time:
             connection_duration = (now - self.connection_start_time).total_seconds()
 
+        time_stats = self.get_query_time_stats()
+        
         return {
             "active_connections": self.active_connections,
             "total_connections": self.total_connections,
             "connection_duration": connection_duration,
             "query_count": self.query_count,
+            "query_times_ms": {
+                "min": time_stats["min"] * 1000 if self.query_durations else 0,
+                "max": time_stats["max"] * 1000 if self.query_durations else 0,
+                "avg": time_stats["avg"] * 1000 if self.query_durations else 0,
+                "median": time_stats["median"] * 1000 if self.query_durations else 0
+            },
+            "query_types": self.query_types,
             "error_count": self.error_count,
             "error_types": self.error_types,
-            "estimated_memory_bytes": self.estimated_memory
+            "estimated_memory_bytes": self.estimated_memory,
+            "peak_memory_bytes": self.peak_memory
         }

mcp_dbutils-0.10.0.dist-info/METADATA

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

@@ -0,0 +1,18 @@
+mcp_dbutils/__init__.py,sha256=9dqT2BdVvwforQVWOvJq2M0zCHxFamWIYWC4-6aY70k,1905
+mcp_dbutils/base.py,sha256=2fLSPL-BxdgKIOT_eq73wQGla6MZB03jUrWqBRSWVBQ,25474
+mcp_dbutils/config.py,sha256=uFI4Haw4en5gxHfCM9zugUqNCQFikdlHJZU_NTht7gQ,1905
+mcp_dbutils/log.py,sha256=fibVIwsb1HVU5zriGrDZTMEirKjgIuxuN_B_YTdAJ7I,996
+mcp_dbutils/stats.py,sha256=WYD9NAKHH2bFKmUSTOg18-SuIXergpznPq8AtIjtxdI,7101
+mcp_dbutils/postgres/__init__.py,sha256=XanCXw-kVE6ayqFqjuLJ9swWPcCVlcKZXB2Et2Wjl9w,154
+mcp_dbutils/postgres/config.py,sha256=FG0YUV4TtP1IGZT87ov_PK-ouOEjAOHdSaK42klk5OE,7750
+mcp_dbutils/postgres/handler.py,sha256=O45K0MOosNQ68SJ8piXXH3aZ74RVQ981hudk6faj28Y,24397
+mcp_dbutils/postgres/server.py,sha256=FROogvjr3xlKAZcAvJMNHGgyHqT_LaMK9-vYbA0Dbm0,8716
+mcp_dbutils/sqlite/__init__.py,sha256=lTUOkSfSWNw_BohJ_KNxYKMCANdtpGa3JK_ZyJsg_Ls,134
+mcp_dbutils/sqlite/config.py,sha256=2ekTp89rcCu4qQN1O3sZjIcOwjhzWi4tisD20T2WAik,4533
+mcp_dbutils/sqlite/handler.py,sha256=VxBVbwpNSQHyiudQXYFYpcdoScvbK2IGzYMbkcpvFcI,17731
+mcp_dbutils/sqlite/server.py,sha256=49ug43nyXZApclMXo0t5dKCN4wjDyDUZ-vmf746ac8M,7709
+mcp_dbutils-0.10.0.dist-info/METADATA,sha256=TC_KrWktHUIG6vznvxhIsz-pJG_WWxgH8s1HQJO7NgQ,6262
+mcp_dbutils-0.10.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+mcp_dbutils-0.10.0.dist-info/entry_points.txt,sha256=XTjt0QmYRgKOJQT6skR9bp1EMUfIrgpHeZJPZ3CJffs,49
+mcp_dbutils-0.10.0.dist-info/licenses/LICENSE,sha256=1A_CwpWVlbjrKdVEYO77vYfnXlW7oxcilZ8FpA_BzCI,1065
+mcp_dbutils-0.10.0.dist-info/RECORD,,