Skip to content

Commit eba6eb5

Browse files
TMHSDigitalTMHSDigital
committed
feat: expand roadmap to 12 versions with 52 tools, add release hygiene to CLAUDE.md
Made-with: Cursor
1 parent ab6f509 commit eba6eb5

3 files changed

Lines changed: 303 additions & 42 deletions

File tree

‎CLAUDE.md‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -124,6 +124,32 @@ npm install -g @tmhs/homelab-mcp
124124
- Skills use kebab-case directory names with YAML frontmatter.
125125
- Rules use kebab-case filenames with `description` and `alwaysApply` frontmatter.
126126

127+
## Release Hygiene
128+
129+
When preparing a new release version, ALL of the following files must be updated to reflect the new version number, tool/skill/rule counts, and any new entries:
130+
131+
| File | What to update |
132+
|------|----------------|
133+
| `mcp-server/package.json` | `version` field |
134+
| `mcp-server/src/index.ts` | `version` in McpServer constructor |
135+
| `.cursor-plugin/plugin.json` | `version` field, `description` tool/skill/rule counts |
136+
| `README.md` | Badge versions, stat line counts, tool/skill/rule tables, roadmap table |
137+
| `CLAUDE.md` | `Version` field, skill/rule/tool counts and tables |
138+
| `ROADMAP.md` | Move version from planned to completed, update status |
139+
| `CHANGELOG.md` | Add new version section with all changes |
140+
| `docs/index.html` | Update any version references or counts |
141+
142+
Checklist before tagging a release:
143+
144+
1. All new tools registered in `mcp-server/src/index.ts`
145+
2. All new tools have input validation tests
146+
3. All new skills have SKILL.md with required frontmatter and sections
147+
4. All new rules have .mdc with required frontmatter
148+
5. Structure tests pass (`pytest tests/ -v`)
149+
6. MCP server builds and tests pass (`npm run build && npm test`)
150+
7. Version numbers match across all files listed above
151+
8. CHANGELOG.md entry added for the new version
152+
127153
## Home Lab Context
128154

129155
The target environment is a Raspberry Pi 5 running:

‎README.md‎

Lines changed: 17 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -269,13 +269,23 @@ Any client supporting MCP stdio transport can use the Home Lab MCP server. Point
269269

270270
 
271271

272-
| Version | Theme | MCP Tools | Highlights |
273-
|---|---|---|---|
274-
| **v0.1.0** | Foundation | 15 | 10 skills, 5 rules, 15 MCP tools, SSH connectivity |
275-
| **v0.2.0** | Expanded monitoring | +5 | Log aggregation, alertmanager integration, dashboard provisioning |
276-
| **v0.3.0** | Multi-node | +5 | Ansible inventory sync, multi-Pi orchestration |
277-
| **v0.4.0** | Advanced networking | +5 | Tailscale ACL management, DNS analytics, certificate automation |
278-
| **v1.0.0** | Stable | +0 | Production release (~30 MCP tools) |
272+
| Version | Theme | New Tools | New Skills | New Rules | Cumulative |
273+
|---|---|---|---|---|---|
274+
| **v0.1.0** | Foundation | 15 | 10 | 5 | 15 |
275+
| v0.2.0 | Extended Monitoring | +5 | +2 | -- | 20 |
276+
| v0.3.0 | DNS and Reverse Proxy | +5 | +2 | +1 | 25 |
277+
| v0.4.0 | Backup and Recovery | +4 | +1 | +1 | 29 |
278+
| v0.5.0 | Security Hardening | +4 | +1 | +2 | 33 |
279+
| v0.6.0 | Logs and Notifications | +4 | +2 | -- | 37 |
280+
| v0.7.0 | OS and Package Management | +4 | +2 | +1 | 41 |
281+
| v0.8.0 | SSL/TLS Certificates | +3 | +1 | -- | 44 |
282+
| v0.9.0 | Multi-Node Foundation | +4 | +1 | +1 | 48 |
283+
| v0.10.0 | Testing Infrastructure | +2 | -- | -- | 50 |
284+
| v0.11.0 | Documentation Site | -- | -- | -- | 50 |
285+
| v0.12.0 | Polish and Hardening | +2 | -- | -- | 52 |
286+
| **v1.0.0** | **Stable Release** | -- | -- | -- | **52** |
287+
288+
See [ROADMAP.md](ROADMAP.md) for detailed per-version tool, skill, and rule breakdowns.
279289

280290
</details>
281291

‎ROADMAP.md‎

Lines changed: 260 additions & 35 deletions
Original file line numberDiff line numberDiff line change
@@ -1,48 +1,273 @@
11
# Roadmap
22

3-
## Version History
3+
## Version Summary
44

5-
| Version | Theme | MCP Tools | Status |
6-
|---------|-------|-----------|--------|
7-
| **v0.1.0** | Foundation | 15 | Current |
8-
| v0.2.0 | Extended Monitoring | +5 | Planned |
9-
| v0.3.0 | Multi-Node | +5 | Planned |
10-
| v1.0.0 | Stable | +0 | Planned |
5+
| Version | Theme | New Tools | New Skills | New Rules | Cumulative Tools |
6+
|---------|-------|-----------|------------|-----------|-----------------|
7+
| **v0.1.0** | Foundation | 15 | 10 | 5 | 15 |
8+
| v0.2.0 | Extended Monitoring | +5 | +2 | -- | 20 |
9+
| v0.3.0 | DNS and Reverse Proxy | +5 | +2 | +1 | 25 |
10+
| v0.4.0 | Backup and Recovery | +4 | +1 | +1 | 29 |
11+
| v0.5.0 | Security Hardening | +4 | +1 | +2 | 33 |
12+
| v0.6.0 | Logs and Notifications | +4 | +2 | -- | 37 |
13+
| v0.7.0 | OS and Package Management | +4 | +2 | +1 | 41 |
14+
| v0.8.0 | SSL/TLS Certificates | +3 | +1 | -- | 44 |
15+
| v0.9.0 | Multi-Node Foundation | +4 | +1 | +1 | 48 |
16+
| v0.10.0 | Testing Infrastructure | +2 | -- | -- | 50 |
17+
| v0.11.0 | Documentation Site | -- | -- | -- | 50 |
18+
| v0.12.0 | Polish and Hardening | +2 | -- | -- | 52 |
19+
| **v1.0.0** | **Stable Release** | -- | -- | -- | **52** |
20+
21+
---
1122

1223
## v0.1.0 - Foundation (current)
1324

1425
- [x] 10 skills covering core home lab workflows
1526
- [x] 5 rules for best-practice enforcement
1627
- [x] 15 MCP tools for Pi management via SSH
1728
- [x] Plugin manifest and structure tests
18-
- [x] CI/CD pipelines
19-
20-
## v0.2.0 - Extended Monitoring (planned)
21-
22-
- [ ] `homelab_prometheusQuery` - Run PromQL queries against Prometheus
23-
- [ ] `homelab_grafanaSnapshot` - Export Grafana dashboard snapshots
24-
- [ ] `homelab_uptimeKumaStatus` - Get Uptime Kuma monitor statuses
25-
- [ ] `homelab_alertList` - List active Alertmanager alerts
26-
- [ ] `homelab_speedtestResults` - Get recent speedtest results
27-
- [ ] New skill: grafana-dashboards (creating and managing dashboards)
28-
- [ ] New skill: alerting-rules (writing Prometheus alert rules)
29-
30-
## v0.3.0 - Multi-Node (planned)
31-
32-
- [ ] Support for multiple SSH targets (not just one Pi)
33-
- [ ] `homelab_nodeList` - List all managed nodes and their status
34-
- [ ] `homelab_nodeExec` - Execute a command on a specific node
35-
- [ ] `homelab_inventorySync` - Sync Ansible inventory with discovered nodes
36-
- [ ] `homelab_tailscaleNodes` - List Tailscale network nodes
37-
- [ ] New skill: multi-node-management
38-
- [ ] New rule: inventory-consistency
39-
40-
## v1.0.0 - Stable (planned)
41-
42-
- [ ] All tools tested against live Pi environments
43-
- [ ] npm package published (@tmhs/homelab-mcp)
44-
- [ ] Comprehensive documentation and examples
45-
- [ ] GitHub Pages site with full tool reference
29+
- [x] CI/CD pipelines (validate, typecheck, CodeQL, release drafter, npm publish)
30+
- [x] npm package published (`@tmhs/homelab-mcp`)
31+
32+
---
33+
34+
## v0.2.0 - Extended Monitoring
35+
36+
Deep integration with the monitoring stack already running on the Pi.
37+
38+
**MCP tools (+5):**
39+
40+
- [ ] `homelab_prometheusQuery` -- run PromQL queries against Prometheus
41+
- [ ] `homelab_grafanaSnapshot` -- export Grafana dashboard snapshots
42+
- [ ] `homelab_uptimeKumaStatus` -- get Uptime Kuma monitor statuses
43+
- [ ] `homelab_alertList` -- list active Alertmanager alerts
44+
- [ ] `homelab_speedtestResults` -- get recent Speedtest Tracker results
45+
46+
**Skills (+2):**
47+
48+
- [ ] `grafana-dashboards` -- creating and managing dashboards
49+
- [ ] `alerting-rules` -- writing Prometheus alert rules
50+
51+
---
52+
53+
## v0.3.0 - DNS and Reverse Proxy
54+
55+
Manage the network gateway layer -- AdGuard Home and Nginx Proxy Manager.
56+
57+
**MCP tools (+5):**
58+
59+
- [ ] `homelab_adguardStats` -- query/filter stats, top blocked domains
60+
- [ ] `homelab_adguardFilters` -- list/toggle filter lists
61+
- [ ] `homelab_adguardQueryLog` -- search DNS query log
62+
- [ ] `homelab_npmProxyHosts` -- list proxy host configs from NPM
63+
- [ ] `homelab_npmCerts` -- list SSL certificates and expiry dates
64+
65+
**Skills (+2):**
66+
67+
- [ ] `dns-management` -- AdGuard filters, local DNS records, blocklists
68+
- [ ] `reverse-proxy-management` -- NPM routing, SSL config, access lists
69+
70+
**Rules (+1):**
71+
72+
- [ ] `exposed-ports` -- flag services bound to 0.0.0.0 or missing proxy config
73+
74+
---
75+
76+
## v0.4.0 - Backup and Recovery
77+
78+
Go beyond "check status / trigger backup" to full disaster recovery workflows.
79+
80+
**MCP tools (+4):**
81+
82+
- [ ] `homelab_backupList` -- list all restic snapshots with filtering
83+
- [ ] `homelab_backupRestore` -- restore files from a snapshot (requires confirm=true)
84+
- [ ] `homelab_backupDiff` -- diff two snapshots
85+
- [ ] `homelab_volumeBackup` -- backup a specific Docker volume
86+
87+
**Skills (+1):**
88+
89+
- [ ] `disaster-recovery` -- full Pi restore workflow, SD card imaging, migration checklist
90+
91+
**Rules (+1):**
92+
93+
- [ ] `backup-coverage` -- flag Docker volumes not covered by any backup job
94+
95+
---
96+
97+
## v0.5.0 - Security Hardening
98+
99+
Deeper security tooling and automated auditing.
100+
101+
**MCP tools (+4):**
102+
103+
- [ ] `homelab_ufwStatus` -- list UFW rules and status
104+
- [ ] `homelab_fail2banStatus` -- list jails, banned IPs, recent bans
105+
- [ ] `homelab_openPorts` -- scan for listening ports and map to services
106+
- [ ] `homelab_containerScan` -- check running containers for known vulnerabilities (via Trivy or similar)
107+
108+
**Skills (+1):**
109+
110+
- [ ] `secrets-management` -- managing credentials with Vaultwarden, env vars, Docker secrets
111+
112+
**Rules (+2):**
113+
114+
- [ ] `privileged-containers` -- flag containers running as root or with privileged mode
115+
- [ ] `weak-credentials` -- flag default/weak passwords in compose env vars
116+
117+
---
118+
119+
## v0.6.0 - Logs and Notifications
120+
121+
Centralized log access and alerting pipelines.
122+
123+
**MCP tools (+4):**
124+
125+
- [ ] `homelab_journalLogs` -- query systemd journal with filters (unit, priority, time range)
126+
- [ ] `homelab_logSearch` -- search across container logs with grep patterns
127+
- [ ] `homelab_ntfySend` -- send a notification via Ntfy
128+
- [ ] `homelab_ntfyTopics` -- list Ntfy topics and recent messages
129+
130+
**Skills (+2):**
131+
132+
- [ ] `log-analysis` -- structured log querying, Loki integration, journald workflows
133+
- [ ] `notification-workflows` -- Ntfy setup, alert routing, webhook pipelines
134+
135+
---
136+
137+
## v0.7.0 - OS and Package Management
138+
139+
System-level maintenance beyond apt update.
140+
141+
**MCP tools (+4):**
142+
143+
- [ ] `homelab_aptUpgradable` -- list upgradable packages with version details
144+
- [ ] `homelab_aptHistory` -- show recent apt install/upgrade history
145+
- [ ] `homelab_kernelInfo` -- kernel version, loaded modules, boot params
146+
- [ ] `homelab_systemdServices` -- list systemd units, enable/disable/status
147+
148+
**Skills (+2):**
149+
150+
- [ ] `os-update-management` -- unattended-upgrades config, kernel updates, reboot scheduling
151+
- [ ] `performance-tuning` -- kernel params, swap config, I/O scheduler, GPU memory split
152+
153+
**Rules (+1):**
154+
155+
- [ ] `resource-limits` -- flag containers without memory/CPU limits set
156+
157+
---
158+
159+
## v0.8.0 - SSL/TLS Certificates
160+
161+
Certificate lifecycle management.
162+
163+
**MCP tools (+3):**
164+
165+
- [ ] `homelab_certCheck` -- check SSL cert expiry for a domain/host
166+
- [ ] `homelab_certRenew` -- trigger Let's Encrypt renewal (requires confirm=true)
167+
- [ ] `homelab_certList` -- list all managed certificates and their status
168+
169+
**Skills (+1):**
170+
171+
- [ ] `certificate-management` -- Let's Encrypt, self-signed certs, renewal automation, NPM cert integration
172+
173+
---
174+
175+
## v0.9.0 - Multi-Node Foundation
176+
177+
Support managing multiple SSH targets. Core infrastructure change.
178+
179+
**MCP tools (+4):**
180+
181+
- [ ] `homelab_nodeList` -- list all managed nodes and their connection status
182+
- [ ] `homelab_nodeExec` -- execute a command on a specific node by name
183+
- [ ] `homelab_nodeStatus` -- get system status for a specific node (like piStatus but for any node)
184+
- [ ] `homelab_inventorySync` -- sync/discover nodes from Ansible inventory or Tailscale
185+
186+
**Infrastructure changes:**
187+
188+
- [ ] `ssh-api.ts` refactored to support a node registry (env var or config file for multiple hosts)
189+
- [ ] All existing tools gain optional `node` parameter (defaults to primary Pi)
190+
191+
**Skills (+1):**
192+
193+
- [ ] `multi-node-management` -- managing fleets, inventory, parallel operations
194+
195+
**Rules (+1):**
196+
197+
- [ ] `inventory-consistency` -- flag nodes in inventory but unreachable, or missing from inventory
198+
199+
---
200+
201+
## v0.10.0 - Testing Infrastructure
202+
203+
Real test coverage before v1.0.
204+
205+
**MCP tools (+2):**
206+
207+
- [ ] `homelab_healthCheck` -- comprehensive self-test (SSH connectivity, Docker availability, required tools present)
208+
- [ ] `homelab_diagnostics` -- collect debug info bundle (versions, connectivity, config)
209+
210+
**Testing layers:**
211+
212+
- [ ] Integration tests with mocked SSH (ssh2-mock or similar)
213+
- [ ] E2E test suite that runs against a real Pi (gated behind `HOMELAB_TEST_PI=true` env var)
214+
- [ ] CI workflow that connects to a Pi via Tailscale for e2e (self-hosted runner or SSH tunnel)
215+
216+
---
217+
218+
## v0.11.0 - Documentation Site
219+
220+
Upgrade GitHub Pages from placeholder to full tool reference.
221+
222+
**Site features:**
223+
224+
- [ ] Interactive tool reference with parameters, examples, and output samples
225+
- [ ] Skill catalog with trigger conditions and example prompts
226+
- [ ] Rule catalog with scope and example violations
227+
- [ ] Search functionality
228+
- [ ] Dark/light mode
229+
230+
**Docs automation:**
231+
232+
- [ ] Rule or CLAUDE.md section ensuring all release-related info (version numbers, tool counts, changelogs) is updated across README, CLAUDE.md, ROADMAP.md, plugin.json, package.json, and the docs site on every release
233+
234+
---
235+
236+
## v0.12.0 - Polish and Hardening
237+
238+
Final quality pass before stable.
239+
240+
**MCP tools (+2):**
241+
242+
- [ ] `homelab_configExport` -- export current MCP server config (sanitized, no secrets)
243+
- [ ] `homelab_configValidate` -- validate environment setup and required Pi-side dependencies
244+
245+
**Quality pass:**
246+
247+
- [ ] All tools reviewed for error handling, timeout tuning, and output formatting
248+
- [ ] All skills reviewed for accuracy, completeness, and cross-linking
249+
- [ ] All rules reviewed for false positive rates
250+
- [ ] README, CLAUDE.md, ROADMAP.md, plugin.json, package.json fully in sync
251+
- [ ] CHANGELOG complete for all versions
252+
253+
---
254+
255+
## v1.0.0 - Stable Release
256+
257+
Production-ready, fully tested, fully documented.
258+
259+
**Release criteria:**
260+
261+
- [ ] All tools tested against live Pi environments (e2e CI green)
262+
- [ ] npm package published with provenance (`@tmhs/homelab-mcp`)
263+
- [ ] GitHub Pages site live with full tool/skill/rule reference
264+
- [ ] Multi-node support functional
265+
- [ ] No known bugs in issue tracker
266+
- [ ] CHANGELOG, README, CLAUDE.md, ROADMAP.md, plugin.json all version-synced
267+
268+
**Final counts: ~52 MCP tools, ~22 skills, ~11 rules**
269+
270+
---
46271

47272
## Completed
48273

0 commit comments

Comments
 (0)