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.