get_device_history

Instructions

Implementation Reference

• src/domoticz_mcp/server.py:793-812 (handler)

  The `get_device_history` tool handler function. It retrieves history logs or graphs for a device by idx or name, supporting sensor types: 'light', 'text', 'temp', 'percentage', 'counter' and time ranges: 'day', 'month', 'year'. Uses Domoticz API endpoints getlightlog, gettextlog, or graph depending on sensor_type.

  @mcp.tool()
  async def get_device_history(idx: int | None = None, name: str | None = None, sensor_type: str = "light", time_range: str = "day") -> str:
      """Get history log or graph for a device. sensor_type: 'light', 'text', 'temp', 'percentage', 'counter'. time_range (for graphs): 'day', 'month', 'year'."""
      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"}'
              
          url = f"{DOMOTICZ_API_URL}?type=command"
          if sensor_type == "light":
              url += f"¶m=getlightlog&idx={resolved_idx}"
          elif sensor_type == "text":
              url += f"¶m=gettextlog&idx={resolved_idx}"
          else:
              url += f"¶m=graph&sensor={sensor_type}&idx={resolved_idx}&range={time_range}"
              
          response = await _do_request(client, "GET", url)
          return response.text

• src/domoticz_mcp/server.py:794-795 (schema)

  The schema/type annotations for the tool parameters: idx (optional int), name (optional str), sensor_type (str, default 'light'), time_range (str, default 'day'). Docstring documents allowed values.

  async def get_device_history(idx: int | None = None, name: str | None = None, sensor_type: str = "light", time_range: str = "day") -> str:
      """Get history log or graph for a device. sensor_type: 'light', 'text', 'temp', 'percentage', 'counter'. time_range (for graphs): 'day', 'month', 'year'."""

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

  The tool is registered via the @mcp.tool() decorator on the get_device_history function (line 793).

  @mcp.tool()

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

  The `_resolve_device_idx` helper used by get_device_history to resolve a device idx from either an explicit idx or a device name.

  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:269-291 (helper)

  The `_do_request` helper used by get_device_history to perform HTTP requests with retry on 401 (token refresh).

  async def _do_request(client: httpx.AsyncClient, method: str, url: str, **kwargs) -> httpx.Response:
      """Perform a request with a single retry on 401 Unauthorized to handle expired tokens."""
      global _oauth_token_cache
      
      try:
          resp = await client.request(method, url, **kwargs)
          if resp.status_code == 401:
              # Token might be expired. Clear cache and retry once.
              _oauth_token_cache = None
              
              # Re-fetch token (this will trigger OAuth flow if needed)
              new_token = await _fetch_oauth_token(force_refresh=True)
              if new_token:
                  # Update headers for the retry
                  if "headers" not in kwargs:
                      kwargs["headers"] = {}
                  kwargs["headers"]["Authorization"] = f"Bearer {new_token}"
                  
                  # Retry the request
                  resp = await client.request(method, url, **kwargs)
          
          resp.raise_for_status()
          return resp