Add methods to query health endpoints (#29)

* Add methods to query health endpoints

* Add the cachetools library

* Cache server health results

* Fix test assertions for cacheable exceptions

* Move assertions outside pytest.raises() context to ensure execution

* Fix assertion to check exception type instead of ExceptionInfo instance

* Add length check to ensure test covers all cacheable exceptions

* Make patching consistent with rest of file using @patch.object decorator

* Add mock reset between test iterations

* Extract cache maxsize to private constant

* Add _SERVER_HEALTH_CACHE_MAXSIZE constant for maintainability

* Add proper docstrings for both class constants

* Add test to verify constant value

* Follows same pattern as _CACHEABLE_EXCEPTIONS

* Add missing test and usage example for HealthStatus.is_transient()

* Add comprehensive test coverage for is_transient() method

* Test both transient (timeout, unknown) and non-transient (ok, unreachable) states

* Also improve test coverage for is_healthy() method

* Add usage example in server_health() docstring showing retry logic pattern

* Improve docstrings for key private methods

* Add complete docstring for _raise_for_server_health() with Args and Raises sections

* Enhance _get_server_health() docs with reference to public API

* Improve _get_tool_definitions() with comprehensive exception documentation

* Helps developers working on public APIs understand private method contracts

* Make is_server_healthy() error handling more specific

* Only catch ServerUnhealthyError and ServerNotFoundError as 'not healthy'

* Let connection/auth/timeout errors propagate to caller

* Update docstring to document which exceptions can be raised

* Update test to verify new error propagation behavior

This improves error visibility - infrastructure issues (connection, auth) are
now distinguishable from server health status issues.

* Add thread safety to health check caching

* Add threading.RLock to protect cache access

* Pass lock to cached decorator for synchronized operations

* Wrap cache.clear() and cache.pop() operations with lock

* Document thread safety in class docstring

The performance impact is negligible since network I/O dominates
execution time. Cache stampede risk is minimal due to 10-second TTL
and typically small number of MCP servers.

* Add one more test case for test_is_healthy_error

---------

Co-authored-by: Peter Wilson <peter@mozilla.ai>

Author: michalismeng

README.md

@@ -12,7 +12,7 @@ This SDK provides high-level and dynamic access to those tools, making it easy t
 - Retrieve tool definitions and schemas for one or all servers
 - Dynamically invoke any tool using a clean, attribute-based syntax
 - Generate self-contained, deepcopy-safe tool functions for frameworks like [any-agent](https://github.com/mozilla-ai/any-agent)
-- Minimal dependencies (`requests` only)
+- Minimal dependencies (`requests` and `cachetools` only)
 
 ## Installation in your project
 
@@ -121,7 +121,8 @@ from mcpd import McpdClient
 
 # Initialize the client with your mcpd API endpoint.
 # api_key is optional and sends an 'MCPD-API-KEY' header.
-client = McpdClient(api_endpoint="http://localhost:8090", api_key="optional-key")
+# server_health_cache_ttl is optional and sets the time in seconds to cache a server health response.
+client = McpdClient(api_endpoint="http://localhost:8090", api_key="optional-key", server_health_cache_ttl=10)
 ```
 
 ### Core Methods
@@ -140,6 +141,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.

pyproject.toml

@@ -6,6 +6,7 @@ readme = "README.md"
 license = {text = "Apache-2.0"}
 requires-python = ">=3.11"
 dependencies = [
+    "cachetools>=6.2.0",
     "requests>=2.32.4",
 ]
 

src/mcpd/__init__.py

@@ -17,19 +17,22 @@
     ConnectionError,
     McpdError,
     ServerNotFoundError,
+    ServerUnhealthyError,
     TimeoutError,
     ToolExecutionError,
     ToolNotFoundError,
     ValidationError,
 )
-from .mcpd_client import McpdClient
+from .mcpd_client import HealthStatus, McpdClient
 
 __all__ = [
     "McpdClient",
+    "HealthStatus",
     "McpdError",
     "AuthenticationError",
     "ConnectionError",
     "ServerNotFoundError",
+    "ServerUnhealthyError",
     "TimeoutError",
     "ToolExecutionError",
     "ToolNotFoundError",

src/mcpd/exceptions.py

@@ -132,6 +132,41 @@ def __init__(self, message: str, server_name: str = None):
         self.server_name = server_name
 
 
+class ServerUnhealthyError(McpdError):
+    """Raised when a specified MCP server is not healthy.
+
+    This indicates that the server exists but is currently unhealthy:
+    - The server is down or unreachable
+    - Timeout occurred while checking health
+    - No health data is available for the server
+
+    Attributes:
+        server_name: The name of the server that is unhealthy.
+        health_status: Details about the server's health status (if available).
+                      Can be one of timeout, unreachable, unknown.
+
+    Example:
+        >>> try:
+        >>>     tools = client.tools("unhealthy_server")
+        >>> except ServerUnhealthyError as e:
+        >>>     print(f"Server '{e.server_name}' is unhealthy")
+        >>>     if e.health_status:
+        >>>         print(f"Health details: {e.health_status}")
+    """
+
+    def __init__(self, message: str, server_name: str, health_status: str):
+        """Initialize ServerUnhealthyError.
+
+        Args:
+            message: The error message.
+            server_name: The name of the server that is unhealthy.
+            health_status: Details about the server's health status.
+        """
+        super().__init__(message)
+        self.server_name = server_name
+        self.health_status = health_status
+
+
 class ToolNotFoundError(McpdError):
     """Raised when a specified tool doesn't exist on a server.