# Hue MCP Server

A production-ready Model Context Protocol (MCP) server that enables Claude to control Philips Hue lights through natural language commands. Built with FastMCP framework and designed for seamless integration with Claude Desktop.

## Features

- **🏠 Room-based Control**: Control current Hue rooms, zones, and groups by name or ID
- **💡 Individual Light Control**: Control any light ID returned by the bridge
- **🔍 Light Discovery**: List all lights and get their current states
- **🌉 Bridge Integration**: Discover and test connectivity to Hue bridge
- **⚡ High Performance**: Async operations with connection pooling and rate limiting
- **🛡️ Error Handling**: Comprehensive error handling with retry logic
- **📊 Production Ready**: Full test coverage, logging, and monitoring

## Available MCP Tools

| Tool | Description | Parameters |
|------|-------------|------------|
| `hue_control_light` | Control individual light by ID | `light_id`, `action`, `brightness?`, `color_temp?` |
| `hue_control_room` | Control all lights in a room | `room`, `action`, `brightness?`, `color_temp?` |
| `hue_get_light_state` | Get current state of a light | `light_id` |
| `hue_list_lights` | List all lights and states | None |
| `hue_list_rooms` | List current bridge rooms, zones, and groups with membership | None |
| `hue_discover_bridge` | Test bridge connectivity | None |

### Rooms and Lights

The bridge is the source of truth. No light IDs, room names, or memberships
are configured in code, and inventory is fetched on each request.

- Call `hue_list_lights` for current light IDs and states.
- Call `hue_list_rooms` for current rooms, zones, and groups with IDs and membership.
- Pass a group ID or name to `hue_control_room`. Names are case-insensitive;
  underscores can replace spaces (for example, `living_room`).
- If multiple groups share a name, use the group ID to select one explicitly.
- `all` or `0` targets every light currently on the bridge.
- Positive light IDs are checked by the bridge, including IDs above 17.
  Missing lights return the bridge's error.

New lights and Hue app room edits take effect on the next request without a restart.
Room names from older local mappings must now match an actual bridge group.

### Supported Actions

- `on` - Turn lights on
- `off` - Turn lights off
- `toggle` - Toggle light state

## Installation

### Prerequisites

- Python 3.10 or higher
- Philips Hue Bridge on local network
- Bridge username (already configured for IP 192.168.1.64)

### Install Dependencies

```bash
# Install the package
pip install -e .

# Or install with development dependencies
pip install -e ".[dev]"
```

### Environment Configuration

1. Copy the environment template:
   ```bash
   cp .env.example .env
   ```

2. Edit `.env` file if needed (default values work for the configured setup):
   ```
   HUE_BRIDGE_IP=192.168.1.64
   HUE_USERNAME=cJdzxhKlxr2h92jwDkTv-DvpOxglPxn147UEg1Gp
   LOG_LEVEL=INFO
   ```

## Usage

### Running the MCP Server

```bash
# Run directly
python -m hue_mcp

# Or using the console script
hue-mcp
```

### Claude Desktop Integration

Add this configuration to your Claude Desktop MCP settings:

```json
{
  "mcpServers": {
    "hue-control": {
      "command": "python",
      "args": ["-m", "hue_mcp"],
      "cwd": "/path/to/hue-mcp-server"
    }
  }
}
```

### Natural Language Examples

Once integrated with Claude Desktop, you can use natural language commands:

- **"Turn on the kitchen lights"** → Turns on the bridge's current kitchen members
- **"Set office light to 50% brightness"** → Dims office light (ID 7) to ~127 brightness
- **"Turn off all lights"** → Turns off all lights using group control
- **"What lights are currently on?"** → Lists all lights with their current states
- **"Toggle the bedroom lights"** → Toggles lights 1 and 4

## Testing

### Run Unit Tests

```bash
# Run all tests
pytest

# Run with coverage
pytest --cov=src --cov-report=term-missing

# Run specific test file
pytest tests/test_hue_client.py -v
```

### Test Bridge Connectivity

```bash
# Test basic connectivity
python -c "
import asyncio
from src.hue_mcp.hue_client import AsyncHueClient

async def test():
    async with AsyncHueClient() as client:
        success = await client.test_connection()
        print(f'Bridge connection: {\"SUCCESS\" if success else \"FAILED\"}')

asyncio.run(test())
"
```

## Development

### Code Quality

```bash
# Linting and formatting
ruff check src/ --fix
ruff format src/

# Type checking
mypy src/

# Run all quality checks
ruff check . --fix && mypy src/ && ruff format .
```

### Project Structure

```
hue-mcp-server/
├── src/hue_mcp/
│   ├── __init__.py          # Package initialization
│   ├── __main__.py          # CLI entry point
│   ├── server.py            # Main MCP server
│   ├── hue_client.py        # Async HTTP client with rate limiting
│   ├── light_manager.py     # Business logic and room mappings
│   ├── config.py            # Configuration management
│   └── tools/               # MCP tool implementations
│       ├── light_control.py # Individual light control
│       ├── room_control.py  # Room-based control
│       └── discovery.py     # Light discovery and bridge testing
├── tests/                   # Comprehensive test suite
├── pyproject.toml           # Project configuration
├── README.md               # This file
└── .env.example            # Environment template
```

## Performance

- **Light Operations**: Under 1 second response time
- **Room Operations**: Under 3 seconds for multiple lights
- **Rate Limiting**: 10 light operations/second, 1 group operation/second
- **Connection Pooling**: Optimized HTTP connections with keepalive
- **Concurrent Operations**: Up to 5 concurrent light operations per room

## Error Handling

The server includes comprehensive error handling for:

- **Network Issues**: Connection timeouts, DNS failures
- **Bridge Errors**: Invalid light IDs, bridge unavailable
- **Rate Limiting**: Automatic retry with exponential backoff
- **Validation Errors**: Invalid parameters, out-of-range values

## Configuration

### Environment Variables

| Variable | Default | Description |
|----------|---------|-------------|
| `HUE_BRIDGE_IP` | `192.168.1.64` | IP address of Hue bridge |
| `HUE_USERNAME` | (configured) | Bridge authentication username |
| `LOG_LEVEL` | `INFO` | Logging level (DEBUG, INFO, WARNING, ERROR) |
| `HUE_TIMEOUT_CONNECT` | `5.0` | Connection timeout (seconds) |
| `HUE_TIMEOUT_READ` | `10.0` | Read timeout (seconds) |
| `HUE_MAX_CONNECTIONS` | `10` | Maximum HTTP connections |
| `HUE_LIGHT_RATE_LIMIT` | `10` | Light operations per second |
| `HUE_GROUP_RATE_LIMIT` | `1.0` | Group operations per second |

## Troubleshooting

### Common Issues

**Bridge Not Found**
```
Error: Failed to connect to Hue bridge at 192.168.1.64
Solution: Verify bridge IP and network connectivity
```

**Authentication Failed**
```
Error: Invalid username/authentication
Solution: Verify HUE_USERNAME in .env file
```

**Rate Limiting**
```
Warning: Rate limited, retrying...
Solution: Normal behavior, requests will retry automatically
```

### Debugging

Enable debug logging:
```bash
export LOG_LEVEL=DEBUG
python -m hue_mcp
```

### Bridge Information

- **IP Address**: 192.168.1.64
- **Username**: cJdzxhKlxr2h92jwDkTv-DvpOxglPxn147UEg1Gp
- **Light IDs**: Discovered from the bridge
- **Rooms and Groups**: Discovered from the bridge

## License

MIT License - see LICENSE file for details.

## Contributing

1. Fork the repository
2. Create a feature branch
3. Make changes with tests
4. Run quality checks: `ruff check . --fix && mypy src/ && pytest`
5. Submit a pull request

---

Built with ❤️ using [FastMCP](https://github.com/jlowin/fastmcp) and designed for seamless Claude integration.

FastMCP is pinned to the version verified by the test suite and live deployment.
Upgrade it deliberately with the MCP integration tests.

### Deployment on dev.local

The active service is `hue-mcp` in `~/nosuch/mcp-gateway/docker-compose.yml`,
built from this repository. Rebuild only that service after pulling changes:

```sh
cd ~/nosuch/mcp-gateway
docker compose up -d --build --no-deps hue-mcp
```

Do not run the standalone Compose service alongside it: both bind host port 8000.