get_overview

Instructions

Implementation Reference

• src/domoticz_mcp/server.py:400-442 (handler)

  The actual handler function for the 'get_overview' tool. It is an async function decorated with @mcp.tool(), fetches system version info, and counts of devices, scenes, user variables, plans, and hardware. Supports 'minimal' and 'standard' detail levels.

  @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:400-400 (registration)

  The tool is registered via the @mcp.tool() decorator on the get_overview function. FastMCP automatically registers it as a tool named 'get_overview'.

  @mcp.tool()

• src/domoticz_mcp/server.py:400-406 (schema)

  The input schema is defined by the function signature and docstring: detail_level parameter (string, defaults to 'minimal', accepts 'standard' for more detail). Output is a JSON string with status and result.

  @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.
      """

• src/domoticz_mcp/server.py:92-94 (helper)

  Helper function _format_response used to format the output as JSON string.

  def _format_response(data: Dict[str, Any]) -> str:
      """Format a dictionary as a JSON string response."""
      return json.dumps(data)

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

  Helper function _simplify_device used to reduce device dictionaries to essential fields when detail_level is not 'minimal'.

  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}