Home Assistant MCP Control

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

项目定位

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

Related MCP server: Home Assistant MCP Server

架构总览

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

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：本地一键启动脚本，内部已切换为跨平台逻辑