homebutler-mcp 0.7.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sanghee Son (Higangssh)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,63 @@
+# homebutler-mcp
+
+MCP server for homelab management. Manage servers, Docker containers, ports, alerts, and more — from any AI tool.
+
+This is an npm wrapper for [homebutler](https://github.com/Higangssh/homebutler). It downloads the correct binary for your platform automatically.
+
+## Quick Setup
+
+Add to your MCP client config (Claude Code, Cursor, Claude Desktop, ChatGPT Desktop):
+
+```json
+{
+  "mcpServers": {
+    "homebutler": {
+      "command": "npx",
+      "args": ["-y", "homebutler-mcp"]
+    }
+  }
+}
+```
+
+That's it. No manual installation needed.
+
+## Try Without Real Servers
+
+```json
+{
+  "mcpServers": {
+    "homebutler": {
+      "command": "npx",
+      "args": ["-y", "homebutler-mcp", "--demo"]
+    }
+  }
+}
+```
+
+Demo mode returns realistic fake data — perfect for trying it out.
+
+## Available Tools
+
+| Tool | Description |
+|---|---|
+| `system_status` | CPU, memory, disk, uptime |
+| `docker_list` | List containers |
+| `docker_restart` | Restart a container |
+| `docker_stop` | Stop a container |
+| `docker_logs` | Container log output |
+| `wake` | Wake-on-LAN magic packet |
+| `open_ports` | Open ports with process info |
+| `network_scan` | Discover LAN devices |
+| `alerts` | Resource threshold alerts |
+
+All tools support an optional `server` parameter for multi-server management via SSH.
+
+## Links
+
+- [GitHub](https://github.com/Higangssh/homebutler)
+- [Full documentation](https://github.com/Higangssh/homebutler#mcp-server)
+- [Report issues](https://github.com/Higangssh/homebutler/issues)
+
+## License
+
+MIT

package/install.js

@@ -0,0 +1,133 @@
+#!/usr/bin/env node
+"use strict";
+
+const { execSync } = require("child_process");
+const fs = require("fs");
+const path = require("path");
+const https = require("https");
+const { createWriteStream } = require("fs");
+const { pipeline } = require("stream/promises");
+
+const REPO = "Higangssh/homebutler";
+const BIN_NAME = process.platform === "win32" ? "homebutler.exe" : "homebutler";
+const BIN_DIR = path.join(__dirname, "bin");
+const BIN_PATH = path.join(BIN_DIR, BIN_NAME);
+
+function getPlatform() {
+  const platform = process.platform;
+  const arch = process.arch;
+
+  const osMap = { linux: "linux", darwin: "darwin", win32: "windows" };
+  const archMap = { x64: "amd64", arm64: "arm64" };
+
+  const os = osMap[platform];
+  const cpu = archMap[arch];
+
+  if (!os || !cpu) {
+    throw new Error(`Unsupported platform: ${platform}/${arch}`);
+  }
+
+  return { os, cpu };
+}
+
+function getVersion() {
+  const pkg = require("./package.json");
+  return pkg.version;
+}
+
+function fetch(url) {
+  return new Promise((resolve, reject) => {
+    https.get(url, { headers: { "User-Agent": "homebutler-mcp" } }, (res) => {
+      if (res.statusCode >= 300 && res.statusCode < 400 && res.headers.location) {
+        return fetch(res.headers.location).then(resolve, reject);
+      }
+      if (res.statusCode !== 200) {
+        return reject(new Error(`HTTP ${res.statusCode} for ${url}`));
+      }
+      resolve(res);
+    }).on("error", reject);
+  });
+}
+
+async function downloadAndExtract() {
+  const { os, cpu } = getPlatform();
+  const version = getVersion();
+  const tag = `v${version}`;
+
+  const ext = os === "windows" ? "zip" : "tar.gz";
+  const assetName = `homebutler_${version}_${os}_${cpu}.${ext}`;
+  const url = `https://github.com/${REPO}/releases/download/${tag}/${assetName}`;
+
+  console.log(`Downloading homebutler ${tag} for ${os}/${cpu}...`);
+
+  fs.mkdirSync(BIN_DIR, { recursive: true });
+
+  const tmpFile = path.join(BIN_DIR, assetName);
+  const stream = createWriteStream(tmpFile);
+  const res = await fetch(url);
+  await pipeline(res, stream);
+
+  console.log("Extracting...");
+
+  if (ext === "tar.gz") {
+    execSync(`tar -xzf "${tmpFile}" -C "${BIN_DIR}"`, { stdio: "inherit" });
+  } else {
+    execSync(`unzip -o "${tmpFile}" -d "${BIN_DIR}"`, { stdio: "inherit" });
+  }
+
+  // Find the binary (goreleaser puts it inside a directory or at root)
+  if (!fs.existsSync(BIN_PATH)) {
+    // Search recursively
+    const found = findFile(BIN_DIR, BIN_NAME);
+    if (found && found !== BIN_PATH) {
+      fs.renameSync(found, BIN_PATH);
+    }
+  }
+
+  if (!fs.existsSync(BIN_PATH)) {
+    throw new Error(`Binary not found after extraction: ${BIN_PATH}`);
+  }
+
+  fs.chmodSync(BIN_PATH, 0o755);
+
+  // Cleanup archive
+  fs.unlinkSync(tmpFile);
+
+  // Cleanup extracted directories
+  for (const entry of fs.readdirSync(BIN_DIR)) {
+    const full = path.join(BIN_DIR, entry);
+    if (fs.statSync(full).isDirectory()) {
+      fs.rmSync(full, { recursive: true });
+    }
+  }
+
+  console.log(`homebutler ${tag} installed successfully.`);
+}
+
+function findFile(dir, name) {
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    const full = path.join(dir, entry.name);
+    if (entry.isFile() && entry.name === name) return full;
+    if (entry.isDirectory()) {
+      const found = findFile(full, name);
+      if (found) return found;
+    }
+  }
+  return null;
+}
+
+// Skip if binary already exists and is correct version
+if (fs.existsSync(BIN_PATH)) {
+  try {
+    const out = execSync(`"${BIN_PATH}" version`, { encoding: "utf8" });
+    if (out.includes(getVersion())) {
+      console.log(`homebutler ${getVersion()} already installed.`);
+      process.exit(0);
+    }
+  } catch {}
+}
+
+downloadAndExtract().catch((err) => {
+  console.error("Failed to install homebutler:", err.message);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "homebutler-mcp",
+  "version": "0.7.1",
+  "description": "MCP server for homelab management — manage servers, Docker, ports, alerts via AI",
+  "keywords": ["mcp", "homelab", "server", "docker", "claude", "ai", "devops", "monitoring"],
+  "license": "MIT",
+  "author": "Higangssh",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Higangssh/homebutler"
+  },
+  "homepage": "https://github.com/Higangssh/homebutler#mcp-server",
+  "bugs": {
+    "url": "https://github.com/Higangssh/homebutler/issues"
+  },
+  "bin": {
+    "homebutler-mcp": "run.js"
+  },
+  "scripts": {
+    "postinstall": "node install.js"
+  },
+  "files": [
+    "install.js",
+    "run.js",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=16"
+  }
+}

package/run.js

@@ -0,0 +1,28 @@
+#!/usr/bin/env node
+"use strict";
+
+const { spawn } = require("child_process");
+const path = require("path");
+const fs = require("fs");
+
+const BIN_NAME = process.platform === "win32" ? "homebutler.exe" : "homebutler";
+const BIN_PATH = path.join(__dirname, "bin", BIN_NAME);
+
+if (!fs.existsSync(BIN_PATH)) {
+  console.error(
+    "homebutler binary not found. Run: npm rebuild homebutler-mcp"
+  );
+  process.exit(1);
+}
+
+const args = ["mcp", ...process.argv.slice(2)];
+
+const child = spawn(BIN_PATH, args, {
+  stdio: ["inherit", "inherit", "inherit"],
+});
+
+child.on("exit", (code) => process.exit(code ?? 0));
+child.on("error", (err) => {
+  console.error("Failed to start homebutler:", err.message);
+  process.exit(1);
+});