# Home Automation MCP Server

A comprehensive smart home automation system that allows AI assistants to control and monitor smart home devices through natural language using the Model Context Protocol (MCP).

## 🏗️ Architecture

```
AI Assistant (Claude Desktop/VS Code)
        ↓ stdio MCP Protocol
    FastMCP Server
        ↓
    SQLite Database ← [Real-time Polling] ← FastAPI Server
                                                ↓ WebSocket
                                            React Frontend
```

**Key Components:**
- **FastMCP Server** - Handles AI interactions via stdio protocol
- **FastAPI Server** - REST API + WebSocket for real-time frontend updates
- **SQLite Database** - Shared state between both servers with timestamp-based change detection
- **React Frontend** - Real-time dashboard with WebSocket updates

## ✨ Features

### MCP Tools (9 Tools)
1. **control_device** - Universal device control (on/off/set/toggle)
2. **get_device_status** - Query device states
3. **get_sensor_reading** - Read temperature, motion sensors
4. **set_home_mode** - Execute scenes (home/away/sleep/vacation)
5. **get_home_mode** - Check current mode
6. **feed_fish** - Trigger fish feeder
7. **water_plants** - Control sprinkler system
8. **start_ev_charging / stop_ev_charging** - EV charger control

### Supported Devices (24+ Sample Devices)
- 💡 Lights (with brightness control)
- 🌡️ Thermostat (temperature + mode control)
- 🔒 Locks
- 🪟 Blinds (with position control)
- 💨 Fans (with speed control)
- 🚗 Garage door
- 🐠 Fish feeder
- 💧 Sprinkler system
- 🔌 EV charger
- 🌡️ Temperature sensors
- 👁️ Motion sensors

### Home Modes
- **Home** - Welcome mode (lights on, 72°F)
- **Away** - Security mode (lights off, locks engaged, 65°F)
- **Sleep** - Night mode (bedroom dim 20%, doors locked, 68°F)
- **Vacation** - Extended away (everything secured, 60°F)

## 🚀 Quick Start

### 1. Install Dependencies

```bash
pip install -r requirements.txt
cd frontend
npm install  # First time only
```

### 2. Start the System

**Option A: Using the Menu (Easiest)**
```bash
start.bat
```
Then select what to start from the menu.

**Option B: Direct Commands (Recommended for Development)**

Open 2 separate terminals:

```bash
# Terminal 1: Start API Server (Backend)
python app/main.py
# → Available at http://localhost:8000

# Terminal 2: Start Frontend (Dashboard)
cd frontend
npm run dev
# → Available at http://localhost:5173
```

### 3. Configure MCP Server for Claude Desktop (Optional)

Run the configuration helper:

```bash
python app/stdio_config.py
```

Copy the output and add it to your Claude Desktop config file:
- **Windows**: `%APPDATA%/Claude/claude_desktop_config.json`
- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Linux**: `~/.config/Claude/claude_desktop_config.json`

Example configuration:

```json
{
  "mcpServers": {
    "home-automation": {
      "command": "python",
      "args": ["C:/path/to/home_automation/app/mcp_server_stdio.py"]
    }
  }
}
```

Restart Claude Desktop after adding the configuration.

## 💬 Example AI Interactions

### Device Control
```
"Turn on the living room lights to 75%"
"Set bedroom temperature to 72 degrees"
"Close all the blinds"
"Lock all doors"
```

### Status Queries
```
"What's the status of my home?"
"What's the temperature in the bedroom?"
"Are all the doors locked?"
```

### Home Modes
```
"I'm leaving" → Sets away mode
"I'm going to bed" → Sets sleep mode
"Good morning" → Sets home mode
```

### Special Actions
```
"Feed the fish"
"Water the front yard for 10 minutes"
"Start charging my car"
```

## 📁 Project Structure

```
home_automation/
├── app/
│   ├── config.py                 # Configuration settings
│   ├── main.py                   # FastAPI server
│   ├── mcp_server_stdio.py       # FastMCP server with tools
│   ├── stdio_config.py           # MCP configuration helper
│   ├── db/
│   │   ├── schema.sql           # Database schema
│   │   ├── database.py          # Database manager
│   │   └── seed_data.py         # Sample devices
│   ├── models/
│   │   └── device.py            # Device models
│   ├── schemas/
│   │   └── responses.py         # API response schemas
│   └── utils/
│       └── websocket_manager.py # WebSocket manager
├── frontend/                     # React dashboard
├── requirements.txt
├── home_automation.db           # SQLite database (auto-created)
├── README.md
└── DEVELOPMENT.md               # Development guide
```

## 🔧 API Endpoints

### REST API
- `GET /` - API information
- `GET /api/devices` - Get all devices (supports `?room=` and `?type=` filters)
- `GET /api/rooms` - Get list of rooms
- `GET /api/stats` - Get dashboard statistics
- `WebSocket /ws` - Real-time device updates

### WebSocket Messages

**From Server:**
```json
{
  "type": "device_update",
  "device_id": "living_room_light_main",
  "state": "on",
  "properties": {"brightness": 75}
}

{
  "type": "mode_change",
  "mode": "away"
}

{
  "type": "full_refresh"
}
```

## 🧪 Testing

### Test API Server
```bash
curl http://localhost:8000
curl http://localhost:8000/api/devices
curl http://localhost:8000/api/stats
```

### Test MCP Tools Directly
```bash
python app/mcp_server_stdio.py
```

### Test with MCP Inspector
```bash
npx @modelcontextprotocol/inspector python app/mcp_server_stdio.py
```

Open browser to: `http://localhost:6274`

## 📋 All Available Commands

| Command | Purpose | URL |
|---------|---------|-----|
| `start.bat` | Menu-driven launcher | - |
| `python app/main.py` | Start API server | http://localhost:8000 |
| `cd frontend && npm run dev` | Start frontend | http://localhost:5173 |
| `python app/mcp_server_stdio.py` | Start MCP server | stdio only |
| `npx @modelcontextprotocol/inspector python app/mcp_server_stdio.py` | Test with inspector | http://localhost:6274 |
| `python app/stdio_config.py` | Get Claude config | - |

## 🔄 Real-time Updates Flow

1. AI assistant calls MCP tool (e.g., `control_device`)
2. MCP server updates SQLite database with timestamp
3. FastAPI server detects timestamp change (polls every 100ms)
4. FastAPI broadcasts update via WebSocket to all connected clients
5. Frontend receives update and re-renders affected devices
6. **Total latency: < 300ms**

## 📊 Performance Metrics

- ✅ Database queries: < 10ms
- ✅ MCP tool execution: < 100ms
- ✅ Change detection: 100ms polling
- ✅ WebSocket broadcast: < 50ms
- ✅ End-to-end update: < 300ms
- ✅ Concurrent WebSocket connections: 100+

## 🐛 Troubleshooting

### MCP Server Not Connecting
- Check Claude Desktop config file path
- Verify Python path in configuration
- Restart Claude Desktop after config changes

### Frontend Not Updating
- Verify FastAPI server is running on port 8000
- Check browser console for WebSocket errors
- Ensure CORS origins include your frontend URL

### Database Locked Errors
- Verify only one process is accessing the database at a time
- WAL mode is enabled automatically in database.py

### Port Already in Use
```bash
# Windows PowerShell - Kill process on port
Get-NetTCPConnection -LocalPort 8000 | 
  Select-Object -ExpandProperty OwningProcess | 
  ForEach-Object { Stop-Process -Id $_ -Force }
```

## 🛠️ Development

### Add New Device Type
1. Add device to `app/db/seed_data.py`
2. Update type hints in `app/models/device.py`
3. Add icon in frontend `DeviceCard.jsx`

### Add New MCP Tool
1. Add `@mcp.tool()` decorated function in `app/mcp_server_stdio.py`
2. Include database operations
3. Document in docstring for AI assistant context

For detailed development information, see [DEVELOPMENT.md](DEVELOPMENT.md)

## 📚 Resources

- [Model Context Protocol Documentation](https://modelcontextprotocol.io)
- [MCP Python SDK](https://github.com/modelcontextprotocol/python-sdk)
- [FastAPI Documentation](https://fastapi.tiangolo.com)
- [React Documentation](https://react.dev)

## 📝 License

MIT License - See LICENSE file for details

## 🤝 Contributing

Contributions welcome! Please open an issue or submit a pull request.