Metadata-Version: 2.5
Name: workbuddy-mcp-homeassistant
Version: 1.0.0
Summary: WorkBuddy Connector MCP server for Home Assistant (stdio, auth_mode: token)
Author: dangsys
License: MIT
Keywords: home assistant,mcp,model-context-protocol,smart home,workbuddy
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Topic :: Software Development
Requires-Python: >=3.10
Requires-Dist: httpx>=0.27
Requires-Dist: mcp<2,>=1.2
Description-Content-Type: text/markdown

# 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 打包**：把 `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 结构
