npm package: @rezti/homeassistant-mcp-plus
Description: Extended Home Assistant MCP Server with enhanced query capabilities
Author: Kelvin
Latest version: 2.1.1

# Home Assistant MCP Plus

一个增强版的Home Assistant MCP服务器，为 Claude Desktop 提供智能家居查询功能。

## 功能特性

### 第一期功能 ✅
- 🏠 **查询房间信息** - 获取所有房间/区域的详细信息，包括实体和设备数量
- 🔧 **查询设备类型** - 按域名统计所有设备类型和数量
- 🔗 **连接测试** - 测试与Home Assistant的连接状态

### 2.0 版本新功能 🚀
- 🔌 **WebSocket 连接** - 更快的实时数据传输
- 📊 **实时状态监控** - 设备状态变化实时通知
- 🔄 **自动重连机制** - 网络中断时自动恢复连接
- ⚡ **性能优化** - 减少网络延迟，提升响应速度

### 即将推出 🚧
- 设备状态查询和控制
- 自动化规则查询
- 历史数据分析
- 能源监控

## 快速开始

### 1. 配置 Claude Desktop

在 Claude Desktop 配置文件中添加：

**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`  
**Linux**: `~/.config/claude/claude_desktop_config.json`

```json
{
  "mcpServers": {
    "homeassistant": {
      "command": "npx",
      "args": ["@rezti/homeassistant-mcp-plus"],
      "env": {
        "HA_URL": "http://homeassistant.local:8123",
        "HA_TOKEN": "your-long-lived-access-token"
      }
    }
  }
}
```

### 2. 获取 Home Assistant 长期访问令牌

1. 登录到Home Assistant Web界面
2. 点击左下角的用户头像
3. 滚动到底部找到"长期访问令牌"部分
4. 点击"创建令牌"
5. 输入令牌名称（如"MCP Server"）
6. 复制生成的令牌

### 3. 重启 Claude Desktop

关闭并重新打开Claude Desktop应用程序。

## 使用方法

重启 Claude Desktop 后，你可以询问：

- "显示我家里有哪些房间？"
- "办公室有哪些设备？"
- "测试Home Assistant连接状态"
- "ban_gong_shi 房间有哪些设备？"

## 可用工具

### 1. get_rooms
获取所有房间/区域的详细信息。

**返回信息：**
- 房间总数
- 每个房间的设备数量
- 房间列表（包含 friendly_name、area_id 和 device_count）

**示例输出：**
```json
{
  "total_rooms": 2,
  "rooms": [
    {
      "friendly_name": "客厅",
      "area_id": "ke_ting",
      "device_count": 5
    },
    {
      "friendly_name": "办公室",
      "area_id": "ban_gong_shi",
      "device_count": 9
    }
  ]
}
```

### 2. get_devices_by_room
获取指定房间的设备明细信息。

**参数：**
- `room_identifier` (string): 房间标识符，可以是房间名称（如"办公室"）或区域ID（如"ban_gong_shi"）

**返回信息：**
- 房间标识符
- 设备总数
- 设备列表（包含 friendly_name、name、id 和 entities）

**示例输出：**
```json
{
  "room_identifier": "办公室",
  "total_devices": 9,
  "devices": [
    {
      "friendly_name": "3D打印台灯",
      "name": "3D打印台灯",
      "id": "dad23a079925a72a2e5391b6b263cc43",
      "entities": [
        {
          "name": "light.3d_da_yin_tai_deng",
          "friendly_name": "3D打印台灯",
          "domain": "light"
        }
      ]
    },
    {
      "friendly_name": "Rezti Switch Z6 4 4 V3-03F87C",
      "name": "Rezti Switch Z6 4 4 V3-03F87C",
      "id": "37a4219cb56b13f01b240e0786a8cb73",
      "entities": [
        {
          "name": "switch.relay1",
          "friendly_name": "Relay 1",
          "domain": "switch"
        },
        {
          "name": "switch.relay2",
          "friendly_name": "Relay 2",
          "domain": "switch"
        }
      ]
    }
  ]
}
```

### 3. update_device_friendly_name
更新指定设备的友好名称。

**参数：**
- `device_id` (string): 设备的唯一标识符
- `friendly_name` (string): 要设置的新友好名称

**返回信息：**
- 操作是否成功
- 消息说明
- 设备ID和新名称（成功时）

**示例输出：**
```json
{
  "success": true,
  "message": "设备名称更新成功",
  "device_id": "dad23a079925a72a2e5391b6b263cc43",
  "friendly_name": "新的设备名称"
}
```

**错误示例：**
```json
{
  "success": false,
  "message": "设备未找到: invalid_device_id"
}
```

### 4. test_ha_connection
测试与Home Assistant的连接。

**返回信息：**
- 连接状态
- Home Assistant版本
- 配置信息

## 高级配置

### 多个 Home Assistant 实例
```json
{
  "mcpServers": {
    "homeassistant-home": {
      "command": "npx",
      "args": ["@rezti/homeassistant-mcp-plus"],
      "env": {
        "HA_URL": "http://home.local:8123",
        "HA_TOKEN": "home-token"
      }
    },
    "homeassistant-office": {
      "command": "npx",
      "args": ["@rezti/homeassistant-mcp-plus"],
      "env": {
        "HA_URL": "http://office.local:8123",
        "HA_TOKEN": "office-token"
      }
    }
  }
}
```

## 开发和测试

### 本地开发
```bash
# 克隆项目
git clone https://github.com/ReZ-TI/mcp-homeassistant-plus
cd mcp-homeassistant-plus

# 安装依赖
npm install

# 构建项目
npm run build

# 开发模式运行
npm run dev
```

### 命令行测试
```bash
# 设置环境变量
export HA_URL="http://homeassistant.local:8123"
export HA_TOKEN="your-long-lived-access-token"

# 运行服务器
npm start
```

## 项目结构
```
homeassistant-mcp-plus/
├── src/
│   ├── index.ts              # MCP服务器主文件
│   └── homeassistant-ws.ts   # Home Assistant WebSocket客户端
├── build/                    # 编译输出目录
├── package.json
├── tsconfig.json
├── README.md
├── QUICK_START.md            # 详细安装指南
├── DEVELOPER.md              # 开发者文档
├── start.sh                  # 启动脚本
└── test-simple.js            # 简单测试脚本
```

## 开发脚本
- `npm run build` - 构建项目
- `npm run watch` - 监听文件变化并自动构建
- `npm run dev` - 开发模式运行
- `npm start` - 运行构建后的服务器

## 故障排除

### 连接问题
- 确保Home Assistant URL正确且可访问
- 验证长期访问令牌有效
- 检查网络连接和防火墙设置

### 工具调用失败
- 查看Claude Desktop启动时的日志信息
- 使用 `test_ha_connection` 工具验证连接
- 确保Home Assistant实例正常运行

### 配置问题
- 确认 Claude Desktop 配置文件路径正确
- 验证环境变量设置正确
- 检查网络连接

## 许可证

MIT License

## 贡献

欢迎提交Issue和Pull Request！

---

详细的安装和使用说明请参考 [QUICK_START.md](./QUICK_START.md)  
开发者文档请参考 [DEVELOPER.md](./DEVELOPER.md)