@stealthmole/mcp 0.1.8 → 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

@@ -20,7 +20,7 @@ const PKG_VERSION = JSON.parse(
 ).version;
 
 /**
- * Auto-register stealthmole.mcp in Claude Desktop's claude_desktop_config.json
+ * 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() {
@@ -38,7 +38,7 @@ function ensureClaudeDesktopConfig() {
     } else if (os === "win32") {
       if (!process.env.APPDATA) {
         console.error(
-          "[stealthmole.mcp] APPDATA environment variable not set, skipping config registration."
+          "[stealthmole-mcp] APPDATA environment variable not set, skipping config registration."
         );
         return false;
       }
@@ -96,21 +96,21 @@ function ensureClaudeDesktopConfig() {
     }
 
     console.error(
-      "\n[stealthmole.mcp] ✔ Registered stealthmole.mcp in Claude Desktop settings."
+      "\n[stealthmole-mcp] ✔ Registered stealthmole.mcp in Claude Desktop settings."
     );
     console.error(
-      "[stealthmole.mcp]   Please restart Claude Desktop to apply the changes.\n"
+      "[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}`
+        `[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."
+        "[stealthmole-mcp] ⚠ Failed to auto-register in Claude Desktop settings."
       );
     }
     return false;
@@ -125,13 +125,20 @@ if (newlyRegistered) {
 }
 
 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 stealthmole.mcp [options]\n" +
+    `@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" +
@@ -211,15 +218,15 @@ function findFreePort(maxAttempts = 20) {
 process.on("uncaughtException", (err) => {
   if (err.code === "EADDRINUSE") {
     console.error(
-      `[stealthmole.mcp] Port ${err.port ?? ""} is already in use. ` +
+      `[stealthmole-mcp] Port ${err.port ?? ""} is already in use. ` +
         "Retrying should resolve this. " +
-        "To use a specific port: npx stealthmole.mcp --port <number>"
+        "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);
+  console.error("[stealthmole-mcp] Unexpected error:", err);
   process.exit(1);
 });
 
@@ -261,6 +268,10 @@ const CLIENT_METADATA = JSON.stringify({
 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++) {
@@ -274,7 +285,7 @@ const filteredArgs = [];
             i++;
             continue;
           }
-          filteredArgs.push(rawArgs[i], val);
+          requestedPort = port;
           i++;
         } else {
           filteredArgs.push(rawArgs[i]);
@@ -287,27 +298,26 @@ const filteredArgs = [];
 process.argv.length = 2;
 process.argv.push(...filteredArgs);
 
-// Check if the user specified a callback port explicitly
-const userSpecifiedPort =
-  process.argv.includes("--port") || process.argv.includes("--callback-port");
-
 // 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 and inject it.
+// 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 (!userSpecifiedPort) {
-  const { port: callbackPort, server } = await findFreePort();
+if (requestedPort === null) {
+  const { port, server } = await findFreePort();
   guardServer = server;
-  process.argv.splice(3, 0, String(callbackPort));
+  requestedPort = port;
   if (DEBUG) {
-    console.error(
-      `Using automatically selected callback port: ${callbackPort}`
-    );
+    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);
 

package/package.json

@@ -1,26 +1,21 @@
 {
   "name": "@stealthmole/mcp",
-  "version": "0.1.8",
+  "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"
-  },
-  "scripts": {
-    "postinstall": "node scripts/patch-oauth-callback.mjs"
+    "stealthmole-mcp": "bin/cli.mjs"
   },
   "type": "module",
   "license": "MIT",
   "homepage": "https://www.stealthmole.com",
   "files": [
-    "bin/",
-    "scripts/"
+    "bin/"
   ],
   "dependencies": {
-    "mcp-remote": "0.1.38"
+    "mcp-remote": "0.15.1"
   },
   "engines": {
-    "node": ">=18.0.0"
+    "node": ">=20.18.1"
   },
   "keywords": [
     "mcp",

package/scripts/patch-oauth-callback.mjs

@@ -1,108 +0,0 @@
-#!/usr/bin/env node
-
-/**
- * Postinstall script that patches mcp-remote's OAuth callback page
- * to redirect to https://www.stealthmole.com/ after successful authentication,
- * instead of showing a "close this window" message.
- *
- * Safety:
- * - Uses exact string matching (not greedy regex) to minimize unintended replacements
- * - Verifies the result still contains the auth-code-received event emission
- * - Non-fatal: CLI works normally even if patching fails
- */
-
-import { readdirSync, readFileSync, writeFileSync } from "fs";
-import { join, dirname } from "path";
-import { fileURLToPath } from "url";
-import { createRequire } from "module";
-
-// pnpm 호환: require.resolve로 mcp-remote의 실제 위치를 찾음
-// (pnpm은 node_modules를 symlink 구조로 관리하므로 상대 경로가 동작하지 않음)
-const require = createRequire(import.meta.url);
-const distDir = join(dirname(require.resolve("mcp-remote/package.json")), "dist");
-
-// Exact string that identifies the callback response in mcp-remote
-const OLD_RESPONSE = `res.send(\`
-      Authorization successful!
-      You may close this window and return to the CLI.
-      <script>
-        // If this is a non-interactive session (no manual approval step was required) then
-        // this should automatically close the window. If not, this will have no effect and
-        // the user will see the message above.
-        window.close();
-      </script>
-    \`)`;
-
-const NEW_HTML = [
-  "<!DOCTYPE html>",
-  '<html lang="en">',
-  "<head>",
-  '  <meta charset="utf-8">',
-  '  <meta http-equiv="refresh" content="3;url=https://www.stealthmole.com/">',
-  "  <title>Authorization Successful - StealthMole</title>",
-  "  <style>",
-  "    body{font-family:-apple-system,BlinkMacSystemFont,sans-serif;display:flex;justify-content:center;align-items:center;min-height:100vh;margin:0;background:#0f172a;color:#e2e8f0}",
-  "    .card{text-align:center;padding:2.5rem 3rem;background:#1e293b;border-radius:16px;box-shadow:0 4px 24px rgba(0,0,0,.3)}",
-  "    h1{font-size:1.4rem;margin:0 0 .8rem;color:#34d399}",
-  "    p{margin:0;font-size:.95rem;color:#94a3b8}",
-  "    span{color:#34d399;font-weight:600}",
-  "  </style>",
-  "</head>",
-  "<body>",
-  '  <div class="card">',
-  "    <h1>Authorization Successful</h1>",
-  '    <p>Redirecting to StealthMole in <span id="c">3</span>s\\u2026</p>',
-  "  </div>",
-  "  <script>",
-  '    var t=3,e=document.getElementById("c"),i=setInterval(function(){if(--t<=0){clearInterval(i);location.href="https://www.stealthmole.com/"}e.textContent=t},1e3);',
-  "  </script>",
-  "</body>",
-  "</html>",
-].join("\n");
-
-const NEW_RESPONSE = "res.send(`" + NEW_HTML + "`)";
-
-// Post-patch integrity marker: this line must exist after the patched res.send()
-const INTEGRITY_MARKER = 'options.events.emit("auth-code-received"';
-
-try {
-  const files = readdirSync(distDir).filter((f) => f.endsWith(".js"));
-  let patched = false;
-
-  for (const file of files) {
-    const filePath = join(distDir, file);
-    const content = readFileSync(filePath, "utf-8");
-
-    if (!content.includes(OLD_RESPONSE)) continue;
-
-    const newContent = content.replace(OLD_RESPONSE, NEW_RESPONSE);
-
-    // Verify: the replacement should change exactly one occurrence
-    if (newContent === content) continue;
-
-    // Integrity check: auth-code-received event must still be present
-    if (!newContent.includes(INTEGRITY_MARKER)) {
-      console.error(
-        `[stealthmole.mcp] Patch integrity check failed for ${file}, skipping.`
-      );
-      continue;
-    }
-
-    writeFileSync(filePath, newContent, "utf-8");
-    console.error(
-      `[stealthmole.mcp] Patched OAuth callback page in ${file}`
-    );
-    patched = true;
-  }
-
-  if (!patched) {
-    console.error(
-      "[stealthmole.mcp] OAuth callback page already patched or pattern not found."
-    );
-  }
-} catch {
-  // Non-fatal: if patching fails the CLI still works, just shows the default page
-  console.error(
-    "[stealthmole.mcp] Could not patch OAuth callback page."
-  );
-}