get_device

Instructions

Implementation Reference

• src/domoticz_mcp/server.py:557-566 (handler)

  The `get_device` tool handler function. It takes an optional idx or name, resolves the device index via `_resolve_device_idx`, and fetches the device state from Domoticz via the `getdevices&rid={idx}` API endpoint. Registered with the `@mcp.tool()` decorator on line 556.

  async def get_device(idx: int | None = None, name: str | None = None) -> str:
      """Get a specific device state by IDX or Name from Domoticz."""
      if idx is None and name is None:
          return '{"status": "error", "message": "Must provide either idx or name"}'
      async with create_client() as client:
          resolved_idx = await _resolve_device_idx(client, idx, name)
          if resolved_idx is None:
              return '{"status": "error", "message": "Device not found"}'
          response = await _do_request(client, "GET", f"{DOMOTICZ_API_URL}?type=command¶m=getdevices&rid={resolved_idx}")
          return response.text

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

  The `@mcp.tool()` decorator that registers the `get_device` function as an MCP tool.

  @mcp.tool()

• src/domoticz_mcp/server.py:373-375 (helper)

  The `_resolve_device_idx` helper function used by `get_device` (and other device tools). It resolves a device by idx (passthrough) or by name (case-insensitive lookup from cached device list).

  async def _resolve_device_idx(client: "httpx.AsyncClient", idx: Optional[int] = None, name: Optional[str] = None) -> Optional[int]:
      """Resolve a device to its idx."""
      return await _resolve_idx(client, idx, name, _device_cache, f"{DOMOTICZ_API_URL}?type=command¶m=getdevices&filter=all&used=true")

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

  The `_simplify_device` helper reduces a device dictionary to essential fields. It is used in resource endpoints but not directly by `get_device` (which returns the raw API response).

  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:354-370 (helper)

  The generic `_resolve_idx` helper used by `_resolve_device_idx`. It accepts an optional idx (passthrough) or name (case-insensitive match against cached items).

  async def _resolve_idx(
      client: "httpx.AsyncClient",
      idx: Optional[int],
      name: Optional[str],
      cache: Dict[str, Any],
      api_url: str
  ) -> Optional[int]:
      """Resolve an entity to its idx by either using the provided idx or looking up by name."""
      if idx is not None:
          return idx
      if not name:
          return None
      items = await _get_cached_data(client, cache, api_url)
      for item in items:
          if item.get("Name", "").lower() == name.lower():
              return int(str(item.get("idx")))
      return None