Home Assistant Connector（WorkBuddy）

为腾讯 WorkBuddy 生态开发的 Home Assistant 连接器：MCP stdio + 用户自填 Token 模式 （规范 06 / 06D 附录C），让 AI 通过自然语言查看和控制家中设备。

目录结构

home-assistant/
├── connector-meta.json   # 连接器元信息（type: mcp, auth_mode: token, minWorkbuddyVersion: 4.23.0）
├── mcp.json              # MCP Server 连接配置（stdio，凭证经 env 注入）
├── token-schema.json     # 用户自填 Token 表单（HA_URL + HA_TOKEN）
├── ha_mcp_server/        # MCP Server（Python，官方 mcp SDK FastMCP）
│   ├── __init__.py
│   ├── __main__.py       # python -m ha_mcp_server 入口
│   └── server.py         # 4 个 tool：list_states / get_state / call_service / list_services
├── skills/
│   └── SKILL.md          # Skill 文件（按 05 规范，教 AI 如何使用工具）
├── icon.svg              # 连接器图标
└── README.md

依赖仅 mcp（v1，FastMCP）+ httpx（Python ≥ 3.10）。

工具一览

HA REST API 端点：GET /api/states、GET /api/states/{entity_id}、 POST /api/services/{domain}/{service}、GET /api/services； 认证头 Authorization: Bearer ${HA_TOKEN}，httpx 超时 10s。

本地测试

cd <项目目录>/connectors/home-assistant

# 1. 装依赖（本目录 .venv 已装好；也可用任意 Python ≥3.10）
#    注意钉 mcp<2：官方 SDK 2.x 把 FastMCP 改名为 MCPServer，本代码按 v1 FastMCP 编写
python3 -m venv .venv
.venv/bin/pip install -i https://pypi.tuna.tsinghua.edu.cn/simple "mcp[cli]>=1.2,<2" httpx

# 2. 导出凭证（HA 界面：左下角用户资料 → 安全 → 长期访问令牌 → 创建令牌）
export HA_URL="http://127.0.0.1:8123"
export HA_TOKEN="eyJhbGciOi..."

# 3a. 用 MCP Inspector 交互测试
.venv/bin/mcp dev ha_mcp_server/server.py

# 3b. 或用脚本直连测试（走 MCP stdio 协议调用工具）
.venv/bin/python tests_smoke.py

错误处理约定

• 连接失败 → 提示检查 HA_URL / 网络可达性
• 401 → 提示令牌无效或已撤销，指引用户重新生成并更新 HA_TOKEN
• 404 → 提示实体 ID / domain / service 拼写问题
• 缺环境变量 / 超时 / 非 200 均返回可读中文错误，不会抛栈给 AI

正式提交前 TODO

• uvx 打包：把 ha_mcp_server 打成 PyPI 包（如 mcp-server-home-assistant）， mcp.json 改为 "command": "uvx", "args": ["mcp-server-home-assistant"]， 用户无需本地准备代码目录即可运行（骨架阶段用 python -m ha_mcp_server 需 cwd 在本目录）。

• 压测报告：按 06 规范 2.2.5 完成压测并附报告——QPS ≥ 50、P50 ≤ 500ms、 P99 ≤ 3000ms、超时率 < 1%、错误率 ≤ 0.5%（stdio 形态需覆盖基础混合调用 + 突发流量 2×QPS 30s 场景；locust/k6 均可）。

• 用真实 HA 令牌跑通全部 4 个 tool 的正路径（当前仅验证了 401 错误路径）。

• 提交前对照 06D 第 13.8 提交检查清单逐项复核。

• 按灵感模块 08 规范：提交 Skill 时必须同步提交 3~5 个灵感案例（case.json + output 单文件 + cover.png 720×400）。参考 <项目目录>/playbooks/asr-feishu-pipeline/ 的 case 结构