@codescene/codehealth-mcp 0.2.1

package/bin/cs-mcp.js

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+
+import { main } from "../lib/index.js";
+
+main();

package/lib/download.js

@@ -0,0 +1,248 @@
+/**
+ * Downloads and caches the cs-mcp binary from GitHub releases.
+ *
+ * The binary is cached inside the package's own directory under
+ * `.cache/{version}/` so it persists across runs but is cleaned
+ * up naturally when the package is reinstalled or upgraded.
+ */
+
+import { createWriteStream, existsSync, readdirSync, mkdirSync, chmodSync } from "node:fs";
+import { rename, rm } from "node:fs/promises";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { execFileSync } from "node:child_process";
+import https from "node:https";
+import http from "node:http";
+import { getPlatformInfo, getDownloadUrl } from "./platform.js";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const PACKAGE_ROOT = join(__dirname, "..");
+
+/**
+ * Returns the directory where binaries are cached for a given version.
+ *
+ * @param {string} version
+ * @returns {string}
+ */
+function getCacheDir(version) {
+  return join(PACKAGE_ROOT, ".cache", version);
+}
+
+/**
+ * Returns the expected path of the cached binary for a given version.
+ *
+ * @param {string} version
+ * @returns {string}
+ */
+export function getCachedBinaryPath(version) {
+  const { binary } = getPlatformInfo();
+  return join(getCacheDir(version), binary);
+}
+
+/**
+ * Checks whether an HTTP response is a redirect with a location header.
+ *
+ * @param {import("node:http").IncomingMessage} response
+ * @returns {boolean}
+ */
+function isRedirect(response) {
+  const status = response.statusCode ?? 0;
+  return status >= 300 && status < 400 && Boolean(response.headers.location);
+}
+
+/**
+ * Reports download progress to stderr at 10% intervals.
+ *
+ * @param {number} downloadedBytes
+ * @param {number} totalBytes
+ * @param {number} lastPercent - The last reported percent value
+ * @returns {number} The updated lastPercent value
+ */
+function reportProgress(downloadedBytes, totalBytes, lastPercent) {
+  if (!totalBytes) return lastPercent;
+
+  const percent = Math.floor((downloadedBytes / totalBytes) * 100);
+  if (percent !== lastPercent && percent % 10 === 0) {
+    const mb = (downloadedBytes / 1024 / 1024).toFixed(1);
+    process.stderr.write(`\r  Downloading... ${percent}% (${mb} MB)`);
+    return percent;
+  }
+  return lastPercent;
+}
+
+/**
+ * Downloads a file from a URL, following redirects (GitHub releases use 302s).
+ *
+ * @param {string} url
+ * @param {string} destPath
+ * @returns {Promise<void>}
+ */
+function downloadFile(url, destPath) {
+  return new Promise((resolve, reject) => {
+    const proto = url.startsWith("https") ? https : http;
+
+    proto
+      .get(url, (response) => {
+        if (isRedirect(response)) {
+          downloadFile(response.headers.location, destPath)
+            .then(resolve)
+            .catch(reject);
+          response.resume();
+          return;
+        }
+
+        if (response.statusCode !== 200) {
+          response.resume();
+          reject(
+            new Error(
+              `Download failed: HTTP ${response.statusCode} from ${url}`
+            )
+          );
+          return;
+        }
+
+        const totalBytes = parseInt(response.headers["content-length"], 10);
+        let downloadedBytes = 0;
+        let lastPercent = -1;
+
+        const file = createWriteStream(destPath);
+        response.on("data", (chunk) => {
+          downloadedBytes += chunk.length;
+          lastPercent = reportProgress(downloadedBytes, totalBytes, lastPercent);
+        });
+        response.pipe(file);
+        file.on("finish", () => {
+          file.close();
+          if (totalBytes) {
+            process.stderr.write("\n");
+          }
+          resolve();
+        });
+        file.on("error", (err) => {
+          file.close();
+          reject(err);
+        });
+      })
+      .on("error", reject);
+  });
+}
+
+/**
+ * Extracts a zip file to a destination directory.
+ *
+ * Uses platform-native tools: `unzip` on Unix (available on macOS and
+ * most Linux distros) and PowerShell's Expand-Archive on Windows.
+ *
+ * @param {string} zipPath
+ * @param {string} destDir
+ * @returns {void}
+ */
+function extractZip(zipPath, destDir) {
+  if (process.platform === "win32") {
+    execFileSync(
+      "powershell",
+      [
+        "-NoProfile",
+        "-Command",
+        `Expand-Archive -Path '${zipPath}' -DestinationPath '${destDir}' -Force`,
+      ],
+      { stdio: "pipe" }
+    );
+  } else {
+    execFileSync("unzip", ["-o", "-q", zipPath, "-d", destDir], {
+      stdio: "pipe",
+    });
+  }
+}
+
+/**
+ * Downloads and extracts a compressed binary, or downloads a bare binary.
+ *
+ * @param {string} url - The download URL
+ * @param {{ asset: string, compressed: boolean }} platformInfo
+ * @param {string} cacheDir - Directory to download into
+ * @param {string} binaryPath - Final expected binary path (for uncompressed)
+ * @returns {Promise<void>}
+ */
+async function downloadAsset(url, platformInfo, cacheDir, binaryPath) {
+  if (!platformInfo.compressed) {
+    await downloadFile(url, binaryPath);
+    return;
+  }
+
+  const zipPath = join(cacheDir, platformInfo.asset);
+  try {
+    await downloadFile(url, zipPath);
+    process.stderr.write("  Extracting...\n");
+    extractZip(zipPath, cacheDir);
+  } finally {
+    await rm(zipPath, { force: true }).catch(() => {});
+  }
+}
+
+/**
+ * Finds and renames a platform-named binary to the canonical name.
+ *
+ * Zip files from GitHub releases contain binaries like "cs-mcp-linux-amd64"
+ * instead of plain "cs-mcp". This function locates such a candidate and
+ * renames it.
+ *
+ * @param {string} cacheDir
+ * @param {string} binaryPath - The expected canonical binary path
+ * @returns {Promise<void>}
+ */
+async function renameExtractedBinary(cacheDir, binaryPath) {
+  if (existsSync(binaryPath)) return;
+
+  const files = readdirSync(cacheDir);
+  const candidate = files.find(
+    (f) => f.startsWith("cs-mcp") && !f.endsWith(".zip")
+  );
+
+  if (candidate) {
+    await rename(join(cacheDir, candidate), binaryPath);
+  } else {
+    throw new Error(
+      `Binary not found after download. Expected cs-mcp in ${cacheDir}. ` +
+        `Found: ${files.join(", ")}`
+    );
+  }
+}
+
+/**
+ * Ensures the cs-mcp binary is available for the given version.
+ *
+ * If the binary is already cached, returns its path immediately.
+ * Otherwise, downloads it from GitHub releases, extracts if needed,
+ * and caches it for future use.
+ *
+ * @param {string} version - The package version (e.g. "0.2.1")
+ * @returns {Promise<string>} Path to the binary
+ */
+export async function ensureBinary(version) {
+  const binaryPath = getCachedBinaryPath(version);
+
+  if (existsSync(binaryPath)) {
+    return binaryPath;
+  }
+
+  const platformInfo = getPlatformInfo();
+  const url = getDownloadUrl(version, platformInfo.asset);
+  const cacheDir = getCacheDir(version);
+
+  mkdirSync(cacheDir, { recursive: true });
+
+  process.stderr.write(
+    `CodeScene MCP Server v${version} - downloading for ${process.platform}/${process.arch}...\n`
+  );
+
+  await downloadAsset(url, platformInfo, cacheDir, binaryPath);
+  await renameExtractedBinary(cacheDir, binaryPath);
+
+  if (process.platform !== "win32") {
+    chmodSync(binaryPath, 0o755);
+  }
+
+  process.stderr.write(`  Ready: ${binaryPath}\n`);
+  return binaryPath;
+}

package/lib/index.js

@@ -0,0 +1,72 @@
+/**
+ * Main orchestrator for the npm wrapper.
+ *
+ * Resolves the binary path (from CS_MCP_BINARY_PATH or by downloading
+ * from GitHub releases) and launches it.
+ */
+
+import { readFileSync, existsSync } from "node:fs";
+import { join, dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { ensureBinary } from "./download.js";
+import { runBinary } from "./run.js";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const PACKAGE_ROOT = join(__dirname, "..");
+
+/**
+ * Reads the package version from package.json.
+ *
+ * @returns {string}
+ */
+function getPackageVersion() {
+  const pkgPath = join(PACKAGE_ROOT, "package.json");
+  const pkg = JSON.parse(readFileSync(pkgPath, "utf-8"));
+  return pkg.version;
+}
+
+/**
+ * Main entry point.
+ *
+ * Resolution order:
+ * 1. CS_MCP_BINARY_PATH env var - use the specified binary directly
+ * 2. Cached binary for the current package version
+ * 3. Download from GitHub releases and cache
+ *
+ * All command-line arguments (except the node binary and script path)
+ * are forwarded to the cs-mcp binary.
+ */
+export async function main() {
+  const args = process.argv.slice(2);
+
+  try {
+    const binaryPath = await resolveBinaryPath();
+    runBinary(binaryPath, args);
+  } catch (err) {
+    process.stderr.write(`Error: ${err.message}\n`);
+    process.exit(1);
+  }
+}
+
+/**
+ * Resolves the path to the cs-mcp binary.
+ *
+ * @returns {Promise<string>}
+ */
+async function resolveBinaryPath() {
+  // 1. Check for explicit binary path override
+  const envPath = process.env.CS_MCP_BINARY_PATH;
+  if (envPath) {
+    const resolved = resolve(envPath);
+    if (!existsSync(resolved)) {
+      throw new Error(
+        `CS_MCP_BINARY_PATH is set to "${envPath}" but the file does not exist.`
+      );
+    }
+    return resolved;
+  }
+
+  // 2. Download or use cached binary matching this package version
+  const version = getPackageVersion();
+  return ensureBinary(version);
+}

package/lib/platform.js

@@ -0,0 +1,77 @@
+/**
+ * Platform and architecture detection for downloading the correct binary.
+ *
+ * Maps Node.js platform/arch identifiers to the GitHub release asset names
+ * used by the codescene-mcp-server build pipeline.
+ */
+
+const PLATFORM_MAP = {
+  "darwin-arm64": {
+    asset: "cs-mcp-macos-aarch64.zip",
+    binary: "cs-mcp",
+    compressed: true,
+  },
+  "darwin-x64": {
+    asset: "cs-mcp-macos-amd64.zip",
+    binary: "cs-mcp",
+    compressed: true,
+  },
+  "linux-arm64": {
+    asset: "cs-mcp-linux-aarch64.zip",
+    binary: "cs-mcp",
+    compressed: true,
+  },
+  "linux-x64": {
+    asset: "cs-mcp-linux-amd64.zip",
+    binary: "cs-mcp",
+    compressed: true,
+  },
+  "win32-x64": {
+    asset: "cs-mcp-windows-amd64.exe",
+    binary: "cs-mcp.exe",
+    compressed: false,
+  },
+};
+
+/**
+ * Returns the platform info for the current OS and architecture.
+ *
+ * @returns {{ asset: string, binary: string, compressed: boolean }}
+ * @throws {Error} If the current platform/arch combination is unsupported.
+ */
+export function getPlatformInfo() {
+  const key = `${process.platform}-${process.arch}`;
+  const info = PLATFORM_MAP[key];
+
+  if (!info) {
+    const supported = Object.keys(PLATFORM_MAP)
+      .map((k) => k.replace("-", "/"))
+      .join(", ");
+    throw new Error(
+      `Unsupported platform: ${process.platform}/${process.arch}. ` +
+        `Supported platforms: ${supported}`
+    );
+  }
+
+  return info;
+}
+
+/**
+ * Constructs the download URL for a given version and asset.
+ *
+ * By default, downloads from GitHub releases. Set CS_MCP_DOWNLOAD_BASE_URL
+ * to override the base URL (useful for testing, mirrors, or air-gapped
+ * environments). The env var should include the full base up to the tag
+ * directory, e.g. "http://localhost:8080/releases/download".
+ *
+ * @param {string} version - The package version (e.g. "0.2.1")
+ * @param {string} asset - The asset filename (e.g. "cs-mcp-macos-aarch64.zip")
+ * @returns {string} The full download URL
+ */
+export function getDownloadUrl(version, asset) {
+  const tag = `MCP-${version}`;
+  const baseUrl =
+    process.env.CS_MCP_DOWNLOAD_BASE_URL ||
+    "https://github.com/codescene-oss/codescene-mcp-server/releases/download";
+  return `${baseUrl}/${tag}/${asset}`;
+}

package/lib/run.js

@@ -0,0 +1,59 @@
+/**
+ * Spawns the cs-mcp binary as a child process.
+ *
+ * Uses `stdio: "inherit"` so that stdin, stdout, and stderr are passed
+ * directly through to the child process. This is critical for the MCP
+ * stdio transport where the MCP client communicates via JSON-RPC over
+ * the process's stdin/stdout.
+ *
+ * Signals are forwarded to the child process so that graceful shutdown
+ * works as expected.
+ */
+
+import { spawnSync } from "node:child_process";
+
+/**
+ * Runs the cs-mcp binary, forwarding all stdio and signals.
+ *
+ * This function does not return until the binary exits.
+ * The current process exits with the same exit code as the binary.
+ *
+ * @param {string} binaryPath - Absolute path to the cs-mcp binary
+ * @param {string[]} args - Command-line arguments to pass through
+ * @returns {never}
+ */
+export function runBinary(binaryPath, args) {
+  const result = spawnSync(binaryPath, args, {
+    stdio: "inherit",
+    env: process.env,
+    windowsHide: true,
+  });
+
+  if (result.error) {
+    // Handle spawn errors (e.g. binary not found, permission denied)
+    if (result.error.code === "ENOENT") {
+      process.stderr.write(`Error: Binary not found at ${binaryPath}\n`);
+      process.exit(127);
+    }
+    if (result.error.code === "EACCES") {
+      process.stderr.write(
+        `Error: Permission denied executing ${binaryPath}\n`
+      );
+      process.exit(126);
+    }
+    throw result.error;
+  }
+
+  // Exit with the same code as the child process.
+  // If the child was killed by a signal, use 128 + signal number convention.
+  if (result.status !== null) {
+    process.exit(result.status);
+  }
+  if (result.signal) {
+    // Convert signal name to number (e.g. SIGTERM -> 15)
+    const signalNumbers = { SIGTERM: 15, SIGINT: 2, SIGKILL: 9, SIGHUP: 1 };
+    const sigNum = signalNumbers[result.signal] || 1;
+    process.exit(128 + sigNum);
+  }
+  process.exit(1);
+}

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@codescene/codehealth-mcp",
+  "version": "0.2.1",
+  "description": "CodeScene MCP Server — Code Health analysis for AI coding agents",
+  "type": "module",
+  "bin": {
+    "cs-mcp": "./bin/cs-mcp.js"
+  },
+  "scripts": {
+    "test": "c8 node --experimental-test-module-mocks --test tests/*.test.js",
+    "test:ci": "c8 --reporter=cobertura --reporter=text node --experimental-test-module-mocks --test tests/*.test.js"
+  },
+  "files": [
+    "bin/",
+    "lib/"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "os": [
+    "darwin",
+    "linux",
+    "win32"
+  ],
+  "cpu": [
+    "x64",
+    "arm64"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/codescene-oss/codescene-mcp-server.git",
+    "directory": "npm"
+  },
+  "homepage": "https://codescene.com",
+  "keywords": [
+    "codescene",
+    "code-health",
+    "mcp",
+    "model-context-protocol",
+    "ai",
+    "code-quality"
+  ],
+  "devDependencies": {
+    "c8": "^11.0.0"
+  }
+}