@stealthmole/mcp 0.1.12 → 0.1.14

package/README.md

@@ -4,6 +4,16 @@ Connect [Claude Desktop](https://claude.ai/download), [Claude Code](https://docs
 
 ## Quick Start
 
+### All MCP clients at once
+
+Register StealthMole in every MCP client installed on this machine (Claude Desktop, Claude Code, Cursor, Codex, VS Code, Windsurf, and more):
+
+```bash
+npx -y @stealthmole/mcp install
+```
+
+Pick clients with `-a` (repeatable), e.g. `npx -y @stealthmole/mcp install -a cursor -a codex`. Run `npx -y @stealthmole/mcp install --help` for the full client list. A client that already runs StealthMole is left unchanged, so running it again is safe. Restart your clients afterwards.
+
 ### Claude Desktop
 
 Simply run the following command — it will automatically register the MCP server in your Claude Desktop configuration:

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}
+ */
+export 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,6 +7,7 @@ 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
@@ -14,6 +15,53 @@ const PKG_VERSION = JSON.parse(
   readFileSync(new URL("../package.json", import.meta.url), "utf-8")
 ).version;
 
+// `install` owns everything after it on the command line (-a <agent>, its own
+// --help), so it is routed before the server's flags are read. Loaded lazily:
+// the MCP server launch path never imports add-mcp.
+if (process.argv[2] === "install") {
+  const installNodeProblem = unsupportedNodeMessage();
+  if (installNodeProblem) {
+    // Registering an entry this Node cannot run is worse than not registering.
+    console.error(installNodeProblem);
+    process.exit(1);
+  }
+  const { install } = await import("./install.mjs");
+  process.exit(await install({ pkgVersion: PKG_VERSION, args: process.argv.slice(3) }));
+}
+
+// --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" +
+      "       npx -y @stealthmole/mcp install [-a <agent>]...   Register in MCP clients\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.
@@ -37,26 +85,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.
  *

package/bin/install.mjs

@@ -0,0 +1,94 @@
+// `npx -y @stealthmole/mcp install [-a <agent>]...` — register this server in
+// every MCP client on the machine (Claude Desktop, Claude Code, Cursor, Codex, …)
+// through add-mcp's library, which knows each client's config path and format.
+//
+//   chosen agents ──▶ listInstalledServers ──┬─ already launches us ─▶ skip
+//   (-a, or all detected)                    └─ not yet ─────────────▶ upsertServer
+//
+// Skipping is the point: add-mcp's own CLI overwrites a same-named entry (the
+// customer's `env` is lost) and adds a second one under a new name (every tool
+// shows up twice). Identity is the package an entry launches, as in
+// claude-desktop-config.mjs.
+
+import {
+  detectGlobalAgents,
+  getAgentTypes,
+  listInstalledServers,
+  upsertServer,
+} from "add-mcp";
+
+import { SERVER_KEY, launchesThisServer } from "./claude-desktop-config.mjs";
+
+const LOG_PREFIX = "[stealthmole-mcp]";
+const AGENT_FLAGS = new Set(["-a", "--agent"]);
+
+const USAGE =
+  "Usage: npx -y @stealthmole/mcp install [-a <agent>]...\n" +
+  "\nRegisters StealthMole MCP in every detected MCP client, or only in the\n" +
+  "clients named with -a. Clients that already run it are left unchanged.\n" +
+  `\nAgents: ${getAgentTypes().join(", ")}\n`;
+
+/**
+ * Collect `-a <agent>` / `--agent <agent>` values.
+ *
+ * @param {string[]} args argv after `install`
+ * @returns {string[]}
+ */
+export function parseAgents(args) {
+  return args.flatMap((arg, i) => (AGENT_FLAGS.has(arg) && args[i + 1] ? [args[i + 1]] : []));
+}
+
+/**
+ * Register this server in each chosen agent's global config.
+ *
+ * @param {{pkgVersion: string, args: string[]}} options
+ * @returns {Promise<number>} process exit code
+ */
+export async function install({ pkgVersion, args }) {
+  if (args.includes("--help") || args.includes("-h")) {
+    console.error(USAGE);
+    return 0;
+  }
+
+  const known = new Set(getAgentTypes());
+  const requested = parseAgents(args);
+  const unknown = requested.filter((agent) => !known.has(agent));
+  if (unknown.length) {
+    console.error(`${LOG_PREFIX} Unknown agent: ${unknown.join(", ")}\n\n${USAGE}`);
+    return 1;
+  }
+
+  const targets = requested.length ? requested : await detectGlobalAgents();
+  if (!targets.length) {
+    console.error(`${LOG_PREFIX} No MCP clients found. Name one with -a <agent>.\n\n${USAGE}`);
+    return 1;
+  }
+
+  const entry = { command: "npx", args: ["-y", `@stealthmole/mcp@^${pkgVersion}`] };
+  let failures = 0;
+  let registered = 0;
+  for (const agent of await listInstalledServers({ global: true, agents: targets })) {
+    const label = `${agent.displayName} (${agent.configPath})`;
+    if (agent.error) {
+      failures += 1;
+      console.error(`${LOG_PREFIX} ✘ ${label}: ${agent.error}`);
+      continue;
+    }
+    const existing = agent.servers.find((server) => launchesThisServer(server.config));
+    if (existing) {
+      console.error(`${LOG_PREFIX} • ${label}: already registered as "${existing.serverName}"`);
+      continue;
+    }
+    const result = upsertServer(agent.agentType, SERVER_KEY, entry, { local: false });
+    if (result.success) {
+      registered += 1;
+      console.error(`${LOG_PREFIX} ✔ ${label}: registered "${SERVER_KEY}"`);
+    } else {
+      failures += 1;
+      console.error(`${LOG_PREFIX} ✘ ${label}: ${result.error}`);
+    }
+  }
+
+  if (registered) console.error(`\n${LOG_PREFIX} Restart your MCP clients to load StealthMole.`);
+  return failures ? 1 : 0;
+}

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stealthmole/mcp",
-  "version": "0.1.12",
+  "version": "0.1.14",
   "description": "StealthMole Threat Intelligence MCP client - connect Claude Desktop, Cursor, and other MCP clients to StealthMole API",
   "bin": {
     "stealthmole-mcp": "bin/cli.mjs"
@@ -12,6 +12,7 @@
     "bin/"
   ],
   "dependencies": {
+    "add-mcp": "2.6.1",
     "mcp-remote": "0.15.1"
   },
   "engines": {