Smart Home MCP Server

# Smart Home Automation System - Development Spec ## 🎯 Project Overview Build a **modular smart home automation system** that bridges IoT devices with AI agents via Model Context Protocol (MCP). Designed as a monorepo for development efficiency, but structured for easy splitting into multiple GitHub repos later. ## 🏗️ Architecture ``` GitHub/n8n → Cloudflare Tunnel → Raspberry Pi → IoT Network (Smart Devices) ↓ MCP Server ← → Smart Home API ← → Device Controllers ``` ## 📁 Monorepo Structure ``` smart-home-automation/ ├── README.md (system overview) ├── docker-compose.yml (full stack) ├── packages/ │ ├── smart-home-core/ # → Future: smart-home-api repo │ │ ├── package.json & README.md (standalone) │ │ ├── Dockerfile & docker-compose.yml │ │ └── src/ │ │ ├── controllers/ (device APIs) │ │ ├── devices/ (kasa.ts, tuya.ts, hue.ts) │ │ └── app.ts (Express server) │ ├── smart-home-mcp/ # → Future: smart-home-mcp repo │ │ ├── package.json & README.md (standalone) │ │ ├── Dockerfile & docker-compose.yml │ │ └── src/ │ │ ├── tools/ (lighting.ts, scenes.ts, alerts.ts) │ │ └── server.ts (MCP server) │ ├── smart-home-dashboard/ # → Future: smart-home-dashboard repo │ │ └── src/ (React app for manual control) │ └── shared-types/ # → Future: @yourname/smart-home-types npm │ └── src/ (TypeScript interfaces) ├── tools/ │ └── split-repos.sh (automated repo splitting) └── examples/ ├── n8n-workflows/ └── claude-config/ ``` ## 🔧 Technology Stack - **Languages**: TypeScript/Node.js - **Deployment**: Docker + Docker Compose - **Networking**: Cloudflare Tunnel (Pi → Internet) - **Hardware**: Raspberry Pi (any version) - **Devices**: TP-Link Kasa, Tuya-based smart lights/plugs - **AI Integration**: Model Context Protocol (MCP) ## 🚀 Development Phases ### **Phase 1: Core Infrastructure** (Weekend 1) 1. **Setup Raspberry Pi** with fresh OS + Docker 2. **Build smart-home-core** package: - Express.js server on port 3001 - Device discovery and control - REST API endpoints: `/api/lights/:id/color`, `/api/scenes/:name` 3. **Test device control** with direct HTTP calls 4. **Docker deployment** working locally ### **Phase 2: MCP Integration** (Weekend 2) 1. **Build smart-home-mcp** package: - MCP server on port 3000 - Tools: `setBuildStatus()`, `createFocusEnvironment()`, `flashAlert()` - Wraps smart-home-core API calls 2. **Test with Claude Desktop** locally 3. **Setup Cloudflare Tunnel** for external access 4. **n8n integration** via MCP Client Tool node ### **Phase 3: Automation & Polish** (Weekend 3) 1. **GitHub webhook workflows** in n8n 2. **Web dashboard** for manual control 3. **Documentation** and demos 4. **Prepare for repo splitting** ## 🛠️ Key Implementation Details ### **Device Control Examples** ```typescript // TP-Link Kasa await fetch(`http://${ip}:9999`, { method: 'POST', body: kasaEncrypt(command) }); // Tuya devices const tuya = new TuyaDevice({ ip, id, key }); await tuya.set({ switch: true }); ``` ### **MCP Tools** ```typescript export const tools = { setBuildStatus: async (status: 'success' | 'failure' | 'running') => { await fetch('http://localhost:3001/api/scenes/build-status', { method: 'POST', body: JSON.stringify({ status }) }); } }; ``` ### **n8n Integration** ``` GitHub Webhook → Parse Build Status → MCP Client Tool → Lights Change Color ``` ## 🔄 Future Repo Split Strategy **Target GitHub repos after splitting:** 1. **smart-home-api** - Device control server 2. **smart-home-mcp** - AI integration layer 3. **smart-home-dashboard** - Web interface 4. **smart-home-examples** - Workflows & configs 5. **@yourname/smart-home-types** - NPM package **Split command**: `./tools/split-repos.sh` (automated with git subtree) ## 🌐 Networking Setup ### **Network Architecture** - **Main Network**: Pi + NAS (192.168.1.x) - **IoT Network**: Smart devices (192.168.50.x) - **Pi Bridge**: Connect both networks OR firewall rules ### **External Access** - **Cloudflare Tunnel**: `smart-home.yourdomain.com` → Pi:3000 - **Security**: Optional Bearer token auth ## 📋 Prerequisites Checklist - [ ] Raspberry Pi (any version) with network access - [ ] Smart devices (TP-Link Kasa or Tuya-based) - [ ] Device IPs identified on IoT network - [ ] Docker installed on Pi - [ ] Cloudflare account (free tier) - [ ] n8n instance running (Hostinger) ## 🎨 Portfolio Value **Demonstrates:** - Microservices architecture - IoT device integration - AI tooling (MCP) knowledge - Docker containerization - Network security awareness - Modern TypeScript development - API design (REST + MCP) ## 🚀 Getting Started Tonight 1. **Flash Pi with latest Raspberry Pi OS** 2. **Install Docker**: `curl -fsSL https://get.docker.com | sh` 3. **Clone/create monorepo structure** 4. **Start with device discovery**: Scan network, identify device IPs 5. **Build basic Express server** for device control 6. **Test with one light** using direct API calls **Success criteria for tonight**: Turn one smart light on/off via HTTP API call to your Pi. --- **Time Estimate**: 2-3 weekends for full system, 2-4 hours tonight for basic proof of concept. **Immediate next step**: Get Pi online and scan for your smart device IPs!