@sentinelsup/mcp 0.1.3 → 0.1.4

package/README.md

@@ -1,17 +1,19 @@
 # Maskbreak MCP Server
 
-Check any IP address for fraud signals — VPN, proxy, Tor, datacenter hosting, anonymity — straight from Claude, Cursor, or any MCP client. Powered by the [Maskbreak](https://maskbreak.com) fraud detection API.
+Look up limited public IP intelligence — cloud-hosting ranges and Tor exit nodes — from Claude, Cursor, or another MCP client. Powered by the [Maskbreak](https://maskbreak.com) fraud detection API. Requires Node.js 18+ for the local server.
 
 ## Tools
 
 | Tool | What it does |
 |------|--------------|
-| `lookup_ip` | Verdict for any public IPv4/IPv6: `allow` / `review` / `block`, 0–100 risk score, VPN/proxy/Tor/datacenter/anonymity signals, ASN + org + country |
+| `lookup_ip` | Public IPv4/IPv6 lookup: `known`, `allow` / `review` / `block`, risk score, and nullable signal/network metadata. Public-feed coverage is limited to cloud hosting and Tor. |
 | `service_status` | Maskbreak API health, uptime, and latency |
 
 ## Setup
 
-Grab a free API key at [maskbreak.com/signup](https://maskbreak.com/signup) (1,000 lookups/hour, no card). The server also works without a key for a few lookups per minute — enough to try it.
+Grab a free API key at [maskbreak.com/signup](https://maskbreak.com/signup) (1,000 lookups/hour, shared with evaluations, no card). Keyless mode uses the free web-tool endpoint, limited to 12 lookups/minute and 80/day per caller IP. Additional endpoint and abuse-protection limits can apply.
+
+Neither mode performs a browser visit. VPN/proxy and device evidence require a browser-SDK-backed `/v1/evaluate` request outside these tools; service names are available only when known. Unknown IPs, false signals and `allow` verdicts are not proof of safety.
 
 ### Claude Code
 
@@ -45,16 +47,18 @@ Prefer a remote server? The same tools are hosted at **`https://maskbreak.com/mc
 
 ## Example
 
-> "Is 185.220.101.34 safe to allow through signup?"
+> "What public-feed evidence is available for this IP?"
+
+Illustrative unknown-IP response, not a live lookup:
 
 ```json
 {
-  "ip": "185.220.101.34",
-  "known": true,
-  "verdict": "block",
-  "risk_score": 90,
-  "signals": { "vpn": false, "proxied": false, "tor": true, "dch": true, "anon": true },
-  "network": { "asn": 205100, "org": "F3 Netze e.V.", "country": "DE" }
+  "ip": "192.0.2.1",
+  "known": false,
+  "verdict": "allow",
+  "risk_score": 0,
+  "signals": null,
+  "network": null
 }
 ```
 
@@ -65,6 +69,19 @@ Prefer a remote server? The same tools are hosted at **`https://maskbreak.com/mc
 | `SENTINEL_API_KEY` | recommended | — | API key from your [dashboard](https://maskbreak.com/dashboard); unlocks 1,000 lookups/hour |
 | `SENTINEL_BASE_URL` | no | `https://maskbreak.com` | Override for testing |
 
+## Failures and local checks
+
+Both tools return MCP `isError: true` for HTTP failures, malformed responses or requests that exceed the five-second timeout (including body reads). An unavailable lookup is not an allow decision.
+
+```bash
+npm ci --ignore-scripts
+npm test
+npm pack --dry-run --ignore-scripts
+npm audit
+```
+
+Tests use a real stdio MCP client with loopback HTTP fixtures, without production keys. CI checks Node.js 18, 22 and 24. No package is published by these checks.
+
 ## Links
 
 - [API docs](https://maskbreak.com/api)

package/index.js

@@ -17,32 +17,55 @@ const { version: VERSION } = JSON.parse(
   readFileSync(new URL('./package.json', import.meta.url), 'utf8')
 );
 
-const BASE = process.env.SENTINEL_BASE_URL || 'https://maskbreak.com';
+const BASE = (process.env.SENTINEL_BASE_URL || 'https://maskbreak.com').replace(/\/+$/, '');
 const API_KEY = process.env.SENTINEL_API_KEY || '';
+const TIMEOUT_MS = 5000;
+
+async function requestJson(path, init = {}, keylessLookup = false) {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), TIMEOUT_MS);
+  try {
+    const res = await fetch(`${BASE}${path}`, {
+      ...init,
+      headers: { 'Accept': 'application/json', ...init.headers },
+      signal: controller.signal
+    });
+    let data;
+    try {
+      data = await res.json();
+    } catch (error) {
+      if (error.name === 'AbortError') throw error;
+      data = null;
+    }
+    if (!res.ok) {
+      const hint = keylessLookup && res.status === 429
+        ? ' (keyless mode is tightly rate-limited — set SENTINEL_API_KEY for 1,000 lookups/hour; free key at https://maskbreak.com/signup)'
+        : '';
+      throw new Error(`${data?.error || `HTTP ${res.status}`}${hint}`);
+    }
+    if (!data || typeof data !== 'object' || Array.isArray(data)) {
+      throw new Error('Invalid JSON response from Maskbreak API');
+    }
+    return data;
+  } catch (error) {
+    if (error.name === 'AbortError') throw new Error(`Maskbreak request timed out after ${TIMEOUT_MS}ms`);
+    throw error;
+  } finally {
+    clearTimeout(timer);
+  }
+}
 
 async function lookupIp(ip) {
-  const opts = { headers: { 'Accept': 'application/json' } };
-  let res;
   if (API_KEY) {
-    res = await fetch(`${BASE}/v1/lookup/${encodeURIComponent(ip)}`, {
-      ...opts,
-      headers: { ...opts.headers, 'Authorization': `Bearer ${API_KEY}` }
+    return requestJson(`/v1/lookup/${encodeURIComponent(ip)}`, {
+      headers: { 'Authorization': `Bearer ${API_KEY}` }
     });
-  } else {
-    res = await fetch(`${BASE}/api/lookup`, {
-      method: 'POST',
-      headers: { ...opts.headers, 'Content-Type': 'application/json' },
-      body: JSON.stringify({ ip })
-    });
-  }
-  const data = await res.json().catch(() => ({}));
-  if (!res.ok) {
-    const hint = !API_KEY && res.status === 429
-      ? ' (keyless mode is tightly rate-limited — set SENTINEL_API_KEY for 1,000 lookups/hour; free key at https://maskbreak.com/signup)'
-      : '';
-    throw new Error(`${data.error || `HTTP ${res.status}`}${hint}`);
   }
-  return data;
+  return requestJson('/api/lookup', {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ ip })
+  }, true);
 }
 
 function text(obj) {
@@ -53,7 +76,7 @@ const server = new McpServer({ name: 'maskbreak', version: VERSION });
 
 server.tool(
   'lookup_ip',
-  'Check an IP address for fraud signals: VPN, proxy, Tor exit node, datacenter hosting, and anonymity. Returns an allow/review/block verdict, a 0-100 risk score, the individual signals, and network info (ASN, organization, country).',
+  'Look up limited public IP intelligence: cloud-hosting ranges and Tor exit nodes. Returns known, an allow/review/block verdict, a 0-100 risk score, and nullable signals/network metadata. Unknown or false signals do not establish safety. VPN/proxy and device evidence require a browser-SDK-backed visit via /v1/evaluate, which this tool does not perform.',
   { ip: z.string().describe('Public IPv4 or IPv6 address to check, e.g. "185.220.101.34"') },
   async ({ ip }) => {
     try {
@@ -70,8 +93,7 @@ server.tool(
   {},
   async () => {
     try {
-      const res = await fetch(`${BASE}/api/status`, { headers: { 'Accept': 'application/json' } });
-      return text(await res.json());
+      return text(await requestJson('/api/status'));
     } catch (e) {
       return { ...text({ error: e.message }), isError: true };
     }

package/package.json

@@ -1,7 +1,8 @@
 {
   "name": "@sentinelsup/mcp",
-  "version": "0.1.3",
-  "description": "MCP server for Maskbreak — check any IP for VPNs, proxies, Tor, datacenter hosting, and fraud risk from Claude, Cursor, or any MCP client.",
+  "version": "0.1.4",
+  "mcpName": "io.github.sentinelsup/maskbreak-mcp",
+  "description": "MCP server for Maskbreak — look up public cloud-hosting and Tor IP signals, with limited reputation evidence and API status, from an MCP client.",
   "keywords": [
     "mcp",
     "model-context-protocol",
@@ -37,6 +38,9 @@
   "engines": {
     "node": ">=18"
   },
+  "scripts": {
+    "test": "node --test test.js"
+  },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.0.0",
     "zod": "^3.23.0"