get_system_health

Instructions

Implementation Reference

• src/domoticz_mcp/server.py:444-483 (handler)

  The handler function for the 'get_system_health' tool. It queries Domoticz hardware gateways and checks device responsiveness (last update > 24h). Returns a JSON report with hardware health status, unresponsive device count, and a recommendation.

  @mcp.tool()
  async def get_system_health() -> str:
      """Check the health of the Domoticz system and hardware gateways."""
      async with create_client() as client:
          hw_resp = await _do_request(client, "GET", f"{DOMOTICZ_API_URL}?type=command¶m=gethardware")
          hardware = hw_resp.json().get("result", [])
          
          health_report = []
          for hw in hardware:
              status = "Online" if hw.get("Enabled") == "true" else "Disabled"
              health_report.append({
                  "Name": hw.get("Name"),
                  "Type": hw.get("Type"),
                  "Status": status,
                  "Address": hw.get("Address"),
                  "Port": hw.get("Port")
              })
              
          # Check for unresponsive devices (last update > 24h)
          devices = await _get_cached_data(client, _device_cache, f"{DOMOTICZ_API_URL}?type=command¶m=getdevices&filter=all&used=true")
          now = datetime.now()
          unresponsive_count = 0
          for dev in devices:
              last_update_str = dev.get("LastUpdate")
              if last_update_str:
                  try:
                      last_update = datetime.strptime(last_update_str, "%Y-%m-%d %H:%M:%S")
                      if now - last_update > timedelta(hours=24):
                          unresponsive_count += 1
                  except ValueError:
                      continue
                      
          return json.dumps({
              "status": "OK", 
              "result": {
                  "hardware_health": health_report,
                  "unresponsive_devices_count": unresponsive_count,
                  "recommendation": "Use `get_connectivity_report` for a detailed list of unresponsive devices." if unresponsive_count > 0 else "System looks healthy."
              }
          })

• src/domoticz_mcp/server.py:444-445 (registration)

  The tool is registered as an MCP tool using the @mcp.tool() decorator on line 444.

  @mcp.tool()
  async def get_system_health() -> str:

• src/domoticz_mcp/server.py:298-339 (helper)

  The DomoticzClient helper class (create_client) used by get_system_health for HTTP requests with OAuth/Basic auth support.

  class DomoticzClient:
      def __init__(self, own_client: bool = False):
          self._own_client = own_client
          if own_client or _global_http_client is None:
              self.client: httpx.AsyncClient = httpx.AsyncClient(timeout=30.0)
              self._owns_client = True
          else:
              self.client = _global_http_client
              self._owns_client = False
  
      async def __aenter__(self) -> "httpx.AsyncClient":
          oauth_token = None
  
          if DOMOTICZ_CLIENT_ID:
              oauth_token = await _fetch_oauth_token()
  
          if oauth_token:
              self.client.headers["Authorization"] = f"Bearer {oauth_token}"
          elif DOMOTICZ_USERNAME and DOMOTICZ_PASSWORD:
              self.client.auth = (DOMOTICZ_USERNAME, DOMOTICZ_PASSWORD)
          else:
              self.client.headers.pop("Authorization", None)
              self.client.auth = None
  
          return self.client
  
      async def __aexit__(self, exc_type, exc_val, exc_tb) -> None:
          if self._owns_client:
              await self.client.aclose()
  
  
  def create_client(own_client: bool = False) -> DomoticzClient:
      """Create a DomoticzClient instance.
  
      Args:
          own_client: If True, creates a dedicated client that will be closed on exit.
                      If False (default), uses a shared client for connection pooling.
      """
      return DomoticzClient(own_client=own_client)
  
  
  async def close_global_client() -> None:

• src/domoticz_mcp/server.py:346-352 (helper)

  The _get_cached_data helper used to fetch and cache devices list for the unresponsive device check.

  async def _get_cached_data(client: "httpx.AsyncClient", cache_obj: Dict[str, Any], api_url: str, key_path: str = "result") -> List[Dict[str, Any]]:
      now = time.time()
      if cache_obj["data"] is None or (now - cache_obj["timestamp"]) > CACHE_TTL:
          response = await _do_request(client, "GET", api_url)
          cache_obj["data"] = response.json().get(key_path, [])
          cache_obj["timestamp"] = now
      return cache_obj["data"]