Home Automation 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

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

2. Start the System

Option A: Using the Menu (Easiest)

start.bat

Then select what to start from the menu.

Option B: Direct Commands (Recommended for Development)

Open 2 separate terminals:

# 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:

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:

{
  "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:

{
  "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

curl http://localhost:8000
curl http://localhost:8000/api/devices
curl http://localhost:8000/api/stats

Test MCP Tools Directly

python app/mcp_server_stdio.py

Test with MCP Inspector

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

# 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

📚 Resources

• Model Context Protocol Documentation
• MCP Python SDK
• FastAPI Documentation
• React Documentation

📝 License

MIT License - See LICENSE file for details

🤝 Contributing

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