get_battery_levels

Instructions

Implementation Reference

• src/domoticz_mcp/server.py:768-791 (handler)

  The main handler function for the 'get_battery_levels' MCP tool. It fetches all devices, filters those with a BatteryLevel at or below the given threshold (excluding 255=no-battery), sorts ascending by battery level, and returns a JSON response.

  @mcp.tool()
  async def get_battery_levels(threshold: int = 20) -> str:
      """Get a list of devices with battery levels at or below the specified threshold.
      
      Args:
          threshold: Battery percentage threshold (default: 20).
      """
      async with create_client() as client:
          devices = await _get_cached_data(client, _device_cache, f"{DOMOTICZ_API_URL}?type=command¶m=getdevices&filter=all&used=true")
          results = []
          for dev in devices:
              battery = dev.get("BatteryLevel", 255)
              # BatteryLevel 255 often means no battery or not reporting
              if battery != 255 and battery <= threshold:
                  results.append({
                      "idx": dev.get("idx"),
                      "Name": dev.get("Name"),
                      "BatteryLevel": battery,
                      "HardwareName": dev.get("HardwareName"),
                      "LastUpdate": dev.get("LastUpdate")
                  })
          # Sort by battery level ascending
          results.sort(key=lambda x: x["BatteryLevel"])
          return json.dumps({"status": "OK", "result": results})

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

  The tool is registered as an MCP tool via the @mcp.tool() decorator on line 768, using the FastMCP instance created on line 70.

  @mcp.tool()

• src/domoticz_mcp/server.py:769-774 (schema)

  The input schema defines an optional 'threshold' parameter (integer, default 20). The output is a JSON string containing 'status' and 'result' array with fields: idx, Name, BatteryLevel, HardwareName, LastUpdate.

  async def get_battery_levels(threshold: int = 20) -> str:
      """Get a list of devices with battery levels at or below the specified threshold.
      
      Args:
          threshold: Battery percentage threshold (default: 20).
      """

• src/domoticz_mcp/server.py:387-394 (helper)

  The _simplify_device helper function is used elsewhere to reduce device payload, but for get_battery_levels the handler manually constructs a simplified dict inline.

  def _simplify_device(dev: Dict[str, Any]) -> Dict[str, Any]:
      """Reduce device dictionary to essential fields to save context space."""
      keys_to_keep = [
          "idx", "Name", "Type", "SubType", "Data", "Status", 
          "BatteryLevel", "Favorite", "HardwareName", "LastUpdate", 
          "TypeImg", "Usage", "CounterToday", "Temp", "Humidity"
      ]
      return {k: dev[k] for k in keys_to_keep if k in dev}

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

  The _get_cached_data helper is used by get_battery_levels to fetch and cache devices data from the Domoticz API.

  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"]