set_dimmer_level

Instructions

Implementation Reference

• src/domoticz_mcp/server.py:600-618 (handler)

  The main handler function for the 'set_dimmer_level' tool. It is decorated with @mcp.tool(), accepts a 'level' (int 0-100), optional 'idx' or 'name', validates inputs, resolves the device ID, and sends a 'Set Level' command to the Domoticz API.

  @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.
      """
      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:600-600 (registration)

  The tool is registered via the @mcp.tool() decorator on line 600, which is the FastMCP instance created on line 70. This decorator registers the function as an MCP tool named 'set_dimmer_level' (derived from the async function name).

  @mcp.tool()

• src/domoticz_mcp/server.py:600-612 (schema)

  Input validation schema: 'level' is an int (0-100), 'idx' is optional int, 'name' is optional string. Lines 609-612 validate that at least idx or name is provided, and that level is in range 0-100.

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

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

  The _resolve_device_idx helper resolves a device name or idx to a Domoticz device index, used by set_dimmer_level to find the target device.

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

• tests/test_server.py:286-308 (registration)

  Test that validates the set_dimmer_level tool works correctly, mocking the Domoticz API and calling set_dimmer_level(50, name='Kitchen Light').

  @pytest.mark.asyncio
  @respx.mock
  async def test_device_control_tools():
      from domoticz_mcp.server import (
          set_switch_state, set_dimmer_level, set_temperature_setpoint, control_blinds
      )
      
      # Mock resolution for Kitchen Light (idx 2)
      respx.get(f"{DOMOTICZ_API_URL}?type=command¶m=getdevices&filter=all&used=true").mock(
          return_value=Response(200, json=DEVICES_MOCK_RESPONSE)
      )
      
      # set_switch_state
      respx.get(f"{DOMOTICZ_API_URL}?type=command¶m=switchlight&idx=2&switchcmd=On").mock(
          return_value=Response(200, json={"status": "OK"})
      )
      await set_switch_state("On", name="Kitchen Light")
      
      # set_dimmer_level
      respx.get(f"{DOMOTICZ_API_URL}?type=command¶m=switchlight&idx=2&switchcmd=Set%20Level&level=50").mock(
          return_value=Response(200, json={"status": "OK"})
      )
      await set_dimmer_level(50, name="Kitchen Light")