10 files

sessions/ha-direct-tools.md

@@ -0,0 +1,72 @@
+# ha-direct MCP Tools Reference
+
+Use these tools only when ha-direct specific features are needed (BPS, backup, python_transform).
+
+## Automations
+| Tool | Purpose |
+|------|---------|
+| `ha_config_get_automation` | Read automation config |
+| `ha_config_set_automation` | Create/update automation |
+| `ha_config_remove_automation` | Delete automation |
+| `ha_get_automation_traces` | Debug automation execution |
+
+## Scripts
+| Tool | Purpose |
+|------|---------|
+| `ha_config_set_script` | Create/update script |
+
+## Scenes
+| Tool | Purpose |
+|------|---------|
+| `ha_config_get_scene` | Read scene config |
+| `ha_config_set_scene` | Create/update scene |
+| `ha_config_remove_scene` | Delete scene |
+
+## Dashboards
+| Tool | Purpose |
+|------|---------|
+| `ha_config_get_dashboard` | List/get/search dashboards |
+| `ha_config_set_dashboard` | Create/update dashboard |
+| `ha_config_delete_dashboard` | Delete dashboard |
+
+## Entities
+| Tool | Purpose |
+|------|---------|
+| `ha_get_entity` | Get entity registry info |
+| `ha_set_entity` | Update entity properties |
+| `ha_remove_entity` | Remove entity |
+
+## Labels/Categories
+| Tool | Purpose |
+|------|---------|
+| `ha_config_get_label` | List/get labels |
+| `ha_config_set_label` | Create/update label |
+| `ha_config_remove_label` | Delete label |
+| `ha_config_get_category` | List/get categories |
+| `ha_config_set_category` | Create/update category |
+| `ha_config_remove_category` | Delete category |
+
+## System
+| Tool | Purpose |
+|------|---------|
+| `ha_reload_core` | Reload config without restart |
+| `ha_manage_updates` | Manage system updates |
+| `ha_get_overview` | System overview |
+| `ha_get_skill_guide` | Best practices |
+| `ha_report_issue` | File bug reports |
+
+## Control
+| Tool | Purpose |
+|------|---------|
+| `ha_call_service` | Call any HA service |
+| `ha_call_event` | Fire custom event |
+
+## Search
+| Tool | Purpose |
+|------|---------|
+| `ha_search` | Search entities/configs |
+
+## Notes
+- Write tools require `BestPracticeKey` (read from `SKILL.md` first)
+- Key rotates hourly, re-read for fresh key
+- `python_transform` requires `config_hash` from GET call

sessions/mcp_backup_test_session.md

@@ -0,0 +1,61 @@
+# MCP Backup Test Session - 2026-07-24
+
+## Goal
+Test ha-direct MCP's auto-backup feature by creating, saving, and modifying an automation.
+
+## Status
+- Automation WAS created successfully (despite error message)
+- User deleted it manually
+- Session interrupted for full restart
+
+## Key Findings
+1. **ha-direct has an asyncio bug**: `ha_config_set_automation` throws `INTERNAL_ERROR: Task got Future attached to a different loop` but the automation still gets created
+2. **Two MCP servers are connected**:
+   - `homeassistant` - Direct HA integration (prefix: `homeassistant_*`)
+   - `ha-direct` - Best practices skill + automation CRUD (prefix: `ha-direct_ha_*`)
+3. **BestPracticeKey**: Required for write tools when strict mode is ON. Key rotates hourly, read from SKILL.md
+
+## Test Automation Created
+```yaml
+alias: "MCP Backup Test"
+description: "Test automation to verify ha-direct backup functionality"
+triggers:
+  - trigger: state
+    entity_id: sun.sun
+    to: above_horizon
+actions:
+  - action: notify.notify
+    data:
+      title: "MCP Test"
+      message: "Automation created via ha-direct!"
+```
+
+## Next Steps After Restart
+1. Recreate the test automation using `ha_config_set_automation`
+2. Verify backup was created using `ha_manage_backup(scope="edits", action="list")`
+3. Modify the automation
+4. Verify new backup was created
+5. Test restore from backup
+
+## Command Sequence
+```
+# 1. Get BestPracticeKey (read SKILL.md)
+ha-direct_ha_get_skill_guide(skill='home-assistant-best-practices', file='SKILL.md')
+
+# 2. Create automation (include BestPracticeKey)
+ha-direct_ha_config_set_automation(config={...}, BestPracticeKey="I-HAVE-READ-THE-BEST-PRACTICES-GUIDE-bd08e62b")
+
+# 3. List backups to verify
+ha-direct_ha_manage_backup(scope="edits", action="list")
+
+# 4. Modify automation (get identifier from step 2)
+ha-direct_ha_config_set_automation(identifier="automation.entity_id", config={...}, BestPracticeKey="...")
+
+# 5. Verify new backup
+ha-direct_ha_manage_backup(scope="edits", action="list")
+```
+
+## Bug Report Filed
+- Error: INTERNAL_ERROR on ha_config_set_automation
+- Details: asyncio event loop mismatch
+- Report saved: /data/.local/share/opencode/tool-output/tool_f95b39529001j266BHbdc6n5ve