Add methods to query health endpoints

Author: michalismeng

README.md

@@ -134,6 +134,12 @@ client = McpdClient(api_endpoint="http://localhost:8090", api_key="optional-key"
 
 * `client.call.<server_name>.<tool_name>(**kwargs)` - The primary way to dynamically call any tool using keyword arguments.
 
+* `client.server_health() -> dict[str, dict]` - Returns a dictionary mapping each server name to the health information of that server.
+
+* `client.server_health(server_name: str) -> dict` - Returns the health information for only the specified server.
+
+* `client.is_server_healthy(server_name: str) -> bool` - Checks if the specified server is healthy and can handle requests.
+
 ## Error Handling
 
 All SDK-level errors, including HTTP and connection errors, will raise a `McpdError` exception.

src/mcpd/mcpd_client.py

@@ -430,3 +430,128 @@ def clear_agent_tools_cache(self) -> None:
             >>> tools_v2 = client.agent_tools()  # Regenerates from latest definitions
         """
         self._function_builder.clear_cache()
+
+    def _get_server_health(self, server_name: str | None = None) -> list[dict] | dict:
+        """Get health information for one or all MCP servers."""
+        try:
+            if server_name:
+                url = f"{self._endpoint}/api/v1/health/servers/{server_name}"
+            else:
+                url = f"{self._endpoint}/api/v1/health/servers"
+            response = self._session.get(url, timeout=5)
+            response.raise_for_status()
+            data = response.json()
+            return data if server_name else data.get("servers", [])
+        except requests.exceptions.ConnectionError as e:
+            raise ConnectionError(f"Cannot connect to mcpd daemon at {self._endpoint}: {e}") from e
+        except requests.exceptions.Timeout as e:
+            operation = f"get health of {server_name}" if server_name else "get health of all servers"
+            raise TimeoutError("Request timed out after 5 seconds", operation=operation, timeout=5) from e
+        except requests.exceptions.HTTPError as e:
+            if e.response.status_code == 401:
+                msg = (
+                    f"Authentication failed when accessing server '{server_name}': {e}"
+                    if server_name
+                    else f"Authentication failed: {e}"
+                )
+                raise AuthenticationError(msg) from e
+            elif e.response.status_code == 404:
+                assert server_name is not None
+                raise ServerNotFoundError(f"Server '{server_name}' not found", server_name=server_name) from e
+            else:
+                msg = (
+                    f"Error retrieving health status for server '{server_name}': {e}"
+                    if server_name
+                    else f"Error retrieving health status for all servers: {e}"
+                )
+                raise McpdError(msg) from e
+        except requests.exceptions.RequestException as e:
+            msg = (
+                f"Error retrieving health status for server '{server_name}': {e}"
+                if server_name
+                else f"Error retrieving health status for all servers: {e}"
+            )
+            raise McpdError(msg) from e
+
+    def server_health(self, server_name: str | None = None) -> dict[str, dict] | dict:
+        """Retrieve health information from one or all MCP servers.
+
+        Args:
+            server_name: Optional name of a specific server to query. If None,
+                         retrieves health information from all available servers.
+
+        Returns:
+            - If server_name is provided: The health information for that server.
+            - If server_name is None: A dictionary mapping server names to their health information.
+
+            Server health is a dictionary that contains:
+            - '$schema': A URL to the JSON schema
+            - 'name': The server identifier
+            - 'status': The current health status of the server ('ok', 'timeout', 'unreachable', 'unknown')
+            - 'latency': The latency of the server in milliseconds (optional)
+            - 'lastChecked': Time when ping was last attempted (optional)
+            - 'lastSuccessful': Time of the most recent successful ping (optional)
+
+        Raises:
+            ConnectionError: If unable to connect to the mcpd daemon.
+            TimeoutError: If requests to the daemon time out.
+            AuthenticationError: If API key authentication fails.
+            ServerNotFoundError: If the specified server doesn't exist (when server_name provided).
+            McpdError: For other daemon errors or API issues.
+
+        Examples:
+            >>> client = McpdClient(api_endpoint="http://localhost:8090")
+            >>>
+            >>> # Get health for a specific server
+            >>> health_info = client.server_health(server_name="time")
+            >>> print(health_info["status"])
+            'ok'
+            >>>
+            >>> # Get health for all servers
+            >>> all_health = client.server_health()
+            >>> for server, health in all_health.items():
+            ...     print(f"{server}: {health['status']}")
+            fetch: ok
+            time: ok
+        """
+        if server_name:
+            return self._get_server_health(server_name)
+
+        try:
+            all_health = self._get_server_health()
+            all_health_by_server = {}
+            for health in all_health:
+                all_health_by_server[health["name"]] = health
+            return all_health_by_server
+        except McpdError as e:
+            raise McpdError(f"Could not retrieve all health information: {e}") from e
+
+    def is_server_healthy(self, server_name: str) -> bool:
+        """Check if the specified MCP server is healthy.
+
+        This method queries the server's health status and determines whether the server is healthy
+        and therefore can handle requests or not. It's useful for validating an MCP server is ready
+        before attempting to call one of its tools.
+
+        Args:
+            server_name: The name of the MCP server to check.
+
+        Returns:
+            True if the server is healthy, False otherwise.
+            Returns False if the server doesn't exist, is unreachable, or if any
+            other error occurs during the check.
+
+        Example:
+            >>> client = McpdClient(api_endpoint="http://localhost:8090")
+            >>>
+            >>> # Check before calling
+            >>> if client.is_server_healthy("time"):
+            ...     result = client.call.time.get_current_time(timezone="UTC")
+            ... else:
+            ...     print("The server is not ready to accept requests yet.")
+        """
+        try:
+            health = self.server_health(server_name=server_name)
+            return health.get("status", None) == "ok"
+        except McpdError:
+            return False

tests/unit/test_mcpd_client.py

@@ -151,3 +151,65 @@ def test_clear_agent_tools_cache(self, client):
         with patch.object(client._function_builder, "clear_cache") as mock_clear:
             client.clear_agent_tools_cache()
             mock_clear.assert_called_once()
+
+    @patch.object(Session, "get")
+    def test_health_single_server(self, mock_get, client):
+        mock_response = Mock()
+        mock_response.json.return_value = {"name": "test_server", "status": "ok"}
+        mock_response.raise_for_status.return_value = None
+        mock_get.return_value = mock_response
+
+        result = client.server_health("test_server")
+
+        assert result == {"name": "test_server", "status": "ok"}
+        mock_get.assert_called_once_with("http://localhost:8090/api/v1/health/servers/test_server", timeout=5)
+
+    @patch.object(Session, "get")
+    def test_health_all_servers(self, mock_get, client):
+        mock_response = Mock()
+        mock_response.json.return_value = {
+            "servers": [{"name": "server1", "status": "ok"}, {"name": "server2", "status": "unreachable"}]
+        }
+        mock_response.raise_for_status.return_value = None
+        mock_get.return_value = mock_response
+
+        result = client.server_health()
+
+        assert result == {
+            "server1": {"name": "server1", "status": "ok"},
+            "server2": {"name": "server2", "status": "unreachable"},
+        }
+        mock_get.assert_called_once_with("http://localhost:8090/api/v1/health/servers", timeout=5)
+
+    @patch.object(Session, "get")
+    def test_health_request_error(self, mock_get, client):
+        mock_get.side_effect = RequestException("Connection failed")
+
+        with pytest.raises(McpdError, match="Error retrieving health status for all servers"):
+            client.server_health()
+
+    @patch.object(McpdClient, "server_health")
+    def test_is_healthy_true(self, mock_health, client):
+        mock_health.return_value = {"name": "test_server", "status": "ok"}
+
+        result = client.is_server_healthy("test_server")
+
+        assert result is True
+        mock_health.assert_called_once_with(server_name="test_server")
+
+    @patch.object(McpdClient, "server_health")
+    def test_is_healthy_false(self, mock_health, client):
+        for status in ["timeout", "unknown", "unreachable"]:
+            mock_health.return_value = {"name": "test_server", "status": status}
+
+            result = client.is_server_healthy("test_server")
+
+            assert result is False
+
+    @patch.object(McpdClient, "server_health")
+    def test_is_healthy_error(self, mock_health, client):
+        mock_health.side_effect = McpdError("Health check failed")
+
+        result = client.is_server_healthy("test_server")
+
+        assert result is False