{"$schema":"https://wellknown.network/schemas/agent-record-v1.json","schemaVersion":"1","id":"ag_agpv4wacytcq","handle":"workbuddy-mcp-homeassistant","url":"https://wellknown.network/agents/workbuddy-mcp-homeassistant","links":{"self":"https://wellknown.network/agents/workbuddy-mcp-homeassistant/record.json","html":"https://wellknown.network/agents/workbuddy-mcp-homeassistant","markdown":"https://wellknown.network/agents/workbuddy-mcp-homeassistant/record.md","api":"https://wellknown.network/api/v1/agents/workbuddy-mcp-homeassistant","status":"https://wellknown.network/api/v1/agents/workbuddy-mcp-homeassistant/status","claim":"https://wellknown.network/agents/workbuddy-mcp-homeassistant/claim","claimApi":"https://wellknown.network/api/v1/claims","claimDescriptor":"https://wellknown.network/agents/workbuddy-mcp-homeassistant/claim.json","badge":"https://wellknown.network/agents/workbuddy-mcp-homeassistant/badge.svg","openapi":"https://wellknown.network/openapi.json","history":"https://wellknown.network/api/v1/agents/workbuddy-mcp-homeassistant/history","tools":"https://wellknown.network/api/v1/agents/workbuddy-mcp-homeassistant/tools"},"ard":{"identifier":"urn:air::server:workbuddy-mcp-homeassistant","type":"application/mcp-server-card+json"},"kind":"mcp_server","declared":{"name":"workbuddy-mcp-homeassistant","summary":"WorkBuddy Connector MCP server for Home Assistant (stdio, auth_mode: token)","description":"# Home Assistant Connector（WorkBuddy）\n\n为腾讯 WorkBuddy 生态开发的 Home Assistant 连接器：MCP stdio + 用户自填 Token 模式\n（规范 06 / 06D 附录C），让 AI 通过自然语言查看和控制家中设备。\n\n## 目录结构\n\n```\nhome-assistant/\n├── connector-meta.json   # 连接器元信息（type: mcp, auth_mode: token, minWorkbuddyVersion: 4.23.0）\n├── mcp.json              # MCP Server 连接配置（stdio，凭证经 env 注入）\n├── token-schema.json     # 用户自填 Token 表单（HA_URL + HA_TOKEN）\n├── ha_mcp_server/        # MCP Server（Python，官方 mcp SDK FastMCP）\n│   ├── __init__.py\n│   ├── __main__.py       # python -m ha_mcp_server 入口\n│   └── server.py         # 4 个 tool：list_states / get_state / call_service / list_services\n├── skills/\n│   └── SKILL.md          # Skill 文件（按 05 规范，教 AI 如何使用工具）\n├── icon.svg              # 连接器图标\n└── README.md\n```\n\n依赖仅 `mcp`（v1，FastMCP）+ `httpx`（Python ≥ 3.10）。\n\n## 工具一览\n\n| Tool | 用途 |\n|---|---|\n| `list_states(entity_id_prefix?)` | 列出实体状态（entity_id/state/friendly_name），可按前缀过滤 |\n| `get_state(entity_id)` | 单个实体详情（含 attributes） |\n| `call_service(domain, service, entity_id, data?)` | 调用 HA 服务控制设备 |\n| `list_services(domain?)` | 查询可用服务（call_service 的参数字典） |\n\nHA REST API 端点：`GET /api/states`、`GET /api/states/{entity_id}`、\n`POST /api/services/{domain}/{service}`、`GET /api/services`；\n认证头 `Authorization: Bearer ${HA_TOKEN}`，httpx 超时 10s。\n\n## 本地测试\n\n```bash\ncd <项目目录>/connectors/home-assistant\n\n# 1. 装依赖（本目录 .venv 已装好；也可用任意 Python ≥3.10）\n#    注意钉 mcp<2：官方 SDK 2.x 把 FastMCP 改名为 MCPServer，本代码按 v1 FastMCP 编写\npython3 -m venv .venv\n.venv/bin/pip install -i https://pypi.tuna.tsinghua.edu.cn/simple \"mcp[cli]>=1.2,<2\" httpx\n\n# 2. 导出凭证（HA 界面：左下角用户资料 → 安全 → 长期访问令牌 → 创建令牌）\nexport HA_URL=\"http://127.0.0.1:8123\"\nexport HA_TOKEN=\"eyJhbGciOi...\"\n\n# 3a. 用 MCP Inspector 交互测试\n.venv/bin/mcp dev ha_mcp_server/server.py\n\n# 3b. 或用脚本直连测试（走 MCP stdio 协议调用工具）\n.venv/bin/python tests_smoke.py\n```\n\n## 错误处理约定\n\n- 连接失败 → 提示检查 HA_URL / 网络可达性\n- 401 → 提示令牌无效或已撤销，指引用户重新生成并更新 HA_TOKEN\n- 404 → 提示实体 ID / domain / service 拼写问题\n- 缺环境变量 / 超时 / 非 200 均返回可读中文错误，不会抛栈给 AI\n\n## 正式提交前 TODO\n\n- [ ] **uvx 打包*…","publisher":{"name":"dangsys","url":null},"homepage":null,"repository":null,"version":"1.0.1","license":"MIT","protocols":["mcp"],"tags":["home","assistant","mcp","model-context-protocol","smart","workbuddy"],"pricing":null,"endpoints":[{"url":"pypi:workbuddy-mcp-homeassistant","type":"package_pypi","auth":null,"probeable":false}],"skills":null,"tools":null,"extra":null,"attribution":{"kind":"pypi","name":"pypi","license":"pypi","summary":"pypi","version":"pypi","description":"pypi","publisherName":"pypi"}},"derived":{"capabilities":[{"slug":"infra.devices","name":"Devices & IoT","confidence":1,"provenance":"derived"},{"slug":"security.identity","name":"Identity & Access","confidence":0.825,"provenance":"derived"},{"slug":"productivity.tasks","name":"Tasks & To-do","confidence":0.745,"provenance":"derived"}],"categories":["infra","productivity","security"],"language":"fr"},"observed":{"status":"unknown","statusReason":"Distributed as a package to run locally; no network endpoint to check.","lastOkAt":null,"lastProbedAt":null,"statusComputedAt":null,"reliability30d":null,"latestObservations":[],"tools":null,"package":{"name":"workbuddy-mcp-homeassistant","registry":"pypi","observedAt":"2026-10-23T00:27:15.872Z","publishedAt":"2026-09-08T17:46:10.880807Z","latestVersion":"1.0.1"},"toolSurface":null,"endpointFacts":[]},"verification":{"claimed":false,"claimedAt":null,"proofs":[]},"provenance":{"sources":[{"source":"pypi","key":"workbuddy-mcp-homeassistant","url":"https://pypi.org/project/workbuddy-mcp-homeassistant/","firstSeenAt":"2026-09-10T16:22:28.130Z","fetchedAt":"2026-10-23T00:25:17.553Z","normalizedAt":"2026-10-23T00:25:17.553Z"}]},"firstSeenAt":"2026-09-10T16:22:28.130Z","updatedAt":"2026-10-23T00:27:15.872Z"}