1

app.py

@@ -69,15 +69,16 @@ MCP_ENDPOINTS = [
 # =============================================================================
 
 def check_mcp_health() -> str:
-    """Check overall MCP server health."""
+    """Check overall MCP server health with extended timeout for cold starts."""
     try:
-        response = requests.get(f"{MCP_SERVER_URL}/", timeout=10)
+        # Extended timeout to handle HuggingFace Space cold starts (up to 60s)
+        response = requests.get(f"{MCP_SERVER_URL}/", timeout=60)
         if response.status_code == 200:
             return f"🟢 **Connected** to MCP Server"
         else:
             return f"🟡 **Partial** - Status {response.status_code}"
     except requests.exceptions.Timeout:
-        return "🟠 **Timeout** - Server slow to respond"
+        return "🟠 **Timeout** - Server may be starting up (cold start can take 30-60s)"
     except requests.exceptions.ConnectionError:
         return "🔴 **Disconnected** - Cannot reach server"
     except Exception as e:
@@ -85,13 +86,14 @@ def check_mcp_health() -> str:
 
 
 def check_endpoint_health(endpoint_name: str) -> Dict:
-    """Check health of a specific MCP endpoint."""
+    """Check health of a specific MCP endpoint with extended timeout."""
     start = time.perf_counter()
     try:
         url = f"{MCP_SERVER_URL}/gradio_api/call/ui_{endpoint_name}"
-        response = requests.post(url, json={"data": []}, timeout=15)
+        # Extended timeout for HuggingFace Space cold starts
+        response = requests.post(url, json={"data": []}, timeout=90)
         elapsed = (time.perf_counter() - start) * 1000
-        
+
         if response.status_code == 200:
             return {"status": "🟢", "latency_ms": round(elapsed, 1), "error": None}
         elif response.status_code == 404:
@@ -99,12 +101,11 @@ def check_endpoint_health(endpoint_name: str) -> Dict:
         else:
             return {"status": "🟠", "latency_ms": round(elapsed, 1), "error": f"HTTP {response.status_code}"}
     except requests.exceptions.Timeout:
-        return {"status": "🟠", "latency_ms": 15000, "error": "Timeout"}
+        elapsed = (time.perf_counter() - start) * 1000
+        return {"status": "🟠", "latency_ms": round(elapsed, 1), "error": "Timeout (server may be cold)"}
     except Exception as e:
         elapsed = (time.perf_counter() - start) * 1000
         return {"status": "🔴", "latency_ms": round(elapsed, 1), "error": str(e)[:50]}
-
-
 def get_all_endpoints_health() -> str:
     """Get health status of all MCP endpoints as formatted markdown."""
     output_lines = [
@@ -200,21 +201,26 @@ I can help you with quantum circuits! Try asking me to:
 # =============================================================================
 
 def quick_build_circuit(template: str, num_qubits: int) -> str:
-    """Generate a circuit from template using MCP client."""
+    """Generate a circuit from template using MCP client with retry and fallback."""
     try:
         from client.mcp_client import get_client
         mcp_client = get_client(MCP_SERVER_URL)
-        result = mcp_client.create_circuit_from_template(template, int(num_qubits))
         
+        # Try to warm up server first (handles HF Space cold start)
+        if not mcp_client._server_warmed:
+            logger.info("Warming up MCP server...")
+            mcp_client.warm_up_server()
+        
+        result = mcp_client.create_circuit_from_template(template, int(num_qubits))
+
         if result.success and result.data:
             if isinstance(result.data, dict) and 'qasm' in result.data:
                 return result.data['qasm']
             return str(result.data)
         return f"# Error: {result.error or 'Unknown error'}"
     except Exception as e:
+        logger.error(f"Quick build error: {e}")
         return f"# Error: {str(e)}"
-
-
 # =============================================================================
 # GRADIO INTERFACE
 # =============================================================================

client/mcp_client.py

@@ -1,6 +1,7 @@
-# Path: QAgents-workflos/client/mcp_client.py
-# Relations: Uses QuantumArchitect-MCP Gradio server
+# Path: QAgents-workflows/client/mcp_client.py
+# Relations: Uses QuantumArchitect-MCP Gradio server (HuggingFace Space)
 # Description: MCP client with fallback local implementations for missing endpoints
+#              Includes retry logic and extended timeouts for HF Space cold starts
 """
 MCP Client: Connection to QuantumArchitect-MCP endpoints.
 Provides both synchronous and async interfaces.
@@ -12,6 +13,11 @@ Available Gradio endpoints (as of latest scan):
 - ui_score_circuit: Score circuit complexity/fitness
 
 Missing endpoints use local fallback implementations.
+
+HuggingFace Space Considerations:
+- Spaces go to sleep after inactivity (cold start takes 30-60s)
+- Extended timeouts and retry logic handle this gracefully
+- Local fallback used when MCP server is unreachable
 """
 
 import requests
@@ -24,9 +30,19 @@ import re
 import time
 import random
 import math
+import os
 
 logger = logging.getLogger(__name__)
 
+# Default MCP Server URL (HuggingFace Space)
+DEFAULT_MCP_URL = "https://mcp-1st-birthday-quantumarchitect-mcp.hf.space"
+
+# Timeout settings for HuggingFace Spaces
+INITIAL_TIMEOUT = 90   # First request - allow cold start time
+RESULT_TIMEOUT = 120   # Result retrieval - allow processing time
+HEALTH_TIMEOUT = 30    # Health check timeout
+MAX_RETRIES = 3        # Number of retries for transient failures
+
 
 @dataclass
 class MCPResponse:
@@ -227,70 +243,139 @@ class MCPClient:
     """
     Client for QuantumArchitect-MCP server.
     Wraps MCP endpoints with fallback to local implementations.
-    
+
     Primary endpoints (from Gradio):
     - ui_create_circuit
     - ui_validate_circuit
     - ui_simulate_circuit
     - ui_score_circuit
-    
+
     Missing endpoints use QASMLocalAnalyzer for fallback.
+    
+    Features:
+    - Extended timeouts for HuggingFace Space cold starts
+    - Automatic retry with exponential backoff
+    - Server warm-up before first request
+    - Graceful fallback to local implementations
     """
 
-    def __init__(self, base_url: str = "http://127.0.0.1:7861"):
+    def __init__(self, base_url: str = None):
+        if base_url is None:
+            base_url = os.environ.get("MCP_SERVER_URL", DEFAULT_MCP_URL)
         self.base_url = base_url.rstrip("/")
         self.session = requests.Session()
         self._connected = False
         self._analyzer = QASMLocalAnalyzer()
+        self._server_warmed = False
+        logger.info(f"MCPClient initialized with base_url: {self.base_url}")
+
+    def warm_up_server(self) -> bool:
+        """
+        Wake up HuggingFace Space before making requests.
+        Spaces go to sleep after inactivity and need time to start.
+        
+        Returns:
+            True if server is warmed up and ready
+        """
+        if self._server_warmed:
+            return True
+            
+        logger.info(f"Warming up MCP server at {self.base_url}...")
+        
+        for attempt in range(MAX_RETRIES):
+            try:
+                # Simple GET to wake up the server
+                response = self.session.get(
+                    f"{self.base_url}/",
+                    timeout=INITIAL_TIMEOUT
+                )
+                if response.status_code == 200:
+                    self._server_warmed = True
+                    self._connected = True
+                    logger.info("MCP server is ready")
+                    return True
+            except requests.exceptions.Timeout:
+                logger.warning(f"Warm-up attempt {attempt + 1}/{MAX_RETRIES} timed out, retrying...")
+            except requests.exceptions.ConnectionError as e:
+                logger.warning(f"Warm-up attempt {attempt + 1}/{MAX_RETRIES} connection error: {e}")
+            except Exception as e:
+                logger.warning(f"Warm-up attempt {attempt + 1}/{MAX_RETRIES} failed: {e}")
+            
+            if attempt < MAX_RETRIES - 1:
+                wait_time = 2 ** attempt  # 1s, 2s, 4s
+                time.sleep(wait_time)
+        
+        logger.warning("Failed to warm up MCP server, will use local fallback")
+        return False
 
     def _call(self, endpoint: str, **kwargs) -> MCPResponse:
-        """Internal method to call MCP endpoints."""
+        """Internal method to call MCP endpoints with retry logic."""
         start = time.perf_counter()
-
-        try:
-            url = f"{self.base_url}/gradio_api/call/{endpoint}"
-            payload = {"data": list(kwargs.values()) if kwargs else []}
+        last_error = None
+        
+        for attempt in range(MAX_RETRIES):
+            try:
+                return self._call_once(endpoint, start, **kwargs)
+            except requests.exceptions.Timeout as e:
+                last_error = f"Timeout after {INITIAL_TIMEOUT}s"
+                logger.warning(f"MCP call {endpoint} attempt {attempt + 1}/{MAX_RETRIES} timed out")
+            except requests.exceptions.ConnectionError as e:
+                last_error = f"Connection error: {e}"
+                logger.warning(f"MCP call {endpoint} attempt {attempt + 1}/{MAX_RETRIES} connection error")
+            except Exception as e:
+                last_error = str(e)
+                logger.warning(f"MCP call {endpoint} attempt {attempt + 1}/{MAX_RETRIES} failed: {e}")
             
-            response = self.session.post(url, json=payload, timeout=30)
-            response.raise_for_status()
-
-            result = response.json()
-            event_id = result.get("event_id")
-
-            if event_id:
-                result_url = f"{self.base_url}/gradio_api/call/{endpoint}/{event_id}"
-                result_response = self.session.get(result_url, timeout=30)
-
-                lines = result_response.text.strip().split("\n")
-                for line in lines:
-                    if line.startswith("data:"):
-                        data = json.loads(line[5:].strip())
-                        elapsed = (time.perf_counter() - start) * 1000
-                        return MCPResponse(
-                            success=True,
-                            data=data[0] if isinstance(data, list) and len(data) == 1 else data,
-                            endpoint=endpoint,
-                            execution_time_ms=elapsed
-                        )
-
-            elapsed = (time.perf_counter() - start) * 1000
-            return MCPResponse(
-                success=True,
-                data=result,
-                endpoint=endpoint,
-                execution_time_ms=elapsed
-            )
+            if attempt < MAX_RETRIES - 1:
+                wait_time = 2 ** attempt  # Exponential backoff: 1s, 2s, 4s
+                time.sleep(wait_time)
+        
+        # All retries failed
+        elapsed = (time.perf_counter() - start) * 1000
+        logger.error(f"MCP call {endpoint} failed after {MAX_RETRIES} attempts: {last_error}")
+        return MCPResponse(
+            success=False,
+            data=None,
+            endpoint=endpoint,
+            error=last_error,
+            execution_time_ms=elapsed
+        )
 
-        except Exception as e:
-            elapsed = (time.perf_counter() - start) * 1000
-            logger.warning(f"MCP call failed: {endpoint} - {e}")
-            return MCPResponse(
-                success=False,
-                data=None,
-                endpoint=endpoint,
-                error=str(e),
-                execution_time_ms=elapsed
-            )
+    def _call_once(self, endpoint: str, start: float, **kwargs) -> MCPResponse:
+        """Single attempt to call an MCP endpoint."""
+        url = f"{self.base_url}/gradio_api/call/{endpoint}"
+        payload = {"data": list(kwargs.values()) if kwargs else []}
+
+        logger.debug(f"Calling MCP endpoint: {url}")
+        response = self.session.post(url, json=payload, timeout=INITIAL_TIMEOUT)
+        response.raise_for_status()
+
+        result = response.json()
+        event_id = result.get("event_id")
+
+        if event_id:
+            result_url = f"{self.base_url}/gradio_api/call/{endpoint}/{event_id}"
+            result_response = self.session.get(result_url, timeout=RESULT_TIMEOUT)
+
+            lines = result_response.text.strip().split("\n")
+            for line in lines:
+                if line.startswith("data:"):
+                    data = json.loads(line[5:].strip())
+                    elapsed = (time.perf_counter() - start) * 1000
+                    return MCPResponse(
+                        success=True,
+                        data=data[0] if isinstance(data, list) and len(data) == 1 else data,
+                        endpoint=endpoint,
+                        execution_time_ms=elapsed
+                    )
+
+        elapsed = (time.perf_counter() - start) * 1000
+        return MCPResponse(
+            success=True,
+            data=result,
+            endpoint=endpoint,
+            execution_time_ms=elapsed
+        )
 
     def _fallback_response(self, endpoint: str, data: Any, start_time: float) -> MCPResponse:
         """Create a fallback response using local implementation."""
@@ -306,10 +391,15 @@ class MCPClient:
     def health_check(self) -> bool:
         """Check if MCP server is reachable."""
         try:
-            response = self.session.get(f"{self.base_url}/", timeout=5)
+            response = self.session.get(f"{self.base_url}/", timeout=HEALTH_TIMEOUT)
             self._connected = response.status_code == 200
             return self._connected
-        except:
+        except requests.exceptions.Timeout:
+            logger.warning(f"Health check timed out after {HEALTH_TIMEOUT}s")
+            self._connected = False
+            return False
+        except Exception as e:
+            logger.warning(f"Health check failed: {e}")
             self._connected = False
             return False
 
@@ -399,8 +489,27 @@ class MCPClient:
 
     # ===== Validation Endpoints =====
 
-    def validate_syntax(self, qasm_code: str) -> MCPResponse:
-        """Validate QASM syntax. Maps to ui_validate_circuit."""
+    def validate_syntax(self, qasm_code: str, use_local_first: bool = True) -> MCPResponse:
+        """
+        Validate QASM syntax.
+        
+        Args:
+            qasm_code: The QASM code to validate
+            use_local_first: If True, use fast local validation first
+            
+        Returns:
+            Validation result with any syntax errors
+        """
+        # Try local validation first (fast, no network)
+        if use_local_first:
+            start = time.perf_counter()
+            local_result = self._analyzer.validate_syntax(qasm_code)
+            if local_result['valid']:
+                return self._fallback_response("validate_syntax", local_result, start)
+            # If local validation found errors, still return them quickly
+            return self._fallback_response("validate_syntax", local_result, start)
+        
+        # Use MCP server for full validation
         return self._call("ui_validate_circuit", qasm=qasm_code, hardware="")
 
     def check_connectivity(self, qasm_code: str, hardware: str = "ibm_brisbane") -> MCPResponse:
@@ -687,15 +796,22 @@ def get_client(base_url: Optional[str] = None) -> MCPClient:
 
     Args:
         base_url: Optional URL override. If None, checks MCP_SERVER_URL env var,
-                  then defaults to the HuggingFace Space URL
+                 then defaults to the HuggingFace Space URL
+
+    Returns:
+        MCPClient instance connected to the MCP server
     """
     global _client
     if _client is None:
         if base_url is None:
-            import os
-            base_url = os.environ.get(
-                "MCP_SERVER_URL", 
-                "https://mcp-1st-birthday-quantumarchitect-mcp.hf.space"
-            )
+            base_url = os.environ.get("MCP_SERVER_URL", DEFAULT_MCP_URL)
         _client = MCPClient(base_url)
-    return _client
+        logger.info(f"Created MCP client for: {base_url}")
+    return _client
+
+
+def reset_client():
+    """Reset the singleton client (useful for testing or reconnection)."""
+    global _client
+    _client = None
+    logger.info("MCP client reset")

tasks-project-state.json

@@ -1,16 +1,44 @@
 {
   "project": "QAgents-Workflows",
-  "version": "0.9.0",
+  "version": "0.9.1",
   "description": "Multi-agent quantum circuit optimization system with chat UI and MCP integration",
   "last_updated": "2025-11-30",
-  "status": "CHAT_UI_AND_MCP_HEALTH_MONITOR_ADDED",
-  "notes": "Added Gradio chat interface for agent interaction. Added MCP endpoints health monitor tab. Updated MCP client to connect to HuggingFace Space. Removed unsupported Blocks theme argument to restore runtime compatibility on Gradio 6.",
+  "status": "MCP_CLIENT_TIMEOUT_FIX_APPLIED",
+  "notes": "Fixed MCP client timeout issues for HuggingFace Space cold starts. Increased timeouts (90s initial, 120s result), added retry logic with exponential backoff, added server warm-up function. Chat UI and MCP health monitor working. Local validation fallback for fast syntax checks.",
+
+  "recent_changes": {
+    "2025-11-30": [
+      "Fixed timeout errors in mcp_client.py for HuggingFace Space cold starts",
+      "Increased INITIAL_TIMEOUT to 90s, RESULT_TIMEOUT to 120s",
+      "Added MAX_RETRIES=3 with exponential backoff",
+      "Added warm_up_server() method to MCPClient",
+      "Updated validate_syntax() to use local fallback first (faster)",
+      "Updated app.py health check functions with extended timeouts",
+      "Improved error messages to indicate cold start situations"
+    ]
+  },
 
   "huggingface_deployment": {
     "qagents_space": "https://huggingface.co/spaces/NLarchive/Qagents-workflows",
     "mcp_server_space": "https://mcp-1st-birthday-quantumarchitect-mcp.hf.space",
+    "mcp_sse_endpoint": "https://mcp-1st-birthday-quantumarchitect-mcp.hf.space/gradio_api/mcp/sse",
     "gradio_version": "6.0.0",
-    "mcp_enabled": true
+    "mcp_enabled": true,
+    "cold_start_note": "HF Spaces go to sleep after inactivity. First request may take 30-60s."
+  },
+
+  "mcp_client_config": {
+    "default_url": "https://mcp-1st-birthday-quantumarchitect-mcp.hf.space",
+    "initial_timeout_s": 90,
+    "result_timeout_s": 120,
+    "health_timeout_s": 30,
+    "max_retries": 3,
+    "features": [
+      "Extended timeouts for cold starts",
+      "Retry with exponential backoff",
+      "Server warm-up before first request",
+      "Local fallback for validation"
+    ]
   },
 
   "app_features": {
@@ -29,7 +57,8 @@
         "Check all endpoints health",
         "Individual endpoint testing",
         "Latency monitoring",
-        "Status indicators (🟢🟡🟠🔴)"
+        "Status indicators (🟢🟡🟠🔴)",
+        "Extended timeouts for cold starts"
       ]
     },
     "quick_build_tab": {

ui/mcp_health.py

@@ -1,14 +1,18 @@
 # Path: QAgents-workflows/ui/mcp_health.py
 # Relations: Uses client/mcp_client.py for health checks
 #            Used by __init__.py, app.py, chat_components.py
-# Description: MCP health monitoring UI components
+# Description: MCP health monitoring UI components with extended timeouts
+#              for HuggingFace Space cold starts
 """
 MCP Health Components: Monitor QuantumArchitect-MCP endpoint availability.
 
 Provides:
-- Server health check
+- Server health check with extended timeout for cold starts
 - Individual endpoint health checks
 - Health status table display
+
+Note: HuggingFace Spaces go to sleep after inactivity. First request may
+      take 30-60 seconds while the server wakes up (cold start).
 """
 
 import os

ui/quick_build.py

@@ -1,14 +1,16 @@
 # Path: QAgents-workflows/ui/quick_build.py
 # Relations: Uses client/mcp_client.py for circuit generation
 #            Used by __init__.py, app.py
-# Description: Quick circuit builder UI components
+# Description: Quick circuit builder UI components with improved error handling
 """
 Quick Build Components: Fast circuit generation from templates.
 
 Provides:
 - Template selection dropdown
 - Qubit count slider
-- Circuit generation via MCP client
+- Circuit generation via MCP client with retry and fallback
+
+Note: First request may take longer if MCP server needs to wake up (cold start).
 """
 
 import os