get_overview

Instructions

Implementation Reference

• src/domoticz_mcp/server.py:396-438 (handler)

  The get_overview handler function, registered as an MCP tool via @mcp.tool(). It fetches system version, device/scene/variable/plan/hardware counts, and optionally includes a sample of favorite devices when detail_level='standard'.

  @mcp.tool()
  async def get_overview(detail_level: str = "minimal") -> str:
      """Get a high-level overview of the Domoticz system.
      
      Args:
          detail_level: 'minimal' (default) for counts and summary, 'standard' for including a sample of devices.
      """
      async with create_client() as client:
          # Get system info
          resp = await _do_request(client, "GET", f"{DOMOTICZ_API_URL}?type=command¶m=getversion")
          sys_info = resp.json()
          
          # Get counts from various caches
          devices = await _get_cached_data(client, _device_cache, f"{DOMOTICZ_API_URL}?type=command¶m=getdevices&filter=all&used=true")
          scenes = await _get_cached_data(client, _scene_cache, f"{DOMOTICZ_API_URL}?type=command¶m=getscenes")
          vars = await _get_cached_data(client, _user_variable_cache, f"{DOMOTICZ_API_URL}?type=command¶m=getuservariables")
          plans = await _get_cached_data(client, _plans_cache, f"{DOMOTICZ_API_URL}?type=command¶m=getplans&order=name&used=true")
          
          # Hardware count
          hw_resp = await _do_request(client, "GET", f"{DOMOTICZ_API_URL}?type=command¶m=gethardware")
          hardware = hw_resp.json().get("result", [])
          
          overview: Dict[str, Any] = {
              "system": {
                  "version": sys_info.get("version"),
                  "build_time": sys_info.get("build_time"),
                  "domoticz_url": DOMOTICZ_BASE_URL
              },
              "counts": {
                  "devices": len(devices),
                  "scenes_and_groups": len(scenes),
                  "user_variables": len(vars),
                  "rooms_plans": len(plans),
                  "hardware_gateways": len(hardware)
              }
          }
          
          if detail_level != "minimal":
              # Add a sample of favorite/active devices
              favorites = [d for d in devices if d.get("Favorite") == 1][:10]
              overview["favorite_devices"] = [_simplify_device(d) for d in favorites]
              
          return json.dumps({"status": "OK", "result": overview})

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

  Registration of get_overview as an MCP tool via the @mcp.tool() decorator on line 396.

  @mcp.tool()

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

  The _simplify_device helper function used by get_overview when detail_level is not minimal, to reduce device dicts to essential fields.

  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:400-401 (schema)

  Input schema for get_overview: the detail_level parameter accepts 'minimal' (default) or 'standard'.

  Args:
      detail_level: 'minimal' (default) for counts and summary, 'standard' for including a sample of devices.

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

  The _get_cached_data helper used by get_overview to fetch and cache data from the Domoticz API with TTL-based caching.

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