Homie5 MCP Server

Homie MCP服务器

允许LLM与以下对象交互的MCP服务器 Homie 5 MQTT上的智能家居设备。它抽象了MQTT主题和Homie约定，提供了一个干净的面向设备的API。

运作原理

1. 启动时（或之后 homie_connect)，订阅 {domain}/5/+/$state 和 {domain}/5/+/$description
2. 当一个设备 $description 到达（保留JSON），解析并订阅 {domain}/5/{deviceId}/+/+ 对于所有房产价值
3. 属性值在到达时被缓存——缓存始终是最新的
4. 当一个设备 $state 清除（空负载）后，设备将从缓存中删除
5. 从缓存读取的工具调用（即时）或向MQTT发布集命令

设置

npm install
npm run build

配置

配置是通过环境变量进行的。有两种模式：

预配置模式：设置 HOMIE_BROKER_URL 服务器在启动时连接。这 homie_connect 工具未暴露。

交互模式：省略 HOMIE_BROKER_URL LLM通过 homie_connect 工具。

凭证包含在代理URL中（例如。 mqtt://user:pass@broker:1883).

使用SSE传输时，服务器始终通过HTTPS运行。如果两者都有 HOMIE_TLS_CERT 和 HOMIE_TLS_KEY 如果已设置，则使用这些证书。如果两者都没有设置，则会自动生成自签名证书。只设置其中一个是错误的。

用法

克劳德代码（预配置）

claude mcp add homie-mcp -- env HOMIE_BROKER_URL=mqtt://localhost:1883 node /path/to/homie-mcp-server/build/index.js

克劳德代码（交互式）

claude mcp add homie-mcp -- node /path/to/homie-mcp-server/build/index.js

法学硕士需要致电 homie_connect 在它可以与设备交互之前。

独立（stdio）

HOMIE_BROKER_URL=mqtt://localhost:1883 node build/index.js

SSE运输（自签名证书）

HOMIE_BROKER_URL=mqtt://localhost:1883 HOMIE_SSE_PORT=3000 node build/index.js

SSE运输（海关证书）

HOMIE_BROKER_URL=mqtt://localhost:1883 HOMIE_SSE_PORT=3000 HOMIE_TLS_CERT=cert.pem HOMIE_TLS_KEY=key.pem node build/index.js

连接到 https://localhost:3000/sse 对于SSE流，POST到 /messages 对于请求。

码头工人

docker build -t homie-mcp-server .
docker run --init -e HOMIE_BROKER_URL=mqtt://user:pass@broker:1883 homie-mcp-server

HOMIE_BROKER_URL 如果没有它，容器将拒绝启动。

要使用SSE传输：

docker run --init -e HOMIE_BROKER_URL=mqtt://broker:1883 -e HOMIE_SSE_PORT=3000 -p 3000:3000 homie-mcp-server

使用自定义证书，将它们装载到容器中：

docker run --init \
  -e HOMIE_BROKER_URL=mqtt://broker:1883 \
  -e HOMIE_SSE_PORT=3000 \
  -e HOMIE_TLS_CERT=/certs/cert.pem \
  -e HOMIE_TLS_KEY=/certs/key.pem \
  -v /path/to/certs:/certs:ro \
  -p 3000:3000 homie-mcp-server

工具

homie_connect

*仅在以下情况下可用 HOMIE_BROKER_URL 未设置。*

连接到MQTT代理。如果已连接，请先断开连接，然后重新连接到新代理。连接后自动启动设备发现。

凭据位于URL中： mqtt://user:pass@host:1883.

homie_get_devices

列出所有发现的设备。返回设备ID、名称、类型和状态。

默认情况下，仅返回活动设备（状态 ready 或 sleeping).通过 include_all: true 还包括设备 init, disconnected，以及 lost 国家。

homie_get_device

获取单个设备的完整详细信息：状态、描述、所有节点和属性及其当前值。

homie_get_value

获取特定属性的当前值及其元数据（数据类型、单位、格式、可设置）。

homie_set_value

向可设置属性发送命令。在发布之前，会根据属性的数据类型和格式验证该值。

验证规则：

• 布尔：必须是 "true" 或 "false"
• 整数：必须是一个整数，与格式中的min:max范围进行核对
• 浮点数：必须是一个数字，根据格式中的min:max范围进行检查
• 枚举：必须是格式中以逗号分隔的值之一
• 颜色：已验证 rgb 或 hsv 格式
• 日期时间：必须是有效的ISO 8601
• 持续时间：必须为ISO 8601持续时间（例如。 PT30S)

命令发布到 {topic}/set 根据Homie规范，QoS为0，不保留。

homie_discover

强制重新发现。清除设备存储，取消订阅所有内容，并重新订阅发现主题。保留的邮件将重新填充存储。没有参数。