@fanduzi/deltascope-mcp 0.8.1

package/README.md

@@ -0,0 +1,30 @@
+# DeltaScope MCP Launcher
+
+Bootstrap package for launching the native `deltascope-mcp` stdio server from npm-based MCP clients.
+
+## What This Package Does
+
+This package does not implement DeltaScope MCP tools itself. It downloads the matching native `deltascope-mcp` release binary, caches it locally, and then starts the real stdio server.
+
+The launcher verifies the downloaded archive against the official DeltaScope release checksums before it updates the local cache.
+
+## Version Contract
+
+- npm package version should track the DeltaScope release version it boots
+- by default the launcher resolves the native binary from its own package version
+- `DELTASCOPE_MCP_VERSION` overrides the target DeltaScope version
+- `DELTASCOPE_MCP_BASE_URL` overrides only the archive download base URL before the version and archive name are appended
+- checksum verification still uses the official GitHub release checksums file
+
+Default download base:
+
+```text
+https://github.com/Fanduzi/DeltaScope/releases/download
+```
+
+Example override:
+
+```bash
+DELTASCOPE_MCP_BASE_URL=https://mirror.example.com/deltascope/releases/download \
+npx -y @fanduzi/deltascope-mcp
+```

package/bin/deltascope-mcp.js

@@ -0,0 +1,91 @@
+#!/usr/bin/env node
+
+import fs from "node:fs/promises";
+import process from "node:process";
+
+import { downloadAndExtractBinary } from "../lib/download.js";
+import { ensureExecutable, formatBootstrapContext, spawnBinary } from "../lib/launcher.js";
+import {
+  resolveArchiveName,
+  resolveArchiveURL,
+  resolveChecksumsURL,
+  resolveDeltaScopeVersion,
+  resolvePlatform
+} from "../lib/releases.js";
+
+const packageJson = JSON.parse(
+  await fs.readFile(new URL("../package.json", import.meta.url), "utf8")
+);
+const version = resolveDeltaScopeVersion({
+  packageVersion: packageJson.version,
+  envVersion: process.env.DELTASCOPE_MCP_VERSION ?? ""
+});
+const platform = resolvePlatform();
+const archiveURL = resolveArchiveURL({
+  baseURL: process.env.DELTASCOPE_MCP_BASE_URL ?? "",
+  version,
+  os: platform.os,
+  arch: platform.arch
+});
+const archiveName = resolveArchiveName({
+  version,
+  os: platform.os,
+  arch: platform.arch
+});
+const checksumsURL = resolveChecksumsURL({
+  version
+});
+
+function log(message) {
+  process.stderr.write(`[deltascope-mcp-launcher] ${message}\n`);
+}
+
+log(`resolved DeltaScope version ${version}`);
+log(`detected platform ${platform.os}-${platform.arch}`);
+
+const binaryPath = await ensureExecutable({
+  version,
+  platform,
+  archiveURL,
+  checksumsURL,
+  downloadBinary: (destinationPath) =>
+    (async () => {
+      log(`cache miss; downloading ${archiveURL}`);
+      log(`cache target ${destinationPath}`);
+      log(`verifying archive against ${checksumsURL}`);
+      try {
+        const result = await downloadAndExtractBinary({
+          archiveURL,
+          checksumsURL,
+          archiveName,
+          destinationPath
+        });
+        log(`downloaded archive and staged native binary for ${destinationPath}`);
+        return result;
+      } catch (error) {
+        process.stderr.write(`${formatBootstrapContext({
+          version,
+          platform,
+          archiveURL,
+          destinationPath
+        })}\n`);
+        throw error;
+      }
+    })()
+});
+
+log(`launching native binary ${binaryPath}`);
+
+const child = spawnBinary(binaryPath, process.argv.slice(2), {
+  stdio: "inherit",
+  env: process.env
+});
+
+child.on("error", (error) => {
+  process.stderr.write(`deltascope-mcp launcher: ${error.message}\n`);
+  process.exit(1);
+});
+
+child.on("close", (code) => {
+  process.exit(code ?? 1);
+});

package/lib/cache.js

@@ -0,0 +1,13 @@
+import path from "node:path";
+
+export function resolveCacheRoot({ homeDir }) {
+  return path.join(homeDir, ".cache", "deltascope-mcp");
+}
+
+export function resolveCacheBinaryPath({ homeDir, version, os, arch }) {
+  return path.join(resolveCacheRoot({ homeDir }), version, `${os}-${arch}`, "deltascope-mcp");
+}
+
+export function resolveCacheMetadataPath({ homeDir, version, os, arch }) {
+  return path.join(resolveCacheRoot({ homeDir }), version, `${os}-${arch}`, "deltascope-mcp.json");
+}

package/lib/download.js

@@ -0,0 +1,96 @@
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { spawn } from "node:child_process";
+import crypto from "node:crypto";
+
+async function runTar(args) {
+  const child = spawn("tar", args, { stdio: ["ignore", "pipe", "pipe"] });
+  let stderr = "";
+  for await (const chunk of child.stderr) {
+    stderr += chunk.toString();
+  }
+
+  const exitCode = await new Promise((resolve, reject) => {
+    child.on("error", reject);
+    child.on("close", resolve);
+  });
+
+  if (exitCode !== 0) {
+    throw new Error(`tar failed: ${stderr.trim()}`);
+  }
+}
+
+function sha256(buffer) {
+  return crypto.createHash("sha256").update(buffer).digest("hex");
+}
+
+function parseChecksums(text) {
+  const map = new Map();
+  for (const rawLine of text.split(/\r?\n/)) {
+    const line = rawLine.trim();
+    if (!line) {
+      continue;
+    }
+    const match = line.match(/^([a-fA-F0-9]{64})\s+\*?(.+)$/);
+    if (!match) {
+      continue;
+    }
+    map.set(match[2].trim(), match[1].toLowerCase());
+  }
+  return map;
+}
+
+export async function downloadAndExtractBinary({
+  archiveURL,
+  checksumsURL,
+  archiveName,
+  destinationPath,
+  fetchImpl = globalThis.fetch
+}) {
+  if (typeof fetchImpl !== "function") {
+    throw new Error("fetch implementation is required");
+  }
+
+  const [archiveResponse, checksumsResponse] = await Promise.all([
+    fetchImpl(archiveURL),
+    fetchImpl(checksumsURL)
+  ]);
+
+  if (!archiveResponse.ok) {
+    throw new Error(`failed to download ${archiveURL}`);
+  }
+  if (!checksumsResponse.ok) {
+    throw new Error(`failed to download ${checksumsURL}`);
+  }
+
+  const tempDir = await fs.mkdtemp(path.join(os.tmpdir(), "deltascope-mcp-archive-"));
+  const archivePath = path.join(tempDir, "archive.tar.gz");
+  const extractDir = path.join(tempDir, "extract");
+  const archiveBuffer = Buffer.from(await archiveResponse.arrayBuffer());
+  const checksums = parseChecksums(await checksumsResponse.text());
+  const expectedChecksum = checksums.get(archiveName);
+  const actualChecksum = sha256(archiveBuffer);
+
+  try {
+    if (!expectedChecksum) {
+      throw new Error(`missing checksum for ${archiveName}`);
+    }
+    if (actualChecksum !== expectedChecksum) {
+      throw new Error(`checksum mismatch for ${archiveName}`);
+    }
+    await fs.mkdir(extractDir, { recursive: true });
+    await fs.writeFile(archivePath, archiveBuffer);
+    await runTar(["-xzf", archivePath, "-C", extractDir]);
+    await fs.mkdir(path.dirname(destinationPath), { recursive: true });
+    const tempBinaryPath = `${destinationPath}.tmp-${process.pid}`;
+    await fs.copyFile(path.join(extractDir, "deltascope-mcp"), tempBinaryPath);
+    await fs.chmod(tempBinaryPath, 0o755);
+    return {
+      binaryPath: tempBinaryPath,
+      archiveChecksum: expectedChecksum
+    };
+  } finally {
+    await fs.rm(tempDir, { recursive: true, force: true });
+  }
+}

package/lib/launcher.js

@@ -0,0 +1,150 @@
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { spawn } from "node:child_process";
+
+import { resolveCacheBinaryPath, resolveCacheMetadataPath } from "./cache.js";
+import { resolvePlatform } from "./releases.js";
+
+async function fileExists(targetPath) {
+  try {
+    await fs.access(targetPath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function readJSON(pathname) {
+  try {
+    return JSON.parse(await fs.readFile(pathname, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+async function acquireLock(lockDir, { staleLockMs = 60000, lockTimeoutMs = 10000, lockRetryDelayMs = 100 } = {}) {
+  const startedAt = Date.now();
+  for (;;) {
+    try {
+      await fs.mkdir(lockDir);
+      return;
+    } catch (error) {
+      if (error && error.code === "EEXIST") {
+        try {
+          const stat = await fs.stat(lockDir);
+          if (Date.now() - stat.mtimeMs > staleLockMs) {
+            await fs.rm(lockDir, { recursive: true, force: true });
+            continue;
+          }
+        } catch {
+          continue;
+        }
+        if (Date.now() - startedAt > lockTimeoutMs) {
+          throw new Error("timed out waiting for launcher cache lock");
+        }
+        await new Promise((resolve) => setTimeout(resolve, lockRetryDelayMs));
+        continue;
+      }
+      throw error;
+    }
+  }
+}
+
+async function releaseLock(lockDir) {
+  await fs.rm(lockDir, { recursive: true, force: true });
+}
+
+export async function ensureExecutable({
+  version,
+  homeDir = os.homedir(),
+  platform = resolvePlatform(),
+  archiveURL = "",
+  checksumsURL = "",
+  staleLockMs,
+  lockTimeoutMs,
+  lockRetryDelayMs,
+  downloadBinary
+}) {
+  const binaryPath = resolveCacheBinaryPath({
+    homeDir,
+    version,
+    os: platform.os,
+    arch: platform.arch
+  });
+  const metadataPath = resolveCacheMetadataPath({
+    homeDir,
+    version,
+    os: platform.os,
+    arch: platform.arch
+  });
+  const cacheDir = path.dirname(binaryPath);
+  const lockDir = path.join(cacheDir, ".lock");
+  const expectedMetadata = {
+    version,
+    os: platform.os,
+    arch: platform.arch,
+    archiveURL,
+    checksumsURL
+  };
+
+  const isCacheValid = async () => {
+    if (!(await fileExists(binaryPath))) {
+      return false;
+    }
+    const metadata = await readJSON(metadataPath);
+    if (!metadata) {
+      return false;
+    }
+    return Object.entries(expectedMetadata).every(([key, value]) => metadata[key] === value);
+  };
+
+  if (await isCacheValid()) {
+    return binaryPath;
+  }
+
+  if (typeof downloadBinary !== "function") {
+    throw new Error("downloadBinary is required when the DeltaScope MCP binary is not cached");
+  }
+
+  await fs.mkdir(cacheDir, { recursive: true });
+  await acquireLock(lockDir, {
+    staleLockMs,
+    lockTimeoutMs,
+    lockRetryDelayMs
+  });
+  try {
+    if (await isCacheValid()) {
+      return binaryPath;
+    }
+
+    const { binaryPath: downloadedBinaryPath, archiveChecksum } = await downloadBinary(binaryPath);
+    const tempMetadataPath = `${metadataPath}.tmp-${process.pid}`;
+    const finalMetadata = {
+      ...expectedMetadata,
+      archiveChecksum
+    };
+    await fs.writeFile(tempMetadataPath, `${JSON.stringify(finalMetadata, null, 2)}\n`);
+    await fs.rename(downloadedBinaryPath, binaryPath);
+    await fs.rename(tempMetadataPath, metadataPath);
+    return binaryPath;
+  } finally {
+    await releaseLock(lockDir);
+  }
+}
+
+export function spawnBinary(binaryPath, args = [], options = {}) {
+  return spawn(binaryPath, args, options);
+}
+
+export function formatBootstrapContext({ version, platform, archiveURL, destinationPath }) {
+  return [
+    `DeltaScope MCP launcher context:`,
+    `  version: ${version}`,
+    `  platform: ${platform.os}-${platform.arch}`,
+    `  archive: ${archiveURL}`,
+    `  cache target: ${destinationPath}`,
+    `  checksums: always verified against the official GitHub release checksums file`,
+    `  hint: if your network requires a proxy, set HTTP_PROXY / HTTPS_PROXY and NODE_USE_ENV_PROXY=1`
+  ].join("\n");
+}

package/lib/releases.js

@@ -0,0 +1,56 @@
+import os from "node:os";
+
+export function resolvePlatform({ platform = os.platform(), arch = os.arch() } = {}) {
+  const resolvedPlatform = platform === "darwin" || platform === "linux" ? platform : null;
+  if (resolvedPlatform === null) {
+    throw new Error(`unsupported platform: ${platform}`);
+  }
+
+  const resolvedArch = (() => {
+    switch (arch) {
+      case "x64":
+      case "amd64":
+        return "amd64";
+      case "arm64":
+      case "aarch64":
+        return "arm64";
+      default:
+        return null;
+    }
+  })();
+
+  if (resolvedArch === null) {
+    throw new Error(`unsupported architecture: ${arch}`);
+  }
+
+  return { os: resolvedPlatform, arch: resolvedArch };
+}
+
+export function resolveDeltaScopeVersion({ packageVersion, envVersion = "" }) {
+  const source = envVersion || packageVersion;
+  if (!source) {
+    throw new Error("could not resolve DeltaScope version");
+  }
+
+  return source.startsWith("v") ? source : `v${source}`;
+}
+
+export function resolveArchiveName({ version, os, arch }) {
+  return `deltascope_${version.replace(/^v/, "")}_${os}_${arch}.tar.gz`;
+}
+
+export function resolveChecksumsName({ version }) {
+  return `deltascope_${version.replace(/^v/, "")}_checksums.txt`;
+}
+
+export function resolveArchiveURL({ repo = "Fanduzi/DeltaScope", version, os, arch }) {
+  const baseURL = arguments[0].baseURL ?? "";
+  if (baseURL) {
+    return `${baseURL.replace(/\/$/, "")}/${version}/${resolveArchiveName({ version, os, arch })}`;
+  }
+  return `https://github.com/${repo}/releases/download/${version}/${resolveArchiveName({ version, os, arch })}`;
+}
+
+export function resolveChecksumsURL({ repo = "Fanduzi/DeltaScope", version }) {
+  return `https://github.com/${repo}/releases/download/${version}/${resolveChecksumsName({ version })}`;
+}

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@fanduzi/deltascope-mcp",
+  "version": "0.8.1",
+  "description": "Launcher package for the DeltaScope MCP stdio server",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Fanduzi/DeltaScope.git"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "bin": {
+    "deltascope-mcp": "bin/deltascope-mcp.js"
+  },
+  "files": [
+    "bin",
+    "lib",
+    "README.md"
+  ],
+  "scripts": {
+    "test": "node --test"
+  },
+  "engines": {
+    "node": ">=24"
+  },
+  "keywords": [
+    "mcp",
+    "deltascope",
+    "sql",
+    "audit"
+  ],
+  "license": "Apache-2.0"
+}