home automation MCP server

家庭自动化MCP服务器

一个全面的智能家居自动化系统，允许AI助手使用模型上下文协议（MCP）通过自然语言控制和监控智能家居设备。

🏗️ 建筑

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

关键部件：

• FastMCP服务器 -通过stdio协议处理AI交互
• FastAPI服务器 -用于实时前端更新的REST API+WebSocket
• SQLite数据库 -通过基于时间戳的更改检测在两台服务器之间共享状态
• 反应前端 -带有WebSocket更新的实时仪表板

✨ 特性

MCP工具（9个工具）

1. 控制装置 -通用设备控制（开/关/设置/切换）
2. get_device_status -查询设备状态
3. get_sensor_reading -读取温度、运动传感器
4. set_home_mode -执行场景（家庭/外出/睡眠/度假）
5. get_home_mode -检查当前模式
6. 饲料鱼 -触发式喂鱼器
7. 水生植物 -控制喷水灭火系统
8. 开始充电/停止充电 -电动汽车充电器控制

支持的设备（24+示例设备）

• 💡 灯（带亮度控制）
• 🌡️ 恒温器（温度+模式控制）
• 🔒 锁
• 🪟 百叶窗（带位置控制）
• 💨 风扇（带速度控制）
• 🚗 车库门
• 🐠 喂鱼器
• 💧 喷淋系统
• 🔌 电动车充电器
• 🌡️ 温度传感器
• 👁️ 运动传感器

主页模式

• 家 -欢迎模式（灯亮，72°F）
• 离开 -安全模式（关灯，锁已锁，65°F）
• 睡眠 -夜间模式（卧室调暗20%，门锁，68°F）
• 假期 -向外延伸（一切安全，60°F）

🚀 快速开始

1.安装依赖项

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

2.启动系统

选项A：使用菜单（最简单）

start.bat

然后从菜单中选择要开始的内容。

选项B：直接命令（建议用于开发）

打开2个单独的终端：

# 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.为Claude Desktop配置MCP服务器（可选）

运行配置帮助程序：

python app/stdio_config.py

复制输出并将其添加到您的Claude Desktop配置文件中：

• 视窗: %APPDATA%/Claude/claude_desktop_config.json
• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

配置示例：

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

添加配置后重新启动Claude Desktop。

💬 AI交互示例

设备控制

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

状态查询

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

主页模式

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

特别行动

"Feed the fish"
"Water the front yard for 10 minutes"
"Start charging my car"

📁 项目结构

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终点

REST API

• GET / -API信息
• GET /api/devices -获取所有设备（支持 ?room= 和 ?type= 过滤器）
• GET /api/rooms -获取房间列表
• GET /api/stats -获取仪表板统计信息
• WebSocket /ws -实时设备更新

WebSocket消息

来自服务器：

{
  "type": "device_update",
  "device_id": "living_room_light_main",
  "state": "on",
  "properties": {"brightness": 75}
}

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

{
  "type": "full_refresh"
}

🧪 测试

测试API服务器

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

直接测试MCP工具

python app/mcp_server_stdio.py

使用MCP检查员进行测试

npx @modelcontextprotocol/inspector python app/mcp_server_stdio.py

打开浏览器： http://localhost:6274

📋 所有可用命令

🔄 实时更新流程

1. AI助手调用MCP工具（例如。， control_device)
2. MCP服务器使用时间戳更新SQLite数据库
3. FastAPI服务器检测时间戳变化（每100ms轮询一次）
4. FastAPI通过WebSocket向所有连接的客户端广播更新
5. 前端接收更新并重新呈现受影响的设备
6. 总延迟：\<300ms

📊 性能指标

• ✅ 数据库查询：\<10ms
• ✅ MCP工具执行：\<100ms
• ✅ 变化检测：100ms轮询
• ✅ WebSocket广播：\<50ms
• ✅ 端到端更新：\<300ms
• ✅ 并发WebSocket连接：100+

🐛 故障排除

MCP服务器未连接

• 检查Claude Desktop配置文件路径
• 验证配置中的Python路径
• 配置更改后重新启动Claude Desktop

前端未更新

• 验证FastAPI服务器是否在端口8000上运行
• 检查浏览器控制台是否存在WebSocket错误
• 确保CORS源包含您的前端URL

数据库锁定错误

• 验证一次只有一个进程访问数据库
• 在database.py中自动启用WAL模式

端口已在使用中

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

🛠️ 发展

添加新设备类型

1. 将设备添加到 app/db/seed_data.py
2. 更新中的类型提示 app/models/device.py
3. 在前端添加图标 DeviceCard.jsx

添加新MCP工具

1. 添加 @mcp.tool() 装饰功能 app/mcp_server_stdio.py
2. 包括数据库操作
3. 用于AI助手上下文的docstring文档

有关详细的开发信息，请参阅 Developpent.md

📚 资源

• 模型上下文协议文档
• MCP Python SDK
• FastAPI文档
• React文档

📝 许可证

MIT许可证-有关详细信息，请参阅许可证文件

🤝 贡献

欢迎投稿！请打开问题或提交拉取请求。