@sentinelsup/mcp 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sentinel Edge Networks LTD
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,70 @@
+# Sentinel 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 [Sentinel](https://sntlhq.com) fraud detection API.
+
+## 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 |
+| `service_status` | Sentinel API health, uptime, and latency |
+
+## Setup
+
+Grab a free API key at [sntlhq.com/signup](https://sntlhq.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.
+
+### Claude Code
+
+```bash
+claude mcp add sentinel -e SENTINEL_API_KEY=sk_live_your_key -- npx -y @sentinelsup/mcp
+```
+
+### Claude Desktop
+
+Add to `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "sentinel": {
+      "command": "npx",
+      "args": ["-y", "@sentinelsup/mcp"],
+      "env": { "SENTINEL_API_KEY": "sk_live_your_key" }
+    }
+  }
+}
+```
+
+### Cursor / other MCP clients
+
+Any client that speaks stdio MCP works the same way: command `npx`, args `["-y", "@sentinelsup/mcp"]`, env `SENTINEL_API_KEY`.
+
+## Example
+
+> "Is 185.220.101.34 safe to allow through signup?"
+
+```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" }
+}
+```
+
+## Environment
+
+| Variable | Required | Default | Purpose |
+|----------|----------|---------|---------|
+| `SENTINEL_API_KEY` | recommended | — | API key from your [dashboard](https://sntlhq.com/dashboard); unlocks 1,000 lookups/hour |
+| `SENTINEL_BASE_URL` | no | `https://sntlhq.com` | Override for testing |
+
+## Links
+
+- [API docs](https://sntlhq.com/api)
+- [Node SDK](https://github.com/sentinelsup/sentinel-node) · [Python SDK](https://pypi.org/project/sentinelsup/)
+- [Status](https://sntlhq.com/status)
+
+MIT © Sentinel Edge Networks LTD

package/index.js

@@ -0,0 +1,75 @@
+#!/usr/bin/env node
+// Sentinel MCP server — IP fraud intelligence for MCP clients (Claude Code,
+// Claude Desktop, Cursor, ...). One stdio server, two tools.
+//
+// With SENTINEL_API_KEY set, lookups go through the authenticated API
+// (GET /v1/lookup/{ip}, 1,000 req/hr on the free tier). Without a key they
+// fall back to the free web-tool endpoint, which is fine for trying it out
+// but rate-limited to a handful of lookups per minute.
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { z } from 'zod';
+
+const BASE = process.env.SENTINEL_BASE_URL || 'https://sntlhq.com';
+const API_KEY = process.env.SENTINEL_API_KEY || '';
+
+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}` }
+    });
+  } 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://sntlhq.com/signup)'
+      : '';
+    throw new Error(`${data.error || `HTTP ${res.status}`}${hint}`);
+  }
+  return data;
+}
+
+function text(obj) {
+  return { content: [{ type: 'text', text: JSON.stringify(obj, null, 2) }] };
+}
+
+const server = new McpServer({ name: 'sentinel', version: '0.1.0' });
+
+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).',
+  { ip: z.string().describe('Public IPv4 or IPv6 address to check, e.g. "185.220.101.34"') },
+  async ({ ip }) => {
+    try {
+      return text(await lookupIp(ip.trim()));
+    } catch (e) {
+      return { ...text({ error: e.message }), isError: true };
+    }
+  }
+);
+
+server.tool(
+  'service_status',
+  'Current operational status of the Sentinel API: uptime, per-service health, and average latency.',
+  {},
+  async () => {
+    try {
+      const res = await fetch(`${BASE}/api/status`, { headers: { 'Accept': 'application/json' } });
+      return text(await res.json());
+    } catch (e) {
+      return { ...text({ error: e.message }), isError: true };
+    }
+  }
+);
+
+const transport = new StdioServerTransport();
+await server.connect(transport);

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@sentinelsup/mcp",
+  "version": "0.1.0",
+  "description": "MCP server for Sentinel — check any IP for VPNs, proxies, Tor, datacenter hosting, and fraud risk from Claude, Cursor, or any MCP client.",
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "fraud-detection",
+    "ip-lookup",
+    "vpn-detection",
+    "proxy-detection",
+    "bot-detection",
+    "sentinel",
+    "sntlhq"
+  ],
+  "type": "module",
+  "main": "index.js",
+  "bin": {
+    "sentinel-mcp": "index.js"
+  },
+  "files": [
+    "index.js",
+    "README.md",
+    "LICENSE"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/sentinelsup/sentinel-mcp.git"
+  },
+  "homepage": "https://sntlhq.com",
+  "bugs": {
+    "url": "https://github.com/sentinelsup/sentinel-mcp/issues"
+  },
+  "author": "Sentinel Edge Networks LTD <support@sntlhq.com>",
+  "license": "MIT",
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "zod": "^3.23.0"
+  }
+}