Skip to content

Commit 0e9115d

Browse files
julienldclaude
andauthored
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

Lines changed: 104 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,104 @@
1+
name: Test Installer Scripts
2+
3+
on:
4+
push:
5+
paths:
6+
- 'scripts/install-macos.sh'
7+
- 'scripts/install-windows.ps1'
8+
- '.github/workflows/test-installer-scripts.yml'
9+
pull_request:
10+
paths:
11+
- 'scripts/install-macos.sh'
12+
- 'scripts/install-windows.ps1'
13+
- '.github/workflows/test-installer-scripts.yml'
14+
schedule:
15+
- cron: '0 21 * * *' # Daily at 4pm Eastern
16+
workflow_dispatch:
17+
18+
jobs:
19+
test-macos:
20+
runs-on: macos-latest
21+
steps:
22+
- uses: actions/checkout@v4
23+
24+
- name: Run macOS installer script (first run)
25+
run: sh scripts/install-macos.sh
26+
27+
- name: Run macOS installer script (second run - idempotency test)
28+
run: |
29+
# Should skip uv install and show "uv is already installed"
30+
sh scripts/install-macos.sh
31+
32+
- name: Verify uv is installed
33+
run: |
34+
command -v uvx || (echo "uvx not found" && exit 1)
35+
uvx --version
36+
37+
- name: Verify Claude Desktop config was created
38+
run: |
39+
CONFIG_FILE="$HOME/Library/Application Support/Claude/claude_desktop_config.json"
40+
if [ ! -f "$CONFIG_FILE" ]; then
41+
echo "Config file not created"
42+
exit 1
43+
fi
44+
cat "$CONFIG_FILE"
45+
# Verify it contains Home Assistant config
46+
grep -q '"Home Assistant"' "$CONFIG_FILE" || (echo "Home Assistant config not found" && exit 1)
47+
grep -q 'ha-mcp@latest' "$CONFIG_FILE" || (echo "ha-mcp not configured" && exit 1)
48+
49+
test-windows:
50+
runs-on: windows-latest
51+
steps:
52+
- uses: actions/checkout@v4
53+
54+
- name: Run Windows installer script (first run)
55+
shell: pwsh
56+
run: |
57+
& ./scripts/install-windows.ps1
58+
59+
- name: Run Windows installer script (second run - idempotency test)
60+
shell: pwsh
61+
run: |
62+
# Should skip uv install and show "uv is already installed"
63+
& ./scripts/install-windows.ps1
64+
65+
- name: Verify uv is installed
66+
shell: pwsh
67+
run: |
68+
# Refresh PATH (winget installs to user PATH which doesn't persist between steps)
69+
$env:Path = [System.Environment]::GetEnvironmentVariable("Path","Machine") + ";" + [System.Environment]::GetEnvironmentVariable("Path","User")
70+
$uvx = Get-Command uvx -ErrorAction SilentlyContinue
71+
if (-not $uvx) {
72+
Write-Error "uvx not found"
73+
exit 1
74+
}
75+
uvx --version
76+
77+
- name: Verify Claude Desktop config was created
78+
shell: pwsh
79+
run: |
80+
$ConfigFile = "$env:APPDATA\Claude\claude_desktop_config.json"
81+
if (-not (Test-Path $ConfigFile)) {
82+
Write-Error "Config file not created"
83+
exit 1
84+
}
85+
Get-Content $ConfigFile
86+
# Verify it contains Home Assistant config
87+
$content = Get-Content $ConfigFile -Raw
88+
if ($content -notmatch '"Home Assistant"') {
89+
Write-Error "Home Assistant config not found"
90+
exit 1
91+
}
92+
if ($content -notmatch 'ha-mcp@latest') {
93+
Write-Error "ha-mcp not configured"
94+
exit 1
95+
}
96+
97+
check-demo-env:
98+
runs-on: ubuntu-latest
99+
steps:
100+
- name: Check demo environment is up
101+
run: |
102+
# Verify the demo Home Assistant server is responding
103+
curl -sf "https://ha-mcp-demo-server.qc-h.net/" -o /dev/null
104+
echo "Demo server is up and responding"

0 commit comments

Comments
 (0)