@helmdeck/mcp-bridge 0.3.0

package/README.md

@@ -0,0 +1,49 @@
+# @helmdeck/mcp-bridge
+
+Stdio MCP bridge for [helmdeck](https://github.com/tosin2013/helmdeck).
+Connects Claude Code, Claude Desktop, OpenClaw, and Gemini CLI to a
+helmdeck control plane via the [Model Context Protocol](https://modelcontextprotocol.io).
+
+## Quick start
+
+```sh
+# One-shot, no install
+HELMDECK_URL=https://helmdeck.example HELMDECK_TOKEN=... npx @helmdeck/mcp-bridge
+
+# Or install globally
+npm install -g @helmdeck/mcp-bridge
+helmdeck-mcp
+```
+
+## Configuration
+
+The bridge reads two environment variables:
+
+| Variable | Description |
+| --- | --- |
+| `HELMDECK_URL` | Base URL of the helmdeck control plane (e.g. `https://helmdeck.example`) |
+| `HELMDECK_TOKEN` | Bearer JWT issued from the Management UI's API Tokens panel |
+
+## Client snippets
+
+The control plane exposes ready-to-paste configuration snippets at
+`GET /api/v1/connect/{client}` for each supported client. Example:
+
+```sh
+curl -H "Authorization: Bearer $HELMDECK_TOKEN" \
+  "$HELMDECK_URL/api/v1/connect/claude-code"
+```
+
+Supported clients: `claude-code`, `claude-desktop`, `openclaw`, `gemini-cli`.
+
+## How it works
+
+`postinstall` downloads the platform-matching `helmdeck-mcp` binary
+from the corresponding GitHub Release, verifies its SHA256 against
+`checksums.txt`, and places it in `bin/`. Set
+`HELMDECK_MCP_SKIP_DOWNLOAD=1` to skip the download (useful in CI
+images that bake the binary in another way).
+
+## License
+
+Apache-2.0

package/bin/helmdeck-mcp.js

@@ -0,0 +1,34 @@
+#!/usr/bin/env node
+// Launcher shim for @helmdeck/mcp-bridge.
+//
+// npm sets up the `helmdeck-mcp` bin symlink at install time, *before*
+// postinstall runs, so this file must exist in the published tarball.
+// At runtime it execs the platform-native binary that postinstall
+// downloaded into the same directory; if the binary is missing it
+// prints a clear remediation hint instead of a cryptic spawn error.
+
+"use strict";
+
+const path = require("path");
+const fs = require("fs");
+const { spawnSync } = require("child_process");
+
+const binName = process.platform === "win32" ? "helmdeck-mcp.exe" : "helmdeck-mcp";
+const binPath = path.join(__dirname, binName);
+
+if (!fs.existsSync(binPath)) {
+  console.error(
+    `[helmdeck-mcp] native binary not found at ${binPath}.\n` +
+    `This usually means the postinstall step was skipped (HELMDECK_MCP_SKIP_DOWNLOAD=1)\n` +
+    `or the download failed. Re-run:\n\n` +
+    `    npm rebuild @helmdeck/mcp-bridge\n`
+  );
+  process.exit(127);
+}
+
+const result = spawnSync(binPath, process.argv.slice(2), { stdio: "inherit" });
+if (result.error) {
+  console.error(`[helmdeck-mcp] failed to spawn ${binPath}: ${result.error.message}`);
+  process.exit(1);
+}
+process.exit(result.status === null ? 1 : result.status);

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@helmdeck/mcp-bridge",
+  "version": "0.3.0",
+  "description": "Stdio MCP bridge that connects Claude Code, Claude Desktop, OpenClaw, and Gemini CLI to a helmdeck control plane.",
+  "bin": {
+    "helmdeck-mcp": "bin/helmdeck-mcp.js"
+  },
+  "files": [
+    "bin/",
+    "scripts/",
+    "README.md"
+  ],
+  "scripts": {
+    "postinstall": "node scripts/postinstall.js"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/tosin2013/helmdeck.git",
+    "directory": "npm"
+  },
+  "homepage": "https://github.com/tosin2013/helmdeck",
+  "bugs": {
+    "url": "https://github.com/tosin2013/helmdeck/issues"
+  },
+  "license": "Apache-2.0",
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "helmdeck",
+    "claude",
+    "gemini",
+    "agent",
+    "bridge"
+  ]
+}

package/scripts/postinstall.js

@@ -0,0 +1,147 @@
+#!/usr/bin/env node
+// postinstall: download the helmdeck-mcp binary matching the host's
+// platform/arch from the GitHub release that corresponds to this
+// package's version, verify its checksum against checksums.txt, and
+// drop it into bin/ next to the launcher shim.
+//
+// Skipped automatically when HELMDECK_MCP_SKIP_DOWNLOAD=1 (so CI
+// images that bake the binary in another way don't double-fetch).
+
+"use strict";
+
+const fs = require("fs");
+const path = require("path");
+const https = require("https");
+const crypto = require("crypto");
+const zlib = require("zlib");
+const { execSync } = require("child_process");
+
+if (process.env.HELMDECK_MCP_SKIP_DOWNLOAD === "1") {
+  console.log("[helmdeck-mcp] HELMDECK_MCP_SKIP_DOWNLOAD=1, skipping binary download");
+  process.exit(0);
+}
+
+const pkg = require("../package.json");
+const VERSION = `v${pkg.version}`;
+const REPO = "tosin2013/helmdeck";
+
+const PLATFORM_MAP = {
+  linux: "linux",
+  darwin: "darwin",
+  win32: "windows",
+};
+const ARCH_MAP = {
+  x64: "amd64",
+  arm64: "arm64",
+};
+
+const os = PLATFORM_MAP[process.platform];
+const arch = ARCH_MAP[process.arch];
+if (!os || !arch) {
+  console.error(`[helmdeck-mcp] unsupported platform ${process.platform}/${process.arch}`);
+  process.exit(1);
+}
+
+const ext = os === "windows" ? "zip" : "tar.gz";
+const archiveName = `helmdeck-mcp_${pkg.version}_${os}_${arch}.${ext}`;
+const baseURL = `https://github.com/${REPO}/releases/download/${VERSION}`;
+const archiveURL = `${baseURL}/${archiveName}`;
+const checksumsURL = `${baseURL}/checksums.txt`;
+
+const binDir = path.join(__dirname, "..", "bin");
+fs.mkdirSync(binDir, { recursive: true });
+
+function get(url) {
+  return new Promise((resolve, reject) => {
+    https
+      .get(url, { headers: { "User-Agent": "helmdeck-mcp-postinstall" } }, (res) => {
+        if (res.statusCode >= 300 && res.statusCode < 400 && res.headers.location) {
+          resolve(get(res.headers.location));
+          return;
+        }
+        if (res.statusCode !== 200) {
+          reject(new Error(`GET ${url} -> ${res.statusCode}`));
+          return;
+        }
+        const chunks = [];
+        res.on("data", (c) => chunks.push(c));
+        res.on("end", () => resolve(Buffer.concat(chunks)));
+        res.on("error", reject);
+      })
+      .on("error", reject);
+  });
+}
+
+(async () => {
+  try {
+    console.log(`[helmdeck-mcp] downloading ${archiveURL}`);
+    const archive = await get(archiveURL);
+
+    console.log(`[helmdeck-mcp] verifying checksum`);
+    const checksums = (await get(checksumsURL)).toString("utf8");
+    const wantLine = checksums.split("\n").find((l) => l.endsWith("  " + archiveName));
+    if (!wantLine) {
+      throw new Error(`checksum entry for ${archiveName} not found in checksums.txt`);
+    }
+    const want = wantLine.split(/\s+/)[0];
+    const got = crypto.createHash("sha256").update(archive).digest("hex");
+    if (got !== want) {
+      throw new Error(`checksum mismatch: want ${want}, got ${got}`);
+    }
+
+    const archivePath = path.join(binDir, archiveName);
+    fs.writeFileSync(archivePath, archive);
+
+    console.log(`[helmdeck-mcp] extracting`);
+    if (ext === "zip") {
+      // Defer to a built-in unzip on each OS rather than ship a JS unzip dep.
+      execSync(`powershell -Command "Expand-Archive -Force '${archivePath}' '${binDir}'"`, {
+        stdio: "inherit",
+      });
+    } else {
+      // Stream-decompress + untar inline so we don't shell out on Linux/Darwin.
+      const tar = zlib.gunzipSync(archive);
+      extractTar(tar, binDir);
+    }
+    fs.unlinkSync(archivePath);
+
+    const binName = os === "windows" ? "helmdeck-mcp.exe" : "helmdeck-mcp";
+    const binPath = path.join(binDir, binName);
+    if (!fs.existsSync(binPath)) {
+      throw new Error(`expected ${binPath} after extraction`);
+    }
+    if (os !== "windows") {
+      fs.chmodSync(binPath, 0o755);
+    }
+
+    // bin/helmdeck-mcp.js is shipped in the tarball — npm has
+    // already symlinked it as the package's bin entry by the time
+    // postinstall runs, so we only need to drop the native binary
+    // next to it.
+    console.log(`[helmdeck-mcp] installed ${binPath}`);
+  } catch (err) {
+    console.error(`[helmdeck-mcp] postinstall failed: ${err.message}`);
+    process.exit(1);
+  }
+})();
+
+// Minimal POSIX-tar extractor: enough for goreleaser archives, which
+// only contain regular files. Does not handle long-name extensions
+// because goreleaser doesn't emit them for our binary names.
+function extractTar(buf, dest) {
+  let offset = 0;
+  while (offset + 512 <= buf.length) {
+    const header = buf.slice(offset, offset + 512);
+    if (header[0] === 0) break;
+    const name = header.slice(0, 100).toString("utf8").replace(/\0.*$/, "");
+    const sizeStr = header.slice(124, 136).toString("utf8").replace(/\0.*$/, "").trim();
+    const size = parseInt(sizeStr, 8);
+    const type = header[156];
+    offset += 512;
+    if ((type === 0 || type === 0x30) && name) {
+      const out = path.join(dest, path.basename(name));
+      fs.writeFileSync(out, buf.slice(offset, offset + size));
+    }
+    offset += Math.ceil(size / 512) * 512;
+  }
+}