Homeassistant MCP

🚀 模型上下文

本项目提供了 home-assistant-model-context 模块，用于与 Home Assistant 进行交互，实现实体、楼层和区域访问、设备控制等功能，方便开发者进行相关开发。

🚀 快速开始

你可以按照以下步骤快速开始使用本项目：

1. 安装项目依赖。
2. 参考使用示例进行开发。
3. 依据开发指南进行项目的运行、构建等操作。

📦 安装指南

使用以下命令安装 home-assistant-model-context：

npm install home-assistant-model-context

💻 使用示例

基础用法

const { ModelContext } = require('home-assistant-model-context');

// 初始化模型上下文
async function initializeModel() {
  const model = new ModelContext({
    host: 'localhost',
    port: 8123,
    tokenPath: '/config/secrets.yaml'
  });

  // 获取当前状态
  await model.initialize();
  const state = await model.getState('light.living_room');
  console.log('灯的状态:', state.state);
}

// 执行初始化
initializeModel().catch(console.error);

📚 详细文档

运行命令

# 开发模式（带热重载）
npm run dev

# 构建项目
npm run build

# 生产模式
npm run start

# 运行测试
npx jest --config=jest.config.cjs

# 代码格式化
npm run lint

# 生成文档
npm run doc:gen

配置文件

// config.json
{
  "host": "localhost",
  "port": 8123,
  "token": "your_api_key_here"
}

🔧 技术细节

故障排除

常见问题

1. Node.js 版本（toSorted is not a function）

   • 解决方案： 更新到 Node.js 20.10.0+

     nvm install 20.10.0
     nvm use 20.10.0
     

2. 连接问题

   • 确保 Home Assistant 正在运行
   • 检查 HASS_HOST 是否可访问
   • 验证令牌权限

3. 设备管理问题

   • 确保 Supervisor 访问权限
   • 检查添加组件兼容性
   • 验证系统资源

项目状态

✅ 已完成

• 实体、楼层和区域访问
• 设备控制（灯、气候、遮阳篷、开关、联系人）
• 添加件管理功能
• HACS 集成包管理
• 先进的自动化配置
• 基本状态管理
• 错误处理与验证
• Docker 容器化
• Jest 测试框架
• TypeScript 整合

🚧 进行中

• WebSocket 实现以支持实时更新
• 增强安全特性
• 工具组织优化
• 性能优化
• 资源上下文整合
• API 文档生成
• 多平台桌面整合
• 高级 macOS 整合
• 类型安全改进
• 测试覆盖率扩展

项目贡献

1. 叉仓库
2. 创建功能分支
3. 实现更改
4. 添加新功能的测试
5. 确保所有测试通过
6. 提交拉取请求

资源链接

• MCP 文档
• Home Assistant 官方文档
• Node.js 官方网站

📄 许可证

MIT License

版权所有 (c) 2023, Author 姓名

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.