chuk-tool-processor 0.6.28__py3-none-any.whl → 0.6.29__py3-none-any.whl

chuk_tool_processor/mcp/mcp_tool.py

@@ -370,7 +370,7 @@ class MCPTool:
             self._circuit_open = False
             self._circuit_open_time = None
             self.connection_state = ConnectionState.HEALTHY
-            logger.info(f"Circuit breaker closed for tool '{self.tool_name}' after successful execution")
+            logger.debug(f"Circuit breaker closed for tool '{self.tool_name}' after successful execution")
 
     async def _record_failure(self, is_connection_error: bool = False) -> None:
         """Record a failed execution."""
@@ -407,7 +407,7 @@ class MCPTool:
             self._circuit_open = False
             self._circuit_open_time = None
             self.connection_state = ConnectionState.HEALTHY
-            logger.info(f"Circuit breaker reset for tool '{self.tool_name}' after timeout")
+            logger.debug(f"Circuit breaker reset for tool '{self.tool_name}' after timeout")
             return False
 
         return True
@@ -462,12 +462,12 @@ class MCPTool:
         self._circuit_open_time = None
         self._consecutive_failures = 0
         self.connection_state = ConnectionState.HEALTHY
-        logger.info(f"Circuit breaker manually reset for tool '{self.tool_name}'")
+        logger.debug(f"Circuit breaker manually reset for tool '{self.tool_name}'")
 
     def disable_resilience(self) -> None:
         """Disable resilience features for this tool instance."""
         self.enable_resilience = False
-        logger.info(f"Resilience features disabled for tool '{self.tool_name}'")
+        logger.debug(f"Resilience features disabled for tool '{self.tool_name}'")
 
     def set_stream_manager(self, stream_manager: StreamManager | None) -> None:
         """
@@ -482,7 +482,7 @@ class MCPTool:
             if self._circuit_open:
                 self._circuit_open = False
                 self._circuit_open_time = None
-                logger.info(f"Circuit breaker closed for tool '{self.tool_name}' due to new stream manager")
+                logger.debug(f"Circuit breaker closed for tool '{self.tool_name}' due to new stream manager")
         else:
             self.connection_state = ConnectionState.DISCONNECTED
 

chuk_tool_processor/mcp/stream_manager.py

@@ -21,6 +21,7 @@ from chuk_tool_processor.mcp.transport import (
     MCPBaseTransport,
     SSETransport,
     StdioTransport,
+    TimeoutConfig,
 )
 
 logger = get_logger("chuk_tool_processor.mcp.stream_manager")
@@ -38,7 +39,7 @@ class StreamManager:
     - HTTP Streamable (modern replacement for SSE, spec 2025-03-26) with graceful headers handling
     """
 
-    def __init__(self) -> None:
+    def __init__(self, timeout_config: TimeoutConfig | None = None) -> None:
         self.transports: dict[str, MCPBaseTransport] = {}
         self.server_info: list[dict[str, Any]] = []
         self.tool_to_server_map: dict[str, str] = {}
@@ -46,7 +47,7 @@ class StreamManager:
         self.all_tools: list[dict[str, Any]] = []
         self._lock = asyncio.Lock()
         self._closed = False  # Track if we've been closed
-        self._shutdown_timeout = 2.0  # Maximum time to spend on shutdown
+        self.timeout_config = timeout_config or TimeoutConfig()
 
     # ------------------------------------------------------------------ #
     #  factory helpers with enhanced error handling                      #
@@ -251,8 +252,12 @@ class StreamManager:
                     self.transports[server_name] = transport
 
                     # Ping and get tools with timeout protection (use longer timeouts for slow servers)
-                    status = "Up" if await asyncio.wait_for(transport.send_ping(), timeout=30.0) else "Down"
-                    tools = await asyncio.wait_for(transport.get_tools(), timeout=30.0)
+                    status = (
+                        "Up"
+                        if await asyncio.wait_for(transport.send_ping(), timeout=self.timeout_config.operation)
+                        else "Down"
+                    )
+                    tools = await asyncio.wait_for(transport.get_tools(), timeout=self.timeout_config.operation)
 
                     for t in tools:
                         name = t.get("name")
@@ -333,8 +338,12 @@ class StreamManager:
 
                     self.transports[name] = transport
                     # Use longer timeouts for slow servers (ping can take time after initialization)
-                    status = "Up" if await asyncio.wait_for(transport.send_ping(), timeout=30.0) else "Down"
-                    tools = await asyncio.wait_for(transport.get_tools(), timeout=30.0)
+                    status = (
+                        "Up"
+                        if await asyncio.wait_for(transport.send_ping(), timeout=self.timeout_config.operation)
+                        else "Down"
+                    )
+                    tools = await asyncio.wait_for(transport.get_tools(), timeout=self.timeout_config.operation)
 
                     for t in tools:
                         tname = t.get("name")
@@ -415,8 +424,12 @@ class StreamManager:
 
                     self.transports[name] = transport
                     # Use longer timeouts for slow servers (ping can take time after initialization)
-                    status = "Up" if await asyncio.wait_for(transport.send_ping(), timeout=30.0) else "Down"
-                    tools = await asyncio.wait_for(transport.get_tools(), timeout=30.0)
+                    status = (
+                        "Up"
+                        if await asyncio.wait_for(transport.send_ping(), timeout=self.timeout_config.operation)
+                        else "Down"
+                    )
+                    tools = await asyncio.wait_for(transport.get_tools(), timeout=self.timeout_config.operation)
 
                     for t in tools:
                         tname = t.get("name")
@@ -462,7 +475,7 @@ class StreamManager:
         transport = self.transports[server_name]
 
         try:
-            tools = await asyncio.wait_for(transport.get_tools(), timeout=10.0)
+            tools = await asyncio.wait_for(transport.get_tools(), timeout=self.timeout_config.operation)
             logger.debug("Found %d tools for server %s", len(tools), server_name)
             return tools
         except TimeoutError:
@@ -481,7 +494,7 @@ class StreamManager:
 
         async def _ping_one(name: str, tr: MCPBaseTransport):
             try:
-                ok = await asyncio.wait_for(tr.send_ping(), timeout=5.0)
+                ok = await asyncio.wait_for(tr.send_ping(), timeout=self.timeout_config.quick)
             except Exception:
                 ok = False
             return {"server": name, "ok": ok}
@@ -496,7 +509,7 @@ class StreamManager:
 
         async def _one(name: str, tr: MCPBaseTransport):
             try:
-                res = await asyncio.wait_for(tr.list_resources(), timeout=10.0)
+                res = await asyncio.wait_for(tr.list_resources(), timeout=self.timeout_config.operation)
                 resources = res.get("resources", []) if isinstance(res, dict) else res
                 for item in resources:
                     item = dict(item)
@@ -516,7 +529,7 @@ class StreamManager:
 
         async def _one(name: str, tr: MCPBaseTransport):
             try:
-                res = await asyncio.wait_for(tr.list_prompts(), timeout=10.0)
+                res = await asyncio.wait_for(tr.list_prompts(), timeout=self.timeout_config.operation)
                 prompts = res.get("prompts", []) if isinstance(res, dict) else res
                 for item in prompts:
                     item = dict(item)
@@ -643,7 +656,7 @@ class StreamManager:
             try:
                 results = await asyncio.wait_for(
                     asyncio.gather(*[task for _, task in close_tasks], return_exceptions=True),
-                    timeout=self._shutdown_timeout,
+                    timeout=self.timeout_config.shutdown,
                 )
 
                 # Process results
@@ -666,7 +679,8 @@ class StreamManager:
                 # Brief wait for cancellations to complete
                 with contextlib.suppress(TimeoutError):
                     await asyncio.wait_for(
-                        asyncio.gather(*[task for _, task in close_tasks], return_exceptions=True), timeout=0.5
+                        asyncio.gather(*[task for _, task in close_tasks], return_exceptions=True),
+                        timeout=self.timeout_config.shutdown,
                     )
 
     async def _sequential_close(self, transport_items: list[tuple[str, MCPBaseTransport]], close_results: list) -> None:
@@ -675,7 +689,7 @@ class StreamManager:
             try:
                 await asyncio.wait_for(
                     self._close_single_transport(name, transport),
-                    timeout=0.5,  # Short timeout per transport
+                    timeout=self.timeout_config.shutdown,
                 )
                 logger.debug("Closed transport: %s", name)
                 close_results.append((name, True, None))
@@ -767,7 +781,7 @@ class StreamManager:
 
         for name, transport in self.transports.items():
             try:
-                ping_ok = await asyncio.wait_for(transport.send_ping(), timeout=5.0)
+                ping_ok = await asyncio.wait_for(transport.send_ping(), timeout=self.timeout_config.quick)
                 health_info["transports"][name] = {
                     "status": "healthy" if ping_ok else "unhealthy",
                     "ping_success": ping_ok,

chuk_tool_processor/mcp/transport/__init__.py

@@ -11,6 +11,12 @@ All transports now follow the same interface and provide consistent behavior:
 
 from .base_transport import MCPBaseTransport
 from .http_streamable_transport import HTTPStreamableTransport
+from .models import (
+    HeadersConfig,
+    ServerInfo,
+    TimeoutConfig,
+    TransportMetrics,
+)
 from .sse_transport import SSETransport
 from .stdio_transport import StdioTransport
 
@@ -19,4 +25,8 @@ __all__ = [
     "StdioTransport",
     "SSETransport",
     "HTTPStreamableTransport",
+    "TimeoutConfig",
+    "TransportMetrics",
+    "ServerInfo",
+    "HeadersConfig",
 ]

chuk_tool_processor/mcp/transport/http_streamable_transport.py

@@ -24,6 +24,7 @@ from chuk_mcp.transports.http.transport import (
 )
 
 from .base_transport import MCPBaseTransport
+from .models import TimeoutConfig, TransportMetrics
 
 logger = logging.getLogger(__name__)
 
@@ -40,12 +41,13 @@ class HTTPStreamableTransport(MCPBaseTransport):
         self,
         url: str,
         api_key: str | None = None,
-        headers: dict[str, str] | None = None,  # NEW: Headers support
+        headers: dict[str, str] | None = None,
         connection_timeout: float = 30.0,
         default_timeout: float = 30.0,
         session_id: str | None = None,
         enable_metrics: bool = True,
-        oauth_refresh_callback: Any | None = None,  # NEW: OAuth token refresh callback
+        oauth_refresh_callback: Any | None = None,
+        timeout_config: TimeoutConfig | None = None,
     ):
         """
         Initialize HTTP Streamable transport with enhanced configuration.
@@ -53,12 +55,13 @@ class HTTPStreamableTransport(MCPBaseTransport):
         Args:
             url: HTTP server URL (should end with /mcp)
             api_key: Optional API key for authentication
-            headers: Optional custom headers (NEW)
-            connection_timeout: Timeout for initial connection
-            default_timeout: Default timeout for operations
+            headers: Optional custom headers
+            connection_timeout: Timeout for initial connection (overrides timeout_config.connect)
+            default_timeout: Default timeout for operations (overrides timeout_config.operation)
             session_id: Optional session ID for stateful connections
             enable_metrics: Whether to track performance metrics
-            oauth_refresh_callback: Optional async callback to refresh OAuth tokens (NEW)
+            oauth_refresh_callback: Optional async callback to refresh OAuth tokens
+            timeout_config: Optional timeout configuration model with connect/operation/quick/shutdown
         """
         # Ensure URL points to the /mcp endpoint
         if not url.endswith("/mcp"):
@@ -67,12 +70,18 @@ class HTTPStreamableTransport(MCPBaseTransport):
             self.url = url
 
         self.api_key = api_key
-        self.configured_headers = headers or {}  # NEW: Store configured headers
-        self.connection_timeout = connection_timeout
-        self.default_timeout = default_timeout
+        self.configured_headers = headers or {}
         self.session_id = session_id
         self.enable_metrics = enable_metrics
-        self.oauth_refresh_callback = oauth_refresh_callback  # NEW: OAuth refresh callback
+        self.oauth_refresh_callback = oauth_refresh_callback
+
+        # Use timeout config or create from individual parameters
+        if timeout_config is None:
+            timeout_config = TimeoutConfig(connect=connection_timeout, operation=default_timeout)
+
+        self.timeout_config = timeout_config
+        self.connection_timeout = timeout_config.connect
+        self.default_timeout = timeout_config.operation
 
         logger.debug("HTTP Streamable transport initialized with URL: %s", self.url)
         if self.api_key:
@@ -93,20 +102,8 @@ class HTTPStreamableTransport(MCPBaseTransport):
         self._consecutive_failures = 0
         self._max_consecutive_failures = 3
 
-        # Performance metrics (enhanced like SSE)
-        self._metrics = {
-            "total_calls": 0,
-            "successful_calls": 0,
-            "failed_calls": 0,
-            "total_time": 0.0,
-            "avg_response_time": 0.0,
-            "last_ping_time": None,
-            "initialization_time": None,
-            "connection_resets": 0,
-            "stream_errors": 0,
-            "connection_errors": 0,  # NEW
-            "recovery_attempts": 0,  # NEW
-        }
+        # Performance metrics (enhanced like SSE) - use Pydantic model
+        self._metrics = TransportMetrics() if enable_metrics else None
 
     def _get_headers(self) -> dict[str, str]:
         """Get headers with authentication and custom headers (like SSE)."""
@@ -136,7 +133,7 @@ class HTTPStreamableTransport(MCPBaseTransport):
         try:
             import httpx
 
-            async with httpx.AsyncClient(timeout=5.0) as client:
+            async with httpx.AsyncClient(timeout=self.timeout_config.quick) as client:
                 # Test basic connectivity to base URL
                 base_url = self.url.replace("/mcp", "")
                 response = await client.get(f"{base_url}/health", headers=self._get_headers())
@@ -204,8 +201,8 @@ class HTTPStreamableTransport(MCPBaseTransport):
             # Verify connection with ping (enhanced like SSE)
             logger.debug("Verifying connection with ping...")
             ping_start = time.time()
-            # Use longer timeout for initial ping - some servers (like Notion) are slow
-            ping_timeout = max(self.default_timeout, 15.0)
+            # Use connect timeout for initial ping - some servers (like Notion) are slow
+            ping_timeout = self.timeout_config.connect
             ping_success = await asyncio.wait_for(
                 send_ping(self._read_stream, self._write_stream, timeout=ping_timeout),
                 timeout=ping_timeout,
@@ -218,9 +215,9 @@ class HTTPStreamableTransport(MCPBaseTransport):
                 self._consecutive_failures = 0
 
                 total_init_time = time.time() - start_time
-                if self.enable_metrics:
-                    self._metrics["initialization_time"] = total_init_time
-                    self._metrics["last_ping_time"] = ping_time
+                if self.enable_metrics and self._metrics:
+                    self._metrics.initialization_time = total_init_time
+                    self._metrics.last_ping_time = ping_time
 
                 logger.debug(
                     "HTTP Streamable transport initialized successfully in %.3fs (ping: %.3fs)",
@@ -233,27 +230,27 @@ class HTTPStreamableTransport(MCPBaseTransport):
                 # Still consider it initialized since connection was established
                 self._initialized = True
                 self._consecutive_failures = 1  # Mark one failure
-                if self.enable_metrics:
-                    self._metrics["initialization_time"] = time.time() - start_time
+                if self.enable_metrics and self._metrics:
+                    self._metrics.initialization_time = time.time() - start_time
                 return True
 
         except TimeoutError:
             logger.error("HTTP Streamable initialization timed out after %ss", self.connection_timeout)
             await self._cleanup()
-            if self.enable_metrics:
-                self._metrics["connection_errors"] += 1
+            if self.enable_metrics and self._metrics:
+                self._metrics.connection_errors += 1
             return False
         except Exception as e:
             logger.error("Error initializing HTTP Streamable transport: %s", e, exc_info=True)
             await self._cleanup()
-            if self.enable_metrics:
-                self._metrics["connection_errors"] += 1
+            if self.enable_metrics and self._metrics:
+                self._metrics.connection_errors += 1
             return False
 
     async def _attempt_recovery(self) -> bool:
         """Attempt to recover from connection issues (NEW - like SSE resilience)."""
-        if self.enable_metrics:
-            self._metrics["recovery_attempts"] += 1
+        if self.enable_metrics and self._metrics:
+            self._metrics.recovery_attempts += 1
 
         logger.debug("Attempting HTTP connection recovery...")
 
@@ -273,16 +270,16 @@ class HTTPStreamableTransport(MCPBaseTransport):
             return
 
         # Enhanced metrics logging (like SSE)
-        if self.enable_metrics and self._metrics["total_calls"] > 0:
-            success_rate = self._metrics["successful_calls"] / self._metrics["total_calls"] * 100
+        if self.enable_metrics and self._metrics and self._metrics.total_calls > 0:
+            success_rate = self._metrics.successful_calls / self._metrics.total_calls * 100
             logger.debug(
                 "HTTP Streamable transport closing - Calls: %d, Success: %.1f%%, "
                 "Avg time: %.3fs, Recoveries: %d, Errors: %d",
-                self._metrics["total_calls"],
+                self._metrics.total_calls,
                 success_rate,
-                self._metrics["avg_response_time"],
-                self._metrics["recovery_attempts"],
-                self._metrics["connection_errors"],
+                self._metrics.avg_response_time,
+                self._metrics.recovery_attempts,
+                self._metrics.connection_errors,
             )
 
         try:
@@ -323,9 +320,9 @@ class HTTPStreamableTransport(MCPBaseTransport):
             else:
                 self._consecutive_failures += 1
 
-            if self.enable_metrics:
+            if self.enable_metrics and self._metrics:
                 ping_time = time.time() - start_time
-                self._metrics["last_ping_time"] = ping_time
+                self._metrics.last_ping_time = ping_time
                 logger.debug("HTTP Streamable ping completed in %.3fs: %s", ping_time, success)
 
             return success
@@ -336,8 +333,8 @@ class HTTPStreamableTransport(MCPBaseTransport):
         except Exception as e:
             logger.error("HTTP Streamable ping failed: %s", e)
             self._consecutive_failures += 1
-            if self.enable_metrics:
-                self._metrics["stream_errors"] += 1
+            if self.enable_metrics and self._metrics:
+                self._metrics.stream_errors += 1
             return False
 
     def is_connected(self) -> bool:
@@ -365,9 +362,19 @@ class HTTPStreamableTransport(MCPBaseTransport):
                 timeout=self.default_timeout,
             )
 
-            # Normalize response
-            if isinstance(tools_response, dict):
+            # Normalize response - handle multiple formats including Pydantic models
+            # 1. Check if it's a Pydantic model with tools attribute (e.g., ListToolsResult from chuk_mcp)
+            if hasattr(tools_response, "tools"):
+                tools = tools_response.tools
+                # Convert Pydantic Tool models to dicts if needed
+                if tools and len(tools) > 0 and hasattr(tools[0], "model_dump"):
+                    tools = [t.model_dump() for t in tools]
+                elif tools and len(tools) > 0 and hasattr(tools[0], "dict"):
+                    tools = [t.dict() for t in tools]
+            # 2. Check if it's a dict with "tools" key
+            elif isinstance(tools_response, dict):
                 tools = tools_response.get("tools", [])
+            # 3. Check if it's already a list
             elif isinstance(tools_response, list):
                 tools = tools_response
             else:
@@ -390,8 +397,8 @@ class HTTPStreamableTransport(MCPBaseTransport):
         except Exception as e:
             logger.error("Error getting tools: %s", e)
             self._consecutive_failures += 1
-            if self.enable_metrics:
-                self._metrics["stream_errors"] += 1
+            if self.enable_metrics and self._metrics:
+                self._metrics.stream_errors += 1
             return []
 
     async def call_tool(
@@ -404,8 +411,8 @@ class HTTPStreamableTransport(MCPBaseTransport):
         tool_timeout = timeout or self.default_timeout
         start_time = time.time()
 
-        if self.enable_metrics:
-            self._metrics["total_calls"] += 1
+        if self.enable_metrics and self._metrics:
+            self._metrics.total_calls += 1
 
         try:
             logger.debug("Calling tool '%s' with timeout %ss", tool_name, tool_timeout)
@@ -430,7 +437,7 @@ class HTTPStreamableTransport(MCPBaseTransport):
                 logger.warning("OAuth error detected: %s", result.get("error"))
 
                 if self.oauth_refresh_callback:
-                    logger.info("Attempting OAuth token refresh...")
+                    logger.debug("Attempting OAuth token refresh...")
                     try:
                         # Call the refresh callback
                         new_headers = await self.oauth_refresh_callback()
@@ -438,18 +445,18 @@ class HTTPStreamableTransport(MCPBaseTransport):
                         if new_headers and "Authorization" in new_headers:
                             # Update configured headers with new token
                             self.configured_headers.update(new_headers)
-                            logger.info("OAuth token refreshed, reconnecting...")
+                            logger.debug("OAuth token refreshed, reconnecting...")
 
                             # Reconnect with new token
                             if await self._attempt_recovery():
-                                logger.info("Retrying tool call after token refresh...")
+                                logger.debug("Retrying tool call after token refresh...")
                                 # Retry the tool call once with new token
                                 raw_response = await asyncio.wait_for(
                                     send_tools_call(self._read_stream, self._write_stream, tool_name, arguments),
                                     timeout=tool_timeout,
                                 )
                                 result = self._normalize_mcp_response(raw_response)
-                                logger.info("Tool call retry completed")
+                                logger.debug("Tool call retry completed")
                             else:
                                 logger.error("Failed to reconnect after token refresh")
                         else:
@@ -488,17 +495,17 @@ class HTTPStreamableTransport(MCPBaseTransport):
         except Exception as e:
             response_time = time.time() - start_time
             self._consecutive_failures += 1
-            if self.enable_metrics:
+            if self.enable_metrics and self._metrics:
                 self._update_metrics(response_time, False)
-                self._metrics["stream_errors"] += 1
+                self._metrics.stream_errors += 1
 
             # Enhanced connection error detection
             error_str = str(e).lower()
             if any(indicator in error_str for indicator in ["connection", "disconnected", "broken pipe", "eof"]):
                 logger.warning("Connection error detected: %s", e)
                 self._initialized = False
-                if self.enable_metrics:
-                    self._metrics["connection_errors"] += 1
+                if self.enable_metrics and self._metrics:
+                    self._metrics.connection_errors += 1
 
             error_msg = f"Tool execution failed: {str(e)}"
             logger.error("Tool '%s' error: %s", tool_name, error_msg)
@@ -506,14 +513,10 @@ class HTTPStreamableTransport(MCPBaseTransport):
 
     def _update_metrics(self, response_time: float, success: bool) -> None:
         """Enhanced metrics tracking (like SSE)."""
-        if success:
-            self._metrics["successful_calls"] += 1
-        else:
-            self._metrics["failed_calls"] += 1
+        if not self._metrics:
+            return
 
-        self._metrics["total_time"] += response_time
-        if self._metrics["total_calls"] > 0:
-            self._metrics["avg_response_time"] = self._metrics["total_time"] / self._metrics["total_calls"]
+        self._metrics.update_call_metrics(response_time, success)
 
     def _is_oauth_error(self, error_msg: str) -> bool:
         """Detect if error is OAuth-related (NEW)."""
@@ -612,7 +615,10 @@ class HTTPStreamableTransport(MCPBaseTransport):
 
     def get_metrics(self) -> dict[str, Any]:
         """Enhanced metrics with health information."""
-        metrics = self._metrics.copy()
+        if not self._metrics:
+            return {}
+
+        metrics = self._metrics.to_dict()
         metrics.update(
             {
                 "is_connected": self.is_connected(),
@@ -625,22 +631,20 @@ class HTTPStreamableTransport(MCPBaseTransport):
 
     def reset_metrics(self) -> None:
         """Enhanced metrics reset preserving health state."""
-        preserved_init_time = self._metrics.get("initialization_time")
-        preserved_last_ping = self._metrics.get("last_ping_time")
-
-        self._metrics = {
-            "total_calls": 0,
-            "successful_calls": 0,
-            "failed_calls": 0,
-            "total_time": 0.0,
-            "avg_response_time": 0.0,
-            "last_ping_time": preserved_last_ping,
-            "initialization_time": preserved_init_time,
-            "connection_resets": self._metrics.get("connection_resets", 0),
-            "stream_errors": 0,
-            "connection_errors": 0,
-            "recovery_attempts": 0,
-        }
+        if not self._metrics:
+            return
+
+        # Preserve important historical values
+        preserved_init_time = self._metrics.initialization_time
+        preserved_last_ping = self._metrics.last_ping_time
+        preserved_resets = self._metrics.connection_resets
+
+        # Create new metrics instance with preserved values
+        self._metrics = TransportMetrics(
+            initialization_time=preserved_init_time,
+            last_ping_time=preserved_last_ping,
+            connection_resets=preserved_resets,
+        )
 
     def get_streams(self) -> list[tuple]:
         """Enhanced streams access with connection check."""

chuk_tool_processor/mcp/transport/models.py

@@ -0,0 +1,100 @@
+# chuk_tool_processor/mcp/transport/models.py
+"""
+Pydantic models for MCP transport configuration and metrics.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+
+class TimeoutConfig(BaseModel):
+    """
+    Unified timeout configuration for all MCP operations.
+
+    Just 4 simple, logical timeout categories:
+    - connect: Connection establishment, initialization, session discovery (30s default)
+    - operation: Normal operations like tool calls, listing resources (30s default)
+    - quick: Fast health checks and pings (5s default)
+    - shutdown: Cleanup and shutdown operations (2s default)
+    """
+
+    connect: float = Field(
+        default=30.0, description="Timeout for connection establishment, initialization, and session discovery"
+    )
+    operation: float = Field(
+        default=30.0, description="Timeout for normal operations (tool calls, listing tools/resources/prompts)"
+    )
+    quick: float = Field(default=5.0, description="Timeout for quick health checks and pings")
+    shutdown: float = Field(default=2.0, description="Timeout for shutdown and cleanup operations")
+
+
+class TransportMetrics(BaseModel):
+    """Performance and connection metrics for transports."""
+
+    model_config = {"validate_assignment": True}
+
+    total_calls: int = Field(default=0, description="Total number of calls made")
+    successful_calls: int = Field(default=0, description="Number of successful calls")
+    failed_calls: int = Field(default=0, description="Number of failed calls")
+    total_time: float = Field(default=0.0, description="Total time spent on calls")
+    avg_response_time: float = Field(default=0.0, description="Average response time")
+    last_ping_time: float | None = Field(default=None, description="Time taken for last ping")
+    initialization_time: float | None = Field(default=None, description="Time taken for initialization")
+    connection_resets: int = Field(default=0, description="Number of connection resets")
+    stream_errors: int = Field(default=0, description="Number of stream errors")
+    connection_errors: int = Field(default=0, description="Number of connection errors")
+    recovery_attempts: int = Field(default=0, description="Number of recovery attempts")
+    session_discoveries: int = Field(default=0, description="Number of session discoveries (SSE)")
+
+    def to_dict(self) -> dict[str, Any]:
+        """Convert to dictionary format."""
+        return self.model_dump()
+
+    def update_call_metrics(self, response_time: float, success: bool) -> None:
+        """Update metrics after a call."""
+        if success:
+            self.successful_calls += 1
+        else:
+            self.failed_calls += 1
+
+        self.total_time += response_time
+        if self.total_calls > 0:
+            self.avg_response_time = self.total_time / self.total_calls
+
+
+class ServerInfo(BaseModel):
+    """Information about a server in StreamManager."""
+
+    id: int = Field(description="Server ID")
+    name: str = Field(description="Server name")
+    tools: int = Field(description="Number of tools available")
+    status: str = Field(description="Server status (Up/Down)")
+
+    def to_dict(self) -> dict[str, Any]:
+        """Convert to dictionary format."""
+        return self.model_dump()
+
+
+class HeadersConfig(BaseModel):
+    """Configuration for HTTP headers."""
+
+    headers: dict[str, str] = Field(default_factory=dict, description="Custom HTTP headers")
+
+    def get_headers(self) -> dict[str, str]:
+        """Get headers as dict."""
+        return self.headers.copy()
+
+    def update_headers(self, new_headers: dict[str, str]) -> None:
+        """Update headers with new values."""
+        self.headers.update(new_headers)
+
+    def has_authorization(self) -> bool:
+        """Check if Authorization header is present."""
+        return "Authorization" in self.headers
+
+    def to_dict(self) -> dict[str, Any]:
+        """Convert to dictionary format."""
+        return self.model_dump()

chuk_tool_processor/mcp/transport/sse_transport.py

@@ -19,6 +19,7 @@ from typing import Any
 import httpx
 
 from .base_transport import MCPBaseTransport
+from .models import TimeoutConfig, TransportMetrics
 
 logger = logging.getLogger(__name__)
 
@@ -38,7 +39,8 @@ class SSETransport(MCPBaseTransport):
         connection_timeout: float = 30.0,
         default_timeout: float = 60.0,
         enable_metrics: bool = True,
-        oauth_refresh_callback: Any | None = None,  # NEW: OAuth token refresh callback
+        oauth_refresh_callback: Any | None = None,
+        timeout_config: TimeoutConfig | None = None,
     ):
         """
         Initialize SSE transport.
@@ -46,10 +48,16 @@ class SSETransport(MCPBaseTransport):
         self.url = url.rstrip("/")
         self.api_key = api_key
         self.configured_headers = headers or {}
-        self.connection_timeout = connection_timeout
-        self.default_timeout = default_timeout
         self.enable_metrics = enable_metrics
-        self.oauth_refresh_callback = oauth_refresh_callback  # NEW: OAuth refresh callback
+        self.oauth_refresh_callback = oauth_refresh_callback
+
+        # Use timeout config or create from individual parameters
+        if timeout_config is None:
+            timeout_config = TimeoutConfig(connect=connection_timeout, operation=default_timeout)
+
+        self.timeout_config = timeout_config
+        self.connection_timeout = timeout_config.connect
+        self.default_timeout = timeout_config.operation
 
         logger.debug("SSE Transport initialized with URL: %s", self.url)
 
@@ -75,18 +83,8 @@ class SSETransport(MCPBaseTransport):
         self._connection_grace_period = 30.0  # NEW: Grace period after initialization
         self._initialization_time = None  # NEW: Track when we initialized
 
-        # Performance metrics
-        self._metrics = {
-            "total_calls": 0,
-            "successful_calls": 0,
-            "failed_calls": 0,
-            "total_time": 0.0,
-            "avg_response_time": 0.0,
-            "last_ping_time": None,
-            "initialization_time": None,
-            "session_discoveries": 0,
-            "stream_errors": 0,
-        }
+        # Performance metrics - use Pydantic model
+        self._metrics = TransportMetrics() if enable_metrics else None
 
     def _construct_sse_url(self, base_url: str) -> str:
         """Construct the SSE endpoint URL from the base URL."""
@@ -176,7 +174,7 @@ class SSETransport(MCPBaseTransport):
 
             # Wait for session discovery
             logger.debug("Waiting for session discovery...")
-            session_timeout = 10.0
+            session_timeout = self.timeout_config.connect
             session_start = time.time()
 
             while not self.message_url and (time.time() - session_start) < session_timeout:
@@ -195,8 +193,8 @@ class SSETransport(MCPBaseTransport):
                 await self._cleanup()
                 return False
 
-            if self.enable_metrics:
-                self._metrics["session_discoveries"] += 1
+            if self.enable_metrics and self._metrics:
+                self._metrics.session_discoveries += 1
 
             logger.debug("Session endpoint discovered: %s", self.message_url)
 
@@ -226,9 +224,9 @@ class SSETransport(MCPBaseTransport):
                 self._last_successful_ping = time.time()
                 self._consecutive_failures = 0  # Reset failure count
 
-                if self.enable_metrics:
+                if self.enable_metrics and self._metrics:
                     init_time = time.time() - start_time
-                    self._metrics["initialization_time"] = init_time
+                    self._metrics.initialization_time = init_time
 
                 logger.debug("SSE transport initialized successfully in %.3fs", time.time() - start_time)
                 return True
@@ -336,8 +334,8 @@ class SSETransport(MCPBaseTransport):
                         logger.debug("Non-JSON data in SSE stream (ignoring): %s", e)
 
         except Exception as e:
-            if self.enable_metrics:
-                self._metrics["stream_errors"] += 1
+            if self.enable_metrics and self._metrics:
+                self._metrics.stream_errors += 1
             logger.error("SSE stream processing error: %s", e)
             # FIXED: Don't increment consecutive failures for stream processing errors
             # These are often temporary and don't indicate connection health
@@ -421,7 +419,7 @@ class SSETransport(MCPBaseTransport):
         start_time = time.time()
         try:
             # Use tools/list as a lightweight ping since not all servers support ping
-            response = await self._send_request("tools/list", {}, timeout=10.0)
+            response = await self._send_request("tools/list", {}, timeout=self.timeout_config.quick)
 
             success = "error" not in response
 
@@ -429,9 +427,9 @@ class SSETransport(MCPBaseTransport):
                 self._last_successful_ping = time.time()
                 # FIXED: Don't reset consecutive failures here - let tool calls do that
 
-            if self.enable_metrics:
+            if self.enable_metrics and self._metrics:
                 ping_time = time.time() - start_time
-                self._metrics["last_ping_time"] = ping_time
+                self._metrics.last_ping_time = ping_time
                 logger.debug("SSE ping completed in %.3fs: %s", ping_time, success)
 
             return success
@@ -509,8 +507,8 @@ class SSETransport(MCPBaseTransport):
             return {"isError": True, "error": "Transport not initialized"}
 
         start_time = time.time()
-        if self.enable_metrics:
-            self._metrics["total_calls"] += 1
+        if self.enable_metrics and self._metrics:
+            self._metrics.total_calls += 1
 
         try:
             logger.debug("Calling tool '%s' with arguments: %s", tool_name, arguments)
@@ -528,7 +526,7 @@ class SSETransport(MCPBaseTransport):
                     logger.warning("OAuth error detected: %s", error_msg)
 
                     if self.oauth_refresh_callback:
-                        logger.info("Attempting OAuth token refresh...")
+                        logger.debug("Attempting OAuth token refresh...")
                         try:
                             # Call the refresh callback
                             new_headers = await self.oauth_refresh_callback()
@@ -536,7 +534,7 @@ class SSETransport(MCPBaseTransport):
                             if new_headers and "Authorization" in new_headers:
                                 # Update configured headers with new token
                                 self.configured_headers.update(new_headers)
-                                logger.info("OAuth token refreshed, retrying tool call...")
+                                logger.debug("OAuth token refreshed, retrying tool call...")
 
                                 # Retry the tool call once with new token
                                 response = await self._send_request(
@@ -545,7 +543,7 @@ class SSETransport(MCPBaseTransport):
 
                                 # Check if retry succeeded
                                 if "error" not in response:
-                                    logger.info("Tool call succeeded after token refresh")
+                                    logger.debug("Tool call succeeded after token refresh")
                                     result = response.get("result", {})
                                     normalized_result = self._normalize_mcp_response({"result": result})
 
@@ -592,14 +590,10 @@ class SSETransport(MCPBaseTransport):
 
     def _update_metrics(self, response_time: float, success: bool) -> None:
         """Update performance metrics."""
-        if success:
-            self._metrics["successful_calls"] += 1
-        else:
-            self._metrics["failed_calls"] += 1
+        if not self._metrics:
+            return
 
-        self._metrics["total_time"] += response_time
-        if self._metrics["total_calls"] > 0:
-            self._metrics["avg_response_time"] = self._metrics["total_time"] / self._metrics["total_calls"]
+        self._metrics.update_call_metrics(response_time, success)
 
     def _is_oauth_error(self, error_msg: str) -> bool:
         """Detect if error is OAuth-related (NEW)."""
@@ -625,7 +619,7 @@ class SSETransport(MCPBaseTransport):
             return {}
 
         try:
-            response = await self._send_request("resources/list", {}, timeout=10.0)
+            response = await self._send_request("resources/list", {}, timeout=self.timeout_config.operation)
             if "error" in response:
                 logger.debug("Resources not supported: %s", response["error"])
                 return {}
@@ -640,7 +634,7 @@ class SSETransport(MCPBaseTransport):
             return {}
 
         try:
-            response = await self._send_request("prompts/list", {}, timeout=10.0)
+            response = await self._send_request("prompts/list", {}, timeout=self.timeout_config.operation)
             if "error" in response:
                 logger.debug("Prompts not supported: %s", response["error"])
                 return {}
@@ -655,12 +649,12 @@ class SSETransport(MCPBaseTransport):
             return
 
         # Log final metrics
-        if self.enable_metrics and self._metrics["total_calls"] > 0:
+        if self.enable_metrics and self._metrics and self._metrics.total_calls > 0:
             logger.debug(
                 "SSE transport closing - Total calls: %d, Success rate: %.1f%%, Avg response time: %.3fs",
-                self._metrics["total_calls"],
-                (self._metrics["successful_calls"] / self._metrics["total_calls"] * 100),
-                self._metrics["avg_response_time"],
+                self._metrics.total_calls,
+                (self._metrics.successful_calls / self._metrics.total_calls * 100),
+                self._metrics.avg_response_time,
             )
 
         await self._cleanup()
@@ -709,7 +703,10 @@ class SSETransport(MCPBaseTransport):
 
     def get_metrics(self) -> dict[str, Any]:
         """Get performance and connection metrics with health info."""
-        metrics = self._metrics.copy()
+        if not self._metrics:
+            return {}
+
+        metrics = self._metrics.to_dict()
         metrics.update(
             {
                 "is_connected": self.is_connected(),
@@ -729,17 +726,20 @@ class SSETransport(MCPBaseTransport):
 
     def reset_metrics(self) -> None:
         """Reset performance metrics."""
-        self._metrics = {
-            "total_calls": 0,
-            "successful_calls": 0,
-            "failed_calls": 0,
-            "total_time": 0.0,
-            "avg_response_time": 0.0,
-            "last_ping_time": self._metrics.get("last_ping_time"),
-            "initialization_time": self._metrics.get("initialization_time"),
-            "session_discoveries": self._metrics.get("session_discoveries", 0),
-            "stream_errors": 0,
-        }
+        if not self._metrics:
+            return
+
+        # Preserve important historical values
+        preserved_last_ping = self._metrics.last_ping_time
+        preserved_init_time = self._metrics.initialization_time
+        preserved_discoveries = self._metrics.session_discoveries
+
+        # Create new metrics instance with preserved values
+        self._metrics = TransportMetrics(
+            last_ping_time=preserved_last_ping,
+            initialization_time=preserved_init_time,
+            session_discoveries=preserved_discoveries,
+        )
 
     def get_streams(self) -> list[tuple]:
         """SSE transport doesn't expose raw streams."""

chuk_tool_processor/mcp/transport/stdio_transport.py

@@ -200,8 +200,8 @@ class StdioTransport(MCPBaseTransport):
                 # Enhanced health verification (like SSE)
                 logger.debug("Verifying connection with ping...")
                 ping_start = time.time()
-                # Use longer timeout for slow servers
-                ping_success = await asyncio.wait_for(send_ping(*self._streams), timeout=30.0)
+                # Use default timeout for initial ping verification
+                ping_success = await asyncio.wait_for(send_ping(*self._streams), timeout=self.default_timeout)
                 ping_time = time.time() - ping_start
 
                 if ping_success:

{chuk_tool_processor-0.6.28.dist-info → chuk_tool_processor-0.6.29.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: chuk-tool-processor
-Version: 0.6.28
+Version: 0.6.29
 Summary: Async-native framework for registering, discovering, and executing tools referenced in LLM responses
 Author-email: CHUK Team <chrishayuk@somejunkmailbox.com>
 Maintainer-email: CHUK Team <chrishayuk@somejunkmailbox.com>
@@ -941,6 +941,79 @@ async def test_calculator():
 
 ## Configuration
 
+### Timeout Configuration
+
+CHUK Tool Processor uses a unified timeout configuration system that applies to all MCP transports (HTTP Streamable, SSE, STDIO) and the StreamManager. Instead of managing dozens of individual timeout values, there are just **4 logical timeout categories**:
+
+```python
+from chuk_tool_processor.mcp.transport import TimeoutConfig
+
+# Create custom timeout configuration
+timeout_config = TimeoutConfig(
+    connect=30.0,     # Connection establishment, initialization, session discovery
+    operation=30.0,   # Normal operations (tool calls, listing tools/resources/prompts)
+    quick=5.0,        # Fast health checks and pings
+    shutdown=2.0      # Cleanup and shutdown operations
+)
+```
+
+**Using timeout configuration with StreamManager:**
+
+```python
+from chuk_tool_processor.mcp.stream_manager import StreamManager
+from chuk_tool_processor.mcp.transport import TimeoutConfig
+
+# Create StreamManager with custom timeouts
+timeout_config = TimeoutConfig(
+    connect=60.0,     # Longer for slow initialization
+    operation=45.0,   # Longer for heavy operations
+    quick=3.0,        # Faster health checks
+    shutdown=5.0      # More time for cleanup
+)
+
+manager = StreamManager(timeout_config=timeout_config)
+```
+
+**Timeout categories explained:**
+
+| Category | Default | Used For | Examples |
+|----------|---------|----------|----------|
+| `connect` | 30.0s | Connection setup, initialization, discovery | HTTP connection, SSE session discovery, STDIO subprocess launch |
+| `operation` | 30.0s | Normal tool operations | Tool calls, listing tools/resources/prompts, get_tools() |
+| `quick` | 5.0s | Fast health/status checks | Ping operations, health checks |
+| `shutdown` | 2.0s | Cleanup and teardown | Transport close, connection cleanup |
+
+**Why this matters:**
+- ✅ **Simple**: 4 timeout values instead of 20+
+- ✅ **Consistent**: Same timeout behavior across all transports
+- ✅ **Configurable**: Adjust timeouts based on your environment (slow networks, large datasets, etc.)
+- ✅ **Type-safe**: Pydantic validation ensures correct values
+
+**Example: Adjusting for slow environments**
+
+```python
+from chuk_tool_processor.mcp import setup_mcp_stdio
+from chuk_tool_processor.mcp.transport import TimeoutConfig
+
+# For slow network or resource-constrained environments
+slow_timeouts = TimeoutConfig(
+    connect=120.0,    # Allow more time for package downloads
+    operation=60.0,   # Allow more time for heavy operations
+    quick=10.0,       # Be patient with health checks
+    shutdown=10.0     # Allow thorough cleanup
+)
+
+processor, manager = await setup_mcp_stdio(
+    config_file="mcp_config.json",
+    servers=["sqlite"],
+    namespace="db",
+    initialization_timeout=120.0
+)
+
+# Set custom timeouts on the manager
+manager.timeout_config = slow_timeouts
+```
+
 ### Environment Variables
 
 | Variable | Default | Description |

{chuk_tool_processor-0.6.28.dist-info → chuk_tool_processor-0.6.29.dist-info}/RECORD

@@ -17,17 +17,18 @@ chuk_tool_processor/logging/formatter.py,sha256=gxbkfR-J-ksRiNfxUijVm4iHUd6OAau-
 chuk_tool_processor/logging/helpers.py,sha256=207AXMHGlw6kq1cFiwLOJRGYgzuuKvTWn94aCJvZZXs,5751
 chuk_tool_processor/logging/metrics.py,sha256=8LRHjgkfdcQnh4H7AP2FJDfcRO3q1UpsBSwoHiuUqXY,3524
 chuk_tool_processor/mcp/__init__.py,sha256=xqtoSGX1_5jZDJ6AKJpBByaytS22baDOrhzFiecvVSs,1031
-chuk_tool_processor/mcp/mcp_tool.py,sha256=zOx3YeuKyuFK-PbUt3gqdq_q8VRrHFD6sgma6qKbfPY,19170
+chuk_tool_processor/mcp/mcp_tool.py,sha256=qCLyapwbGtqUFj7-pTIov9XJEBV8dL_qEpprjcjXWAk,19175
 chuk_tool_processor/mcp/register_mcp_tools.py,sha256=OyHczwVnqhvBZO9g4I0T56EPMvFYBOl0Y2ivNPdKjCE,4822
 chuk_tool_processor/mcp/setup_mcp_http_streamable.py,sha256=8NCjeEZjV0KrapCqAvGh6jr5G8B24xOxxAaKUyoiykw,4935
 chuk_tool_processor/mcp/setup_mcp_sse.py,sha256=gvixVml8HN2BdM9Ug_JYp0yHqA1owieyX8Yxx0HNOqg,4174
 chuk_tool_processor/mcp/setup_mcp_stdio.py,sha256=KxCC0BL0C6z5ZHxBzPhWZC9CKrGUACXqx1tkjru-UYI,2922
-chuk_tool_processor/mcp/stream_manager.py,sha256=BA1vhk6azGg-Yt4N2iyqIT3ryvwqoq2ncRNuLMmStkk,34120
-chuk_tool_processor/mcp/transport/__init__.py,sha256=Gpw9QZctxfO-tWZ8URpyFU8rePc5Xe7VZiAvXaiF8cw,657
+chuk_tool_processor/mcp/stream_manager.py,sha256=398j65oGvMMwi_EC9qS2EPHXvGefUDJ4IR9Tkg4jaGY,34781
+chuk_tool_processor/mcp/transport/__init__.py,sha256=od-7f_cYv31_ioZCJu57ozA8IXywMyf-0N4HlM2J_bU,841
 chuk_tool_processor/mcp/transport/base_transport.py,sha256=rG61TlaignbVZbsqdBS38TnFzTVO666ehKEI0IUAJCM,8675
-chuk_tool_processor/mcp/transport/http_streamable_transport.py,sha256=aE-ITNoT-iipJ5tF97eGzv3hxABnbfFpjPokbCsy1rg,26545
-chuk_tool_processor/mcp/transport/sse_transport.py,sha256=BCd2e8QlIQN0qaPBAC9w0Q9ybOXnRdg8GUkKZ6Oo4k0,30635
-chuk_tool_processor/mcp/transport/stdio_transport.py,sha256=kS90NpQA-KdxRdH-hYN63P22vc0fF4MvQ4N2spo8U6k,29558
+chuk_tool_processor/mcp/transport/http_streamable_transport.py,sha256=m2_SXHWeFT2fEfpGY88YYLOQIS88YNVWxJtyWK7kJF0,27231
+chuk_tool_processor/mcp/transport/models.py,sha256=nve0EMHXMzRIzZNdWpK_QyWSYidUF088GvQHZsmI_Eo,3994
+chuk_tool_processor/mcp/transport/sse_transport.py,sha256=CDAVutW6X4ykgJipJAfTt4JEEpzwKteM8vV5AtRX3z4,30781
+chuk_tool_processor/mcp/transport/stdio_transport.py,sha256=SHECMFlFxmT6XKLJ9FC1arXCO4t1yMr6kfNz7QpRQew,29588
 chuk_tool_processor/models/__init__.py,sha256=A3ysSvRxaxso_AN57QZt5ZYahJH5zlL-IENqNaius84,41
 chuk_tool_processor/models/execution_strategy.py,sha256=O0h8d8JSgm-tv26Cc5jAkZqup8vIgx0zfb5n0b2vpSk,1967
 chuk_tool_processor/models/streaming_tool.py,sha256=3IXe9VV6sgPHzMeHpuNzZThFhu5BuB3MQdoYSogz348,3359
@@ -54,7 +55,7 @@ chuk_tool_processor/registry/providers/__init__.py,sha256=iGc_2JzlYJSBRQ6tFbX781
 chuk_tool_processor/registry/providers/memory.py,sha256=udfboAHH0gRxtnf3GsI3wMshhobJxYnCkMwKjQ_uqkw,5017
 chuk_tool_processor/utils/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 chuk_tool_processor/utils/validation.py,sha256=jHPO65sB61ynm9P6V3th4pN7j4u0SQhYR-bstj5QjnI,4175
-chuk_tool_processor-0.6.28.dist-info/METADATA,sha256=6GwYbhRhrVlOCYCd0fX9fMkHuBniPUEIDhp4byjdrdg,39362
-chuk_tool_processor-0.6.28.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-chuk_tool_processor-0.6.28.dist-info/top_level.txt,sha256=7lTsnuRx4cOW4U2sNJWNxl4ZTt_J1ndkjTbj3pHPY5M,20
-chuk_tool_processor-0.6.28.dist-info/RECORD,,
+chuk_tool_processor-0.6.29.dist-info/METADATA,sha256=_kc0aseQ8XgB6T3HzaIzxhp9LTh8z7ZgnDMJ9intc2M,42164
+chuk_tool_processor-0.6.29.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+chuk_tool_processor-0.6.29.dist-info/top_level.txt,sha256=7lTsnuRx4cOW4U2sNJWNxl4ZTt_J1ndkjTbj3pHPY5M,20
+chuk_tool_processor-0.6.29.dist-info/RECORD,,