# LIFX MCP Server

A comprehensive Model Context Protocol (MCP) server for controlling LIFX smart lights, built with TypeScript and Bun. This server provides seamless integration between AI assistants and LIFX lighting systems.

## Features

### 💡 LIFX Control Tools
- **List Lights**: Discover and list all LIFX lights with detailed information
- **Set State**: Control light power, color, brightness, and transitions
- **Toggle Power**: Smart power toggling based on current state
- **Effects**: Apply breathe, pulse, and other lighting effects
- **Scenes**: List and activate LIFX scenes
- **Color Validation**: Validate and convert color formats

### 📚 LIFX Resources
- **Server Information**: Runtime information and LIFX API status
- **Color Examples**: Comprehensive guide to LIFX color formats
- **Selector Examples**: Examples of LIFX light selector syntax

### 💬 Smart Prompts
- **Lighting Scenes**: Generate custom lighting setups for moods and activities
- **Troubleshooting**: Diagnose and fix LIFX lighting issues
- **Color Recommendations**: Get scientifically-backed color suggestions

### 🚀 Transport Support
- **Stdio Transport**: For Claude Desktop and command-line integration
- **HTTP Transport**: For web-based clients with session management

## Installation

### Prerequisites
- [Bun](https://bun.sh/) installed on your system
- Node.js v18+ (for compatibility)
- LIFX API token from [LIFX Cloud](https://cloud.lifx.com/settings)

### Setup

```bash
# Clone or create the project
cd lifx-mcp-server

# Install dependencies
bun install

# Configure your LIFX API token
cp .env.example .env
# Edit .env and add your LIFX_API_TOKEN
```

### Get Your LIFX API Token

1. Go to [LIFX Cloud Settings](https://cloud.lifx.com/settings)
2. Generate a new personal access token
3. Copy the token to your `.env` file or pass it as a command line argument

## Usage

### Stdio Mode (for Claude Desktop, etc.)

```bash
# Start with token from environment
bun run start:stdio

# Or pass token directly
bun run src/index.ts --token=YOUR_LIFX_TOKEN

# Development mode with auto-reload
bun run dev
```

### HTTP Mode (for web clients)

```bash
# Start HTTP server (requires token in .env)
bun run start:http

# The server will be available at:
# http://localhost:3000
```

### Configuration for Claude Desktop

Add this to your Claude Desktop configuration:

```json
{
  "mcpServers": {
    "lifx-mcp-server": {
      "command": "bun",
      "args": ["run", "src/index.ts", "--token=YOUR_LIFX_TOKEN"],
      "cwd": "/path/to/your/lifx-mcp-server"
    }
  }
}
```

## LIFX Tools Reference

### list-lights
Discover and list LIFX lights with detailed information.

**Parameters:**
- `selector`: string (default: "all") - Light selector (e.g., "all", "label:Kitchen", "group:Living Room")

**Example:**
```typescript
{
  "name": "list-lights",
  "arguments": {
    "selector": "group:Living Room"
  }
}
```

### set-state
Control light properties including power, color, brightness.

**Parameters:**
- `selector`: string (default: "all") - Light selector
- `power`: "on" | "off" (optional) - Power state
- `color`: string (optional) - Color (e.g., "red", "#ff0000", "kelvin:3500")
- `brightness`: number (optional) - Brightness (0.0 to 1.0)
- `duration`: number (optional) - Transition duration in seconds
- `fast`: boolean (optional) - Use fast mode for quicker response

**Example:**
```typescript
{
  "name": "set-state",
  "arguments": {
    "selector": "label:Bedroom",
    "power": "on",
    "color": "blue saturation:0.5",
    "brightness": 0.7,
    "duration": 2
  }
}
```

### toggle-power
Smart power toggle - turns off if any lights are on, turns on if all are off.

**Parameters:**
- `selector`: string (default: "all") - Light selector
- `duration`: number (optional) - Transition duration in seconds

### breathe-effect
Apply a breathing effect to lights.

**Parameters:**
- `selector`: string (default: "all") - Light selector
- `color`: string - Effect color
- `fromColor`: string (optional) - Starting color
- `period`: number (default: 1.0) - Period in seconds
- `cycles`: number (default: 1.0) - Number of cycles
- `persist`: boolean (default: false) - Keep final color
- `powerOn`: boolean (default: true) - Turn on lights if off
- `peak`: number (default: 1.0) - Brightness peak (0.0 to 1.0)

### pulse-effect
Apply a pulsing effect to lights.

**Parameters:**
- `selector`: string (default: "all") - Light selector
- `color`: string - Effect color
- `fromColor`: string (optional) - Starting color
- `period`: number (default: 1.0) - Period in seconds
- `cycles`: number (default: 1.0) - Number of cycles
- `persist`: boolean (default: false) - Keep final color
- `powerOn`: boolean (default: true) - Turn on lights if off

### list-scenes
List all available LIFX scenes in your account.

### activate-scene
Activate a LIFX scene by UUID.

**Parameters:**
- `sceneUuid`: string - Scene UUID
- `duration`: number (optional) - Transition duration
- `ignore`: string[] (optional) - Device IDs to ignore
- `overrides`: object (optional) - State overrides

### validate-color
Validate a color string and get its HSBK representation.

**Parameters:**
- `color`: string - Color to validate

## Color Format Guide

LIFX supports various color formats:

### Named Colors
- Basic: "red", "blue", "green", "yellow", "orange", "purple", "pink", "cyan", "white"
- Extended: "gold", "coral", "lime", "navy", etc.

### Hex Colors
- Standard: "#ff0000", "#00ff00", "#0000ff"
- Short: "#f00", "#0f0", "#00f"

### HSL Format
- "hue:120 saturation:1.0"
- "hue:240 saturation:0.5 brightness:0.8"

### Kelvin Temperature
- "kelvin:2700" (warm white)
- "kelvin:6500" (cool white)
- "kelvin:9000" (very cool)

### Combined Formats
- "red brightness:0.3"
- "blue saturation:0.5"
- "kelvin:3500 brightness:0.8"

## Light Selectors

LIFX uses powerful selectors to target specific lights:

### Basic Selectors
- `all` - All lights
- `id:d3b2f1d97452` - Specific light by ID

### Label Selectors
- `label:Kitchen` - Single light by label
- `label:Kitchen,Bedroom` - Multiple lights by label

### Group Selectors
- `group:Living Room` - All lights in a group
- `group:Living Room,Kitchen` - Multiple groups

### Location Selectors
- `location:Home` - All lights at a location
- `location:Home,Office` - Multiple locations

### Combined Selectors
- `group:Living Room label:Lamp` - Intersection
- `location:Home group:Bedroom` - Complex targeting

## Example Usage Scenarios

### 1. Morning Routine
```typescript
// Gradually turn on bedroom lights
{
  "name": "set-state",
  "arguments": {
    "selector": "group:Bedroom",
    "power": "on",
    "color": "kelvin:2700",
    "brightness": 0.3,
    "duration": 10
  }
}
```

### 2. Work Focus Setup
```typescript
// Set office lights to cool white, high brightness
{
  "name": "set-state",
  "arguments": {
    "selector": "location:Office",
    "power": "on",
    "color": "kelvin:6500",
    "brightness": 0.9,
    "duration": 3
  }
}
```

### 3. Party Mode
```typescript
// Apply colorful pulse effect
{
  "name": "pulse-effect",
  "arguments": {
    "selector": "all",
    "color": "hue:300 saturation:1.0",
    "period": 0.5,
    "cycles": 10,
    "persist": false
  }
}
```

### 4. Relaxation Scene
```typescript
// Dim warm lights with breathing effect
{
  "name": "breathe-effect",
  "arguments": {
    "selector": "group:Living Room",
    "color": "kelvin:2200 brightness:0.2",
    "period": 4,
    "cycles": 5,
    "persist": true
  }
}
```

## Development

### Project Structure

```
src/
├── index.ts          # Main LIFX MCP server implementation
├── server-http.ts    # HTTP transport server
└── test-client.ts    # Test client for development

package.json         # Dependencies and scripts
tsconfig.json       # TypeScript configuration
.env                 # Environment configuration
README.md           # This file
```

### Testing

```bash
# Run the test client
bun run test:manual

# Build for production
bun run build

# Format code
bun run format

# Lint code
bun run lint
```

## Security & Best Practices

- Store your LIFX API token securely
- Use environment variables instead of hardcoding tokens
- Be mindful of rate limits when making frequent API calls
- Test selectors to ensure they target the correct lights
- Use `fast=true` mode sparingly for better reliability

## Troubleshooting

### Common Issues

1. **API Token Invalid**: Check your token at [LIFX Cloud Settings](https://cloud.lifx.com/settings)
2. **No Lights Found**: Verify lights are online and connected to WiFi
3. **Selector Not Working**: Check light labels and group names in LIFX app
4. **Rate Limit Errors**: Reduce frequency of API calls
5. **Effects Not Working**: Ensure lights support the requested effect type

### Debug Mode

Set `DEBUG=true` in your `.env` file for detailed API request/response logging.

## License

MIT License - see LICENSE file for details.

## Resources

- [LIFX HTTP API Documentation](https://api.developer.lifx.com/docs)
- [LIFX Cloud Settings](https://cloud.lifx.com/settings)
- [Model Context Protocol Specification](https://spec.modelcontextprotocol.io/)
- [MCP TypeScript SDK](https://github.com/modelcontextprotocol/typescript-sdk)