Home Assistant Control

一个用于控制外部 Home Assistant 设备的 MCP 控制层与前端系统页面。

项目定位

本仓库不是 Home Assistant 本体，也不是通用的自动化平台，而是一个围绕你自己的 Home Assistant 实例构建的控制与观测层。它的目标是把“设备发现、能力映射、MCP 工具暴露、审计日志、前端管理页面”串成一条稳定链路，方便大模型、前端页面和人工运维统一调用。

架构总览

整体架构按职责拆分为七层，彼此之间尽量保持单向依赖：

1. 启动装配层

负责进程启动、环境变量加载、运行模式选择和服务编排。

• 入口位于 packages/mcp-server/src/main.ts
• 支持 stdio 与 http 两种 MCP 运行模式
• 负责同时启动：
  • 管理 API（默认 4000）
  • MCP HTTP 服务（默认 4010）
• 负责把 runtime、工具集合、设备注册表、Home Assistant 客户端装配到 HTTP 或 stdio 入口中

2. 配置与设备映射层

负责把静态配置和 Home Assistant 动态实体融合成可控制设备视图。

• 配置文件：config/lights.json
• 作用：维护可控设备白名单和历史命名映射
• 设备映射会结合 Home Assistant 实体信息、房间信息、能力信息生成统一的 DeviceRecord
• 这层的目标不是“直接控制设备”，而是产出稳定、适合上层使用的设备视图

3. Schema 与策略校验层

负责对外部输入做结构化约束、字段校验和动作合法性检查。

• 入口文件：packages/mcp-server/src/models/schemas.ts
• 使用 zod 对所有工具参数进行强校验
• 负责把自然语言解析后的参数，转换成可执行、可验证的结构化输入
• 典型职责包括：
  • entity_id 非空校验
  • 亮度范围归一化
  • hvac_mode 枚举限制
  • 数值型参数的有限性校验

4. 工具层

负责把 schema 校验后的输入转成具体控制逻辑。

• 入口文件：packages/mcp-server/src/tools/*
• 负责设备发现、状态查询、开关控制、亮度控制、数值控制、空调控制等
• 工具层面向的是“业务动作”，而不是 HTTP 或 MCP 协议

5. Home Assistant 访问层

负责与真实 Home Assistant 实例通信。

• 入口文件：packages/mcp-server/src/services/ha-client.ts
• 负责读取 Home Assistant 实体、查询状态、下发控制指令
• 处理鉴权、超时、错误转换、实体发现等能力
• 上层只看到统一错误格式，不直接处理底层 API 细节

6. 对外服务层

负责把同一套 runtime 暴露成 HTTP 管理 API 与 MCP 服务。

• HTTP 管理 API：packages/mcp-server/src/server.ts
• MCP JSON-RPC / HTTP：packages/mcp-server/src/mcp-http.ts
• stdio MCP：packages/mcp-server/src/mcp.ts

这层主要解决三件事：

• 给前端页面提供数据接口
• 给 MCP 客户端提供工具注册与调用接口
• 保证不同传输方式下工具定义一致

7. 审计与记录层

负责记录每次工具调用、失败信息与统计数据。

• 入口文件：packages/mcp-server/src/services/audit-store.ts
• 记录请求时间、工具名、设备名、结果状态、错误码、耗时等字段
• 前端的“日志查询”和“失败统计”均依赖这一层

---

运行时数据流

一次典型的控制请求大致会经过以下链路：

1. 前端或 MCP 客户端发起请求
2. 对外服务层接收请求
3. Schema 层校验参数
4. 工具层决定具体动作
5. Home Assistant 访问层执行真实控制
6. 审计层记录结果
7. 前端或客户端拿到统一结果格式

这个链路的设计目标是：

• 输入可验证
• 控制可追踪
• 错误可定位
• HTTP 与 MCP 共用同一套底层能力

MCP 接入方式

stdio 模式

适合本地 MCP 客户端直接启动进程连接。

HTTP 模式

适合通过远程 URL 访问 MCP。

默认对外地址：

• http://127.0.0.1:4010/mcp

兼容的消息入口：

• POST /mcp
• POST /mcp/messages
• GET /mcp 用于 SSE 连接和会话协商

管理 API

默认管理 API 运行在：

• http://127.0.0.1:4000

常用接口：

• GET /healthz
• GET /api/admin/stats/overview
• GET /api/admin/stats/errors
• GET /api/admin/logs
• GET /api/admin/devices
• GET /api/admin/ha/entities/discover

Schema 设计说明

这一层的原则是：外部请求尽量宽松，内部执行尽量严格。

• MCP 工具会接收自然语言拆解后的参数
• 进入控制层之前必须经过 schema 校验
• 校验后的数据再交给工具层和 Home Assistant 访问层

通用字段规范

• entity_id

  • 类型：string
  • 要求：非空
  • 含义：Home Assistant 实体标识，例如 light.living_room_main

• query

  • 类型：string
  • 要求：非空
  • 含义：自然语言设备描述，例如“打开客厅灯”

• domain

  • 类型：string
  • 要求：可选
  • 含义：实体域，例如 light、switch、climate

• room

  • 类型：string
  • 要求：可选
  • 含义：房间/区域过滤条件

• keyword

  • 类型：string
  • 要求：可选
  • 含义：模糊搜索关键字

• enabled_only

  • 类型：boolean
  • 要求：可选
  • 含义：是否只返回启用设备

具体 Schema 参数结构

以下内容对应 packages/mcp-server/src/models/schemas.ts 的实际定义。

1. listDevicesInputSchema

用于列出可控制设备。

{
  domain?: string;
  room?: string;
  keyword?: string;
  enabled_only?: boolean;
}

字段说明

• domain
  • 可选
  • 设备域过滤，例如 light、switch、button、number、climate、sensor
• room
  • 可选
  • 房间过滤，例如 living_room
• keyword
  • 可选
  • 根据显示名、别名或实体特征做模糊筛选
• enabled_only
  • 可选
  • true 表示只返回启用设备；未传或 false 时返回所有匹配项

---

2. resolveDeviceInputSchema

用于把自然语言请求解析为设备候选。

{
  query: string;
  domain?: string;
  room?: string;
}

字段说明

• query
  • 必填
  • 最小长度 1
  • 例如：打开客厅灯
• domain
  • 可选
  • 进一步缩小解析范围
• room
  • 可选
  • 进一步限定房间范围

返回场景

此 schema 常用于“智能匹配候选设备”，不是直接控制设备。

---

3. getDeviceStateInputSchema

用于查询某个设备当前状态。

{
  entity_id: string;
}

字段说明

• entity_id
  • 必填
  • 最小长度 1
  • 例如：switch.kitchen_main

---

4. controlDeviceInputSchema

用于统一控制多种设备类型。

{
  entity_id: string;
  action:
    | 'turn_on'
    | 'turn_off'
    | 'press'
    | 'set_brightness'
    | 'set_value'
    | 'set_temperature'
    | 'set_hvac_mode'
    | 'set_fan_mode'
    | 'set_swing_mode';
  brightness?: number;
  value?: number;
  temperature?: number;
  hvac_mode?: 'off' | 'heat' | 'cool' | 'heat_cool' | 'auto' | 'dry' | 'fan_only';
  fan_mode?: string;
  swing_mode?: string;
}

字段说明

• entity_id
  • 必填
  • 目标实体 ID
• action
  • 必填
  • 控制动作类型
• brightness
  • 可选
  • 当 action = set_brightness 时使用
  • 亮度值通常应在 0 ~ 255 之间，前端会做滑块控制
• value
  • 可选
  • 当 action = set_value 时使用
  • 用于 number 域
• temperature
  • 可选
  • 当 action = set_temperature 时使用
  • 用于 climate 域
• hvac_mode
  • 可选
  • 当 action = set_hvac_mode 时使用
  • 仅允许以下值：off、heat、cool、heat_cool、auto、dry、fan_only
• fan_mode
  • 可选
  • 当 action = set_fan_mode 时使用
• swing_mode
  • 可选
  • 当 action = set_swing_mode 时使用

动作与参数关系

• turn_on
  • 只需要 entity_id
• turn_off
  • 只需要 entity_id
• press
  • 只需要 entity_id
• set_brightness
  • 需要 entity_id + brightness
• set_value
  • 需要 entity_id + value
• set_temperature
  • 需要 entity_id + temperature
• set_hvac_mode
  • 需要 entity_id + hvac_mode
• set_fan_mode
  • 需要 entity_id + fan_mode
• set_swing_mode
  • 需要 entity_id + swing_mode

---

5. listLightsInputSchema

用于列出灯光设备。

{
  room?: string;
  keyword?: string;
  support_brightness?: boolean;
}

字段说明

• room
  • 可选
• keyword
  • 可选
• support_brightness
  • 可选
  • 是否只看支持亮度的灯

---

6. resolveLightInputSchema

用于自然语言解析灯光目标。

{
  query: string;
}

字段说明

• query
  • 必填
  • 例如：打开卧室灯

---

7. getLightStateInputSchema

用于查询灯光状态。

{
  entity_id: string;
}

---

8. turnOnLightInputSchema

{
  entity_id: string;
}

---

9. turnOffLightInputSchema

{
  entity_id: string;
}

---

10. setLightBrightnessInputSchema

用于设置灯光亮度。

{
  entity_id: string;
  brightness: number;
}

约束

• brightness 会先转换为数字
• 会四舍五入为整数
• 最终必须在 0 ~ 255 之间

---

11. setLightStateInputSchema

用于同时设置灯光开关状态与可选亮度。

{
  entity_id: string;
  state: 'on' | 'off';
  brightness?: number;
}

字段说明

• state
  • 必填
  • 仅允许 on 或 off
• brightness
  • 可选
  • 一般与 state = on 联合使用

---

12. pressButtonInputSchema

{
  entity_id: string;
}

用于按钮类实体执行一次按下动作。

---

13. setNumberValueInputSchema

{
  entity_id: string;
  value: number;
}

用于数值类实体设置目标值。

---

14. turnOnSwitchInputSchema

{
  entity_id: string;
}

---

15. turnOffSwitchInputSchema

{
  entity_id: string;
}

---

16. listClimateDevicesInputSchema

用于列出空调/气候类设备。

{
  room?: string;
  keyword?: string;
}

---

17. setClimateTemperatureInputSchema

{
  entity_id: string;
  temperature: number;
}

用于设置气候设备目标温度。

---

18. setClimateHvacModeInputSchema

{
  entity_id: string;
  hvac_mode: 'off' | 'heat' | 'cool' | 'heat_cool' | 'auto' | 'dry' | 'fan_only';
}

约束

• hvac_mode 是枚举值，必须是 Home Assistant 支持的 HVAC 模式之一
• 不允许传入任意字符串

---

19. setClimateFanModeInputSchema

{
  entity_id: string;
  fan_mode: string;
}

字段说明

• fan_mode
  • 必填
  • 非空字符串
  • 具体可用值由目标设备自身支持的模式决定

---

20. setClimateSwingModeInputSchema

{
  entity_id: string;
  swing_mode: string;
}

字段说明

• swing_mode
  • 必填
  • 非空字符串
  • 具体可用值由目标设备自身支持的模式决定

设备域支持说明

当前支持的设备域：

• light：开关、亮度、状态查询
• switch：开关、状态查询
• button：按下、状态查询
• number：数值设置、状态查询
• climate：温度、HVAC 模式、风扇模式、摆风模式、状态查询
• sensor：状态查询

常用命令

pnpm docker:dev
docker compose up -d --build
docker compose up -d
docker compose ps
docker compose logs -f mcp-server
docker compose logs -f log-platform
docker compose down

目录说明

• packages/mcp-server：MCP 控制层后端
• apps/log-platform：前端系统页面
• config/lights.json：可控制设备白名单，历史命名保留，内容已支持多设备域
• start.bat / start.ps1：本地一键启动脚本，内部已切换为跨平台逻辑