set_dimmer_level

Instructions

Implementation Reference

• src/domoticz_mcp/server.py:607-624 (handler)

  The actual handler function for the 'set_dimmer_level' tool. It sets the brightness level of a dimmer switch by calling the Domoticz API with 'switchlight' command, 'Set Level' switchcmd, and the level parameter. Validates level (0-100) and resolves device by idx or name.

  async def set_dimmer_level(level: int, idx: int | None = None, name: str | None = None) -> str:
      """Set the brightness level of a dimmer switch.
      
      Args:
          level: Integer from 0 to 100. Note: 0 is Off, 100 is Full Brightness.
          idx: Device index.
          name: Device name.
      """
      if idx is None and name is None:
          return '{"status": "error", "message": "Must provide either idx or name"}'
      if not (0 <= level <= 100):
          return '{"status": "error", "message": "level must be between 0 and 100"}'
      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=switchlight&idx={resolved_idx}&switchcmd=Set%20Level&level={level}")
          return response.text

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

  Registration of the tool via the @mcp.tool() decorator on the async function, which registers it with the FastMCP instance named 'Domoticz'.

  @mcp.tool()
  async def set_dimmer_level(level: int, idx: int | None = None, name: str | None = None) -> str:

• src/domoticz_mcp/server.py:607-614 (schema)

  Input schema: 'level' (int, 0-100), 'idx' (optional int), 'name' (optional str). The docstring serves as the type/schema definition for the MCP tool.

  async def set_dimmer_level(level: int, idx: int | None = None, name: str | None = None) -> str:
      """Set the brightness level of a dimmer switch.
      
      Args:
          level: Integer from 0 to 100. Note: 0 is Off, 100 is Full Brightness.
          idx: Device index.
          name: Device name.
      """

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

  Helper function _resolve_device_idx used by set_dimmer_level to resolve a device by idx or name to its numeric idx.

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

  Helper function _resolve_idx used by _resolve_device_idx to look up entity name->idx using cached API data.

  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