mcp-dbutils 0.2.4__py3-none-any.whl → 0.2.8__py3-none-any.whl

mcp_dbutils/base.py

@@ -1,13 +1,27 @@
 """Database server base class"""
 
+class DatabaseError(Exception):
+    """Base exception for database errors"""
+    pass
+
+class ConfigurationError(DatabaseError):
+    """Configuration related errors"""
+    pass
+
+class ConnectionError(DatabaseError):
+    """Connection related errors"""
+    pass
+
 from abc import ABC, abstractmethod
 from typing import Any, List, Optional, AsyncContextManager
 from contextlib import asynccontextmanager
+import json
 import yaml
 from mcp.server import Server, NotificationOptions
 import mcp.server.stdio
 import mcp.types as types
 from .log import create_logger
+from .stats import ResourceStats
 
 class DatabaseHandler(ABC):
     """Abstract base class defining common interface for database handlers"""
@@ -24,6 +38,7 @@ class DatabaseHandler(ABC):
         self.database = database
         self.debug = debug
         self.log = create_logger(f"db-handler-{database}", debug)
+        self.stats = ResourceStats()
 
     @abstractmethod
     async def get_tables(self) -> list[types.Resource]:
@@ -36,9 +51,22 @@ class DatabaseHandler(ABC):
         pass
 
     @abstractmethod
+    async def _execute_query(self, sql: str) -> str:
+        """Internal query execution method to be implemented by subclasses"""
+        pass
+
     async def execute_query(self, sql: str) -> str:
         """Execute SQL query"""
-        pass
+        try:
+            self.stats.record_query()
+            result = await self._execute_query(sql)
+            self.stats.update_memory_usage(result)
+            self.log("info", f"Resource stats: {json.dumps(self.stats.to_dict())}")
+            return result
+        except Exception as e:
+            self.stats.record_error(e.__class__.__name__)
+            self.log("error", f"Query error - {str(e)}\nResource stats: {json.dumps(self.stats.to_dict())}")
+            raise
 
     @abstractmethod
     async def cleanup(self):
@@ -57,9 +85,18 @@ class DatabaseServer:
         """
         self.config_path = config_path
         self.debug = debug
-        self.log = create_logger("db-server", debug)
+        self.logger = create_logger("db-server", debug)
         self.server = Server("database-server")
         self._setup_handlers()
+        self._setup_prompts()
+
+    def _setup_prompts(self):
+        """Setup prompts handlers"""
+        async def handle_list_prompts() -> list[types.Prompt]:
+            """Return empty list of prompts for now"""
+            return []
+        
+        self.server.request_handlers["prompts/list"] = handle_list_prompts
 
     @asynccontextmanager
     async def get_handler(self, database: str) -> AsyncContextManager[DatabaseHandler]:
@@ -77,28 +114,42 @@ class DatabaseServer:
         with open(self.config_path, 'r') as f:
             config = yaml.safe_load(f)
             if not config or 'databases' not in config:
-                raise ValueError("Configuration file must contain 'databases' section")
+                raise ConfigurationError("Configuration file must contain 'databases' section")
             if database not in config['databases']:
                 available_dbs = list(config['databases'].keys())
-                raise ValueError(f"Database configuration not found: {database}. Available configurations: {available_dbs}")
+                raise ConfigurationError(f"Database configuration not found: {database}. Available configurations: {available_dbs}")
 
             db_config = config['databases'][database]
 
             handler = None
             try:
-                # Create appropriate handler based on configuration
-                if 'path' in db_config:
+                if 'type' not in db_config:
+                    raise ConfigurationError("Database configuration must include 'type' field")
+
+                db_type = db_config['type']
+                self.logger("debug", f"Creating handler for database type: {db_type}")
+                if db_type == 'sqlite':
                     from .sqlite.handler import SqliteHandler
                     handler = SqliteHandler(self.config_path, database, self.debug)
-                elif 'dbname' in db_config or 'host' in db_config:
+                elif db_type == 'postgres':
                     from .postgres.handler import PostgresHandler
                     handler = PostgresHandler(self.config_path, database, self.debug)
                 else:
-                    raise ValueError("Cannot determine database type, missing required parameters in configuration")
+                    raise ConfigurationError(f"Unsupported database type: {db_type}")
 
+                handler.stats.record_connection_start()
+                self.logger("debug", f"Handler created successfully for {database}")
+                self.logger("info", f"Resource stats: {json.dumps(handler.stats.to_dict())}")
                 yield handler
+            except yaml.YAMLError as e:
+                raise ConfigurationError(f"Invalid YAML configuration: {str(e)}")
+            except ImportError as e:
+                raise ConfigurationError(f"Failed to import handler for {db_type}: {str(e)}")
             finally:
                 if handler:
+                    self.logger("debug", f"Cleaning up handler for {database}")
+                    handler.stats.record_connection_end()
+                    self.logger("info", f"Final resource stats: {json.dumps(handler.stats.to_dict())}")
                     await handler.cleanup()
 
     def _setup_handlers(self):
@@ -116,11 +167,11 @@ class DatabaseServer:
         @self.server.read_resource()
         async def handle_read_resource(uri: str, arguments: dict | None = None) -> str:
             if not arguments or 'database' not in arguments:
-                raise ValueError("Database configuration name must be specified")
+                raise ConfigurationError("Database configuration name must be specified")
 
             parts = uri.split('/')
             if len(parts) < 3:
-                raise ValueError("Invalid resource URI")
+                raise ConfigurationError("Invalid resource URI format")
 
             database = arguments['database']
             table_name = parts[-2]  # URI format: xxx/table_name/schema
@@ -154,18 +205,18 @@ class DatabaseServer:
         @self.server.call_tool()
         async def handle_call_tool(name: str, arguments: dict) -> list[types.TextContent]:
             if name != "query":
-                raise ValueError(f"Unknown tool: {name}")
+                raise ConfigurationError(f"Unknown tool: {name}")
 
             if "database" not in arguments:
-                raise ValueError("Database configuration name must be specified")
+                raise ConfigurationError("Database configuration name must be specified")
 
             sql = arguments.get("sql", "").strip()
             if not sql:
-                raise ValueError("SQL query cannot be empty")
+                raise ConfigurationError("SQL query cannot be empty")
 
             # Only allow SELECT statements
             if not sql.lower().startswith("select"):
-                raise ValueError("Only SELECT queries are supported")
+                raise ConfigurationError("Only SELECT queries are supported for security reasons")
 
             database = arguments["database"]
             async with self.get_handler(database) as handler:
@@ -175,8 +226,10 @@ class DatabaseServer:
     async def run(self):
         """Run server"""
         async with mcp.server.stdio.stdio_server() as streams:
+            init_options = self.server.create_initialization_options()
+            init_options.capabilities.prompts = types.PromptsCapability(list=True)
             await self.server.run(
                 streams[0],
                 streams[1],
-                self.server.create_initialization_options()
+                init_options
             )

mcp_dbutils/postgres/handler.py

@@ -4,7 +4,7 @@ import psycopg2
 from psycopg2.pool import SimpleConnectionPool
 import mcp.types as types
 
-from ..base import DatabaseHandler
+from ..base import DatabaseHandler, DatabaseError
 from .config import PostgresConfig
 
 class PostgresHandler(DatabaseHandler):
@@ -51,8 +51,8 @@ class PostgresHandler(DatabaseHandler):
                 ]
         except psycopg2.Error as e:
             error_msg = f"Failed to get table list: [Code: {e.pgcode}] {e.pgerror or str(e)}"
-            self.log("error", error_msg)
-            raise
+            self.stats.record_error(e.__class__.__name__)
+            raise DatabaseError(error_msg)
         finally:
             if conn:
                 conn.close()
@@ -104,18 +104,19 @@ class PostgresHandler(DatabaseHandler):
                 })
         except psycopg2.Error as e:
             error_msg = f"Failed to read table schema: [Code: {e.pgcode}] {e.pgerror or str(e)}"
-            self.log("error", error_msg)
-            raise
+            self.stats.record_error(e.__class__.__name__)
+            raise DatabaseError(error_msg)
         finally:
             if conn:
                 conn.close()
 
-    async def execute_query(self, sql: str) -> str:
+    async def _execute_query(self, sql: str) -> str:
         """Execute SQL query"""
+        conn = None
         try:
             conn_params = self.config.get_connection_params()
             conn = psycopg2.connect(**conn_params)
-            self.log("info", f"Executing query: {sql}")
+            self.log("debug", f"Executing query: {sql}")
 
             with conn.cursor() as cur:
                 # Start read-only transaction
@@ -132,19 +133,18 @@ class PostgresHandler(DatabaseHandler):
                         'row_count': len(results)
                     })
 
-                    self.log("info", f"Query completed, returned {len(results)} rows")
+                    self.log("debug", f"Query completed, returned {len(results)} rows")
                     return result_text
                 finally:
                     cur.execute("ROLLBACK")
         except psycopg2.Error as e:
             error_msg = f"Query execution failed: [Code: {e.pgcode}] {e.pgerror or str(e)}"
-            self.log("error", error_msg)
-            raise
+            raise DatabaseError(error_msg)
         finally:
             if conn:
                 conn.close()
 
     async def cleanup(self):
         """Cleanup resources"""
-        # No special cleanup needed since we're not using connection pool
-        pass
+        # Log final stats before cleanup
+        self.log("info", f"Final PostgreSQL handler stats: {self.stats.to_dict()}")

mcp_dbutils/sqlite/handler.py

@@ -5,7 +5,7 @@ from pathlib import Path
 from contextlib import closing
 import mcp.types as types
 
-from ..base import DatabaseHandler
+from ..base import DatabaseHandler, DatabaseError
 from .config import SqliteConfig
 
 class SqliteHandler(DatabaseHandler):
@@ -86,11 +86,23 @@ class SqliteHandler(DatabaseHandler):
             self.log("error", error_msg)
             raise
 
-    async def execute_query(self, sql: str) -> str:
+    async def _execute_query(self, sql: str) -> str:
         """Execute SQL query"""
+        # Check for non-SELECT queries
+        sql_lower = sql.lower().strip()
+        if not sql_lower.startswith('select'):
+            error_msg = "cannot execute DELETE statement"
+            if sql_lower.startswith('delete'):
+                error_msg = "cannot execute DELETE statement"
+            elif sql_lower.startswith('update'):
+                error_msg = "cannot execute UPDATE statement"
+            elif sql_lower.startswith('insert'):
+                error_msg = "cannot execute INSERT statement"
+            raise DatabaseError(error_msg)
+
         try:
             with closing(self._get_connection()) as conn:
-                self.log("info", f"Executing query: {sql}")
+                self.log("debug", f"Executing query: {sql}")
                 cursor = conn.execute(sql)
                 results = cursor.fetchall()
 
@@ -103,15 +115,14 @@ class SqliteHandler(DatabaseHandler):
                     'row_count': len(results)
                 })
 
-                self.log("info", f"Query completed, returned {len(results)} rows")
+                self.log("debug", f"Query completed, returned {len(results)} rows")
                 return result_text
 
         except sqlite3.Error as e:
             error_msg = f"Query execution failed: {str(e)}"
-            self.log("error", error_msg)
-            raise
+            raise DatabaseError(error_msg)
 
     async def cleanup(self):
         """Cleanup resources"""
-        # No special cleanup needed for SQLite
-        pass
+        # Log final stats before cleanup
+        self.log("info", f"Final SQLite handler stats: {self.stats.to_dict()}")

mcp_dbutils/stats.py

@@ -0,0 +1,85 @@
+"""Resource monitoring statistics module"""
+
+from dataclasses import dataclass
+from datetime import datetime
+from typing import Optional
+import sys
+
+@dataclass
+class ResourceStats:
+    """Resource statistics tracking"""
+    # Connection stats
+    active_connections: int = 0
+    total_connections: int = 0
+    connection_start_time: Optional[datetime] = None
+
+    # Query stats
+    query_count: int = 0
+    last_query_time: Optional[datetime] = None
+
+    # Error stats
+    error_count: int = 0
+    last_error_time: Optional[datetime] = None
+    error_types: dict[str, int] = None
+
+    # Resource stats
+    estimated_memory: int = 0
+
+    def __post_init__(self):
+        """Initialize mutable defaults"""
+        if self.error_types is None:
+            self.error_types = {}
+
+    def record_connection_start(self):
+        """Record new connection start"""
+        self.active_connections += 1
+        self.total_connections += 1
+        self.connection_start_time = datetime.now()
+
+    def record_connection_end(self):
+        """Record connection end"""
+        self.active_connections = max(0, self.active_connections - 1)
+
+    def record_query(self):
+        """Record query execution"""
+        self.query_count += 1
+        self.last_query_time = datetime.now()
+
+    def record_error(self, error_type: str):
+        """Record error occurrence
+
+        Args:
+            error_type: Type/class name of the error
+        """
+        self.error_count += 1
+        self.last_error_time = datetime.now()
+        self.error_types[error_type] = self.error_types.get(error_type, 0) + 1
+
+    def update_memory_usage(self, obj: object):
+        """Update estimated memory usage
+
+        Args:
+            obj: Object to estimate size for
+        """
+        self.estimated_memory = sys.getsizeof(obj)
+
+    def to_dict(self) -> dict:
+        """Convert stats to dictionary for logging
+
+        Returns:
+            Dictionary of current statistics
+        """
+        now = datetime.now()
+        connection_duration = None
+        if self.connection_start_time:
+            connection_duration = (now - self.connection_start_time).total_seconds()
+
+        return {
+            "active_connections": self.active_connections,
+            "total_connections": self.total_connections,
+            "connection_duration": connection_duration,
+            "query_count": self.query_count,
+            "error_count": self.error_count,
+            "error_types": self.error_types,
+            "estimated_memory_bytes": self.estimated_memory
+        }

{mcp_dbutils-0.2.4.dist-info → mcp_dbutils-0.2.8.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mcp-dbutils
-Version: 0.2.4
+Version: 0.2.8
 Summary: MCP Database Utilities Service
 Author: Dong Hao
 License-Expression: MIT
@@ -10,14 +10,24 @@ 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)
 
@@ -35,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`:
@@ -86,6 +103,7 @@ 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
 ```
@@ -101,6 +119,8 @@ Add to Claude configuration:
       "--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"
@@ -112,6 +132,12 @@ Add to Claude configuration:
 }
 ```
 
+> **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)
@@ -122,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
@@ -283,3 +310,7 @@ For detailed guidelines, see [CONTRIBUTING.md](.github/CONTRIBUTING.md)
   * [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)

{mcp_dbutils-0.2.4.dist-info → mcp_dbutils-0.2.8.dist-info}/RECORD

@@ -1,17 +1,18 @@
 mcp_dbutils/__init__.py,sha256=_zVdjN2P_G5qEye7f5vQxiXAd6EwX2gyTL1wpFpqKck,1718
-mcp_dbutils/base.py,sha256=BQ6lEduhnR0pZnc-YY_OsO-w4XM06dzCJRU1uWnL-5M,6810
+mcp_dbutils/base.py,sha256=Hj35seBlmYgcq0qyoZchnUbKzDMPlhUxsCw7U79OA2c,9186
 mcp_dbutils/config.py,sha256=EwnPNuQVCBKd5WOXQfROyDTM-YpM_Odp0GhCPRg8YwE,1863
 mcp_dbutils/log.py,sha256=RJwWtHyZnJA2YRcyCK-WgnFadNuwtJeYKSxPbE-DCG0,991
+mcp_dbutils/stats.py,sha256=2hiKi_M8V4xhVHlH5FS-Df5GuMEpuzif12C8ik06Khs,2538
 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/handler.py,sha256=mvktsgak0tR-L4oknqv7UhOZ0_R8KPB9JRWiswh0bl4,5955
 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/handler.py,sha256=7mD50sQRii7UKX-8dE9RNicIXGwMDPB59Ee1dmncSlg,4842
 mcp_dbutils/sqlite/server.py,sha256=Q29O2YOW4kqDGc3z1hMXVv4M0KSkuZbqvVDMgZE8Fd8,7593
-mcp_dbutils-0.2.4.dist-info/METADATA,sha256=Eq2rC77Wrf6UAUSiJVhWNU0N-nQKZw7rSUadOD5Bm4Y,7718
-mcp_dbutils-0.2.4.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-mcp_dbutils-0.2.4.dist-info/entry_points.txt,sha256=XTjt0QmYRgKOJQT6skR9bp1EMUfIrgpHeZJPZ3CJffs,49
-mcp_dbutils-0.2.4.dist-info/licenses/LICENSE,sha256=1A_CwpWVlbjrKdVEYO77vYfnXlW7oxcilZ8FpA_BzCI,1065
-mcp_dbutils-0.2.4.dist-info/RECORD,,
+mcp_dbutils-0.2.8.dist-info/METADATA,sha256=YdBbIw37bEGOtLGOE1XTjZaE7ESHog-y6rXxIp5N5y8,9466
+mcp_dbutils-0.2.8.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+mcp_dbutils-0.2.8.dist-info/entry_points.txt,sha256=XTjt0QmYRgKOJQT6skR9bp1EMUfIrgpHeZJPZ3CJffs,49
+mcp_dbutils-0.2.8.dist-info/licenses/LICENSE,sha256=1A_CwpWVlbjrKdVEYO77vYfnXlW7oxcilZ8FpA_BzCI,1065
+mcp_dbutils-0.2.8.dist-info/RECORD,,