Introduce REQUEST_TIMEOUT_SECONDS constant: replace hardcoded timeouts and improve error message clarity for timeout scenarios

Author: rodion-m

src/core/__init__.py

@@ -1,14 +1,15 @@
 """Core components for CodeAlive MCP server."""
 
 from .client import CodeAliveContext, get_api_key_from_context, codealive_lifespan
-from .config import Config
+from .config import Config, REQUEST_TIMEOUT_SECONDS
 from .logging import setup_debug_logging, log_api_request, log_api_response
 
 __all__ = [
     'CodeAliveContext',
     'get_api_key_from_context',
     'codealive_lifespan',
     'Config',
+    'REQUEST_TIMEOUT_SECONDS',
     'setup_debug_logging',
     'log_api_request',
     'log_api_response',

src/core/client.py

@@ -9,7 +9,7 @@
 from fastmcp import Context, FastMCP
 from fastmcp.server.dependencies import get_http_headers
 
-from .config import Config
+from .config import Config, REQUEST_TIMEOUT_SECONDS
 
 
 @dataclass
@@ -68,7 +68,7 @@ async def codealive_lifespan(server: FastMCP) -> AsyncIterator[CodeAliveContext]
                 "Authorization": f"Bearer {config.api_key}",
                 "Content-Type": "application/json",
             },
-            timeout=300.0,
+            timeout=REQUEST_TIMEOUT_SECONDS,
             verify=config.verify_ssl,
         )
     else:
@@ -78,7 +78,7 @@ async def codealive_lifespan(server: FastMCP) -> AsyncIterator[CodeAliveContext]
             headers={
                 "Content-Type": "application/json",
             },
-            timeout=300.0,
+            timeout=REQUEST_TIMEOUT_SECONDS,
             verify=config.verify_ssl,
         )
 

src/core/config.py

@@ -4,6 +4,9 @@
 from dataclasses import dataclass
 from typing import Optional
 
+# Request timeout in seconds (5 minutes)
+REQUEST_TIMEOUT_SECONDS = 300.0
+
 
 @dataclass
 class Config:

src/utils/errors.py

@@ -4,6 +4,8 @@
 import httpx
 from fastmcp import Context
 
+from core.config import REQUEST_TIMEOUT_SECONDS
+
 
 async def handle_api_error(
     ctx: Context,
@@ -21,6 +23,16 @@ async def handle_api_error(
     Returns:
         User-friendly error message string
     """
+    # Handle timeout errors first
+    if isinstance(error, httpx.TimeoutException):
+        timeout_minutes = int(REQUEST_TIMEOUT_SECONDS // 60)
+        error_msg = (
+            f"Request timeout during {operation}: The CodeAlive service did not respond within {timeout_minutes} minutes. "
+            "This may happen due to temporarily overloaded LLMs. Please try again later."
+        )
+        await ctx.error(error_msg)
+        return f"Error: {error_msg}"
+
     if isinstance(error, httpx.HTTPStatusError):
         error_code = error.response.status_code
         error_detail = error.response.text