高级家庭助手-mcp
项目介绍
家庭助手 MCP
弥合AI助手与智能家居之间的差距 🚀
一个强大、安全且可扩展的模型上下文协议（MCP）服务器，使像Claude、GPT和Cursor这样的AI助手能够无缝地与家庭助手交互。通过自然语言命令控制灯光、气候、自动化等。
✨ 功能概述
🤖 AI驱动的智能家居控制
- 自然语言处理：将“将客厅灯光调暗到50%”转换成实际设备命令
- 多助手支持：兼容Claude、GPT-4、Cursor和其他MCP兼容助手
- 智能上下文：记住设备状态、关系和用户偏好
- Smithery 集成：通过Smithery.ai一键安装和部署
🛡️ 企业级安全性
- 速率限制：通过可配置请求限制防止滥用
- 输入净化：防止XSS和注入攻击
- JWT认证：基于令牌的安全访问控制
- 安全头：全面保护Web漏洞
⚡ 高性能架构
- Bun 运行时：比Node.js快4倍，并内置TypeScript支持
- 流式响应：长时间运行操作的实时更新
- 模块化设计：清晰的责任分离和可扩展插件系统
- 多种传输方式：HTTP REST API、WebSocket和标准I/O支持
🏠 全面设备控制
- 照明控制：亮度、色温、RGB颜色和效果
- 气候管理：恒温器、HVAC模式、风扇控制和调度
- 自动化与场景：触发自动化、激活场景和管理例行程序
- 设备发现：智能设备列表，过滤和搜索
- 通知系统：通过家庭助手的通知渠道发送警报
- 智能维护：查找孤立设备，分析使用模式，能耗监控
- 智能场景：自动检测并管理无人在家、窗户/加热冲突、能源浪费
🚀 快速开始
几分钟内启动并运行：
# 克隆并安装
git clone https://github.com/jango-blockchained/advanced-homeassistant-mcp.git
cd advanced-homeassistant-mcp
bun install
# 配置环境
cp .env.example .env
# 编辑.env文件，填写您的家庭助手详情
# 启动服务器
bun run start:stdio
就这样！您的AI助手现在可以控制您的智能家居了。 🤖✨
📦 安装
前提条件
方案1：Smithery.ai（推荐快速设置）
Smithery是一个MCP服务器注册表，使得安装非常简单：
# 安装到Claude桌面
npx @smithery/cli install @jango-blockchained/homeassistant-mcp --client claude
# 安装到Cursor
npx @smithery/cli install @jango-blockchained/homeassistant-mcp --client cursor
# 安装到VS Code
npx @smithery/cli install @jango-blockchained/homeassistant-mcp --client vscode
您将被提示配置：
- 家庭助手URL
- 长期访问令牌
- 可选设置（端口、调试模式）
参见SMITHERY_DEPLOYMENT.md获取详细的部署指南。
方案2：NPX（快速启动）
npx @jango-blockchained/homeassistant-mcp@latest
方案3：Bunx与GitHub（无需登录NPM）
如果您无法登录NPM，可以使用Bunx直接从GitHub运行：
# 如果没有Bun，请先安装
curl -fsSL https://bun.sh/install | bash
# 然后从GitHub运行
bunx github:jango-blockchained/advanced-homeassistant-mcp
或者直接从Git安装：
bun add git+https://github.com/jango-blockchained/
advanced-homeassistant-mcp.git
homeassistant-mcp
方案4：Docker（容器化）
在Docker容器中运行MCP服务器：
# 拉取最新镜像
docker pull ghcr.io/jango-blockchained/advanced-homeassistant-mcp:latest
# 使用环境变量运行
docker run -d \
-e HOME_ASSISTANT_URL=http://your-ha-instance:8123 \
-e HOME_ASSISTANT_TOKEN=your_long_lived_access_token \
-p 4000:4000 \
--name homeassistant-mcp \
ghcr.io/jango-blockchained/advanced-homeassistant-mcp:latest
# 或者使用docker-compose（参见docker/目录中的示例）
可用的Docker标签：
latest- 最新稳定版1.0.x- 特定版本dev- 主分支的最新开发构建
方案5：本地安装
# 全局安装
bun add -g @jango-blockchained/homeassistant-mcp
# 或本地安装
bun add homeassistant-mcp
# 运行
homeassistant-mcp
方案6：从源码（最灵活）
git clone https://github.com/jango-blockchained/advanced-homeassistant-mcp.git
cd advanced-homeassistant-mcp
bun install
bun run build
bun run start:stdio
🛠️ 使用
AI助手集成
Claude桌面
添加到您的claude_desktop_config.json：
{
"mcpServers": {
"homeassistant-mcp": {
"command": "bunx",
"args": ["github:jango-blockchained/advanced-homeassistant-mcp"]
}
}
}
或使用npx：
{
"mcpServers": {
"homeassistant-mcp": {
"command": "npx",
"args": ["@jango-blockchained/homeassistant-mcp@latest"]
}
}
}
VS Code + Claude扩展
.vscode/settings.json已预配置以立即使用。
Cursor
添加到.cursor/config/config.json：
{
"mcpServers": {
"homeassistant-mcp": {
"command": "bunx",
"args": ["github:jango-blockchained/advanced-homeassistant-mcp"]
}
}
}
或使用npx：
{
"mcpServers": {
"homeassistant-mcp": {
"command": "npx",
"args": ["@jango-blockchained/homeassistant-mcp@latest"]
}
}
}
API使用
启动HTTP服务器：
bun run start -- --http
可用端点：
POST /api/tools/call- 执行工具GET /api/resources/list- 列出资源GET /api/health- 健康检查WebSocket /api/ws- 实时更新
配置
创建一个.env文件：
# 家庭助手
HASS_HOST=http://your-ha-instance:8123
HASS_TOKEN=your_long_lived_access_token
# 服务器
PORT=3000
NODE_ENV=production
# 安全
JWT_SECRET=your-secret-key
RATE_LIMIT_WINDOW=15
RATE_LIMIT_MAX=50
🏗️ 架构
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ AI助手 │◄──►│ MCP服务器 │◄──►│ 家庭助手 │
│ (Claude/GPT) │ │ │ │ │
└─────────────────┘ │ ┌─────────────┐ │ └─────────────────┘
│ │ 传输层 │ │
│ │ │ │
│ └─────────────┘ │
│ ┌─────────────┐ │
│ │ 中间件层 │ │
│ │ │ │
│ └─────────────┘ │
│ ┌─────────────┐ │
│ │ 工具层 │ │
│ │ │ │
└─────────────────┘
核心组件
- 传输层：HTTP、WebSocket、Stdio
- 中间件层：安全、验证、日志
- 工具层：设备控制、自动化、通知
- 资源管理器：状态管理和缓存
内置工具（共34个）
🎨 Aurora声光同步（10个工具）✨ 新增！
- 🎵 音频分析：提取BPM、节拍、情绪、频率数据
- 🔍 设备扫描：找到兼容Aurora的灯光
- 📊 设备配置：测量延迟及同步能力
- 🎬 时间线渲染：生成预渲染的灯光秀
- ▶️ 播放控制：播放/暂停/停止/跳转时间线
- 📋 时间线管理：列出、导出、导入时间线
- 📈 状态监控：系统状态和统计信息
- 🎯 智能同步：设备特定的定时补偿
- 🌈 能力感知：RGB、可调白光、仅亮度支持
- 🎶 节拍检测：灯光与音乐同步脉冲
🎨 Aurora 是一个完整的声光同步系统，将您的家庭助手灯光变成专业灯光秀，同步到音乐！
🏠 设备控制（13个工具）
- 🔦 灯光控制：亮度、色温、RGB、效果
- 🌡️ 气候控制：HVAC模式、温度、风扇控制
- 📺 媒体播放器：播放、音量、来源、声音模式
- 🪟 覆盖物：百叶窗、窗帘、车库门、位置控制
- 🔒 锁：带密码支持的锁定/解锁
- 💨 风扇：速度、摆动、方向、预设
- 🤖 吸尘器：清洁、对接、定点清洁、风扇速度
- 🚨 报警控制：布防/撤防模式，安全管理
- 🎛️ 通用控制：通用设备控制接口
⚙️ 自动化与场景（3个工具）
- 🎬 场景：激活预定义场景
- ⚙️ 自动化：列出、切换、触发自动化
- 🔧 自动化配置：创建/更新/删除复杂自动化
🔧 系统管理（6个工具）
- 📋 设备发现：按领域/区域列出和筛选设备
- 📱 通知：多通道警报系统
- 📊 历史记录：查询历史状态数据
- 📦 附加组件管理：安装、配置、控制附加组件
- 📦 包管理：HACS集成和自定义组件
- 🔔 事件订阅：实时SSE事件流
🧠 智能特性（2个工具）
-
🔧 维护工具：类似Spook的维护特性
- 查找孤立/不可用设备
- 分析房间的灯光使用模式
- 监控能耗
- 设备健康检查，电池警告
- 实体清理建议
-
🧠 智能场景：智能自动化检测
- 无人在家：自动关闭灯光，降低气候
- 窗户/加热冲突：自动禁用加热
- 节能：检测白天灯光，待机电源
- 生成自动化配置
📖 参见完整工具参考获取详细文档
MCP特性
-
📝 提示：预定义的常见家庭自动化任务模板
- 早晨/晚上例行程序
- 节能建议
- 安全设置
- 气候优化
- 媒体控制
- 故障排除助手
-
📊 资源：直接访问家庭助手的状态和配置
- 按类型列出设备（灯光、气候、传感器等）
- 区域/房间配置
- 自动化和场景列表
- 当前家庭状态的仪表板摘要
-
🛠️ 24个全面工具：完整的设备控制和智能自动化
- 参见完整工具参考获取所有可用工具
- 设备控制、自动化、系统管理和智能特性
- 自然语言到家庭助手API的翻译
🎯 示例命令
一旦集成，您的AI助手可以理解如下命令：
设备控制：
"关闭卧室的所有灯光"
"将恒温器设置为72°F"
"在客厅扬声器上播放音乐"
"打开车库门"
"锁定所有门"
"启动机器人吸尘器"
"将卧室风扇设置为50%"
自动化与场景：
"激活电影场景"
"触发早晨例行程序自动化"
"显示我所有的自动化"
信息与监控：
"客厅当前的温度是多少？"
"显示所有不可用的设备"
"哪些灯目前是开着的？"
通知：
"通知所有人晚餐准备好了"
"向我的手机发送警报"
智能维护：
"检查我的家庭助手健康状况"
"查找孤立或不可用的设备"
"分析我的灯光使用模式"
"显示我的能耗"
"哪些设备电池电量低？"
Aurora声光同步： ✨ 新增！
"分析这个音乐文件并同步我的灯光"
"扫描可以做Aurora效果的灯光"
"配置我的客厅灯光进行同步"
"为这首歌创建一个灯光秀"
"播放我刚创建的时间线"
"暂停灯光秀"
"显示Aurora状态"
智能场景：
"我要离开家，激活离家模式"
"有窗户开着并且加热开启吗？"
"检查是否有浪费能源的问题"
"关掉一切，我要去度假"
"我可以做什么来节省能源？"
您还可以使用提示进行引导性帮助：
"帮我设置一个早晨例行程序"
"显示节能技巧"
"如何控制我的媒体播放器？"
🤝 贡献
我们欢迎贡献！以下是参与的方法：
- 🍴 分叉仓库
- 🌿 创建功能分支
- 💻 进行更改
- 🧪 如适用，添加测试
- 📝 更新文档
- 🔄 提交拉取请求
开发设置
bun install
bun run build
bun test
代码风格
- TypeScript严格模式
- ESLint用于代码质量
- Prettier用于格式化
- Husky用于提交前钩子
发布
此项目使用自动化发布到GitHub、npm和Docker。参见AUTOMATED_RELEASES.md获取详细信息。
快速发布：
- 转到操作→版本提升和发布
- 点击运行工作流程
- 选择版本提升类型（补丁/次要/主要）
- 系统会自动：
- 📦 创建GitHub发行版
- 📤 发布到npm
- 🐳 构建并推送Docker镜像
📄 许可证
MIT许可证 - 详情见LICENSE。
🙏 致谢
使用以下工具构建：
将您的智能家居转变为AI驱动的体验