workbuddy-mcp-homeassistant

# 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）。 ## 工具一览 | Tool | 用途 | |---|---| | `list_states(entity_id_prefix?)` | 列出实体状态（entity_id/state/friendly_name），可按前缀过滤 | | `get_state(entity_id)` | 单个实体详情（含 attributes） | | `call_service(domain, service, entity_id, data?)` | 调用 HA 服务控制设备 | | `list_services(domain?)` | 查询可用服务（call_service 的参数字典） | 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。 ## 本地测试 ```bash 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 打包*…