@stealthmole/mcp 0.1.11 → 0.1.13

package/bin/claude-desktop-config.mjs

@@ -27,6 +27,29 @@ const CONFIG_FILENAME = "claude_desktop_config.json";
 /** npx specifier for the retired `stealthmole.mcp` package, with or without a version range. */
 const RETIRED_PACKAGE_ARG = /^stealthmole\.mcp(@.+)?$/;
 
+/**
+ * npx specifier for either package that launches this server.
+ *
+ * Deliberately wider than {@link RETIRED_PACKAGE_ARG}: that one drives the
+ * rewrite and must not touch an entry already on the scoped package, while this
+ * one only answers "is this entry ours".
+ */
+const SERVER_PACKAGE_ARG = /^(?:@stealthmole\/mcp|stealthmole\.mcp)(@.+)?$/;
+
+/**
+ * Whether an `mcpServers` entry launches this server.
+ *
+ * Matched on `args`, not `command`: the command is `npx`, `npx.cmd`, or an
+ * absolute path depending on platform and install, while the package specifier
+ * is identical everywhere.
+ *
+ * @param {object} entry an `mcpServers` entry
+ * @returns {boolean}
+ */
+function launchesThisServer(entry) {
+  return Array.isArray(entry?.args) && entry.args.some((arg) => SERVER_PACKAGE_ARG.test(arg));
+}
+
 /**
  * Repoint an entry's npx args at `@stealthmole/mcp`.
  *
@@ -166,6 +189,21 @@ export function ensureClaudeDesktopConfig({
         return "migrated";
       }
 
+      // The customer may have registered this server by hand under a key of
+      // their own choosing. Identity is the package the entry launches, not the
+      // key it sits under — judging by key alone adds a SECOND entry, so the
+      // server runs twice, every tool shows up twice, and the entry we add
+      // carries none of their `env` (notably STEALTHMOLE_CLIENT_SECRET).
+      const foreignKey = Object.keys(servers).find((key) => launchesThisServer(servers[key]));
+      if (foreignKey) {
+        if (debug) {
+          console.error(
+            `${LOG_PREFIX} Already registered under "${foreignKey}", leaving it as is.`
+          );
+        }
+        return "unchanged";
+      }
+
       servers[SERVER_KEY] = {
         command: "npx",
         args: ["-y", `@stealthmole/mcp@^${pkgVersion}`],

package/bin/cli.mjs

@@ -7,12 +7,46 @@ import { createServer } from "net";
 import { readFileSync } from "fs";
 
 import { ensureClaudeDesktopConfig } from "./claude-desktop-config.mjs";
+import { unsupportedNodeMessage } from "./node-version-guard.mjs";
+import { migrateTokenCache } from "./token-cache-shim.mjs";
 
 // Read current package version for pinned auto-registration
 const PKG_VERSION = JSON.parse(
   readFileSync(new URL("../package.json", import.meta.url), "utf-8")
 ).version;
 
+// --help and --version come first. Both are diagnostics a customer runs to
+// report what they have installed, so nothing below may run ahead of them:
+// a fresh registration exits the process, and argv filtering rewrites
+// process.argv out from under them.
+if (process.argv.includes("--help") || process.argv.includes("-h")) {
+  console.error(
+    `@stealthmole/mcp v${PKG_VERSION}\n` +
+      "\nUsage: npx -y @stealthmole/mcp [options]\n" +
+      "\nOptions:\n" +
+      "  --port <number>           Callback port for OAuth redirect\n" +
+      "  --callback-port <number>  Alias for --port\n" +
+      "  --debug                   Enable debug logging\n" +
+      "  --help, -h                Show this help message\n" +
+      "  --version, -v             Show version number\n"
+  );
+  process.exit(0);
+}
+
+if (process.argv.includes("--version") || process.argv.includes("-v")) {
+  console.error(PKG_VERSION);
+  process.exit(0);
+}
+
+// Refuse an unsupported Node before touching anything. Registering a config
+// entry that cannot run is worse than not registering: Claude Desktop would
+// keep launching a server that crashes inside node_modules.
+const nodeProblem = unsupportedNodeMessage();
+if (nodeProblem) {
+  console.error(nodeProblem);
+  process.exit(1);
+}
+
 // Register (or migrate) the Claude Desktop entry before starting the proxy.
 // A rename keeps running: Claude Desktop launched this process under the old
 // key, so exiting would break the session the user is in right now.
@@ -36,26 +70,6 @@ const AUTH_SUCCESS_URL = "https://www.stealthmole.com/";
 const CALLBACK_HOST = "localhost";
 const DEBUG = process.argv.includes("--debug");
 
-// Handle --help and --version before argv filtering
-if (process.argv.includes("--help") || process.argv.includes("-h")) {
-  console.error(
-    `@stealthmole/mcp v${PKG_VERSION}\n` +
-      "\nUsage: npx -y @stealthmole/mcp [options]\n" +
-      "\nOptions:\n" +
-      "  --port <number>           Callback port for OAuth redirect\n" +
-      "  --callback-port <number>  Alias for --port\n" +
-      "  --debug                   Enable debug logging\n" +
-      "  --help, -h                Show this help message\n" +
-      "  --version, -v             Show version number\n"
-  );
-  process.exit(0);
-}
-
-if (process.argv.includes("--version") || process.argv.includes("-v")) {
-  console.error(PKG_VERSION);
-  process.exit(0);
-}
-
 /**
  * Find an available port not occupied by another process.
  *
@@ -223,6 +237,11 @@ process.argv.push("--host", CALLBACK_HOST);
 process.argv.push("--static-oauth-client-info", CLIENT_INFO);
 process.argv.push("--static-oauth-client-metadata", CLIENT_METADATA);
 
+// Carry a login saved by an older mcp-remote into the store the current one
+// reads. Must run before the proxy starts, otherwise it asks for a browser
+// sign-in the customer has already completed once.
+migrateTokenCache({ serverUrl: SERVER_URL, debug: DEBUG });
+
 // Suppress mcp-remote startup logs unless --debug is set.
 // Uses mcp-remote's built-in --silent flag (safer than overriding console.error).
 if (!DEBUG) {

package/bin/node-version-guard.mjs

@@ -0,0 +1,56 @@
+// Node.js version guard for the StealthMole MCP client.
+//
+// mcp-remote depends on undici, which dereferences the global `File` at require
+// time (undici/lib/web/webidl/index.js). `File` became global in Node 20, so on
+// Node 18 the proxy dies with `ReferenceError: File is not defined` and a stack
+// trace through node_modules — the customer sees a crash, not a cause.
+//
+// `engines.node` does not prevent this: npm and npx print a warning and run
+// anyway. The check has to happen at runtime.
+
+import { readFileSync } from "fs";
+
+const LOG_PREFIX = "[stealthmole-mcp]";
+
+/**
+ * Node.js version declared in `engines.node`, for the install advice.
+ *
+ * Read from package.json so the number is written once. It mirrors undici's own
+ * `engines` and is only a recommendation here — the guard below refuses strictly
+ * less, because versions between 20.0.0 and this one still run fine (measured:
+ * 20.9.0 loads undici without error).
+ */
+export const RECOMMENDED_NODE_VERSION = JSON.parse(
+  readFileSync(new URL("../package.json", import.meta.url), "utf-8")
+).engines.node.replace(/^[^\d]*/, "");
+
+/**
+ * Explain why this Node cannot run the client, or `null` when it can.
+ *
+ * Tests the missing global directly instead of comparing version numbers.
+ * A version range has to be guessed and then maintained as undici moves, and
+ * guessing it too high is the worse error: it would refuse customers who are
+ * working today. The global either exists or it does not.
+ *
+ * Returns the message rather than printing and exiting, so the decision to
+ * terminate stays with the caller and the rule stays unit-testable.
+ *
+ * @param {boolean} [hasFileGlobal] whether `File` is a global in this runtime
+ * @param {string} [current] version to name in the message
+ * @returns {string|null}
+ */
+export function unsupportedNodeMessage(
+  hasFileGlobal = typeof File !== "undefined",
+  current = process.versions.node
+) {
+  if (hasFileGlobal) {
+    return null;
+  }
+
+  return (
+    `${LOG_PREFIX} Node.js ${current} is too old: mcp-remote needs the global ` +
+    `"File", which Node.js added in version 20.\n` +
+    `${LOG_PREFIX}   Install Node.js ${RECOMMENDED_NODE_VERSION} or newer from ` +
+    `https://nodejs.org/ and restart Claude Desktop.`
+  );
+}

package/bin/token-cache-shim.mjs

@@ -0,0 +1,162 @@
+// Carry a saved OAuth login over to mcp-remote's renamed token store.
+//
+// mcp-remote 0.15 moved its token store from `~/.mcp-auth/mcp-remote-<version>/`
+// to `~/.mcp-auth/mcp-remote-v<CONFIG_STORE_VERSION>/`. Tokens written by the
+// version we shipped before (0.1.38) are therefore in a directory the current
+// one never looks at, which pushes every upgrading customer into a fresh browser
+// login. Customers who do not complete that login get no error — the proxy waits
+// for authorization indefinitely and Claude Desktop simply shows no tools.
+//
+// The store filename is `md5(serverUrl)_tokens.json` in both versions and the
+// added fields (`issuer`, `expires_at`, `requested_scope`) are optional, so
+// copying the old file across is enough: mcp-remote gets a 401 on the stale
+// access token and silently refreshes it with the Keycloak offline token.
+//
+// TEMPORARY. This couples to mcp-remote's private store layout. Delete it once
+// either is true:
+//   - mcp-remote bumps CONFIG_STORE_VERSION past 1, making the target dead, or
+//   - no customers remain on a version older than 0.1.12.
+//
+// NOTE: In MCP (Model Context Protocol), stdout is reserved for JSON-RPC messages.
+// All user-facing messages MUST use console.error (stderr), not console.log (stdout).
+
+import { readdirSync, statSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "fs";
+import { join, dirname } from "path";
+import { homedir } from "os";
+import { createHash } from "crypto";
+
+const LOG_PREFIX = "[stealthmole-mcp]";
+
+/**
+ * Store directory mcp-remote 0.15 reads.
+ *
+ * Mirrors `mcp-remote-v${CONFIG_STORE_VERSION}` in its `lib/mcp-auth-config.ts`.
+ */
+export const CONFIG_STORE_DIR = "mcp-remote-v1";
+
+/**
+ * Store directories named after an mcp-remote release, e.g. `mcp-remote-0.1.37`.
+ *
+ * Deliberately anchored on a digit: a `mcp-remote-v2` directory is a *newer*
+ * layout, and copying out of it would move tokens into a store that has been
+ * retired.
+ */
+const LEGACY_STORE_DIR = /^mcp-remote-\d/;
+
+/**
+ * Resolve the base directory holding mcp-remote's token stores.
+ *
+ * @param {Record<string, string|undefined>} [env] environment variables
+ * @param {string} [home] home directory; injectable so tests can stay hermetic
+ * @returns {string} absolute path
+ */
+export function resolveBaseDir(env = process.env, home = homedir()) {
+  return env.MCP_REMOTE_CONFIG_DIR || join(home, ".mcp-auth");
+}
+
+/**
+ * Find the legacy store holding the most recently written copy of `tokensFile`.
+ *
+ * Ordering is by the token file's own mtime rather than the directory's: the
+ * directory is touched by lock and verifier files from flows that never
+ * completed, so only the token file identifies where the customer last
+ * successfully signed in.
+ *
+ * @param {string} baseDir
+ * @param {string} tokensFile
+ * @returns {string|null} absolute path to the newest match
+ */
+function findLegacyTokens(baseDir, tokensFile) {
+  let entries;
+  try {
+    entries = readdirSync(baseDir, { withFileTypes: true });
+  } catch (err) {
+    if (err.code === "ENOENT") {
+      // mcp-remote has never run on this machine — nothing to carry over
+      return null;
+    }
+    throw err;
+  }
+
+  let newest = null;
+  let newestMtime = -Infinity;
+
+  for (const entry of entries) {
+    if (!entry.isDirectory() || !LEGACY_STORE_DIR.test(entry.name)) {
+      continue;
+    }
+
+    const candidate = join(baseDir, entry.name, tokensFile);
+    let mtimeMs;
+    try {
+      mtimeMs = statSync(candidate).mtimeMs;
+    } catch {
+      // No token file for this server in that store
+      continue;
+    }
+
+    if (mtimeMs > newestMtime) {
+      newest = candidate;
+      newestMtime = mtimeMs;
+    }
+  }
+
+  return newest;
+}
+
+/**
+ * Copy a saved login into the token store the current mcp-remote reads.
+ *
+ * Non-destructive in every direction: an existing token file is never
+ * overwritten, the legacy copy is never deleted, and a hash mismatch or an
+ * unreadable store leaves the normal browser sign-in as the fallback.
+ *
+ * Outcomes:
+ * - `"copied"`  — a legacy login was carried over
+ * - `"present"` — the current store already has a token file
+ * - `"none"`    — no legacy login found for this server
+ * - `"failed"`  — the store could not be read or written; non-fatal
+ *
+ * @param {object} options
+ * @param {string} options.serverUrl MCP server URL the tokens belong to
+ * @param {string} [options.baseDir] override the resolved store base directory
+ * @param {boolean} [options.debug] include the error message on failure
+ * @returns {"copied"|"present"|"none"|"failed"}
+ */
+export function migrateTokenCache({ serverUrl, baseDir = resolveBaseDir(), debug = false }) {
+  try {
+    const serverUrlHash = createHash("md5").update(serverUrl).digest("hex");
+    const tokensFile = `${serverUrlHash}_tokens.json`;
+    const target = join(baseDir, CONFIG_STORE_DIR, tokensFile);
+
+    if (existsSync(target)) {
+      return "present";
+    }
+
+    const source = findLegacyTokens(baseDir, tokensFile);
+    if (!source) {
+      return "none";
+    }
+
+    // mcp-remote creates this itself, but only after the point where it would
+    // already have asked for a browser login — upgrades straight from 0.1.8
+    // reach here with no store at all.
+    mkdirSync(dirname(target), { recursive: true, mode: 0o700 });
+
+    // Read-then-write rather than copyFile: the source mode is whatever the
+    // older version left behind, and a refresh token must stay owner-only.
+    writeFileSync(target, readFileSync(source), { mode: 0o600 });
+
+    // Logged unconditionally, not just under --debug: support needs to be able
+    // to tell "the shim ran" apart from "the shim found nothing".
+    console.error(`${LOG_PREFIX} ✔ Restored your saved sign-in from a previous version.`);
+    return "copied";
+  } catch (err) {
+    // Non-fatal: the customer signs in through the browser as before
+    if (debug) {
+      console.error(`${LOG_PREFIX} ⚠ Could not carry over the saved sign-in: ${err.message}`);
+      console.error(err.stack);
+    }
+    return "failed";
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stealthmole/mcp",
-  "version": "0.1.11",
+  "version": "0.1.13",
   "description": "StealthMole Threat Intelligence MCP client - connect Claude Desktop, Cursor, and other MCP clients to StealthMole API",
   "bin": {
     "stealthmole-mcp": "bin/cli.mjs"