使用说明
HA MCP桥
家庭助理 监督员附加组件 + 自定义集成 连接到 家庭助理的内置 MCP服务器 并将MCP工具可用性视为可发现的HA实体。
添加到家庭助理
步骤1--添加Supervisor存储库
或手动： 设置→ 附加组件→ 附加应用商店→ ⋮ → 仓库 → paste https://github.com/Amantux/ha-mcp-bridge
步骤2——通过HACS添加集成
或者在HACS中手动操作： 集成→ ⋮ → 自定义仓库 → paste https://github.com/Amantux/ha-mcp-bridge → 类别 整合.
步骤3--启动插件，观看它自动显示
安装 HA MCP桥 从附加商店，然后 开始 它 A. 找到新设备 卡片出现在 设置→ 设备和服务 自动。
运作原理
┌──────────────────────────────────────────────────────────────────────┐
│ Supervisor host │
│ │
│ ┌──────────────────────────┐ ┌───────────────────────────┐ │
│ │ HA MCP Bridge add-on │ │ Home Assistant core │ │
│ │ (Docker container) │ 1 │ │ │
│ │ main.py starts │──POST─▶│ Supervisor /discovery │ │
│ │ register_discovery() │ │ validates + assigns UUID │ │
│ │ │ │ │ │ │
│ │ probe_mcp_server() 2 │◀──────▶│ /core/api/mcp_server/sse │ │
│ │ lists MCP tools │ │ (HA's built-in MCP Srv) │ │
│ │ │ │ │ 3 │ │
│ │ ThreadingHTTPServer │ │ ▼ │ │
│ │ GET /health │ │ async_step_hassio() │ │
│ │ GET /status ◀──────────│────────│ validate /health 4 │ │
│ │ │ │ │ │ │
│ └──────────────────────────┘ │ ▼ │ │
│ │ async_step_hassio_ │ │
│ │ confirm() │ │
│ │ _set_confirm_only() 5 │ │
│ │ → "New device found" │ │
│ │ badge in UI │ │
│ │ │ user clicks │ │
│ │ ▼ │ │
│ │ coordinator polls │ │
│ │ /status every 60 s │ │
└──────────────────────────────────────┴───────────────────────────┘
| # | 什么 | 为什么 |
|---|---|---|
| 1 | register_discovery() POST到 http://supervisor/discovery |
"discovery" 在 config.json 只是一个allowlist——插件必须发出调用，否则HA永远不会触发 async_step_hassio. |
| 2 | 附加探头 /core/api/mcp_server/sse 通过Supervisor代理 |
不需要用户令牌-- SUPERVISOR_TOKEN 自动注射。检查HA的MCP服务器是否已启用，并列出可用工具。 |
| 3 | 主管转发 HassioServiceInfo(uuid, config) 到HA核心 |
context={"source": SOURCE_HASSIO} → HA路线 async_step_hassio （不是 async_step_discovery，仅限于mDNS/DHCP）。 |
| 4 | async_step_hassio 验证 /health 在显示UI之前 |
快速失败。如果插件尚未准备就绪，请彻底中止，不发出孤立通知。 |
| 5 | async_step_hassio_confirm 电话 _set_confirm_only() |
这是一个召唤 “找到新设备” 徽章。如果没有它，流程将悄无声息地完成，没有可见的通知。 |
实体
| 实体 | 州 | 注释 |
|---|---|---|
sensor.*_status |
ok /错误字符串 |
附加活性 |
sensor.*_mcp_tool_count |
integer | HA MCP服务器公开的工具； 0 如果MCP服务器未启用；属性包括工具名称和错误 |
先决条件：启用HA的MCP服务器
对于 mcp_tool_count 要显示非零值，请启用内置集成：
设置→ 设备和服务→ 添加集成→ 搜索“MCP服务器” → 安装。
选项
设置→ 设备和服务→ HA MCP桥→ 配置
| 选项 | 默认值 | 范围 |
|---|---|---|
| 轮询间隔 | 60秒 | 10-3600秒 |
发展
# Test add-on locally (no Supervisor token = discovery skipped, MCP probe skipped)
python3 addon/main.py
curl http://127.0.0.1:8099/health
curl http://127.0.0.1:8099/status
# Version bump checklist (both files must match):
# 1. config.json "version": "x.y.z"
# 2. manifest.json "version": "x.y.z"
# 3. CHANGELOG.md new entry
# 4. git commit && git push
# → CI validates version sync, auto-creates GitHub Release for HACS
看 更改日志.md 完整的历史。
