@stealthmole/mcp 0.1.7 → 0.1.9

package/README.md

@@ -1,22 +1,176 @@
-# @stealthmole/mcp
+# StealthMole MCP
 
-> Alias package for [`stealthmole.mcp`](https://www.npmjs.com/package/stealthmole.mcp)
-
-This package provides the **same functionality** as `stealthmole.mcp` under an alternative name.
-Use whichever name you prefer — both are maintained in sync.
+Connect [Claude Desktop](https://claude.ai/download), [Claude Code](https://docs.anthropic.com/en/docs/claude-code), [Cursor](https://cursor.sh), [Windsurf](https://codeium.com/windsurf), and other MCP clients to the [StealthMole](https://www.stealthmole.com) Threat Intelligence API.
 
 ## Quick Start
 
+### Claude Desktop
+
+Simply run the following command — it will automatically register the MCP server in your Claude Desktop configuration:
+
+```bash
+npx -y @stealthmole/mcp
+```
+
+Or manually add to your config file:
+
+```json
+{
+  "mcpServers": {
+    "stealthmole": {
+      "command": "npx",
+      "args": ["-y", "@stealthmole/mcp"],
+      "env": {
+        "STEALTHMOLE_CLIENT_SECRET": "<your-client-secret>"
+      }
+    }
+  }
+}
+```
+
+### Claude Code
+
+Add to your project's `.mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "stealthmole": {
+      "command": "npx",
+      "args": ["-y", "@stealthmole/mcp"],
+      "env": {
+        "STEALTHMOLE_CLIENT_SECRET": "<your-client-secret>"
+      }
+    }
+  }
+}
+```
+
+### Other MCP Clients
+
+Add the configuration above to your MCP client's config file:
+
+| Client | Config File |
+|--------|-------------|
+| Claude Desktop (macOS) | `~/Library/Application Support/Claude/claude_desktop_config.json` |
+| Claude Desktop (Windows) | `%APPDATA%\Claude\claude_desktop_config.json` |
+| Claude Desktop (Linux) | `~/.config/Claude/claude_desktop_config.json` |
+| Cursor | `.cursor/mcp.json` in your project root |
+| Windsurf | `~/.codeium/windsurf/mcp_config.json` |
+
+## How It Works
+
+1. Run `npx -y @stealthmole/mcp` (or your MCP client starts it automatically)
+2. On first run, it auto-registers itself in Claude Desktop's config (if not already registered)
+3. A browser window opens for StealthMole authentication via OAuth 2.1
+4. After login the browser is redirected to [stealthmole.com](https://www.stealthmole.com/), and the OAuth token is cached in `~/.mcp-auth/`
+5. The stdio-to-HTTP bridge connects your MCP client to the remote server
+
+## Requirements
+
+- **Node.js 20.18.1+**
+- A StealthMole account with API access
+- `STEALTHMOLE_CLIENT_SECRET` environment variable (optional, for confidential client flow)
+
+## Available Tools
+
+Once connected, your MCP client will have access to the following tools:
+
+### Dark Web Tracker
+
+| Tool | Description |
+|------|-------------|
+| `dark_web_search` | Search dark web content by indicator (domain, email, keyword, etc.) |
+| `dark_web_targets` | Get available search targets for a given indicator |
+| `download_dark_web_file` | Download a file by SHA256 hash |
+
+### Telegram Tracker
+
+| Tool | Description |
+|------|-------------|
+| `telegram_search` | Search Telegram content by indicator |
+| `telegram_targets` | Get available search targets for a given indicator |
+| `download_telegram_file` | Download a file by SHA256 hash |
+
+### Credential Lookout
+
+| Tool | Description |
+|------|-------------|
+| `credential_search` | Search for leaked credentials |
+| `credential_export` | Export leaked credentials to CSV/JSON |
+
+### Compromised Dataset
+
+| Tool | Description |
+|------|-------------|
+| `compromised_dataset_search` | Search compromised data with host/URL info |
+| `compromised_dataset_node` | Get detailed node information |
+| `compromised_dataset_export` | Export compromised data to CSV/JSON |
+
+### Combo Binder
+
+| Tool | Description |
+|------|-------------|
+| `combo_binder_search` | Search leaked ID/Password combinations |
+| `combo_binder_export` | Export combo data to CSV/JSON |
+
+### ULP Binder
+
+| Tool | Description |
+|------|-------------|
+| `ulp_binder_search` | Search URL-Login-Password combinations |
+| `ulp_binder_export` | Export ULP data to CSV/JSON |
+
+### Monitoring
+
+| Tool | Description |
+|------|-------------|
+| `ransomware_monitoring_search` | Track ransomware activities and attack groups |
+| `government_monitoring_search` | Monitor government sector threats |
+| `leaked_monitoring_search` | Monitor enterprise data leaks |
+
+### Utilities
+
+| Tool | Description |
+|------|-------------|
+| `node_details` | Get detailed information about a specific node from any service |
+| `search_pagination` | Paginate through large result sets (DT/TT) |
+| `search_targets` | Get available targets for any service and indicator |
+| `api_usage` | Check API usage quotas by service |
+
+## CLI Options
+
 ```bash
-npx @stealthmole/mcp
+npx -y @stealthmole/mcp --debug                  # Enable debug logging
+npx -y @stealthmole/mcp --port 3335              # Use custom callback port
+npx -y @stealthmole/mcp --callback-port 3335     # Alias for --port
+npx -y @stealthmole/mcp --help                   # Show help message
+npx -y @stealthmole/mcp --version                # Show version number
 ```
 
-Or install globally:
+> A free callback port is automatically selected if `--port` is not specified.
+> Only the flags listed above are supported; other flags are silently ignored.
+
+## Troubleshooting
+
+### Reset authentication
+
+Delete the cached token directory `~/.mcp-auth/`, then restart your MCP client to re-authenticate.
+
+### Connection issues
+
+1. Ensure Node.js 20.18.1+ is installed: `node --version`
+2. Try with debug logging: `npx -y @stealthmole/mcp --debug`
+3. Check that your StealthMole account has API access
+
+### Port conflicts
+
+If you see "Port is already in use" errors, the client will automatically retry with a different port. You can also specify a port manually:
 
 ```bash
-npm install -g @stealthmole/mcp
+npx -y @stealthmole/mcp --port 3335
 ```
 
-## Documentation
+## License
 
-See the main package for full documentation: [stealthmole.mcp](https://www.npmjs.com/package/stealthmole.mcp)
+MIT

package/bin/cli.mjs

@@ -1,8 +1,337 @@
 #!/usr/bin/env node
 
+// 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 { createServer } from "net";
+import {
+  readFileSync,
+  writeFileSync,
+  mkdirSync,
+  renameSync,
+  unlinkSync,
+} from "fs";
+import { join } from "path";
+import { platform, homedir } from "os";
+
+// 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();
+
+// First run after registration: exit without starting the proxy
+if (newlyRegistered) {
+  process.exit(0);
+}
+
+const SERVER_URL = "https://mcp.stealthmole.com/mcp";
+// OAuth 인증 완료 후 브라우저가 이동할 주소.
+// mcp-remote 가 303 으로 리다이렉트하므로 "이 창을 닫으세요" 안내가 노출되지 않음.
+const AUTH_SUCCESS_URL = "https://www.stealthmole.com/";
+// mcp-remote 0.15 부터 win32 기본 콜백 호스트가 127.0.0.1 로 바뀌었다.
+// Keycloak stealthmole_front 의 Valid Redirect URIs 가 localhost 기준이므로
+// 플랫폼 무관하게 localhost 로 고정해 redirect_uri 를 기존과 동일하게 유지한다.
+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);
+}
+
 /**
- * Thin wrapper that delegates to the main stealthmole.mcp package.
- * This allows `npx stealthmole-mcp` to work as an alias for `npx stealthmole.mcp`.
+ * Find an available port not occupied by another process.
+ *
+ * Step 1: Bind to port 0 — OS assigns a candidate port
+ * Step 2: Close candidate, rebind explicitly to verify availability
+ *         (SO_REUSEADDR can cause listen(0) to return an in-use port)
+ * Step 3: On verification failure, retry with a new candidate (up to maxAttempts)
+ *
+ * The verified guard server is returned open to hold the port.
  */
+function findFreePort(maxAttempts = 20) {
+  let attempts = 0;
+
+  function tryOnce() {
+    return new Promise((resolve, reject) => {
+      // Step 1: Get a candidate port from the OS
+      const probe = createServer();
+      probe.listen(0, "127.0.0.1", () => {
+        const { port } = probe.address();
+        probe.close(() => {
+          // Step 2: Verify by explicitly rebinding to the same port
+          const guard = createServer();
+          guard.once("error", (err) => {
+            // Port occupied by another process — retry
+            attempts++;
+            if (DEBUG) {
+              console.error(
+                `Port ${port} is occupied by another process, retrying... (${attempts}/${maxAttempts})`
+              );
+            }
+            if (attempts >= maxAttempts) {
+              reject(
+                new Error(
+                  `Could not find a free port after ${maxAttempts} attempts`
+                )
+              );
+            } else {
+              resolve(tryOnce());
+            }
+          });
+          guard.listen(port, "127.0.0.1", () => {
+            // Port confirmed free — return with guard server still open
+            resolve({ port, server: guard });
+          });
+        });
+      });
+      probe.on("error", (err) => {
+        attempts++;
+        if (attempts >= maxAttempts) {
+          reject(err);
+        } else {
+          resolve(tryOnce());
+        }
+      });
+    });
+  }
+
+  return tryOnce();
+}
+
+// Show user-friendly message for EADDRINUSE instead of a stack trace
+process.on("uncaughtException", (err) => {
+  if (err.code === "EADDRINUSE") {
+    console.error(
+      `[stealthmole-mcp] Port ${err.port ?? ""} is already in use. ` +
+        "Retrying should resolve this. " +
+        "To use a specific port: npx -y @stealthmole/mcp --port <number>"
+    );
+    process.exit(1);
+  }
+  // Re-throwing inside uncaughtException causes undefined behavior in Node.js.
+  // Log and exit instead.
+  console.error("[stealthmole-mcp] Unexpected error:", err);
+  process.exit(1);
+});
+
+const clientInfo = {
+  client_id: "stealthmole_front",
+  redirect_uris: ["http://127.0.0.1"],
+};
+if (process.env.STEALTHMOLE_CLIENT_SECRET) {
+  clientInfo.client_secret = process.env.STEALTHMOLE_CLIENT_SECRET;
+}
+const CLIENT_INFO = JSON.stringify(clientInfo);
+
+// Inline Keycloak OIDC metadata — includes offline_access for token refresh support
+// scope (string) controls actual scope sent to Keycloak via mcp-remote's getEffectiveScope()
+// scopes_supported (array) is declarative only — not used by mcp-remote for scope resolution
+const CLIENT_METADATA = JSON.stringify({
+  issuer: "https://xoxo.stealthmole.com/auth/realms/stealthmole",
+  authorization_endpoint:
+    "https://xoxo.stealthmole.com/auth/realms/stealthmole/protocol/openid-connect/auth",
+  token_endpoint:
+    "https://xoxo.stealthmole.com/auth/realms/stealthmole/protocol/openid-connect/token",
+  registration_endpoint:
+    "https://xoxo.stealthmole.com/auth/realms/stealthmole/clients-registrations/openid-connect",
+  jwks_uri:
+    "https://xoxo.stealthmole.com/auth/realms/stealthmole/protocol/openid-connect/certs",
+  scopes_supported: ["openid", "offline_access"],
+  response_types_supported: ["code"],
+  code_challenge_methods_supported: ["S256"],
+  token_endpoint_auth_methods_supported: [
+    "client_secret_basic",
+    "client_secret_post",
+    "none",
+  ],
+  scope: "openid offline_access",
+});
+
+// Extract only allowed flags and discard the rest
+// Prevents injection of unverified flags like --allow-http or --header
+const ALLOWED_FLAGS = new Set(["--port", "--callback-port", "--debug"]);
+const VALUE_FLAGS = new Set(["--port", "--callback-port"]);
+const filteredArgs = [];
+// mcp-remote accepts the callback port ONLY as a positional argument
+// (`<server-url> [callback-port]`), so the flag value is held here and injected
+// as a positional below. Forwarding `--port` itself would be silently ignored.
+let requestedPort = null;
+{
+  const rawArgs = process.argv.slice(2);
+  for (let i = 0; i < rawArgs.length; i++) {
+    if (rawArgs[i].startsWith("--")) {
+      if (ALLOWED_FLAGS.has(rawArgs[i])) {
+        if (VALUE_FLAGS.has(rawArgs[i]) && i + 1 < rawArgs.length) {
+          const val = rawArgs[i + 1];
+          const port = Number(val);
+          // Reject flag-like values and invalid port ranges
+          if (val.startsWith("--") || !Number.isInteger(port) || port < 1 || port > 65535) {
+            i++;
+            continue;
+          }
+          requestedPort = port;
+          i++;
+        } else {
+          filteredArgs.push(rawArgs[i]);
+        }
+      }
+      // Unknown flags are silently ignored
+    }
+  }
+}
+process.argv.length = 2;
+process.argv.push(...filteredArgs);
+
+// Inject server URL as the first positional argument for mcp-remote
+process.argv.splice(2, 0, SERVER_URL);
+
+// If no port was specified, auto-discover a free port.
+// The guard server holds the port until mcp-remote is ready to bind.
+let guardServer = null;
+if (requestedPort === null) {
+  const { port, server } = await findFreePort();
+  guardServer = server;
+  requestedPort = port;
+  if (DEBUG) {
+    console.error(`Using automatically selected callback port: ${requestedPort}`);
+  }
+}
+
+// Second positional argument: the callback port
+process.argv.splice(3, 0, String(requestedPort));
+
+process.argv.push("--auth-success-url", AUTH_SUCCESS_URL);
+process.argv.push("--host", CALLBACK_HOST);
+process.argv.push("--static-oauth-client-info", CLIENT_INFO);
+process.argv.push("--static-oauth-client-metadata", CLIENT_METADATA);
+
+// Suppress mcp-remote startup logs unless --debug is set.
+// Uses mcp-remote's built-in --silent flag (safer than overriding console.error).
+if (!DEBUG) {
+  process.argv.push("--silent");
+}
+
+// Release the guard server and immediately start mcp-remote to minimize the TOCTOU window.
+// NOTE: mcp-remote binds the port itself, so the guard must be released first.
+// This brief TOCTOU window is an architectural constraint of mcp-remote.
+if (guardServer) {
+  await new Promise((resolve) => guardServer.close(resolve));
+}
 
-import "stealthmole.mcp/bin/cli.mjs";
+await import("mcp-remote/dist/proxy.js");

package/package.json

@@ -1,10 +1,9 @@
 {
   "name": "@stealthmole/mcp",
-  "version": "0.1.7",
-  "description": "StealthMole Threat Intelligence MCP client — alias package for stealthmole.mcp",
+  "version": "0.1.9",
+  "description": "StealthMole Threat Intelligence MCP client - connect Claude Desktop, Cursor, and other MCP clients to StealthMole API",
   "bin": {
-    "stealthmole-mcp": "./bin/cli.mjs",
-    "stealthmole.mcp": "./bin/cli.mjs"
+    "stealthmole-mcp": "bin/cli.mjs"
   },
   "type": "module",
   "license": "MIT",
@@ -13,10 +12,10 @@
     "bin/"
   ],
   "dependencies": {
-    "stealthmole.mcp": "0.1.7"
+    "mcp-remote": "0.15.1"
   },
   "engines": {
-    "node": ">=18.0.0"
+    "node": ">=20.18.1"
   },
   "keywords": [
     "mcp",