npm package: @kaizhang0808/hacs-mcp
Description: MCP server for HomeAssistant integration
Author: kai
Latest version: 1.0.2

# HomeAssistant MCP 服务器

这是一个基于 Model Context Protocol (MCP) 的 HomeAssistant 服务器，允许通过 MCP 协议与 HomeAssistant 智能家居系统进行交互。

## 功能特性

- 🔍 获取所有实体列表
- 📊 获取特定实体状态
- 💡 控制灯光（打开/关闭/设置亮度）
- 🔄 切换开关状态
- 🛠️ 调用任意 HomeAssistant 服务
- 📋 获取可用服务列表
- 🔗 检查连接状态
- 💬 智能提示词生成
- ⚙️ 自动化管理（创建、删除、启用/禁用）
- 📋 全局系统提示词生成

## 安装和配置

### 1. 安装依赖

```bash
cd HomeAssistant_MCP
npm install
```

### 2. 配置环境变量

创建 `.env` 文件或在系统环境变量中设置：

```bash
HA_BASE_URL=http://your-homeassistant-ip:8123
HA_ACCESS_TOKEN=your_long_lived_access_token
```

**获取访问令牌：**
1. 登录 HomeAssistant
2. 点击用户资料 → 创建令牌
3. 复制生成的令牌

### 3. 构建项目

```bash
npm run build
```

## 使用方法

### 开发模式运行

```bash
npm run dev
```

### 生产模式运行

```bash
npm run build
npm start
```

## 可用工具

### get_entities
获取实体列表（支持分页、过滤和搜索）。

**参数：**
- `page` (number, 可选): 页码（从1开始），默认：1
- `page_size` (number, 可选): 每页实体数量，默认：20，最大：50
- `domain` (string, 可选): 过滤特定域，例如：`light`, `switch`, `sensor`
- `search` (string, 可选): 搜索实体名称中的关键词

**响应示例：**
```json
{
  "total_entities": 150,
  "page": 1,
  "page_size": 20,
  "total_pages": 8,
  "entities": [
    {
      "entity_id": "light.living_room",
      "state": "on",
      "friendly_name": "客厅灯",
      "domain": "light",
      "last_updated": "2024-01-01T12:00:00.000Z"
    }
  ],
  "domain_statistics": {
    "light": 25,
    "switch": 18,
    "sensor": 107
  },
  "filters": {
    "domain": "light",
    "search": "living"
  }
}
```

### get_entity_state
获取特定实体的详细信息。

**参数：**
- `entity_id` (string): 实体ID，例如 `light.living_room`

### turn_on_light
打开灯光。

**参数：**
- `entity_id` (string): 灯光实体ID
- `brightness` (number, 可选): 亮度值 (0-255)

### turn_off_light
关闭灯光。

**参数：**
- `entity_id` (string): 灯光实体ID

### set_light_brightness
设置灯光亮度。

**参数：**
- `entity_id` (string): 灯光实体ID
- `brightness` (number): 亮度值 (0-255)

### toggle_switch
切换开关状态。

**参数：**
- `entity_id` (string): 开关实体ID

### get_services
获取所有可用服务列表。

### call_service
调用任意 HomeAssistant 服务。

**参数：**
- `domain` (string): 服务域，例如 `light`
- `service` (string): 服务名称，例如 `turn_on`
- `service_data` (object, 可选): 服务数据

### check_connection
检查与 HomeAssistant 的连接状态。

### generate_prompt
根据实体状态生成智能家居控制提示词。

**参数：**
- `context` (string): 用户意图或场景描述
- `style` (string, 可选): 提示词风格，可选值：`natural`（自然语言）、`technical`（技术版）、`concise`（简洁版）

**示例用法：**

```json
{
  "tool": "generate_prompt",
  "arguments": {
    "context": "晚上准备睡觉",
    "style": "natural"
  }
}
```

**响应示例：**
```
基于当前智能家居状态，以下是针对"晚上准备睡觉"的提示词：

当前设备状态：
💡 灯光：
  - 客厅灯: 开启 (亮度: 80%)
  - 卧室灯: 关闭
🔌 开关：
  - 电视开关: 开启
📊 传感器：
  - 温度传感器: 22°C
  - 湿度传感器: 45%

建议操作：
• 关闭不必要的灯光
• 调暗卧室灯光
• 检查门窗传感器状态
```

## 改进功能

### 解决上下文窗口溢出问题
针对大量实体导致上下文窗口溢出的问题，我们实施了以下改进：

1. **分页机制**：支持按页获取实体，避免一次性加载所有数据
2. **域过滤**：可以按实体域（如 light、switch、sensor）进行过滤
3. **搜索功能**：支持按关键词搜索实体名称或友好名称
4. **响应精简**：返回简化的实体信息，减少数据量
5. **统计信息**：提供域统计和分页信息

## 示例用法

### 获取所有实体（分页）
```json
{
  "tool": "get_entities",
  "arguments": {
    "page": 1,
    "page_size": 20
  }
}
```

### 过滤灯光实体
```json
{
  "tool": "get_entities",
  "arguments": {
    "domain": "light",
    "page_size": 10
  }
}
```

### 搜索实体
```json
{
  "tool": "get_entities",
  "arguments": {
    "search": "living",
    "page_size": 5
  }
}
```

### 组合过滤和搜索
```json
{
  "tool": "get_entities",
  "arguments": {
    "domain": "sensor",
    "search": "temperature",
    "page": 1,
    "page_size": 8
  }
}
```

### 获取特定灯光状态
```json
{
  "tool": "get_entity_state",
  "arguments": {
    "entity_id": "light.living_room"
  }
}
```

### 打开灯光
```json
{
  "tool": "turn_on_light",
  "arguments": {
    "entity_id": "light.living_room",
    "brightness": 200
  }
}
```

### 调用服务
```json
{
  "tool": "call_service",
  "arguments": {
    "domain": "light",
    "service": "turn_on",
    "service_data": {
      "entity_id": "light.living_room",
      "brightness": 150
    }
  }
}
```

### 生成智能提示词
```json
{
  "tool": "generate_prompt",
  "arguments": {
    "context": "节能模式",
    "style": "technical"
  }
}
```

```json
{
  "tool": "generate_prompt",
  "arguments": {
    "context": "回家场景",
    "style": "concise"
  }
}
```

## 自动化功能

### get_automations
获取所有自动化列表。

**参数：** 无

**响应示例：**
```json
{
  "total_automations": 5,
  "automations": {
    "automation.0": {
      "alias": "晚上自动关灯",
      "description": "晚上10点自动关闭所有灯光",
      "trigger_count": 1,
      "condition_count": 0,
      "action_count": 1,
      "mode": "single",
      "enabled": true
    },
    "automation.1": {
      "alias": "温度过高开空调",
      "description": "当温度超过28度时自动打开空调",
      "trigger_count": 1,
      "condition_count": 1,
      "action_count": 1,
      "mode": "single",
      "enabled": true
    }
  }
}
```

### create_automation
创建新的自动化。

**参数：**
- `alias` (string): 自动化名称
- `description` (string, 可选): 自动化描述
- `trigger` (array): 触发器配置
  - `platform` (string): 触发器平台，如：`time`, `state`, `numeric_state`等
  - `at` (string, 可选): 定时触发时间（HH:MM:SS格式）
  - `entity_id` (string, 可选): 实体ID，用于状态触发
  - `from` (string, 可选): 状态从什么值变化
  - `to` (string, 可选): 状态变化到什么值
- `condition` (array, 可选): 条件配置
  - `condition` (string): 条件类型，如：`state`, `numeric_state`等
  - `entity_id` (string): 实体ID
  - `state` (string, 可选): 期望的状态值
  - `above` (number, 可选): 数值条件：大于
  - `below` (number, 可选): 数值条件：小于
- `action` (array): 动作配置
  - `service` (string): 要调用的服务，如：`light.turn_on`
  - `entity_id` (string): 目标实体ID
  - `brightness` (number, 可选): 灯光亮度（0-255）
  - `data` (object, 可选): 其他服务数据
- `mode` (string, 可选): 自动化模式，如：`single`, `restart`, `queued`, `parallel`
- `enabled` (boolean, 可选): 是否启用自动化

**示例用法：**

定时自动化（晚上10点关灯）：
```json
{
  "tool": "create_automation",
  "arguments": {
    "alias": "晚上自动关灯",
    "description": "晚上10点自动关闭所有灯光",
    "trigger": [
      {
        "platform": "time",
        "at": "22:00:00"
      }
    ],
    "action": [
      {
        "service": "light.turn_off",
        "entity_id": "light.living_room"
      },
      {
        "service": "light.turn_off",
        "entity_id": "light.bedroom"
      }
    ],
    "mode": "single",
    "enabled": true
  }
}
```

条件自动化（温度过高开空调）：
```json
{
  "tool": "create_automation",
  "arguments": {
    "alias": "温度过高开空调",
    "description": "当温度超过28度时自动打开空调",
    "trigger": [
      {
        "platform": "state",
        "entity_id": "sensor.temperature",
        "to": "on"
      }
    ],
    "condition": [
      {
        "condition": "numeric_state",
        "entity_id": "sensor.temperature",
        "above": 28
      }
    ],
    "action": [
      {
        "service": "climate.turn_on",
        "entity_id": "climate.air_conditioner"
      }
    ],
    "mode": "single",
    "enabled": true
  }
}
```

状态变化自动化（有人回家开灯）：
```json
{
  "tool": "create_automation",
  "arguments": {
    "alias": "有人回家开灯",
    "description": "当门传感器检测到有人回家时自动开灯",
    "trigger": [
      {
        "platform": "state",
        "entity_id": "binary_sensor.front_door",
        "from": "off",
        "to": "on"
      }
    ],
    "action": [
      {
        "service": "light.turn_on",
        "entity_id": "light.entrance",
        "brightness": 150
      }
    ],
    "mode": "single",
    "enabled": true
  }
}
```

### delete_automation
删除自动化。

**参数：**
- `automation_id` (string): 自动化ID

**示例用法：**
```json
{
  "tool": "delete_automation",
  "arguments": {
    "automation_id": "automation.0"
  }
}
```

### toggle_automation
启用或禁用自动化。

**参数：**
- `automation_id` (string): 自动化ID
- `enabled` (boolean): 是否启用

**示例用法：**
```json
{
  "tool": "toggle_automation",
  "arguments": {
    "automation_id": "automation.0",
    "enabled": false
  }
}
```

## 故障排除

1. **连接失败**
   - 检查 `HA_BASE_URL` 是否正确
   - 验证 `HA_ACCESS_TOKEN` 是否有效
   - 确保 HomeAssistant 实例正在运行

2. **权限问题**
   - 确保访问令牌具有足够的权限
   - 检查实体是否可访问

3. **网络问题**
   - 确保可以访问 HomeAssistant 实例
   - 检查防火墙设置

4. **自动化创建失败**
   - 检查触发器、条件、动作的配置格式
   - 确保引用的实体存在且可访问
   - 验证服务调用参数是否正确

## 许可证

MIT