From 847a1cb9a365acda342f5b653bec8571f2fb33e3 Mon Sep 17 00:00:00 2001 From: fOuttaMyPaint Date: Sun, 5 Apr 2026 16:38:07 -0400 Subject: [PATCH] v0.7.0: OS and Package Management 4 new MCP tools (aptUpgradable, aptHistory, kernelInfo, systemdServices), 2 new skills (os-update-management, performance-tuning), 1 new rule (resource-limits). 88 vitest + 250 pytest passing. Made-with: Cursor --- .cursor-plugin/plugin.json | 4 +- CHANGELOG.md | 17 ++ CLAUDE.md | 17 +- README.md | 32 ++-- ROADMAP.md | 15 +- docs/index.html | 26 +++- mcp-server/README.md | 6 +- mcp-server/package-lock.json | 4 +- mcp-server/package.json | 4 +- mcp-server/src/index.ts | 10 +- .../tools/__tests__/input-validation.test.ts | 66 ++++++++ mcp-server/src/tools/aptHistory.ts | 38 +++++ mcp-server/src/tools/aptUpgradable.ts | 28 ++++ mcp-server/src/tools/kernelInfo.ts | 31 ++++ mcp-server/src/tools/systemdServices.ts | 33 ++++ rules/resource-limits.mdc | 76 +++++++++ skills/os-update-management/SKILL.md | 138 +++++++++++++++++ skills/performance-tuning/SKILL.md | 146 ++++++++++++++++++ 18 files changed, 656 insertions(+), 35 deletions(-) create mode 100644 mcp-server/src/tools/aptHistory.ts create mode 100644 mcp-server/src/tools/aptUpgradable.ts create mode 100644 mcp-server/src/tools/kernelInfo.ts create mode 100644 mcp-server/src/tools/systemdServices.ts create mode 100644 rules/resource-limits.mdc create mode 100644 skills/os-update-management/SKILL.md create mode 100644 skills/performance-tuning/SKILL.md diff --git a/.cursor-plugin/plugin.json b/.cursor-plugin/plugin.json index 14b6db7..17fe729 100644 --- a/.cursor-plugin/plugin.json +++ b/.cursor-plugin/plugin.json @@ -1,8 +1,8 @@ { "name": "home-lab-developer-tools", "displayName": "Home Lab Developer Tools", - "version": "0.6.0", - "description": "Home lab and Raspberry Pi workflows for Cursor, Claude Code, and MCP-compatible editors - 18 skills, 9 rules, and 37 MCP tools for managing Docker Compose stacks, monitoring, DNS, reverse proxy, networking, backups, disaster recovery, security auditing, logs, notifications, and system administration on a Raspberry Pi home lab via SSH.", + "version": "0.7.0", + "description": "Home lab and Raspberry Pi workflows for Cursor, Claude Code, and MCP-compatible editors - 20 skills, 10 rules, and 41 MCP tools for managing Docker Compose stacks, monitoring, DNS, reverse proxy, networking, backups, disaster recovery, security auditing, logs, notifications, OS management, and system administration on a Raspberry Pi home lab via SSH.", "author": { "name": "TMHSDigital", "url": "https://github.com/TMHSDigital" diff --git a/CHANGELOG.md b/CHANGELOG.md index f4dc9c1..3ad1470 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -5,6 +5,22 @@ All notable changes to this project will be documented in this file. The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). +## [0.7.0] - 2026-04-05 + +### Added + +- 4 new MCP tools for OS and package management + - `homelab_aptUpgradable` -- list upgradable packages with current and candidate versions + - `homelab_aptHistory` -- show recent apt install, upgrade, and remove history + - `homelab_kernelInfo` -- kernel version, boot parameters, and loaded modules + - `homelab_systemdServices` -- list systemd units or get status of a specific unit +- 2 new skills + - `os-update-management` -- unattended-upgrades config, kernel updates, reboot scheduling + - `performance-tuning` -- kernel params, swap config, I/O scheduler, GPU memory split +- 1 new rule + - `resource-limits` -- flag Docker Compose services without memory or CPU limits +- Input validation tests for all 4 new tools + ## [0.6.0] - 2026-04-05 ### Added @@ -121,6 +137,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 - Full documentation (README, CLAUDE.md, CONTRIBUTING, ROADMAP, SECURITY) - Project logo (assets/logo.png) +[0.7.0]: https://github.com/TMHSDigital/Home-Lab-Developer-Tools/releases/tag/v0.7.0 [0.6.0]: https://github.com/TMHSDigital/Home-Lab-Developer-Tools/releases/tag/v0.6.0 [0.5.0]: https://github.com/TMHSDigital/Home-Lab-Developer-Tools/releases/tag/v0.5.0 [0.4.0]: https://github.com/TMHSDigital/Home-Lab-Developer-Tools/releases/tag/v0.4.0 diff --git a/CLAUDE.md b/CLAUDE.md index 3c8c653..c0c58f3 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -4,13 +4,13 @@ Project documentation for Claude Code and AI assistants working on this reposito ## Project Overview -Home Lab Developer Tools integrates home lab and Raspberry Pi workflows into AI-assisted development. It includes 18 skills, 9 rules, and a companion MCP server with 37 tools for managing Docker Compose stacks, monitoring, DNS, reverse proxy, networking, backups, disaster recovery, security auditing, logs, notifications, and system administration via SSH. +Home Lab Developer Tools integrates home lab and Raspberry Pi workflows into AI-assisted development. It includes 20 skills, 10 rules, and a companion MCP server with 41 tools for managing Docker Compose stacks, monitoring, DNS, reverse proxy, networking, backups, disaster recovery, security auditing, logs, notifications, OS management, and system administration via SSH. **Works with:** Cursor (plugin), Claude Code (terminal and in-editor), and any MCP-compatible client. This is a monorepo -- the skills, rules, and companion MCP server live in the same repository. The MCP server connects to a Raspberry Pi via SSH to execute commands. -**Version:** 0.6.0 +**Version:** 0.7.0 **License:** CC-BY-NC-ND-4.0 **npm:** @tmhs/homelab-mcp **Author:** TMHSDigital @@ -38,7 +38,7 @@ Home-Lab-Developer-Tools/ tests/ # Python structure tests ``` -## Skills (18) +## Skills (20) | Skill | Description | |-------|-------------| @@ -58,10 +58,12 @@ Home-Lab-Developer-Tools/ | secrets-management | Vaultwarden, env vars, Docker secrets, credential auditing | | log-analysis | Structured log querying, journald workflows, container log searching | | notification-workflows | Ntfy setup, alert routing, notification pipelines | +| os-update-management | Unattended-upgrades, kernel updates, reboot scheduling | +| performance-tuning | Kernel params, swap config, I/O scheduler, GPU memory split | | storage-management | Samba, Syncthing, volumes, disk monitoring | | troubleshooting | Debug crashes, network issues, hardware problems | -## Rules (9) +## Rules (10) | Rule | Scope | Description | |------|-------|-------------| @@ -74,8 +76,9 @@ Home-Lab-Developer-Tools/ | backup-coverage | compose*.yml | Flag Docker volumes not covered by any backup job | | privileged-containers | compose*.yml | Flag containers with elevated privileges or missing security opts | | weak-credentials | compose*.yml, .env* | Flag default/weak passwords and insecure credential storage | +| resource-limits | compose*.yml | Flag containers without memory or CPU limits | -## MCP Tools (37) +## MCP Tools (41) All tools connect to the Pi via SSH using environment variables for configuration. @@ -117,6 +120,10 @@ All tools connect to the Pi via SSH using environment variables for configuratio | `homelab_logSearch` | Search across container logs with grep patterns | | `homelab_ntfySend` | Send a push notification via Ntfy | | `homelab_ntfyTopics` | List Ntfy topics and recent messages | +| `homelab_aptUpgradable` | List upgradable packages with version details | +| `homelab_aptHistory` | Show recent apt install/upgrade/remove history | +| `homelab_kernelInfo` | Kernel version, boot parameters, loaded modules | +| `homelab_systemdServices` | List systemd units or get status of a specific unit | | `homelab_sshTest` | Test SSH connectivity | ## Development diff --git a/README.md b/README.md index c1547fa..295830d 100644 --- a/README.md +++ b/README.md @@ -29,7 +29,7 @@

- 18 skills  •  9 rules  •  37 MCP tools + 20 skills  •  10 rules  •  41 MCP tools

--- @@ -41,9 +41,9 @@ This project works with any AI coding tool that supports skills, rules, or MCP: | Component | Cursor | Claude Code (terminal) | Claude Code in Cursor | Other MCP clients | |---|:---:|:---:|:---:|:---:| | **CLAUDE.md** context | Yes | Yes | Yes | - | -| **18 Skills** (SKILL.md) | Yes | Yes | Yes | - | -| **9 Rules** (.mdc) | Yes | Via CLAUDE.md | Yes | - | -| **37 MCP tools** | Yes | Yes | Yes | Yes | +| **20 Skills** (SKILL.md) | Yes | Yes | Yes | - | +| **10 Rules** (.mdc) | Yes | Via CLAUDE.md | Yes | - | +| **41 MCP tools** | Yes | Yes | Yes | Yes | > **Claude Code** reads `CLAUDE.md` automatically and can reference skills. The MCP server works with any client that supports the MCP stdio transport. @@ -71,7 +71,7 @@ flowchart LR ---
-18 Skills - on-demand home lab expertise +20 Skills - on-demand home lab expertise   @@ -93,13 +93,15 @@ flowchart LR | **Security** | `secrets-management` | Vaultwarden, env vars, Docker secrets, credential auditing | | **Logs** | `log-analysis` | Structured log querying, journald workflows, container log searching | | **Notifications** | `notification-workflows` | Ntfy setup, alert routing, notification pipelines | +| **OS** | `os-update-management` | Unattended-upgrades, kernel updates, reboot scheduling | +| **OS** | `performance-tuning` | Kernel params, swap config, I/O scheduler, GPU memory split | | **Storage** | `storage-management` | Samba, Syncthing, volumes, disk monitoring | | **Debug** | `troubleshooting` | Debug crashes, network issues, hardware problems |
-9 Rules - automatic best-practice enforcement +10 Rules - automatic best-practice enforcement   @@ -114,6 +116,7 @@ flowchart LR | `backup-coverage` | Compose files | Flag Docker volumes not covered by any backup job | | `privileged-containers` | Compose files | Flag containers with elevated privileges or missing security opts | | `weak-credentials` | Compose / .env files | Flag default/weak passwords and insecure credential storage | +| `resource-limits` | Compose files | Flag containers without memory or CPU limits |
@@ -125,7 +128,7 @@ The MCP server gives your AI assistant live access to your Raspberry Pi via SSH.

transport - tools + tools runtime connection

@@ -150,7 +153,7 @@ Add to your Cursor MCP config (`.cursor/mcp.json`): ```
-37 MCP Tools - full tool reference +41 MCP Tools - full tool reference   @@ -226,6 +229,15 @@ Add to your Cursor MCP config (`.cursor/mcp.json`): | `homelab_openPorts` | Scan listening TCP ports and map to processes | | `homelab_containerScan` | Scan container images for vulnerabilities via Trivy | +**OS / Packages** (4) + +| Tool | What It Does | +|---|---| +| `homelab_aptUpgradable` | List upgradable packages with version details | +| `homelab_aptHistory` | Show recent apt install/upgrade/remove history | +| `homelab_kernelInfo` | Kernel version, boot parameters, loaded modules | +| `homelab_systemdServices` | List systemd units or get status of a specific unit | + **SSH** (1) | Tool | What It Does | @@ -314,6 +326,8 @@ Any client supporting MCP stdio transport can use the Home Lab MCP server. Point | `secrets-management` | "Audit my Pi for weak passwords and scan containers for vulnerabilities" | | `log-analysis` | "Search all container logs for OOM errors in the last hour" | | `notification-workflows` | "Send a test notification to my phone via Ntfy" | +| `os-update-management` | "Are there any security updates pending on my Pi?" | +| `performance-tuning` | "My Pi is sluggish with 13 containers. How can I optimize it?" |
@@ -330,7 +344,7 @@ Any client supporting MCP stdio transport can use the Home Lab MCP server. Point | **v0.4.0** | **Backup and Recovery** | **+4** | **+1** | **+1** | **29** | | **v0.5.0** | **Security Hardening** | **+4** | **+1** | **+2** | **33** | | **v0.6.0** | **Logs and Notifications** | **+4** | **+2** | **--** | **37** | -| v0.7.0 | OS and Package Management | +4 | +2 | +1 | 41 | +| **v0.7.0** | **OS and Package Management** | **+4** | **+2** | **+1** | **41** | | v0.8.0 | SSL/TLS Certificates | +3 | +1 | -- | 44 | | v0.9.0 | Multi-Node Foundation | +4 | +1 | +1 | 48 | | v0.10.0 | Testing Infrastructure | +2 | -- | -- | 50 | diff --git a/ROADMAP.md b/ROADMAP.md index 67e8b91..e2bc6d6 100644 --- a/ROADMAP.md +++ b/ROADMAP.md @@ -140,19 +140,19 @@ System-level maintenance beyond apt update. **MCP tools (+4):** -- [ ] `homelab_aptUpgradable` -- list upgradable packages with version details -- [ ] `homelab_aptHistory` -- show recent apt install/upgrade history -- [ ] `homelab_kernelInfo` -- kernel version, loaded modules, boot params -- [ ] `homelab_systemdServices` -- list systemd units, enable/disable/status +- [x] `homelab_aptUpgradable` -- list upgradable packages with version details +- [x] `homelab_aptHistory` -- show recent apt install/upgrade history +- [x] `homelab_kernelInfo` -- kernel version, loaded modules, boot params +- [x] `homelab_systemdServices` -- list systemd units, enable/disable/status **Skills (+2):** -- [ ] `os-update-management` -- unattended-upgrades config, kernel updates, reboot scheduling -- [ ] `performance-tuning` -- kernel params, swap config, I/O scheduler, GPU memory split +- [x] `os-update-management` -- unattended-upgrades config, kernel updates, reboot scheduling +- [x] `performance-tuning` -- kernel params, swap config, I/O scheduler, GPU memory split **Rules (+1):** -- [ ] `resource-limits` -- flag containers without memory/CPU limits set +- [x] `resource-limits` -- flag containers without memory/CPU limits set --- @@ -271,6 +271,7 @@ Production-ready, fully tested, fully documented. ## Completed +- v0.7.0: OS and Package Management -- 4 new tools (aptUpgradable, aptHistory, kernelInfo, systemdServices), 2 new skills (os-update-management, performance-tuning), 1 new rule (resource-limits) - v0.6.0: Logs and Notifications -- 4 new tools (journalLogs, logSearch, ntfySend, ntfyTopics), 2 new skills (log-analysis, notification-workflows) - v0.5.0: Security Hardening -- 4 new tools (ufwStatus, fail2banStatus, openPorts, containerScan), 1 new skill (secrets-management), 2 new rules (privileged-containers, weak-credentials) - v0.4.0: Backup and Recovery -- 4 new tools (backupList, backupRestore, backupDiff, volumeBackup), 1 new skill (disaster-recovery), 1 new rule (backup-coverage) diff --git a/docs/index.html b/docs/index.html index 8d13de1..f44c0fb 100644 --- a/docs/index.html +++ b/docs/index.html @@ -4,9 +4,9 @@ Home Lab Developer Tools - + - +