@tomasko/mcpbox 0.0.0-stage → 0.1.1

package/README.md

@@ -1,3 +1,97 @@
-# Temporary Holding Version
+# `@tomasko/mcpbox`
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The npm launcher for [`mcpbox`](https://github.com/tomasky/mcpbox) — a
+self-contained MCP (Model Context Protocol) client CLI in the spirit of
+`mcporter`, written in MoonBit.
+
+```sh
+npm install -g @tomasko/mcpbox
+mcpbox list
+mcpbox call playwright.browser_close
+mcpbox call adhoc.echo --stdio "python3 echo_server.py" name=hi count=5
+```
+
+`mcpbox` discovers the MCP servers you already have configured — in `mcpbox`
+files, Cursor, Claude Code/Desktop, Windsurf or VS Code — connects to them over
+stdio or Streamable HTTP, and lists or calls their tools from a shell, a script
+or an agent. One process, no daemon, no background state.
+
+## What this package contains
+
+A small launcher, not the binary itself. On the first `mcpbox` run it downloads
+the prebuilt native binary for your platform from the GitHub release and caches
+it. Nothing is downloaded at install time.
+
+| Platform | Target |
+| --- | --- |
+| Linux x86-64 | `mcpbox-linux-x86_64` (static, musl) |
+| Linux arm64 | `mcpbox-linux-aarch64` (static, musl) |
+| macOS Apple silicon | `mcpbox-darwin-aarch64` |
+
+The Linux builds are linked statically against musl, so they run on any
+distribution regardless of its glibc version.
+
+## Why there is no `postinstall`
+
+This package deliberately declares **no install script**. Since npm 12,
+dependency lifecycle scripts are blocked unless the user opts in; and pnpm 12
+fails a *project* install outright with `ERR_PNPM_IGNORED_BUILDS` when a
+dependency declares one:
+
+```console
+$ pnpm add @tomasko/mcpbox
+Error: ERR_PNPM_IGNORED_BUILDS
+  × adding a new package
+  ╰─▶ Ignored build scripts: @tomasko/mcpbox@0.1.1
+```
+
+Downloading lazily from `bin/mcpbox.js` sidesteps all of it: it works under
+npm, pnpm, yarn, bun, `npx`, and `--ignore-scripts`, because it is an ordinary
+command rather than an install hook.
+
+## Cache location
+
+The downloaded binary is kept outside the package, so reinstalling or clearing
+`node_modules` never triggers a second download:
+
+| Platform | Path |
+| --- | --- |
+| Linux | `$XDG_CACHE_HOME/mcpbox` or `~/.cache/mcpbox` |
+| macOS | `~/Library/Caches/mcpbox` |
+
+## Environment variables
+
+| Variable | Effect |
+| --- | --- |
+| `MCPBOX_BINARY` | Run this binary and never download anything |
+| `MCPBOX_CACHE_DIR` | Where to keep the downloaded binary |
+| `MCPBOX_VERSION` | Release version to fetch (default: this package's version) |
+| `MCPBOX_REPO` | `owner/repo` to download from (default: `tomasky/mcpbox`) |
+| `MCPBOX_DOWNLOAD_BASE` | Full base URL, overriding `MCPBOX_REPO`/`MCPBOX_VERSION` |
+| `MCPBOX_FORCE_DOWNLOAD` | Re-download even if the cached binary exists |
+| `MCPBOX_SKIP_DOWNLOAD` | Never download; fail if the binary is absent |
+| `MCPBOX_NO_VERIFY` | Skip SHA-256 verification of the download |
+
+`MCPBOX_DOWNLOAD_BASE` and `MCPBOX_REPO` are there for forks, private mirrors
+and air-gapped installs:
+
+```sh
+MCPBOX_DOWNLOAD_BASE=https://internal.example.com/mcpbox npm install -g @tomasko/mcpbox
+```
+
+The CLI itself also reads `MCPBOX_CONFIG` to point at an explicit config file.
+
+## Other ways to install
+
+```sh
+# Installer script (no Node.js required)
+curl -LsSf https://raw.githubusercontent.com/tomasky/mcpbox/master/install.sh | bash
+
+# Build from source
+git clone https://github.com/tomasky/mcpbox && cd mcpbox
+moon build --target native --release
+```
+
+## License
+
+Apache-2.0

package/bin/mcpbox.js

@@ -0,0 +1,58 @@
+#!/usr/bin/env node
+// Launcher for the native `mcpbox` binary.
+//
+// The package ships no install script, so this is where the binary is fetched:
+// on the first run, straight into the user cache. Arguments, stdio, signals and
+// the exit code are all forwarded to the real binary.
+"use strict";
+
+const { spawn } = require("child_process");
+const { ensureBinary } = require("../lib.js");
+
+const SIGNALS = ["SIGINT", "SIGTERM", "SIGHUP", "SIGQUIT"];
+
+async function main() {
+  let binary;
+  try {
+    binary = await ensureBinary({
+      log: (line) => process.stderr.write(`${line}\n`),
+    });
+  } catch (err) {
+    process.stderr.write(`mcpbox: ${err.message}\n`);
+    process.exit(1);
+  }
+
+  const child = spawn(binary, process.argv.slice(2), { stdio: "inherit" });
+
+  // Forward signals so Ctrl-C reaches the CLI rather than killing only the
+  // wrapper and orphaning the child.
+  for (const signal of SIGNALS) {
+    process.on(signal, () => {
+      try {
+        child.kill(signal);
+      } catch {
+        /* already gone */
+      }
+    });
+  }
+
+  child.on("error", (err) => {
+    process.stderr.write(`mcpbox: failed to launch ${binary}: ${err.message}\n`);
+    process.exit(1);
+  });
+
+  child.on("exit", (code, signal) => {
+    if (signal) {
+      // Mirror the child's death by signal instead of inventing an exit code.
+      process.removeAllListeners(signal);
+      process.kill(process.pid, signal);
+      return;
+    }
+    process.exit(code === null ? 1 : code);
+  });
+}
+
+main().catch((err) => {
+  process.stderr.write(`mcpbox: ${err && err.stack ? err.stack : err}\n`);
+  process.exit(1);
+});

package/lib.js

@@ -0,0 +1,270 @@
+"use strict";
+
+// Shared logic for the npm launcher: work out which prebuilt `mcpbox` binary
+// belongs on this machine, and fetch it from GitHub Releases on demand.
+//
+// mcpbox deliberately ships **no install script**. As of npm 12 dependency
+// lifecycle scripts are blocked unless the user opts in, and pnpm 12 fails a
+// *project* install outright with ERR_PNPM_IGNORED_BUILDS when a dependency
+// declares one. Downloading on first run works under every package manager,
+// under `--ignore-scripts`, and under `npx`, so that is what this does.
+//
+// Overrides (all optional):
+//   MCPBOX_REPO            owner/repo       (default: tomasky/mcpbox)
+//   MCPBOX_VERSION         release version  (default: this package's version)
+//   MCPBOX_DOWNLOAD_BASE   full base URL    (overrides MCPBOX_REPO/MCPBOX_VERSION)
+//   MCPBOX_CACHE_DIR       where the binary is kept
+//   MCPBOX_BINARY          run this binary and never download
+//   MCPBOX_FORCE_DOWNLOAD  re-download even if the binary is already present
+//   MCPBOX_SKIP_DOWNLOAD   never download; fail if the binary is absent
+//   MCPBOX_NO_VERIFY       skip SHA-256 verification
+
+const crypto = require("crypto");
+const fs = require("fs");
+const os = require("os");
+const path = require("path");
+const https = require("https");
+const http = require("http");
+
+const pkg = require("./package.json");
+
+// Node's `platform-arch` -> the release target name. Intel macOS is absent on
+// purpose: the MoonBit toolchain no longer ships a darwin-x86_64 target.
+const TARGETS = {
+  "linux-x64": "linux-x86_64",
+  "linux-arm64": "linux-aarch64",
+  "darwin-arm64": "darwin-aarch64",
+};
+
+const SUPPORTED = "linux-x86_64, linux-aarch64 and darwin-aarch64";
+
+function targetName() {
+  return TARGETS[`${process.platform}-${process.arch}`];
+}
+
+function repoSlug() {
+  if (process.env.MCPBOX_REPO) return process.env.MCPBOX_REPO;
+  const url =
+    typeof pkg.repository === "string"
+      ? pkg.repository
+      : (pkg.repository && pkg.repository.url) || "";
+  const m = url.match(/github\.com[/:]([^/]+)\/([^/.]+)/);
+  return m ? `${m[1]}/${m[2]}` : "tomasky/mcpbox";
+}
+
+function version() {
+  return (process.env.MCPBOX_VERSION || pkg.version).replace(/^v/, "");
+}
+
+function assetName(target) {
+  return `mcpbox-${target}`;
+}
+
+// Both URLs are tried in order: the pinned version first, then whatever is
+// latest. The fallback keeps the launcher useful when a release was re-cut
+// under a different tag, or when package.json was bumped ahead of the tag.
+function downloadUrls(target) {
+  const asset = assetName(target);
+  if (process.env.MCPBOX_DOWNLOAD_BASE) {
+    const base = process.env.MCPBOX_DOWNLOAD_BASE.replace(/\/+$/, "");
+    return [`${base}/${asset}`];
+  }
+  const repo = repoSlug();
+  return [
+    `https://github.com/${repo}/releases/download/v${version()}/${asset}`,
+    `https://github.com/${repo}/releases/latest/download/${asset}`,
+  ];
+}
+
+function cacheDir() {
+  if (process.env.MCPBOX_CACHE_DIR) return process.env.MCPBOX_CACHE_DIR;
+  const home = os.homedir();
+  if (process.platform === "darwin") {
+    return path.join(home, "Library", "Caches", "mcpbox");
+  }
+  const base = process.env.XDG_CACHE_HOME || path.join(home, ".cache");
+  return path.join(base, "mcpbox");
+}
+
+function binaryPath(target) {
+  return path.join(cacheDir(), `mcpbox-${version()}-${target}`);
+}
+
+function isRunnable(file) {
+  try {
+    fs.accessSync(file, fs.constants.X_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// --- HTTP ------------------------------------------------------------------
+
+function fetch(url, redirects) {
+  return new Promise((resolve, reject) => {
+    if (redirects > 10) {
+      reject(new Error("too many redirects"));
+      return;
+    }
+    const client = url.startsWith("http:") ? http : https;
+    const req = client.get(
+      url,
+      { headers: { "user-agent": `mcpbox-npm/${pkg.version}` } },
+      (res) => {
+        const { statusCode, headers } = res;
+        if (statusCode >= 300 && statusCode < 400 && headers.location) {
+          res.resume();
+          resolve(fetch(new URL(headers.location, url).toString(), redirects + 1));
+          return;
+        }
+        if (statusCode !== 200) {
+          res.resume();
+          const err = new Error(`GET ${url} -> HTTP ${statusCode}`);
+          err.statusCode = statusCode;
+          reject(err);
+          return;
+        }
+        resolve(res);
+      }
+    );
+    req.on("error", reject);
+    req.setTimeout(120000, () => req.destroy(new Error(`timed out fetching ${url}`)));
+  });
+}
+
+async function fetchBuffer(url) {
+  const res = await fetch(url, 0);
+  const chunks = [];
+  for await (const chunk of res) chunks.push(chunk);
+  return Buffer.concat(chunks);
+}
+
+async function fetchText(url) {
+  return (await fetchBuffer(url)).toString("utf8");
+}
+
+// --- install ---------------------------------------------------------------
+
+// Download to a sibling temp file and rename into place, so a crashed or
+// concurrent run can never leave a half-written binary at `dest`.
+async function downloadTo(url, dest) {
+  const res = await fetch(url, 0);
+  fs.mkdirSync(path.dirname(dest), { recursive: true });
+  const tmp = `${dest}.${process.pid}.${Date.now()}.part`;
+  try {
+    await new Promise((resolve, reject) => {
+      const out = fs.createWriteStream(tmp, { mode: 0o755 });
+      res.pipe(out);
+      out.on("finish", () => out.close(resolve));
+      out.on("error", reject);
+      res.on("error", reject);
+    });
+    const size = fs.statSync(tmp).size;
+    if (size === 0) throw new Error(`${url} returned an empty file`);
+    fs.chmodSync(tmp, 0o755);
+    fs.renameSync(tmp, dest);
+  } catch (err) {
+    fs.rmSync(tmp, { force: true });
+    throw err;
+  }
+}
+
+// Verify against the `<asset>.sha256` published next to the binary. A missing
+// checksum is a warning, not a failure, so older releases keep working.
+async function verify(dest, url, log) {
+  if (process.env.MCPBOX_NO_VERIFY) return;
+  let published;
+  try {
+    published = (await fetchText(`${url}.sha256`)).trim();
+  } catch {
+    log(`mcpbox: warning: no checksum published for ${path.basename(url)}`);
+    return;
+  }
+  const expected = (published.split(/\s+/)[0] || "").toLowerCase();
+  if (!/^[0-9a-f]{64}$/.test(expected)) {
+    log("mcpbox: warning: published checksum is not a SHA-256 digest");
+    return;
+  }
+  const actual = crypto.createHash("sha256").update(fs.readFileSync(dest)).digest("hex");
+  if (actual !== expected) {
+    fs.rmSync(dest, { force: true });
+    throw new Error(
+      `checksum mismatch for ${path.basename(url)}\n` +
+        `  expected ${expected}\n  actual   ${actual}`
+    );
+  }
+}
+
+/**
+ * Resolve to a runnable `mcpbox` binary, downloading it when it is missing.
+ */
+async function ensureBinary({ force = false, log = () => {} } = {}) {
+  if (process.env.MCPBOX_BINARY) {
+    if (!fs.existsSync(process.env.MCPBOX_BINARY)) {
+      throw new Error(
+        `MCPBOX_BINARY points at ${process.env.MCPBOX_BINARY}, which does not exist`
+      );
+    }
+    return process.env.MCPBOX_BINARY;
+  }
+
+  const target = targetName();
+  if (!target) {
+    throw new Error(
+      `mcpbox does not ship a binary for ${process.platform}/${process.arch}; ` +
+        `supported: ${SUPPORTED}. Build from source instead: ` +
+        `https://github.com/${repoSlug()}#build-from-source`
+    );
+  }
+
+  const dest = binaryPath(target);
+  const wanted = force || process.env.MCPBOX_FORCE_DOWNLOAD;
+  if (!wanted && isRunnable(dest)) return dest;
+
+  if (process.env.MCPBOX_SKIP_DOWNLOAD) {
+    if (isRunnable(dest)) return dest;
+    throw new Error(
+      `MCPBOX_SKIP_DOWNLOAD is set but no mcpbox binary is installed at ${dest}`
+    );
+  }
+
+  const urls = downloadUrls(target);
+  let lastError;
+  for (const url of urls) {
+    try {
+      log(`mcpbox: downloading ${url}`);
+      await downloadTo(url, dest);
+      await verify(dest, url, log);
+      log(`mcpbox: installed ${dest}`);
+      return dest;
+    } catch (err) {
+      lastError = err;
+      log(`mcpbox: ${err.message}`);
+    }
+  }
+
+  throw new Error(
+    `could not download the mcpbox binary for ${target}.\n` +
+      `Tried:\n${urls.map((u) => `  ${u}`).join("\n")}\n` +
+      `Last error: ${lastError && lastError.message}\n\n` +
+      `Install it another way instead:\n` +
+      `  curl -LsSf https://raw.githubusercontent.com/${repoSlug()}/master/install.sh | bash\n` +
+      `or set MCPBOX_DOWNLOAD_BASE to a mirror.`
+  );
+}
+
+module.exports = {
+  pkg,
+  TARGETS,
+  SUPPORTED,
+  targetName,
+  repoSlug,
+  version,
+  assetName,
+  downloadUrls,
+  cacheDir,
+  binaryPath,
+  isRunnable,
+  ensureBinary,
+};

package/package.json

@@ -1,6 +1,45 @@
 {
   "name": "@tomasko/mcpbox",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "description": "Carry Model Context Protocol tools into scripts, CLIs and agents — a self-contained MCP client in the spirit of mcporter.",
+  "license": "Apache-2.0",
+  "bin": {
+    "mcpbox": "bin/mcpbox.js"
+  },
+  "files": [
+    "bin/mcpbox.js",
+    "lib.js",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "os": [
+    "darwin",
+    "linux"
+  ],
+  "cpu": [
+    "x64",
+    "arm64"
+  ],
+  "scripts": {
+    "test": "node --test"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/tomasky/mcpbox.git"
+  },
+  "homepage": "https://github.com/tomasky/mcpbox",
+  "bugs": "https://github.com/tomasky/mcpbox/issues",
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "mcp-client",
+    "cli",
+    "agent",
+    "tools",
+    "mcporter",
+    "moonbit"
+  ],
+  "preferGlobal": true
+}