chuk-tool-processor 0.6.26__tar.gz → 0.6.28__tar.gz

{chuk_tool_processor-0.6.26 → chuk_tool_processor-0.6.28}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: chuk-tool-processor
-Version: 0.6.26
+Version: 0.6.28
 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>
@@ -770,6 +770,78 @@ results = await processor.process(
 
 See `examples/notion_oauth.py`, `examples/stdio_sqlite.py`, and `examples/stdio_echo.py` for complete working implementations.
 
+#### OAuth Token Refresh
+
+For MCP servers that use OAuth authentication, CHUK Tool Processor supports automatic token refresh when access tokens expire. This prevents your tools from failing due to expired tokens during long-running sessions.
+
+**How it works:**
+1. When a tool call receives an OAuth-related error (e.g., "invalid_token", "expired token", "unauthorized")
+2. The processor automatically calls your refresh callback
+3. Updates the authentication headers with the new token
+4. Retries the tool call with fresh credentials
+
+**Setup with HTTP Streamable:**
+
+```python
+from chuk_tool_processor.mcp import setup_mcp_http_streamable
+
+async def refresh_oauth_token():
+    """Called automatically when tokens expire."""
+    # Your token refresh logic here
+    # Return dict with new Authorization header
+    new_token = await your_refresh_logic()
+    return {"Authorization": f"Bearer {new_token}"}
+
+processor, manager = await setup_mcp_http_streamable(
+    servers=[{
+        "name": "notion",
+        "url": "https://mcp.notion.com/mcp",
+        "headers": {"Authorization": f"Bearer {initial_access_token}"}
+    }],
+    namespace="notion",
+    oauth_refresh_callback=refresh_oauth_token  # Enable auto-refresh
+)
+```
+
+**Setup with SSE:**
+
+```python
+from chuk_tool_processor.mcp import setup_mcp_sse
+
+async def refresh_oauth_token():
+    """Refresh expired OAuth token."""
+    # Exchange refresh token for new access token
+    new_access_token = await exchange_refresh_token(refresh_token)
+    return {"Authorization": f"Bearer {new_access_token}"}
+
+processor, manager = await setup_mcp_sse(
+    servers=[{
+        "name": "atlassian",
+        "url": "https://mcp.atlassian.com/v1/sse",
+        "headers": {"Authorization": f"Bearer {initial_token}"}
+    }],
+    namespace="atlassian",
+    oauth_refresh_callback=refresh_oauth_token
+)
+```
+
+**OAuth errors detected automatically:**
+- `invalid_token`
+- `expired token`
+- `OAuth validation failed`
+- `unauthorized`
+- `token expired`
+- `authentication failed`
+- `invalid access token`
+
+**Important notes:**
+- The refresh callback must return a dict with an `Authorization` key
+- If refresh fails or returns invalid headers, the original error is returned
+- Token refresh is attempted only once per tool call (no infinite retry loops)
+- After successful refresh, the updated headers are used for all subsequent calls
+
+See `examples/notion_oauth.py` for a complete OAuth 2.1 implementation with PKCE and automatic token refresh.
+
 ### Observability
 
 #### Structured Logging

{chuk_tool_processor-0.6.26 → chuk_tool_processor-0.6.28}/README.md

@@ -742,6 +742,78 @@ results = await processor.process(
 
 See `examples/notion_oauth.py`, `examples/stdio_sqlite.py`, and `examples/stdio_echo.py` for complete working implementations.
 
+#### OAuth Token Refresh
+
+For MCP servers that use OAuth authentication, CHUK Tool Processor supports automatic token refresh when access tokens expire. This prevents your tools from failing due to expired tokens during long-running sessions.
+
+**How it works:**
+1. When a tool call receives an OAuth-related error (e.g., "invalid_token", "expired token", "unauthorized")
+2. The processor automatically calls your refresh callback
+3. Updates the authentication headers with the new token
+4. Retries the tool call with fresh credentials
+
+**Setup with HTTP Streamable:**
+
+```python
+from chuk_tool_processor.mcp import setup_mcp_http_streamable
+
+async def refresh_oauth_token():
+    """Called automatically when tokens expire."""
+    # Your token refresh logic here
+    # Return dict with new Authorization header
+    new_token = await your_refresh_logic()
+    return {"Authorization": f"Bearer {new_token}"}
+
+processor, manager = await setup_mcp_http_streamable(
+    servers=[{
+        "name": "notion",
+        "url": "https://mcp.notion.com/mcp",
+        "headers": {"Authorization": f"Bearer {initial_access_token}"}
+    }],
+    namespace="notion",
+    oauth_refresh_callback=refresh_oauth_token  # Enable auto-refresh
+)
+```
+
+**Setup with SSE:**
+
+```python
+from chuk_tool_processor.mcp import setup_mcp_sse
+
+async def refresh_oauth_token():
+    """Refresh expired OAuth token."""
+    # Exchange refresh token for new access token
+    new_access_token = await exchange_refresh_token(refresh_token)
+    return {"Authorization": f"Bearer {new_access_token}"}
+
+processor, manager = await setup_mcp_sse(
+    servers=[{
+        "name": "atlassian",
+        "url": "https://mcp.atlassian.com/v1/sse",
+        "headers": {"Authorization": f"Bearer {initial_token}"}
+    }],
+    namespace="atlassian",
+    oauth_refresh_callback=refresh_oauth_token
+)
+```
+
+**OAuth errors detected automatically:**
+- `invalid_token`
+- `expired token`
+- `OAuth validation failed`
+- `unauthorized`
+- `token expired`
+- `authentication failed`
+- `invalid access token`
+
+**Important notes:**
+- The refresh callback must return a dict with an `Authorization` key
+- If refresh fails or returns invalid headers, the original error is returned
+- Token refresh is attempted only once per tool call (no infinite retry loops)
+- After successful refresh, the updated headers are used for all subsequent calls
+
+See `examples/notion_oauth.py` for a complete OAuth 2.1 implementation with PKCE and automatic token refresh.
+
 ### Observability
 
 #### Structured Logging

{chuk_tool_processor-0.6.26 → chuk_tool_processor-0.6.28}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "chuk-tool-processor"
-version = "0.6.26"
+version = "0.6.28"
 description = "Async-native framework for registering, discovering, and executing tools referenced in LLM responses"
 readme = "README.md"
 requires-python = ">=3.11"

{chuk_tool_processor-0.6.26 → chuk_tool_processor-0.6.28}/src/chuk_tool_processor/core/processor.py

@@ -260,7 +260,7 @@ class ToolProcessor:
                         unknown_tools.append(call.tool)
 
                 if unknown_tools:
-                    self.logger.warning(f"Unknown tools: {unknown_tools}")
+                    self.logger.debug(f"Unknown tools: {unknown_tools}")
 
                 # Execute tools
                 results = await self.executor.execute(calls, timeout=timeout)
@@ -412,7 +412,7 @@ class ToolProcessor:
                     duration=duration,
                     num_calls=0,
                 )
-                self.logger.error(f"Parser {parser_name} failed: {str(e)}")
+                self.logger.debug(f"Parser {parser_name} failed: {str(e)}")
                 return []
 
 

{chuk_tool_processor-0.6.26 → chuk_tool_processor-0.6.28}/src/chuk_tool_processor/mcp/setup_mcp_http_streamable.py

@@ -44,6 +44,7 @@ async def setup_mcp_http_streamable(
     enable_retries: bool = True,
     max_retries: int = 3,
     namespace: str = "http",
+    oauth_refresh_callback: any | None = None,  # NEW: OAuth token refresh callback
 ) -> tuple[ToolProcessor, StreamManager]:
     """
     Initialize HTTP Streamable transport MCP + a :class:`ToolProcessor`.
@@ -69,6 +70,7 @@ async def setup_mcp_http_streamable(
         enable_retries: Whether to enable automatic retries
         max_retries: Maximum retry attempts
         namespace: Namespace for registered tools
+        oauth_refresh_callback: Optional async callback to refresh OAuth tokens (NEW)
 
     Returns:
         Tuple of (ToolProcessor, StreamManager)
@@ -93,6 +95,7 @@ async def setup_mcp_http_streamable(
         connection_timeout=connection_timeout,
         default_timeout=default_timeout,
         initialization_timeout=initialization_timeout,
+        oauth_refresh_callback=oauth_refresh_callback,  # NEW: Pass OAuth callback
     )
 
     # 2️⃣  pull the remote tool list and register each one locally

{chuk_tool_processor-0.6.26 → chuk_tool_processor-0.6.28}/src/chuk_tool_processor/mcp/setup_mcp_sse.py

@@ -40,6 +40,7 @@ async def setup_mcp_sse(  # noqa: C901 - long but just a config facade
     enable_retries: bool = True,
     max_retries: int = 3,
     namespace: str = "sse",
+    oauth_refresh_callback: any | None = None,  # NEW: OAuth token refresh callback
 ) -> tuple[ToolProcessor, StreamManager]:
     """
     Initialise SSE-transport MCP + a :class:`ToolProcessor`.
@@ -61,6 +62,7 @@ async def setup_mcp_sse(  # noqa: C901 - long but just a config facade
         enable_retries: Whether to enable automatic retries
         max_retries: Maximum retry attempts
         namespace: Namespace for registered tools
+        oauth_refresh_callback: Optional async callback to refresh OAuth tokens (NEW)
 
     Returns:
         Tuple of (ToolProcessor, StreamManager)
@@ -72,6 +74,7 @@ async def setup_mcp_sse(  # noqa: C901 - long but just a config facade
         connection_timeout=connection_timeout,  # 🔧 ADD THIS LINE
         default_timeout=default_timeout,  # 🔧 ADD THIS LINE
         initialization_timeout=initialization_timeout,
+        oauth_refresh_callback=oauth_refresh_callback,  # NEW: Pass OAuth callback
     )
 
     # 2️⃣  pull the remote tool list and register each one locally

{chuk_tool_processor-0.6.26 → chuk_tool_processor-0.6.28}/src/chuk_tool_processor/mcp/stream_manager.py

@@ -81,6 +81,7 @@ class StreamManager:
         connection_timeout: float = 10.0,
         default_timeout: float = 30.0,
         initialization_timeout: float = 60.0,  # NEW
+        oauth_refresh_callback: any | None = None,  # NEW: OAuth token refresh callback
     ) -> StreamManager:
         """Create StreamManager with SSE transport and timeout protection."""
         inst = cls()
@@ -90,6 +91,7 @@ class StreamManager:
             connection_timeout=connection_timeout,
             default_timeout=default_timeout,
             initialization_timeout=initialization_timeout,
+            oauth_refresh_callback=oauth_refresh_callback,  # NEW: Pass OAuth callback
         )
         return inst
 
@@ -101,6 +103,7 @@ class StreamManager:
         connection_timeout: float = 30.0,
         default_timeout: float = 30.0,
         initialization_timeout: float = 60.0,  # NEW
+        oauth_refresh_callback: any | None = None,  # NEW: OAuth token refresh callback
     ) -> StreamManager:
         """Create StreamManager with HTTP Streamable transport and timeout protection."""
         inst = cls()
@@ -110,6 +113,7 @@ class StreamManager:
             connection_timeout=connection_timeout,
             default_timeout=default_timeout,
             initialization_timeout=initialization_timeout,
+            oauth_refresh_callback=oauth_refresh_callback,  # NEW: Pass OAuth callback
         )
         return inst
 
@@ -178,7 +182,7 @@ class StreamManager:
                             params, connection_timeout=initialization_timeout, default_timeout=default_timeout
                         )
                     elif transport_type == "sse":
-                        logger.warning(
+                        logger.debug(
                             "Using SSE transport in initialize() - consider using initialize_with_sse() instead"
                         )
                         params = await load_config(config_file, server_name)
@@ -191,7 +195,7 @@ class StreamManager:
                             sse_url = "http://localhost:8000"
                             api_key = None
                             headers = {}
-                            logger.warning("No URL configured for SSE transport, using default: %s", sse_url)
+                            logger.debug("No URL configured for SSE transport, using default: %s", sse_url)
 
                         # Build SSE transport with optional headers
                         transport_params = {"url": sse_url, "api_key": api_key, "default_timeout": default_timeout}
@@ -201,7 +205,7 @@ class StreamManager:
                         transport = SSETransport(**transport_params)
 
                     elif transport_type == "http_streamable":
-                        logger.warning(
+                        logger.debug(
                             "Using HTTP Streamable transport in initialize() - consider using initialize_with_http_streamable() instead"
                         )
                         params = await load_config(config_file, server_name)
@@ -216,9 +220,7 @@ class StreamManager:
                             api_key = None
                             headers = {}
                             session_id = None
-                            logger.warning(
-                                "No URL configured for HTTP Streamable transport, using default: %s", http_url
-                            )
+                            logger.debug("No URL configured for HTTP Streamable transport, using default: %s", http_url)
 
                         # Build HTTP transport (headers not supported yet)
                         transport_params = {
@@ -240,7 +242,7 @@ class StreamManager:
                     # Initialize with timeout protection
                     try:
                         if not await asyncio.wait_for(transport.initialize(), timeout=initialization_timeout):
-                            logger.error("Failed to init %s", server_name)
+                            logger.warning("Failed to init %s", server_name)
                             continue
                     except TimeoutError:
                         logger.error("Timeout initialising %s (timeout=%ss)", server_name, initialization_timeout)
@@ -285,6 +287,7 @@ class StreamManager:
         connection_timeout: float = 10.0,
         default_timeout: float = 30.0,
         initialization_timeout: float = 60.0,
+        oauth_refresh_callback: any | None = None,  # NEW: OAuth token refresh callback
     ) -> None:
         """Initialize with SSE transport with optional headers support."""
         if self._closed:
@@ -313,11 +316,16 @@ class StreamManager:
                         logger.debug("SSE %s: Using configured headers: %s", name, list(headers.keys()))
                         transport_params["headers"] = headers
 
+                    # Add OAuth refresh callback if provided (NEW)
+                    if oauth_refresh_callback:
+                        transport_params["oauth_refresh_callback"] = oauth_refresh_callback
+                        logger.debug("SSE %s: OAuth refresh callback configured", name)
+
                     transport = SSETransport(**transport_params)
 
                     try:
                         if not await asyncio.wait_for(transport.initialize(), timeout=initialization_timeout):
-                            logger.error("Failed to init SSE %s", name)
+                            logger.warning("Failed to init SSE %s", name)
                             continue
                     except TimeoutError:
                         logger.error("Timeout initialising SSE %s (timeout=%ss)", name, initialization_timeout)
@@ -354,6 +362,7 @@ class StreamManager:
         connection_timeout: float = 30.0,
         default_timeout: float = 30.0,
         initialization_timeout: float = 60.0,
+        oauth_refresh_callback: any | None = None,  # NEW: OAuth token refresh callback
     ) -> None:
         """Initialize with HTTP Streamable transport with graceful headers handling."""
         if self._closed:
@@ -385,12 +394,17 @@ class StreamManager:
                         transport_params["headers"] = headers
                         logger.debug("HTTP Streamable %s: Custom headers configured: %s", name, list(headers.keys()))
 
+                    # Add OAuth refresh callback if provided (NEW)
+                    if oauth_refresh_callback:
+                        transport_params["oauth_refresh_callback"] = oauth_refresh_callback
+                        logger.debug("HTTP Streamable %s: OAuth refresh callback configured", name)
+
                     transport = HTTPStreamableTransport(**transport_params)
 
                     logger.debug(f"Calling transport.initialize() for {name} with timeout={initialization_timeout}s")
                     try:
                         if not await asyncio.wait_for(transport.initialize(), timeout=initialization_timeout):
-                            logger.error("Failed to init HTTP Streamable %s", name)
+                            logger.warning("Failed to init HTTP Streamable %s", name)
                             continue
                     except TimeoutError:
                         logger.error(

{chuk_tool_processor-0.6.26 → chuk_tool_processor-0.6.28}/src/chuk_tool_processor/mcp/transport/http_streamable_transport.py

@@ -45,6 +45,7 @@ class HTTPStreamableTransport(MCPBaseTransport):
         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
     ):
         """
         Initialize HTTP Streamable transport with enhanced configuration.
@@ -57,6 +58,7 @@ class HTTPStreamableTransport(MCPBaseTransport):
             default_timeout: Default timeout for operations
             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)
         """
         # Ensure URL points to the /mcp endpoint
         if not url.endswith("/mcp"):
@@ -70,6 +72,7 @@ class HTTPStreamableTransport(MCPBaseTransport):
         self.default_timeout = default_timeout
         self.session_id = session_id
         self.enable_metrics = enable_metrics
+        self.oauth_refresh_callback = oauth_refresh_callback  # NEW: OAuth refresh callback
 
         logger.debug("HTTP Streamable transport initialized with URL: %s", self.url)
         if self.api_key:
@@ -226,7 +229,7 @@ class HTTPStreamableTransport(MCPBaseTransport):
                 )
                 return True
             else:
-                logger.warning("HTTP connection established but ping failed")
+                logger.debug("HTTP connection established but ping failed")
                 # Still consider it initialized since connection was established
                 self._initialized = True
                 self._consecutive_failures = 1  # Mark one failure
@@ -302,7 +305,7 @@ class HTTPStreamableTransport(MCPBaseTransport):
     async def send_ping(self) -> bool:
         """Enhanced ping with health monitoring (like SSE)."""
         if not self._initialized or not self._read_stream:
-            logger.error("Cannot send ping: transport not initialized")
+            logger.debug("Cannot send ping: transport not initialized")
             return False
 
         start_time = time.time()
@@ -352,7 +355,7 @@ class HTTPStreamableTransport(MCPBaseTransport):
     async def get_tools(self) -> list[dict[str, Any]]:
         """Enhanced tools retrieval with error handling."""
         if not self._initialized:
-            logger.error("Cannot get tools: transport not initialized")
+            logger.debug("Cannot get tools: transport not initialized")
             return []
 
         start_time = time.time()
@@ -422,9 +425,44 @@ class HTTPStreamableTransport(MCPBaseTransport):
             response_time = time.time() - start_time
             result = self._normalize_mcp_response(raw_response)
 
+            # NEW: Check for OAuth errors and attempt refresh if callback is available
+            if result.get("isError", False) and self._is_oauth_error(result.get("error", "")):
+                logger.warning("OAuth error detected: %s", result.get("error"))
+
+                if self.oauth_refresh_callback:
+                    logger.info("Attempting OAuth token refresh...")
+                    try:
+                        # Call the refresh callback
+                        new_headers = await self.oauth_refresh_callback()
+
+                        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...")
+
+                            # Reconnect with new token
+                            if await self._attempt_recovery():
+                                logger.info("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")
+                            else:
+                                logger.error("Failed to reconnect after token refresh")
+                        else:
+                            logger.warning("Token refresh did not return valid Authorization header")
+                    except Exception as refresh_error:
+                        logger.error("OAuth token refresh failed: %s", refresh_error)
+                else:
+                    logger.warning("OAuth error detected but no refresh callback configured")
+
             # Reset failure count on success
-            self._consecutive_failures = 0
-            self._last_successful_ping = time.time()  # Update health timestamp
+            if not result.get("isError", False):
+                self._consecutive_failures = 0
+                self._last_successful_ping = time.time()  # Update health timestamp
 
             if self.enable_metrics:
                 self._update_metrics(response_time, not result.get("isError", False))
@@ -477,6 +515,24 @@ class HTTPStreamableTransport(MCPBaseTransport):
         if self._metrics["total_calls"] > 0:
             self._metrics["avg_response_time"] = self._metrics["total_time"] / self._metrics["total_calls"]
 
+    def _is_oauth_error(self, error_msg: str) -> bool:
+        """Detect if error is OAuth-related (NEW)."""
+        if not error_msg:
+            return False
+
+        error_lower = error_msg.lower()
+        oauth_indicators = [
+            "invalid_token",
+            "expired token",
+            "oauth validation",
+            "unauthorized",
+            "token expired",
+            "authentication failed",
+            "invalid access token",
+        ]
+
+        return any(indicator in error_lower for indicator in oauth_indicators)
+
     async def list_resources(self) -> dict[str, Any]:
         """Enhanced resource listing with error handling."""
         if not self._initialized:

{chuk_tool_processor-0.6.26 → chuk_tool_processor-0.6.28}/src/chuk_tool_processor/mcp/transport/sse_transport.py

@@ -38,6 +38,7 @@ 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
     ):
         """
         Initialize SSE transport.
@@ -48,6 +49,7 @@ class SSETransport(MCPBaseTransport):
         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
 
         logger.debug("SSE Transport initialized with URL: %s", self.url)
 
@@ -184,12 +186,12 @@ class SSETransport(MCPBaseTransport):
                 if self.sse_task.done():
                     exception = self.sse_task.exception()
                     if exception:
-                        logger.error(f"SSE task died during session discovery: {exception}")
+                        logger.debug(f"SSE task died during session discovery: {exception}")
                         await self._cleanup()
                         return False
 
             if not self.message_url:
-                logger.error("Failed to discover session endpoint within %.1fs", session_timeout)
+                logger.warning("Failed to discover session endpoint within %.1fs", session_timeout)
                 await self._cleanup()
                 return False
 
@@ -211,7 +213,7 @@ class SSETransport(MCPBaseTransport):
                 )
 
                 if "error" in init_response:
-                    logger.error("MCP initialize failed: %s", init_response["error"])
+                    logger.warning("MCP initialize failed: %s", init_response["error"])
                     await self._cleanup()
                     return False
 
@@ -476,7 +478,7 @@ class SSETransport(MCPBaseTransport):
     async def get_tools(self) -> list[dict[str, Any]]:
         """Get list of available tools from the server."""
         if not self._initialized:
-            logger.error("Cannot get tools: transport not initialized")
+            logger.debug("Cannot get tools: transport not initialized")
             return []
 
         start_time = time.time()
@@ -484,7 +486,7 @@ class SSETransport(MCPBaseTransport):
             response = await self._send_request("tools/list", {})
 
             if "error" in response:
-                logger.error("Error getting tools: %s", response["error"])
+                logger.warning("Error getting tools: %s", response["error"])
                 return []
 
             tools = response.get("result", {}).get("tools", [])
@@ -517,11 +519,55 @@ class SSETransport(MCPBaseTransport):
                 "tools/call", {"name": tool_name, "arguments": arguments}, timeout=timeout
             )
 
+            # Check for errors
             if "error" in response:
+                error_msg = response["error"].get("message", "Unknown error")
+
+                # NEW: Check for OAuth errors and attempt refresh if callback is available
+                if self._is_oauth_error(error_msg):
+                    logger.warning("OAuth error detected: %s", error_msg)
+
+                    if self.oauth_refresh_callback:
+                        logger.info("Attempting OAuth token refresh...")
+                        try:
+                            # Call the refresh callback
+                            new_headers = await self.oauth_refresh_callback()
+
+                            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...")
+
+                                # Retry the tool call once with new token
+                                response = await self._send_request(
+                                    "tools/call", {"name": tool_name, "arguments": arguments}, timeout=timeout
+                                )
+
+                                # Check if retry succeeded
+                                if "error" not in response:
+                                    logger.info("Tool call succeeded after token refresh")
+                                    result = response.get("result", {})
+                                    normalized_result = self._normalize_mcp_response({"result": result})
+
+                                    if self.enable_metrics:
+                                        self._update_metrics(time.time() - start_time, True)
+
+                                    return normalized_result
+                                else:
+                                    error_msg = response["error"].get("message", "Unknown error")
+                                    logger.error("Tool call failed after token refresh: %s", error_msg)
+                            else:
+                                logger.warning("Token refresh did not return valid Authorization header")
+                        except Exception as refresh_error:
+                            logger.error("OAuth token refresh failed: %s", refresh_error)
+                    else:
+                        logger.warning("OAuth error detected but no refresh callback configured")
+
+                # Return error (original or from failed retry)
                 if self.enable_metrics:
                     self._update_metrics(time.time() - start_time, False)
 
-                return {"isError": True, "error": response["error"].get("message", "Unknown error")}
+                return {"isError": True, "error": error_msg}
 
             # Extract and normalize result using base class method
             result = response.get("result", {})
@@ -555,6 +601,24 @@ class SSETransport(MCPBaseTransport):
         if self._metrics["total_calls"] > 0:
             self._metrics["avg_response_time"] = self._metrics["total_time"] / self._metrics["total_calls"]
 
+    def _is_oauth_error(self, error_msg: str) -> bool:
+        """Detect if error is OAuth-related (NEW)."""
+        if not error_msg:
+            return False
+
+        error_lower = error_msg.lower()
+        oauth_indicators = [
+            "invalid_token",
+            "expired token",
+            "oauth validation",
+            "unauthorized",
+            "token expired",
+            "authentication failed",
+            "invalid access token",
+        ]
+
+        return any(indicator in error_lower for indicator in oauth_indicators)
+
     async def list_resources(self) -> dict[str, Any]:
         """List available resources from the server."""
         if not self._initialized:

{chuk_tool_processor-0.6.26 → chuk_tool_processor-0.6.28}/src/chuk_tool_processor/mcp/transport/stdio_transport.py

@@ -221,7 +221,7 @@ class StdioTransport(MCPBaseTransport):
                     )
                     return True
                 else:
-                    logger.warning("STDIO connection established but ping failed")
+                    logger.debug("STDIO connection established but ping failed")
                     # Still consider it initialized
                     self._initialized = True
                     self._consecutive_failures = 1
@@ -229,7 +229,7 @@ class StdioTransport(MCPBaseTransport):
                         self._metrics["initialization_time"] = time.time() - start_time
                     return True
             else:
-                logger.error("STDIO initialization failed")
+                logger.warning("STDIO initialization failed")
                 await self._cleanup()
                 return False
 
@@ -382,7 +382,7 @@ class StdioTransport(MCPBaseTransport):
     async def get_tools(self) -> list[dict[str, Any]]:
         """Enhanced tools retrieval with recovery."""
         if not self._initialized:
-            logger.error("Cannot get tools: transport not initialized")
+            logger.debug("Cannot get tools: transport not initialized")
             return []
 
         start_time = time.time()

{chuk_tool_processor-0.6.26 → chuk_tool_processor-0.6.28}/src/chuk_tool_processor/plugins/discovery.py

@@ -121,7 +121,7 @@ class PluginDiscovery:
         # ------------------- Parser plugins -------------------------
         if issubclass(cls, ParserPlugin) and cls is not ParserPlugin:
             if not inspect.iscoroutinefunction(getattr(cls, "try_parse", None)):
-                logger.warning("Skipping parser plugin %s: try_parse is not async", cls.__qualname__)
+                logger.debug("Skipping parser plugin %s: try_parse is not async", cls.__qualname__)
             else:
                 try:
                     self._registry.register_plugin("parser", cls.__name__, cls())

{chuk_tool_processor-0.6.26 → chuk_tool_processor-0.6.28}/src/chuk_tool_processor.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: chuk-tool-processor
-Version: 0.6.26
+Version: 0.6.28
 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>
@@ -770,6 +770,78 @@ results = await processor.process(
 
 See `examples/notion_oauth.py`, `examples/stdio_sqlite.py`, and `examples/stdio_echo.py` for complete working implementations.
 
+#### OAuth Token Refresh
+
+For MCP servers that use OAuth authentication, CHUK Tool Processor supports automatic token refresh when access tokens expire. This prevents your tools from failing due to expired tokens during long-running sessions.
+
+**How it works:**
+1. When a tool call receives an OAuth-related error (e.g., "invalid_token", "expired token", "unauthorized")
+2. The processor automatically calls your refresh callback
+3. Updates the authentication headers with the new token
+4. Retries the tool call with fresh credentials
+
+**Setup with HTTP Streamable:**
+
+```python
+from chuk_tool_processor.mcp import setup_mcp_http_streamable
+
+async def refresh_oauth_token():
+    """Called automatically when tokens expire."""
+    # Your token refresh logic here
+    # Return dict with new Authorization header
+    new_token = await your_refresh_logic()
+    return {"Authorization": f"Bearer {new_token}"}
+
+processor, manager = await setup_mcp_http_streamable(
+    servers=[{
+        "name": "notion",
+        "url": "https://mcp.notion.com/mcp",
+        "headers": {"Authorization": f"Bearer {initial_access_token}"}
+    }],
+    namespace="notion",
+    oauth_refresh_callback=refresh_oauth_token  # Enable auto-refresh
+)
+```
+
+**Setup with SSE:**
+
+```python
+from chuk_tool_processor.mcp import setup_mcp_sse
+
+async def refresh_oauth_token():
+    """Refresh expired OAuth token."""
+    # Exchange refresh token for new access token
+    new_access_token = await exchange_refresh_token(refresh_token)
+    return {"Authorization": f"Bearer {new_access_token}"}
+
+processor, manager = await setup_mcp_sse(
+    servers=[{
+        "name": "atlassian",
+        "url": "https://mcp.atlassian.com/v1/sse",
+        "headers": {"Authorization": f"Bearer {initial_token}"}
+    }],
+    namespace="atlassian",
+    oauth_refresh_callback=refresh_oauth_token
+)
+```
+
+**OAuth errors detected automatically:**
+- `invalid_token`
+- `expired token`
+- `OAuth validation failed`
+- `unauthorized`
+- `token expired`
+- `authentication failed`
+- `invalid access token`
+
+**Important notes:**
+- The refresh callback must return a dict with an `Authorization` key
+- If refresh fails or returns invalid headers, the original error is returned
+- Token refresh is attempted only once per tool call (no infinite retry loops)
+- After successful refresh, the updated headers are used for all subsequent calls
+
+See `examples/notion_oauth.py` for a complete OAuth 2.1 implementation with PKCE and automatic token refresh.
+
 ### Observability
 
 #### Structured Logging