Skip to content

Commit 7494b4e

Browse files
TMHSDigitalTMHSDigital
committed
Enhance README.md with improved formatting, added badges, and a new logo. Update skill and rule sections for clarity and consistency.
1 parent 1fe15ad commit 7494b4e

2 files changed

Lines changed: 176 additions & 66 deletions

File tree

‎README.md‎

Lines changed: 176 additions & 66 deletions
Original file line numberDiff line numberDiff line change
@@ -1,27 +1,57 @@
1-
# Home Lab Developer Tools
2-
3-
**Home lab and Raspberry Pi workflows for Cursor, Claude Code, and any MCP-compatible editor.**
4-
5-
Version 0.1.0 | CC-BY-NC-ND-4.0 License | npm: @tmhs/homelab-mcp
6-
7-
**10 skills** -- **5 rules** -- **15 MCP tools**
1+
<p align="center">
2+
<img src="assets/logo.png" alt="Home Lab Developer Tools" width="120">
3+
</p>
4+
5+
<h1 align="center">Home Lab Developer Tools</h1>
6+
7+
<p align="center">
8+
Home lab and Raspberry Pi workflows for Cursor, Claude Code, and any MCP-compatible editor.
9+
</p>
10+
11+
<p align="center">
12+
<a href="https://github.com/TMHSDigital/Home-Lab-Developer-Tools/releases"><img src="https://img.shields.io/github/v/release/TMHSDigital/Home-Lab-Developer-Tools?label=version" alt="version"></a>
13+
<a href="https://github.com/TMHSDigital/Home-Lab-Developer-Tools/releases"><img src="https://img.shields.io/github/v/release/TMHSDigital/Home-Lab-Developer-Tools?label=release&color=blue" alt="release"></a>
14+
<a href="https://www.npmjs.com/package/@tmhs/homelab-mcp"><img src="https://img.shields.io/npm/v/@tmhs/homelab-mcp" alt="npm"></a>
15+
<a href="LICENSE"><img src="https://img.shields.io/badge/license-CC--BY--NC--ND--4.0-green" alt="license"></a>
16+
<a href="https://tmhsdigital.github.io/Home-Lab-Developer-Tools/"><img src="https://img.shields.io/badge/docs-website-blue" alt="docs"></a>
17+
</p>
18+
19+
<p align="center">
20+
<a href="https://github.com/TMHSDigital/Home-Lab-Developer-Tools/actions"><img src="https://img.shields.io/github/actions/workflow/status/TMHSDigital/Home-Lab-Developer-Tools/validate.yml?label=validate" alt="validate"></a>
21+
<a href="https://github.com/TMHSDigital/Home-Lab-Developer-Tools/actions"><img src="https://img.shields.io/github/actions/workflow/status/TMHSDigital/Home-Lab-Developer-Tools/codeql.yml?label=CodeQL" alt="CodeQL"></a>
22+
</p>
23+
24+
<p align="center">
25+
<img src="https://img.shields.io/github/stars/TMHSDigital/Home-Lab-Developer-Tools?style=flat" alt="stars">
26+
<img src="https://img.shields.io/github/issues/TMHSDigital/Home-Lab-Developer-Tools" alt="issues">
27+
<img src="https://img.shields.io/github/issues-pr/TMHSDigital/Home-Lab-Developer-Tools" alt="PRs">
28+
<img src="https://img.shields.io/npm/dm/@tmhs/homelab-mcp" alt="downloads">
29+
</p>
30+
31+
<p align="center">
32+
<strong>10 skills &nbsp;&bull;&nbsp; 5 rules &nbsp;&bull;&nbsp; 15 MCP tools</strong>
33+
</p>
834

935
---
1036

1137
## Compatibility
1238

39+
This project works with any AI coding tool that supports skills, rules, or MCP:
40+
1341
| Component | Cursor | Claude Code (terminal) | Claude Code in Cursor | Other MCP clients |
14-
|-----------|--------|------------------------|-----------------------|-------------------|
42+
|---|:---:|:---:|:---:|:---:|
1543
| **CLAUDE.md** context | Yes | Yes | Yes | - |
1644
| **10 Skills** (SKILL.md) | Yes | Yes | Yes | - |
1745
| **5 Rules** (.mdc) | Yes | Via CLAUDE.md | Yes | - |
1846
| **15 MCP tools** | Yes | Yes | Yes | Yes |
1947

48+
> **Claude Code** reads `CLAUDE.md` automatically and can reference skills. The MCP server works with any client that supports the MCP stdio transport.
49+
2050
## Quick Start
2151

2252
Install the plugin, then ask anything about your home lab:
2353

24-
```
54+
```text
2555
"What's the CPU temperature on my Pi?"
2656
"Restart the Grafana container"
2757
"Show me which services are unhealthy"
@@ -30,41 +60,64 @@ Install the plugin, then ask anything about your home lab:
3060

3161
## How It Works
3262

33-
The MCP server connects to your Raspberry Pi via SSH. Skills teach AI assistants how to manage home lab infrastructure. Rules enforce best practices automatically.
63+
```mermaid
64+
flowchart LR
65+
A[User asks home lab question] --> B[AI loads a Skill]
66+
B --> C[Skill guides the response]
67+
C --> D[MCP tools run commands via SSH]
68+
D --> E[User gets expert help]
69+
```
3470

3571
---
3672

37-
**10 Skills** - on-demand home lab expertise
73+
<details>
74+
<summary><strong>10 Skills</strong> - on-demand home lab expertise</summary>
75+
76+
&nbsp;
3877

3978
| Category | Skill | Description |
40-
|----------|-------|-------------|
41-
| **System** | pi-system-management | Monitor Pi hardware -- temp, throttling, memory, reboots |
42-
| **Containers** | docker-compose-stacks | Manage multi-file Docker Compose deployments |
43-
| **Monitoring** | service-monitoring | Prometheus, Grafana, Uptime Kuma, alert rules |
44-
| **Network** | network-configuration | AdGuard DNS, NPM reverse proxy, Tailscale VPN |
45-
| **Backup** | backup-recovery | Restic backup config, scheduling, and restore |
46-
| **SSH** | ssh-management | SSH keys, hardening, tunnels, troubleshooting |
47-
| **Automation** | ansible-workflows | Ansible playbooks for multi-node management |
48-
| **Security** | security-hardening | UFW, fail2ban, SSH lockdown, container security |
49-
| **Storage** | storage-management | Samba, Syncthing, volumes, disk monitoring |
50-
| **Debug** | troubleshooting | Debug crashes, network issues, hardware problems |
51-
52-
**5 Rules** - automatic best-practice enforcement
79+
|---|---|---|
80+
| **System** | `pi-system-management` | Monitor Pi hardware -- temp, throttling, memory, reboots |
81+
| **Containers** | `docker-compose-stacks` | Manage multi-file Docker Compose deployments |
82+
| **Monitoring** | `service-monitoring` | Prometheus, Grafana, Uptime Kuma, alert rules |
83+
| **Network** | `network-configuration` | AdGuard DNS, NPM reverse proxy, Tailscale VPN |
84+
| **Backup** | `backup-recovery` | Restic backup config, scheduling, and restore |
85+
| **SSH** | `ssh-management` | SSH keys, hardening, tunnels, troubleshooting |
86+
| **Automation** | `ansible-workflows` | Ansible playbooks for multi-node management |
87+
| **Security** | `security-hardening` | UFW, fail2ban, SSH lockdown, container security |
88+
| **Storage** | `storage-management` | Samba, Syncthing, volumes, disk monitoring |
89+
| **Debug** | `troubleshooting` | Debug crashes, network issues, hardware problems |
90+
91+
</details>
92+
93+
<details>
94+
<summary><strong>5 Rules</strong> - automatic best-practice enforcement</summary>
95+
96+
&nbsp;
5397

5498
| Rule | Scope | What It Does |
55-
|------|-------|--------------|
56-
| homelab-secrets | Global (always active) | Flag hardcoded passwords, IPs, and SSH keys |
57-
| compose-arm64 | Compose files | Flag images without arm64 support, missing healthchecks |
58-
| ssh-safety | Global (always active) | Flag dangerous SSH commands (rm -rf, dd, mkfs) |
59-
| yaml-conventions | YAML files | Enforce 2-space indent, document start, explicit booleans |
60-
| ansible-best-practices | Ansible files | Flag non-FQCN modules, missing tags, shell misuse |
99+
|---|---|---|
100+
| `homelab-secrets` | Global (always active) | Flag hardcoded passwords, IPs, and SSH keys |
101+
| `compose-arm64` | Compose files | Flag images without arm64 support, missing healthchecks |
102+
| `ssh-safety` | Global (always active) | Flag dangerous SSH commands (rm -rf, dd, mkfs) |
103+
| `yaml-conventions` | YAML files | Enforce 2-space indent, document start, explicit booleans |
104+
| `ansible-best-practices` | Ansible files | Flag non-FQCN modules, missing tags, shell misuse |
105+
106+
</details>
61107

62108
---
63109

64110
## Companion: Home Lab MCP Server
65111

66112
The MCP server gives your AI assistant live access to your Raspberry Pi via SSH. Works with Cursor, Claude Code, and any MCP-compatible client.
67113

114+
<p align="center">
115+
<img src="https://img.shields.io/badge/transport-stdio-blue" alt="transport">
116+
<img src="https://img.shields.io/badge/tools-15-green" alt="tools">
117+
<img src="https://img.shields.io/badge/runtime-Node%20%E2%89%A5%2020-yellow" alt="runtime">
118+
<img src="https://img.shields.io/badge/connection-SSH-orange" alt="connection">
119+
</p>
120+
68121
Add to your Cursor MCP config (`.cursor/mcp.json`):
69122

70123
```json
@@ -84,29 +137,64 @@ Add to your Cursor MCP config (`.cursor/mcp.json`):
84137
}
85138
```
86139

87-
**15 MCP Tools**
88-
89-
| Category | Tool | Description |
90-
|----------|------|-------------|
91-
| System | `homelab_piStatus` | CPU temp, memory, disk, uptime, throttle state |
92-
| System | `homelab_piReboot` | Safe reboot with pre-checks |
93-
| System | `homelab_diskUsage` | Disk usage breakdown by directory |
94-
| System | `homelab_aptUpdate` | Run apt update, list upgradable packages |
95-
| Containers | `homelab_serviceHealth` | Docker container health status |
96-
| Containers | `homelab_serviceLogs` | Tail container logs |
97-
| Containers | `homelab_serviceRestart` | Restart a container |
98-
| Compose | `homelab_composeUp` | Start compose stacks |
99-
| Compose | `homelab_composeDown` | Stop compose stacks |
100-
| Compose | `homelab_composePull` | Pull latest images |
101-
| Compose | `homelab_composePs` | List running containers |
102-
| Network | `homelab_networkInfo` | IP addresses, DNS, Tailscale status |
103-
| Backup | `homelab_backupStatus` | Check latest restic snapshots |
104-
| Backup | `homelab_backupRun` | Trigger restic backup |
105-
| SSH | `homelab_sshTest` | Test SSH connectivity |
140+
<details>
141+
<summary><strong>15 MCP Tools</strong> - full tool reference</summary>
142+
143+
&nbsp;
144+
145+
**System** (4)
146+
147+
| Tool | What It Does |
148+
|---|---|
149+
| `homelab_piStatus` | CPU temp, memory, disk, uptime, throttle state |
150+
| `homelab_piReboot` | Safe reboot with pre-checks (requires confirm=true) |
151+
| `homelab_diskUsage` | Disk usage breakdown by directory |
152+
| `homelab_aptUpdate` | Run apt update, list upgradable packages |
153+
154+
**Containers** (3)
155+
156+
| Tool | What It Does |
157+
|---|---|
158+
| `homelab_serviceHealth` | Docker container health status |
159+
| `homelab_serviceLogs` | Tail container logs |
160+
| `homelab_serviceRestart` | Restart a container |
161+
162+
**Compose** (4)
163+
164+
| Tool | What It Does |
165+
|---|---|
166+
| `homelab_composeUp` | Start compose stacks (all or specific) |
167+
| `homelab_composeDown` | Stop compose stacks |
168+
| `homelab_composePull` | Pull latest images |
169+
| `homelab_composePs` | List running compose containers |
170+
171+
**Network** (1)
172+
173+
| Tool | What It Does |
174+
|---|---|
175+
| `homelab_networkInfo` | IP addresses, DNS, Tailscale status |
176+
177+
**Backup** (2)
178+
179+
| Tool | What It Does |
180+
|---|---|
181+
| `homelab_backupStatus` | Check latest restic snapshots |
182+
| `homelab_backupRun` | Trigger restic backup (requires confirm=true) |
183+
184+
**SSH** (1)
185+
186+
| Tool | What It Does |
187+
|---|---|
188+
| `homelab_sshTest` | Test SSH connectivity |
189+
190+
</details>
106191

107192
---
108193

109-
## Installation
194+
<details>
195+
<summary><h2>Installation</h2></summary>
196+
197+
&nbsp;
110198

111199
### Cursor (plugin + MCP)
112200

@@ -132,7 +220,7 @@ npm install
132220
npm run build
133221
```
134222

135-
Then add the JSON config from the MCP Server section to `.cursor/mcp.json`.
223+
Then add the JSON config from the [MCP Server section](#companion-home-lab-mcp-server) to `.cursor/mcp.json`.
136224

137225
### Claude Code (terminal or in Cursor)
138226

@@ -154,22 +242,42 @@ claude mcp add homelab -- npx @tmhs/homelab-mcp
154242

155243
Any client supporting MCP stdio transport can use the Home Lab MCP server. Point it at `node ./mcp-server/dist/index.js` or the global `npx @tmhs/homelab-mcp`.
156244

157-
---
245+
</details>
246+
247+
<details>
248+
<summary><h2>Example Prompts</h2> - one per skill</summary>
158249

159-
## Example Prompts
250+
&nbsp;
160251

161252
| Skill | Try This |
162-
|-------|----------|
163-
| pi-system-management | "Is my Pi overheating? Check the CPU temp and throttle status" |
164-
| docker-compose-stacks | "Pull latest images and redeploy the monitoring stack" |
165-
| service-monitoring | "Set up a Prometheus alert for when disk usage exceeds 85%" |
166-
| network-configuration | "Configure AdGuard to block ads for all devices on my network" |
167-
| backup-recovery | "When was the last backup? Show me the recent snapshots" |
168-
| ssh-management | "Harden my SSH config -- disable password auth, change the port" |
169-
| ansible-workflows | "Write an Ansible playbook to deploy all compose stacks" |
170-
| security-hardening | "Audit my Pi's firewall rules and suggest improvements" |
171-
| storage-management | "Which directories are using the most disk space?" |
172-
| troubleshooting | "Grafana won't start -- help me debug the container" |
253+
|---|---|
254+
| `pi-system-management` | "Is my Pi overheating? Check the CPU temp and throttle status" |
255+
| `docker-compose-stacks` | "Pull latest images and redeploy the monitoring stack" |
256+
| `service-monitoring` | "Set up a Prometheus alert for when disk usage exceeds 85%" |
257+
| `network-configuration` | "Configure AdGuard to block ads for all devices on my network" |
258+
| `backup-recovery` | "When was the last backup? Show me the recent snapshots" |
259+
| `ssh-management` | "Harden my SSH config -- disable password auth, change the port" |
260+
| `ansible-workflows` | "Write an Ansible playbook to deploy all compose stacks" |
261+
| `security-hardening` | "Audit my Pi's firewall rules and suggest improvements" |
262+
| `storage-management` | "Which directories are using the most disk space?" |
263+
| `troubleshooting` | "Grafana won't start -- help me debug the container" |
264+
265+
</details>
266+
267+
<details>
268+
<summary><h2>Roadmap</h2></summary>
269+
270+
&nbsp;
271+
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) |
279+
280+
</details>
173281

174282
---
175283

@@ -181,10 +289,12 @@ Any client supporting MCP stdio transport can use the Home Lab MCP server. Point
181289

182290
## Contributing
183291

184-
Contributions welcome - see [CONTRIBUTING.md](CONTRIBUTING.md).
292+
Contributions welcome - see [CONTRIBUTING.md](CONTRIBUTING.md). Found a bug? [Open an issue](https://github.com/TMHSDigital/Home-Lab-Developer-Tools/issues).
185293

186294
## License
187295

188296
**CC-BY-NC-ND-4.0** - Copyright 2026 TM Hospitality Strategies. See [LICENSE](LICENSE).
189297

190-
Built by [TMHSDigital](https://github.com/TMHSDigital)
298+
<p align="center">
299+
<a href="https://github.com/TMHSDigital">Built by TMHSDigital</a>
300+
</p>

‎assets/logo.png‎

109 KB
Loading

0 commit comments

Comments
 (0)