@stealthmole/mcp 0.1.10 → 0.1.12

package/bin/claude-desktop-config.mjs

@@ -0,0 +1,201 @@
+// Claude Desktop config registration for the StealthMole MCP server.
+//
+// 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 { readFileSync, writeFileSync, mkdirSync, renameSync, unlinkSync } from "fs";
+import { join, dirname } from "path";
+import { platform, homedir } from "os";
+
+const LOG_PREFIX = "[stealthmole-mcp]";
+
+/** Key this server is registered under in `mcpServers`. */
+export const SERVER_KEY = "stealthmole-mcp";
+
+/**
+ * Keys this server used to be registered under.
+ *
+ * `stealthmole.mcp` mirrored the npm package of the same name, which has since
+ * been deprecated in favour of `@stealthmole/mcp`. A legacy entry is renamed
+ * rather than left in place, otherwise the user ends up running the same server
+ * twice and sees every tool duplicated.
+ */
+export const LEGACY_SERVER_KEYS = ["stealthmole.mcp"];
+
+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(@.+)?$/;
+
+/**
+ * Repoint an entry's npx args at `@stealthmole/mcp`.
+ *
+ * A hand-written entry may still launch the retired `stealthmole.mcp` wrapper,
+ * which pins the user to whatever `@stealthmole/mcp` version that wrapper
+ * depends on. Only the package specifier is swapped — the user's own flags and
+ * `env` are left alone.
+ *
+ * @param {object} entry an `mcpServers` entry
+ * @param {string} pkgVersion version to pin
+ * @returns {object} the entry, with args repointed when needed
+ */
+function repointRetiredPackage(entry, pkgVersion) {
+  if (!Array.isArray(entry?.args)) {
+    return entry;
+  }
+
+  const args = entry.args.map((arg) =>
+    RETIRED_PACKAGE_ARG.test(arg) ? `@stealthmole/mcp@^${pkgVersion}` : arg
+  );
+
+  return args.some((arg, i) => arg !== entry.args[i]) ? { ...entry, args } : entry;
+}
+
+/**
+ * Resolve Claude Desktop's config file path for the current platform.
+ *
+ * @param {string} [os] platform identifier, as returned by `os.platform()`
+ * @param {Record<string, string|undefined>} [env] environment variables
+ * @param {string} [home] home directory; injectable so tests can stay hermetic
+ * @returns {string|null} absolute path, or null when it cannot be determined
+ */
+export function resolveConfigPath(os = platform(), env = process.env, home = homedir()) {
+  let configDir;
+
+  if (os === "darwin") {
+    configDir = join(home, "Library", "Application Support", "Claude");
+  } else if (os === "win32") {
+    if (!env.APPDATA) {
+      return null;
+    }
+    configDir = join(env.APPDATA, "Claude");
+  } else {
+    // Linux: use XDG_CONFIG_HOME or fall back to ~/.config
+    configDir = join(env.XDG_CONFIG_HOME || join(home, ".config"), "Claude");
+  }
+
+  return join(configDir, CONFIG_FILENAME);
+}
+
+/**
+ * Write `config` to `configPath` atomically.
+ *
+ * Writes to a sibling temp file then renames, so a concurrent run can never
+ * observe (or be truncated to) a half-written config.
+ *
+ * @param {string} configPath
+ * @param {object} config
+ */
+function writeConfigAtomically(configPath, config) {
+  // Owner-only permissions: the config may hold a client secret
+  mkdirSync(dirname(configPath), { recursive: true, mode: 0o700 });
+
+  const tmpPath = configPath + ".tmp";
+  try {
+    writeFileSync(tmpPath, JSON.stringify(config, null, 2) + "\n", {
+      encoding: "utf-8",
+      mode: 0o600,
+    });
+    renameSync(tmpPath, configPath);
+  } catch (writeErr) {
+    try {
+      unlinkSync(tmpPath);
+    } catch {
+      /* ignore cleanup failure */
+    }
+    throw writeErr;
+  }
+}
+
+/**
+ * Ensure this server is registered in Claude Desktop under {@link SERVER_KEY}.
+ *
+ * Outcomes:
+ * - `"unchanged"` — already registered correctly, config untouched
+ * - `"migrated"`  — a legacy key was renamed; the caller should keep running so
+ *                   the current session (launched under the old key) still works
+ * - `"registered"` — newly added; the caller should exit and ask for a restart
+ * - `"failed"`    — config could not be read or written; non-fatal
+ *
+ * @param {object} options
+ * @param {string} options.pkgVersion version to pin in the npx args
+ * @param {boolean} [options.debug] include the error message on failure
+ * @param {string|null} [options.configPath] override the resolved config path
+ * @returns {"unchanged"|"migrated"|"registered"|"failed"}
+ */
+export function ensureClaudeDesktopConfig({
+  pkgVersion,
+  debug = false,
+  configPath = resolveConfigPath(),
+}) {
+  if (!configPath) {
+    console.error(`${LOG_PREFIX} Could not determine the Claude Desktop config path, skipping registration.`);
+    return "failed";
+  }
+
+  try {
+    let config;
+    try {
+      config = JSON.parse(readFileSync(configPath, "utf-8"));
+    } catch {
+      // File missing or invalid JSON — start fresh
+      config = {};
+    }
+
+    if (!config.mcpServers) {
+      config.mcpServers = {};
+    }
+
+    const servers = config.mcpServers;
+    const staleKeys = LEGACY_SERVER_KEYS.filter((key) => key in servers);
+
+    if (staleKeys.length === 0) {
+      const current = servers[SERVER_KEY];
+      if (current) {
+        // The key may be current while the args still launch the retired wrapper
+        const repointed = repointRetiredPackage(current, pkgVersion);
+        if (repointed === current) {
+          return "unchanged";
+        }
+
+        servers[SERVER_KEY] = repointed;
+        writeConfigAtomically(configPath, config);
+
+        console.error(`\n${LOG_PREFIX} ✔ Repointed "${SERVER_KEY}" at @stealthmole/mcp in Claude Desktop settings.`);
+        console.error(`${LOG_PREFIX}   Restart Claude Desktop when convenient; this session keeps working.\n`);
+        return "migrated";
+      }
+
+      servers[SERVER_KEY] = {
+        command: "npx",
+        args: ["-y", `@stealthmole/mcp@^${pkgVersion}`],
+      };
+      writeConfigAtomically(configPath, config);
+
+      console.error(`\n${LOG_PREFIX} ✔ Registered ${SERVER_KEY} in Claude Desktop settings.`);
+      console.error(`${LOG_PREFIX}   Please restart Claude Desktop to apply the changes.\n`);
+      return "registered";
+    }
+
+    // Carry the legacy entry over so user customisation (env, extra args)
+    // survives the rename. An entry already under SERVER_KEY wins.
+    for (const key of staleKeys) {
+      servers[SERVER_KEY] ??= repointRetiredPackage(servers[key], pkgVersion);
+      delete servers[key];
+    }
+    writeConfigAtomically(configPath, config);
+
+    console.error(`\n${LOG_PREFIX} ✔ Renamed "${staleKeys.join('", "')}" to "${SERVER_KEY}" in Claude Desktop settings.`);
+    console.error(`${LOG_PREFIX}   Restart Claude Desktop when convenient; this session keeps working.\n`);
+    return "migrated";
+  } catch (err) {
+    // Config write failed — warn and let the caller continue normal execution
+    if (debug) {
+      console.error(`${LOG_PREFIX} ⚠ Failed to update Claude Desktop settings: ${err.message}`);
+      console.error(err.stack);
+    } else {
+      console.error(`${LOG_PREFIX} ⚠ Failed to update Claude Desktop settings.`);
+    }
+    return "failed";
+  }
+}

package/bin/cli.mjs

@@ -4,123 +4,26 @@
 // All user-facing messages MUST use console.error (stderr), not console.log (stdout).
 
 import { createServer } from "net";
-import {
-  readFileSync,
-  writeFileSync,
-  mkdirSync,
-  renameSync,
-  unlinkSync,
-} from "fs";
-import { join } from "path";
-import { platform, homedir } from "os";
+import { readFileSync } from "fs";
+
+import { ensureClaudeDesktopConfig } from "./claude-desktop-config.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;
 
-/**
- * Auto-register the StealthMole MCP server in Claude Desktop's claude_desktop_config.json
- * if not already present. Returns true if newly registered, false otherwise.
- */
-function ensureClaudeDesktopConfig() {
-  try {
-    const os = platform();
-    let configDir;
-
-    if (os === "darwin") {
-      configDir = join(
-        homedir(),
-        "Library",
-        "Application Support",
-        "Claude"
-      );
-    } else if (os === "win32") {
-      if (!process.env.APPDATA) {
-        console.error(
-          "[stealthmole-mcp] APPDATA environment variable not set, skipping config registration."
-        );
-        return false;
-      }
-      configDir = join(process.env.APPDATA, "Claude");
-    } else {
-      // Linux: use XDG_CONFIG_HOME or fall back to ~/.config
-      configDir = join(
-        process.env.XDG_CONFIG_HOME || join(homedir(), ".config"),
-        "Claude"
-      );
-    }
-
-    const configPath = join(configDir, "claude_desktop_config.json");
-
-    let config;
-    try {
-      config = JSON.parse(readFileSync(configPath, "utf-8"));
-    } catch {
-      // File missing or invalid JSON — start fresh
-      config = {};
-    }
-
-    if (!config.mcpServers) {
-      config.mcpServers = {};
-    }
-
-    // Already registered — nothing to do
-    if (config.mcpServers["stealthmole.mcp"]) {
-      return false;
-    }
-
-    config.mcpServers["stealthmole.mcp"] = {
-      command: "npx",
-      args: ["-y", `@stealthmole/mcp@^${PKG_VERSION}`],
-    };
-
-    // Create directory with owner-only permissions if it doesn't exist
-    mkdirSync(configDir, { recursive: true, mode: 0o700 });
-
-    // Atomic write: write to temp file then rename to prevent data loss on concurrent runs
-    const tmpPath = configPath + ".tmp";
-    try {
-      writeFileSync(tmpPath, JSON.stringify(config, null, 2) + "\n", {
-        encoding: "utf-8",
-        mode: 0o600,
-      });
-      renameSync(tmpPath, configPath);
-    } catch (writeErr) {
-      try {
-        unlinkSync(tmpPath);
-      } catch {
-        /* ignore cleanup failure */
-      }
-      throw writeErr;
-    }
-
-    console.error(
-      "\n[stealthmole-mcp] ✔ Registered stealthmole.mcp in Claude Desktop settings."
-    );
-    console.error(
-      "[stealthmole-mcp]   Please restart Claude Desktop to apply the changes.\n"
-    );
-    return true;
-  } catch (err) {
-    // Config write failed — warn and continue normal execution
-    if (process.argv.includes("--debug")) {
-      console.error(
-        `[stealthmole-mcp] ⚠ Failed to auto-register in Claude Desktop settings: ${err.message}`
-      );
-    } else {
-      console.error(
-        "[stealthmole-mcp] ⚠ Failed to auto-register in Claude Desktop settings."
-      );
-    }
-    return false;
-  }
-}
-
-const newlyRegistered = ensureClaudeDesktopConfig();
+// 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.
+const configStatus = ensureClaudeDesktopConfig({
+  pkgVersion: PKG_VERSION,
+  debug: process.argv.includes("--debug"),
+});
 
-// First run after registration: exit without starting the proxy
-if (newlyRegistered) {
+// First run after a fresh registration: exit without starting the proxy
+if (configStatus === "registered") {
   process.exit(0);
 }
 
@@ -321,6 +224,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/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.10",
+  "version": "0.1.12",
   "description": "StealthMole Threat Intelligence MCP client - connect Claude Desktop, Cursor, and other MCP clients to StealthMole API",
   "bin": {
     "stealthmole-mcp": "bin/cli.mjs"