Bond MCP Server

Instructions

Implementation Reference

• src/bond_mcp/server.py:97-118 (handler)

  The FastMCP tool handler for 'get_device_state', registered via @mcp.tool(). It creates a BondClient instance, calls get_device_state on it, and returns the state wrapped with the device_id or an error.

  @mcp.tool()
  async def get_device_state(device_id: str) -> Dict[str, Any]:
      """Get current state of a Bond device.
      
      Args:
          device_id: The Bond device identifier
          
      Returns:
          Current device state including power, speed, direction, etc.
      """
      try:
          async with await get_bond_client() as client:
              state = await client.get_device_state(device_id)
              return {
                  "device_id": device_id,
                  "state": state
              }
      except BondAPIError as e:
          return {"error": f"Failed to get device state: {str(e)}"}
      except Exception as e:
          logger.error(f"Unexpected error getting device state: {e}")
          return {"error": f"Unexpected error: {str(e)}"}

• src/bond_mcp/bond_client.py:119-128 (helper)

  BondClient helper method that performs the actual HTTP GET request to the Bond Bridge API endpoint /v2/devices/{device_id}/state to retrieve the raw device state.

  async def get_device_state(self, device_id: str) -> Dict[str, Any]:
      """Get current state of a device.
      
      Args:
          device_id: Device identifier
          
      Returns:
          Device state
      """
      return await self._request("GET", f"devices/{device_id}/state")

• src/bond_mcp/models.py:52-78 (schema)

  Pydantic model defining the structure and validation for Bond device states, relevant to the output of get_device_state.

  class DeviceState(BaseModel):
      """Device state model."""
      power: Optional[int] = None  # 0 = off, 1 = on
      speed: Optional[int] = None  # Fan speed (0-8)
      direction: Optional[int] = None  # Fan direction (1 = forward, -1 = reverse)
      brightness: Optional[int] = None  # Light brightness (0-100)
      position: Optional[int] = None  # Shade position (0-100)
      timer: Optional[int] = None  # Timer in seconds
      
      @validator('speed')
      def validate_speed(cls, v):
          if v is not None and not (0 <= v <= 8):
              raise ValueError('Speed must be between 0 and 8')
          return v
      
      @validator('brightness', 'position')
      def validate_percentage(cls, v):
          if v is not None and not (0 <= v <= 100):
              raise ValueError('Value must be between 0 and 100')
          return v
      
      @validator('direction')
      def validate_direction(cls, v):
          if v is not None and v not in [-1, 1]:
              raise ValueError('Direction must be -1 (reverse) or 1 (forward)')
          return v