Commit 0e9115d
docs: improve onboarding UX with demo environment (#265)
* docs: improve onboarding UX with demo environment and clearer guides
- Add public demo environment (ha-mcp-demo-server.qc-h.net)
- Credentials: mcp/mcp
- Token in tests/test_constants.py
- Resets weekly
- Restructure README:
- Quick Start section for Claude Desktop (most common path)
- Other Clients section with collapsed details
- Add 80+ tools badge
- Clarify HA add-on is optional, not required
- Simplify platform guides:
- macOS guide: shorter, includes demo config
- Windows guide: shorter, includes demo config
- Common troubleshooting moved to FAQ.md
- Add FAQ page:
- Common questions (add-on not required, free tier, etc.)
- Demo environment info
- Troubleshooting section
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
* feat: add "demo" token shortcut for easy onboarding
- HOMEASSISTANT_TOKEN="demo" now auto-replaces with actual demo token
- Centralized demo token in config.py
- Updated all docs to use simple "demo" instead of long JWT
- Much cleaner copy-paste experience for new users
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
* feat: add one-liner installer scripts for macOS and Windows
- Add scripts/install-macos.sh: installs uv, configures Claude Desktop
- Add scripts/install-windows.ps1: same for Windows with winget
- Both scripts auto-configure demo environment for immediate testing
- Rewrite macOS/Windows guides with streamlined 5-step flow
- Manual installation moved to collapsed <details> section
- Update README Quick Start with one-liner commands
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
* docs: streamline README and add feedback step to guides
- Condense Features section to compact table format
- Move tool list into collapsible section under Features
- Remove redundant Available Tools section (now in Features)
- Move Configuration Options to FAQ
- Remove Development Roadmap section
- Remove YouTube link
- Update examples to focus on automation management
- Add Step 6 (feedback) to macOS and Windows guides
- Add GitHub Discussions link for community sharing
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
* docs: remove (Optional) from add-on section title
* docs: clarify tagline with entity ID example
* docs: improve tagline and fix Features table headers
* docs: redesign Get Started section with OS badges and quick install
- Rename "Quick Start" to "Get Started" (call to action)
- Add side-by-side macOS/Windows badges linking to full guides
- Add collapsible quick install sections for each OS
- Clear steps: Claude account → install app → run script → restart → test
- Link to Step 5 for connecting own Home Assistant
- Move FAQ link to bottom of section
* feat: run installer before Claude Desktop install (no restart needed)
- Update install scripts to create config even if Claude Desktop not installed
- Scripts now show appropriate next steps based on installation state
- Reorder guide steps: account → run script → install Claude Desktop → test
- Eliminates the restart step for new users
- Renumber all guide steps accordingly (now 7 steps total)
- Update README links to point to correct step anchors
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
* docs: add restart instructions for existing Claude Desktop users
- Scripts now show note about restarting if Claude was already running
- Update menu paths: "Claude menu > Quit Claude" (macOS), "File > Exit" (Windows)
- Guide Step 3 now titled "Install or Restart Claude Desktop"
- README quick install mentions restart option with keyboard shortcuts
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
* fix: remove Alt+F4 from Windows instructions (doesn't quit app)
* fix: remove Cmd+Q from macOS instructions, use menu only
* docs: enlarge OS badges with call-to-action subtitles
* docs: make OS badges bigger (height=80), remove table borders
* docs: bigger badges (120px) with integrated CTA text
* docs: fix badge spacing, align left, update section titles
* docs: update Get Started section and reorganize
- Add "(~10 min)" to full guide title
- Add "Click on your operating system:" instruction
- Change quick install from 2 min to 5 min
- Move Demo Environment to FAQ (already existed there)
- Rename "Other Clients" to "Other Installation Methods"
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
* docs: fix times, add demo caption, improve examples
- Update guides to say "~10 minutes" (was "2 minutes")
- Rename guides from "Quick Start" to "Setup Guide"
- Add "Demo with Claude Desktop" caption to demo image
- Add context to FAQ link: "Having issues? Check the..."
- Replace search example with dashboard example for variety
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
* docs: improve guides UX and consistency
- Remove --- separators between steps for cleaner look
- Fix restart instructions to use menu (not keyboard shortcuts)
- Change "installs uv" to "installs required tools" (clearer)
- Add clarity to Step 4: "list of entities (lights, sensors, switches, etc.)"
- Use table format for demo environment info in Step 5
- Move FAQ link to bottom with context: "Having issues? See the..."
- Remove redundant "Problems?" section
- Consistent restart instructions throughout
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
* feat: improve installer scripts with sh compatibility and CI testing
- Convert macOS script to POSIX sh (printf instead of echo -e)
- Add dependency pre-warm step to both scripts (Step 3)
- Add explicit exit 0 to Windows script
- Fix table formatting in setup guides (use bullet lists)
- Update docs to reference sh instead of bash
- Add CI workflow to test scripts on macOS and Windows
- Daily scheduled run at 4pm Eastern with demo env health check
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
---------
Co-authored-by: Claude <noreply@anthropic.com>1 parent 1562ed9 commit 0e9115d
8 files changed
Lines changed: 899 additions & 550 deletions
File tree
- .github/workflows
- docs
- scripts
- src/ha_mcp
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
| 1 | + | |
| 2 | + | |
| 3 | + | |
| 4 | + | |
| 5 | + | |
| 6 | + | |
| 7 | + | |
| 8 | + | |
| 9 | + | |
| 10 | + | |
| 11 | + | |
| 12 | + | |
| 13 | + | |
| 14 | + | |
| 15 | + | |
| 16 | + | |
| 17 | + | |
| 18 | + | |
| 19 | + | |
| 20 | + | |
| 21 | + | |
| 22 | + | |
| 23 | + | |
| 24 | + | |
| 25 | + | |
| 26 | + | |
| 27 | + | |
| 28 | + | |
| 29 | + | |
| 30 | + | |
| 31 | + | |
| 32 | + | |
| 33 | + | |
| 34 | + | |
| 35 | + | |
| 36 | + | |
| 37 | + | |
| 38 | + | |
| 39 | + | |
| 40 | + | |
| 41 | + | |
| 42 | + | |
| 43 | + | |
| 44 | + | |
| 45 | + | |
| 46 | + | |
| 47 | + | |
| 48 | + | |
| 49 | + | |
| 50 | + | |
| 51 | + | |
| 52 | + | |
| 53 | + | |
| 54 | + | |
| 55 | + | |
| 56 | + | |
| 57 | + | |
| 58 | + | |
| 59 | + | |
| 60 | + | |
| 61 | + | |
| 62 | + | |
| 63 | + | |
| 64 | + | |
| 65 | + | |
| 66 | + | |
| 67 | + | |
| 68 | + | |
| 69 | + | |
| 70 | + | |
| 71 | + | |
| 72 | + | |
| 73 | + | |
| 74 | + | |
| 75 | + | |
| 76 | + | |
| 77 | + | |
| 78 | + | |
| 79 | + | |
| 80 | + | |
| 81 | + | |
| 82 | + | |
| 83 | + | |
| 84 | + | |
| 85 | + | |
| 86 | + | |
| 87 | + | |
| 88 | + | |
| 89 | + | |
| 90 | + | |
| 91 | + | |
| 92 | + | |
| 93 | + | |
| 94 | + | |
| 95 | + | |
| 96 | + | |
| 97 | + | |
| 98 | + | |
| 99 | + | |
| 100 | + | |
| 101 | + | |
| 102 | + | |
| 103 | + | |
| 104 | + | |
0 commit comments