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

mcp_dbutils/base.py

@@ -31,6 +31,16 @@ from .stats import ResourceStats
 # 获取包信息用于日志命名
 pkg_meta = metadata("mcp-dbutils")
 
+# MCP日志级别常量
+LOG_LEVEL_DEBUG = "debug"       # 0
+LOG_LEVEL_INFO = "info"        # 1
+LOG_LEVEL_NOTICE = "notice"    # 2
+LOG_LEVEL_WARNING = "warning"  # 3
+LOG_LEVEL_ERROR = "error"      # 4
+LOG_LEVEL_CRITICAL = "critical" # 5
+LOG_LEVEL_ALERT = "alert"      # 6
+LOG_LEVEL_EMERGENCY = "emergency" # 7
+
 class ConnectionHandler(ABC):
     """Abstract base class defining common interface for connection handlers"""
 
@@ -45,8 +55,27 @@ class ConnectionHandler(ABC):
         self.config_path = config_path
         self.connection = connection
         self.debug = debug
+        # 创建stderr日志记录器用于本地调试
         self.log = create_logger(f"{pkg_meta['Name']}.handler.{connection}", debug)
         self.stats = ResourceStats()
+        self._session = None
+
+    def send_log(self, level: str, message: str):
+        """通过MCP发送日志消息和写入stderr
+        
+        Args:
+            level: 日志级别 (debug/info/notice/warning/error/critical/alert/emergency)
+            message: 日志内容
+        """
+        # 本地stderr日志
+        self.log(level, message)
+        
+        # MCP日志通知
+        if self._session and hasattr(self._session, 'request_context'):
+            self._session.request_context.session.send_log_message(
+                level=level,
+                data=message
+            )
 
     @property
     @abstractmethod
@@ -78,12 +107,12 @@ class ConnectionHandler(ABC):
             duration = (datetime.now() - start_time).total_seconds()
             self.stats.record_query_duration(sql, duration)
             self.stats.update_memory_usage(result)
-            self.log("info", f"Query executed in {duration*1000:.2f}ms. Resource stats: {json.dumps(self.stats.to_dict())}")
+            self.send_log(LOG_LEVEL_INFO, f"Query executed in {duration*1000:.2f}ms. Resource stats: {json.dumps(self.stats.to_dict())}")
             return result
         except Exception as e:
             duration = (datetime.now() - start_time).total_seconds()
             self.stats.record_error(e.__class__.__name__)
-            self.log("error", f"Query error after {duration*1000:.2f}ms - {str(e)}\nResource stats: {json.dumps(self.stats.to_dict())}")
+            self.send_log(LOG_LEVEL_ERROR, f"Query error after {duration*1000:.2f}ms - {str(e)}\nResource stats: {json.dumps(self.stats.to_dict())}")
             raise
 
     @abstractmethod
@@ -195,12 +224,12 @@ class ConnectionHandler(ABC):
                 raise ValueError(f"Unknown tool: {tool_name}")
                 
             self.stats.update_memory_usage(result)
-            self.log("info", f"Resource stats: {json.dumps(self.stats.to_dict())}")
+            self.send_log(LOG_LEVEL_INFO, f"Resource stats: {json.dumps(self.stats.to_dict())}")
             return f"[{self.db_type}]\n{result}"
             
         except Exception as e:
             self.stats.record_error(e.__class__.__name__)
-            self.log("error", f"Tool error - {str(e)}\nResource stats: {json.dumps(self.stats.to_dict())}")
+            self.send_log(LOG_LEVEL_ERROR, f"Tool error - {str(e)}\nResource stats: {json.dumps(self.stats.to_dict())}")
             raise
 
 class ConnectionServer:
@@ -222,19 +251,40 @@ class ConnectionServer:
             name=pkg_meta["Name"],
             version=pkg_meta["Version"]
         )
+        self._session = None
         self._setup_handlers()
         self._setup_prompts()
 
+    def send_log(self, level: str, message: str):
+        """通过MCP发送日志消息和写入stderr
+        
+        Args:
+            level: 日志级别 (debug/info/notice/warning/error/critical/alert/emergency)
+            message: 日志内容
+        """
+        # 本地stderr日志
+        self.logger(level, message)
+        
+        # MCP日志通知
+        if hasattr(self.server, 'session') and self.server.session:
+            try:
+                self.server.session.send_log_message(
+                    level=level,
+                    data=message
+                )
+            except Exception as e:
+                self.logger("error", f"Failed to send MCP log message: {str(e)}")
+
     def _setup_prompts(self):
         """Setup prompts handlers"""
         @self.server.list_prompts()
         async def handle_list_prompts() -> list[types.Prompt]:
             """Handle prompts/list request"""
             try:
-                self.logger("debug", "Handling list_prompts request")
+                self.send_log(LOG_LEVEL_DEBUG, "Handling list_prompts request")
                 return []
             except Exception as e:
-                self.logger("error", f"Error in list_prompts: {str(e)}")
+                self.send_log(LOG_LEVEL_ERROR, f"Error in list_prompts: {str(e)}")
                 raise
 
     @asynccontextmanager
@@ -266,19 +316,26 @@ class ConnectionServer:
                     raise ConfigurationError("Database configuration must include 'type' field")
 
                 db_type = db_config['type']
-                self.logger("debug", f"Creating handler for database type: {db_type}")
+                self.send_log(LOG_LEVEL_DEBUG, f"Creating handler for database type: {db_type}")
                 if db_type == 'sqlite':
                     from .sqlite.handler import SQLiteHandler
                     handler = SQLiteHandler(self.config_path, connection, self.debug)
                 elif db_type == 'postgres':
                     from .postgres.handler import PostgreSQLHandler
                     handler = PostgreSQLHandler(self.config_path, connection, self.debug)
+                elif db_type == 'mysql':
+                    from .mysql.handler import MySQLHandler
+                    handler = MySQLHandler(self.config_path, connection, self.debug)
                 else:
                     raise ConfigurationError(f"Unsupported database type: {db_type}")
 
+                # Set session for MCP logging
+                if hasattr(self.server, 'session'):
+                    handler._session = self.server.session
+
                 handler.stats.record_connection_start()
-                self.logger("debug", f"Handler created successfully for {connection}")
-                self.logger("info", f"Resource stats: {json.dumps(handler.stats.to_dict())}")
+                self.send_log(LOG_LEVEL_DEBUG, f"Handler created successfully for {connection}")
+                self.send_log(LOG_LEVEL_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)}")
@@ -286,9 +343,9 @@ class ConnectionServer:
                 raise ConfigurationError(f"Failed to import handler for {db_type}: {str(e)}")
             finally:
                 if handler:
-                    self.logger("debug", f"Cleaning up handler for {connection}")
+                    self.send_log(LOG_LEVEL_DEBUG, f"Cleaning up handler for {connection}")
                     handler.stats.record_connection_end()
-                    self.logger("info", f"Final resource stats: {json.dumps(handler.stats.to_dict())}")
+                    self.send_log(LOG_LEVEL_INFO, f"Final resource stats: {json.dumps(handler.stats.to_dict())}")
                     await handler.cleanup()
 
     def _setup_handlers(self):
@@ -567,7 +624,7 @@ class ConnectionServer:
                             await handler.execute_query(sql)
                         except Exception as e:
                             # If query fails, we still provide the execution plan
-                            self.logger("error", f"Query execution failed during analysis: {str(e)}")
+                            self.send_log(LOG_LEVEL_ERROR, f"Query execution failed during analysis: {str(e)}")
                     duration = (datetime.now() - start_time).total_seconds()
                     
                     # Combine analysis results

mcp_dbutils/config.py

@@ -8,7 +8,7 @@ from typing import Optional, Dict, Any, Literal
 from pathlib import Path
 
 # Supported connection types
-ConnectionType = Literal['sqlite', 'postgres']
+ConnectionType = Literal['sqlite', 'postgres', 'mysql']
 
 class ConnectionConfig(ABC):
     """Base class for connection configuration"""
@@ -48,7 +48,7 @@ class ConnectionConfig(ABC):
             if 'type' not in db_config:
                 raise ValueError(f"Database configuration {conn_name} missing required 'type' field")
             db_type = db_config['type']
-            if db_type not in ('sqlite', 'postgres'):
+            if db_type not in ('sqlite', 'postgres', 'mysql'):
                 raise ValueError(f"Invalid type value in database configuration {conn_name}: {db_type}")
 
         return connections

mcp_dbutils/log.py

@@ -2,20 +2,19 @@
 
 import sys
 from datetime import datetime
-from typing import Callable, Optional
+from typing import Callable
 
 def create_logger(name: str, is_debug: bool = False) -> Callable:
-    """创建日志函数
+    """创建stderr日志函数，用于本地调试
     Args:
         name: 服务名称
         is_debug: 是否输出debug级别日志
     """
-    def log(level: str, message: str, notify: Optional[Callable] = None):
-        """输出日志
+    def log(level: str, message: str):
+        """输出日志到stderr
         Args:
             level: 日志级别 (debug/info/warning/error)
             message: 日志内容
-            notify: MCP通知函数(可选)
         """
         if level == "debug" and not is_debug:
             return
@@ -23,11 +22,7 @@ def create_logger(name: str, is_debug: bool = False) -> Callable:
         timestamp = datetime.utcnow().isoformat(timespec='milliseconds') + 'Z'
         log_message = f"{timestamp} [{name}] [{level}] {message}"
 
-        # 始终输出到stderr
+        # 输出到stderr
         print(log_message, file=sys.stderr, flush=True)
 
-        # 如果提供了notify函数，同时发送MCP通知
-        if notify:
-            notify(level=level, data=message)
-
     return log

mcp_dbutils/mysql/__init__.py

@@ -0,0 +1,6 @@
+"""MySQL module"""
+
+from .handler import MySQLHandler
+from .config import MySQLConfig
+
+__all__ = ['MySQLHandler', 'MySQLConfig']

mcp_dbutils/mysql/config.py

@@ -0,0 +1,219 @@
+"""MySQL configuration module"""
+from dataclasses import dataclass
+from typing import Optional, Dict, Any, Literal
+from urllib.parse import urlparse, parse_qs
+from ..config import ConnectionConfig
+
+@dataclass
+class SSLConfig:
+    """SSL configuration for MySQL connection"""
+    mode: Literal['disabled', 'required', 'verify_ca', 'verify_identity'] = 'disabled'
+    ca: Optional[str] = None
+    cert: Optional[str] = None
+    key: Optional[str] = None
+
+def parse_url(url: str) -> Dict[str, Any]:
+    """Parse MySQL URL into connection parameters
+    
+    Args:
+        url: URL (e.g. mysql://host:port/dbname?ssl-mode=verify_identity)
+        
+    Returns:
+        Dictionary of connection parameters including SSL settings
+    """
+    if not url.startswith('mysql://'):
+        raise ValueError("Invalid MySQL URL format")
+    
+    if '@' in url:
+        raise ValueError("URL should not contain credentials. Please provide username and password separately.")
+    
+    # Parse URL and query parameters
+    parsed = urlparse(url)
+    query_params = parse_qs(parsed.query)
+    
+    params = {
+        'host': parsed.hostname or 'localhost',
+        'port': str(parsed.port or 3306),
+        'database': parsed.path.lstrip('/') if parsed.path else '',
+        'charset': query_params.get('charset', ['utf8mb4'])[0]
+    }
+    
+    if not params['database']:
+        raise ValueError("MySQL database name must be specified in URL")
+
+    # Parse SSL parameters if present
+    ssl_params = {}
+    if 'ssl-mode' in query_params:
+        mode = query_params['ssl-mode'][0]
+        if mode not in ['disabled', 'required', 'verify_ca', 'verify_identity']:
+            raise ValueError(f"Invalid ssl-mode: {mode}")
+        ssl_params['mode'] = mode
+        
+    if 'ssl-ca' in query_params:
+        ssl_params['ca'] = query_params['ssl-ca'][0]
+    if 'ssl-cert' in query_params:
+        ssl_params['cert'] = query_params['ssl-cert'][0]
+    if 'ssl-key' in query_params:
+        ssl_params['key'] = query_params['ssl-key'][0]
+        
+    if ssl_params:
+        params['ssl'] = SSLConfig(**ssl_params)
+        
+    return params
+
+@dataclass
+class MySQLConfig(ConnectionConfig):
+    database: str
+    user: str
+    password: str
+    host: str = 'localhost'
+    port: str = '3306'
+    charset: str = 'utf8mb4'
+    local_host: Optional[str] = None
+    type: Literal['mysql'] = 'mysql'
+    url: Optional[str] = None
+    ssl: Optional[SSLConfig] = None
+
+    @classmethod
+    def from_yaml(cls, yaml_path: str, db_name: str, local_host: Optional[str] = None) -> 'MySQLConfig':
+        """Create configuration from YAML file
+
+        Args:
+            yaml_path: Path to YAML configuration file
+            db_name: Connection configuration name to use
+            local_host: Optional local host address
+        """
+        configs = cls.load_yaml_config(yaml_path)
+        if not db_name:
+            raise ValueError("Connection name must be specified")
+        if db_name not in configs:
+            available_dbs = list(configs.keys())
+            raise ValueError(f"Connection configuration not found: {db_name}. Available configurations: {available_dbs}")
+
+        db_config = configs[db_name]
+        if 'type' not in db_config:
+            raise ValueError("Connection configuration must include 'type' field")
+        if db_config['type'] != 'mysql':
+            raise ValueError(f"Configuration is not MySQL type: {db_config['type']}")
+
+        # Check required credentials
+        if not db_config.get('user'):
+            raise ValueError("User must be specified in connection configuration")
+        if not db_config.get('password'):
+            raise ValueError("Password must be specified in connection configuration")
+
+        # Get connection parameters
+        if 'url' in db_config:
+            # Parse URL for connection parameters
+            params = parse_url(db_config['url'])
+            config = cls(
+                database=params['database'],
+                user=db_config['user'],
+                password=db_config['password'],
+                host=params['host'],
+                port=params['port'],
+                charset=params['charset'],
+                local_host=local_host,
+                url=db_config['url'],
+                ssl=params.get('ssl')
+            )
+        else:
+            if not db_config.get('database'):
+                raise ValueError("MySQL database name must be specified in configuration")
+            if not db_config.get('host'):
+                raise ValueError("Host must be specified in connection configuration")
+            if not db_config.get('port'):
+                raise ValueError("Port must be specified in connection configuration")
+            
+            # Parse SSL configuration if present
+            ssl_config = None
+            if 'ssl' in db_config:
+                ssl_params = db_config['ssl']
+                if not isinstance(ssl_params, dict):
+                    raise ValueError("SSL configuration must be a dictionary")
+                
+                if ssl_params.get('mode') not in [None, 'disabled', 'required', 'verify_ca', 'verify_identity']:
+                    raise ValueError(f"Invalid ssl-mode: {ssl_params.get('mode')}")
+                
+                ssl_config = SSLConfig(
+                    mode=ssl_params.get('mode', 'disabled'),
+                    ca=ssl_params.get('ca'),
+                    cert=ssl_params.get('cert'),
+                    key=ssl_params.get('key')
+                )
+            
+            config = cls(
+                database=db_config['database'],
+                user=db_config['user'],
+                password=db_config['password'],
+                host=db_config['host'],
+                port=str(db_config['port']),
+                charset=db_config.get('charset', 'utf8mb4'),
+                local_host=local_host,
+                ssl=ssl_config
+            )
+        config.debug = cls.get_debug_mode()
+        return config
+
+    @classmethod
+    def from_url(cls, url: str, user: str, password: str, 
+                local_host: Optional[str] = None) -> 'MySQLConfig':
+        """Create configuration from URL and credentials
+        
+        Args:
+            url: URL (mysql://host:port/dbname)
+            user: Username for connection
+            password: Password for connection
+            local_host: Optional local host address
+            
+        Raises:
+            ValueError: If URL format is invalid or required parameters are missing
+        """
+        params = parse_url(url)
+        
+        config = cls(
+            database=params['database'],
+            user=user,
+            password=password,
+            host=params['host'],
+            port=params['port'],
+            charset=params['charset'],
+            local_host=local_host,
+            url=url,
+            ssl=params.get('ssl')
+        )
+        config.debug = cls.get_debug_mode()
+        return config
+
+    def get_connection_params(self) -> Dict[str, Any]:
+        """Get MySQL connection parameters"""
+        params = {
+            'database': self.database,
+            'user': self.user,
+            'password': self.password,
+            'host': self.local_host or self.host,
+            'port': int(self.port),
+            'charset': self.charset,
+            'use_unicode': True
+        }
+        
+        # Add SSL parameters if configured
+        if self.ssl:
+            params['ssl_mode'] = self.ssl.mode
+            if self.ssl.ca:
+                params['ssl_ca'] = self.ssl.ca
+            if self.ssl.cert:
+                params['ssl_cert'] = self.ssl.cert
+            if self.ssl.key:
+                params['ssl_key'] = self.ssl.key
+                
+        return {k: v for k, v in params.items() if v is not None}
+
+    def get_masked_connection_info(self) -> Dict[str, Any]:
+        """Return masked connection information for logging"""
+        return {
+            'database': self.database,
+            'host': self.local_host or self.host,
+            'port': self.port,
+            'charset': self.charset
+        }