# Bond MCP Server

A Model Context Protocol (MCP) server that provides tools for controlling [Bond Bridge](https://bondhome.io/product/bond-bridge/) smart home devices. This server enables AI assistants like Claude to interact with ceiling fans, fireplaces, shades, lights, and other RF-controlled devices through Bond Bridge hubs.

## Features

- **Device Management**: List and get information about all connected Bond devices
- **Fan Control**: Control ceiling fan speed, direction, and power state
- **Shade Control**: Open, close, and set positions for motorized shades
- **Light Control**: Control dimmable lights and brightness levels
- **Custom Actions**: Send any Bond API action to devices
- **Bridge Information**: Get Bond Bridge status and configuration

## Quick Start

### Prerequisites

- Bond Bridge on your local network
- Bond API token (obtained from Bond Home app)

### Getting Your Bond Token

1. Open the Bond Home app on your mobile device
2. Go to Settings → Bond Bridge → Advanced → API
3. Copy the Local Token (not the Cloud Token)

### Add to your MCP settings:

```json
{
  "mcpServers": {
    "bond": {
      "command": "podman",
      "args": [
        "run", "-i", "--rm",
        "-e", "BOND_TOKEN=your_token_here",
        "-e", "BOND_HOST=192.168.1.100",
        "quay.io/madorn/bond-mcp-server:latest"
      ]
    }
  }
}
```

## Installation

1. **Create and activate virtual environment:**
   ```bash
   python3 -m venv bond-mcp-env
   source bond-mcp-env/bin/activate  # On Windows: bond-mcp-env\Scripts\activate
   ```

2. **Install dependencies:**
   ```bash
   pip install -r requirements.txt
   ```

3. **Configure environment:**
   ```bash
   cp .env.example .env
   # Edit .env with your Bond Bridge settings
   ```

4. **Run the server:**
   ```bash
   python -m bond_mcp.server
   ```

### Configuration

Create a `.env` file with your Bond Bridge configuration:

```env
# Required: Bond Bridge settings
BOND_TOKEN=your_bond_api_token_here
BOND_HOST=192.168.1.100

# Optional: Connection settings
BOND_TIMEOUT=10.0
BOND_MAX_RETRIES=3
BOND_RETRY_DELAY=1.0

# Optional: Logging
LOG_LEVEL=INFO
```

## Available Tools

### Device Management
- `list_devices()` - List all Bond devices
- `get_device_info(device_id)` - Get detailed device information
- `get_device_state(device_id)` - Get current device state
- `get_bridge_info()` - Get Bond Bridge information

### Device Control
- `toggle_device_power(device_id)` - Toggle device on/off
- `send_custom_action(device_id, action, argument?)` - Send custom Bond action

### Fan Control
- `set_fan_speed(device_id, speed)` - Set fan speed (0-8)
- `set_fan_direction(device_id, direction)` - Set direction ("forward"/"reverse")

### Shade Control
- `control_shades(device_id, action, position?)` - Control shades
  - Actions: "open", "close", "set_position"
  - Position: 0-100 (for set_position action)

### Light Control
- `set_light_brightness(device_id, brightness)` - Set brightness (0-100)

### Bond API Reference

This server uses the Bond Local API v2:
- Base URL: `http://{bridge_ip}/v2/`
- Authentication: Bearer token in Authorization header
- Docs: [Bond Local API Documentation](https://docs-local.appbond.com)

## Troubleshooting

### Common Issues

1. **Connection refused**: Ensure Bond Bridge IP is correct and accessible
2. **Authentication failed**: Verify Bond token is correct (use Local Token, not Cloud Token)
3. **Device not found**: Check device ID exists using `list_devices()`
4. **Action not supported**: Verify device supports the action using `get_device_info()`

### Debug Logging

Enable debug logging by setting `LOG_LEVEL=DEBUG` in your environment.

## License

This project is licensed under the MIT License. See the LICENSE file for details.