netintel-mcp 1.1.53 → 1.1.56

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Karim Gueye (NetIntel)
+
+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

@@ -4,6 +4,17 @@ MCP server for NetIntel — 122 network intelligence tools for AI agents.
 DNS, SSL, WHOIS, email security, cloud fingerprinting, OSINT and more.
 Pay-per-call via x402 — the NetIntel API accepts USDC on Base or Solana; this MCP server pays on Base. No API keys needed — just a wallet with USDC.
 
+## Install as a Claude Code plugin (recommended)
+
+The plugin installs the MCP server **and** a skill that knows which NetIntel endpoint fits a task and what it costs, and prompts once for the agent wallet key (stored in Claude Code's secure storage, never in settings files):
+
+```
+/plugin marketplace add kjgueye/netintel-mcp
+/plugin install netintel@netintel
+```
+
+Then just ask — "is this IP malicious?", "does this domain have DMARC?", "fetch this URL as JSON" — and the tools pay per call from that wallet.
+
 ## Install
 
 ```bash
@@ -26,8 +37,8 @@ Or add manually to your Claude Desktop config:
 ```
 
 ## Requirements
-- A wallet private key with USDC on Base mainnet
-- EVM_PRIVATE_KEY environment variable set
+- **Optional:** `EVM_PRIVATE_KEY` — a dedicated agent wallet holding USDC on Base mainnet (gasless; a few dollars is plenty). With it, every tool pays its listed price automatically.
+- **Without a wallet** the server still runs: `netintel_dns_lookup`, `netintel_ssl_cert`, `netintel_whois_lookup`, `netintel_subnet_calc` and `netintel_email_auth` work free (about 30 calls/hour per client, then the normal price), and paid tools reply with what they cost and how to fund. `netintel_wallet_status` shows the wallet, its USDC balance and the free tools. **Spending limits (≥1.1.55):** the server refuses to sign a payment above `NETINTEL_MAX_PER_CALL_USD` (default $0.25) or once it has authorized `NETINTEL_MAX_SESSION_USD` (default $5) in total per process; a refusal returns `SPEND_LIMIT: …` and nothing is paid. Listed prices are what a call costs, not a cap — with a wallet configured every 402 (including a free-tier route past its quota) is paid automatically, so authorize paid calls with your user first.
 
 ## Tools
 

package/dist/client.js

@@ -1,18 +1,111 @@
 import { x402Client, wrapAxiosWithPayment } from "@x402/axios";
 import { registerExactEvmScheme } from "@x402/evm/exact/client";
 import { privateKeyToAccount } from "viem/accounts";
+import { createPublicClient, http, formatUnits } from "viem";
+import { base } from "viem/chains";
 import axios from "axios";
 // Canonical domain. The legacy netintel-production-440c.up.railway.app host
 // still serves the same app as a fallback, but new clients target netintel.dev.
 const BASE_URL = "https://netintel.dev";
+/** USDC on Base mainnet — the asset every NetIntel price is quoted in. */
+const USDC_BASE = "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913";
+/** Tools that work with NO wallet: NetIntel's free tier (per-client quota, then the normal price). */
+export const FREE_TOOLS = [
+    "netintel_dns_lookup",
+    "netintel_ssl_cert",
+    "netintel_whois_lookup",
+    "netintel_subnet_calc",
+    "netintel_email_auth",
+];
+let walletAddress = null;
+/**
+ * Spending limits, enforced INSIDE the x402 client immediately before a payment
+ * payload is signed — the only place a limit can be real, because with a wallet
+ * configured every 402 (including a free-tier route past its quota) is paid
+ * automatically. The listed per-call prices are what a route costs, not a cap.
+ *   NETINTEL_MAX_PER_CALL_USD  — refuse any single payment above this (default $0.25)
+ *   NETINTEL_MAX_SESSION_USD   — refuse once this MCP server process has authorized
+ *                                this much in total (default $5.00)
+ * A refusal aborts the payment (nothing is signed or sent) and the tool returns
+ * "SPEND_LIMIT: …" telling the agent which limit and how to raise it. Session
+ * spend counts every authorized payment, whether or not the call then succeeds
+ * (conservative: a payment that settles for a failed call is not charged by
+ * NetIntel, but the signature was still handed out).
+ */
+const SPEND_LIMIT = "SPEND_LIMIT";
+function limit(envName, fallback) {
+    const n = Number(process.env[envName]);
+    return Number.isFinite(n) && n >= 0 ? n : fallback;
+}
+export const MAX_PER_CALL_USD = limit("NETINTEL_MAX_PER_CALL_USD", 0.25);
+export const MAX_SESSION_USD = limit("NETINTEL_MAX_SESSION_USD", 5);
+let sessionAuthorizedUsd = 0;
+let refusedPayments = 0;
+/** What the limits are and how much this server process has authorized so far. */
+export function spendStatus() {
+    return {
+        max_per_call_usd: MAX_PER_CALL_USD,
+        max_session_usd: MAX_SESSION_USD,
+        session_authorized_usd: Number(sessionAuthorizedUsd.toFixed(6)),
+        session_remaining_usd: Number(Math.max(0, MAX_SESSION_USD - sessionAuthorizedUsd).toFixed(6)),
+        refused_payments: refusedPayments,
+        configure: "NETINTEL_MAX_PER_CALL_USD / NETINTEL_MAX_SESSION_USD (env, or the Claude Code plugin config); limits are per MCP server process",
+    };
+}
+/** The configured agent wallet's address, or null when the server runs wallet-less. */
+export function configuredWallet() {
+    return walletAddress;
+}
+/**
+ * The HTTP client every tool uses. With EVM_PRIVATE_KEY set, responses that
+ * demand payment are paid automatically (x402) and retried; without it, the
+ * server still starts — the free-tier tools work as-is and paid tools return
+ * an explanation of what a call costs and how to fund a wallet, instead of
+ * failing to boot for everyone who installed the plugin before funding one.
+ */
 export async function createClient() {
-    const key = process.env.EVM_PRIVATE_KEY;
+    const key = process.env.EVM_PRIVATE_KEY?.trim();
+    const plain = axios.create({ baseURL: BASE_URL });
     if (!key) {
-        throw new Error("EVM_PRIVATE_KEY environment variable is required. " +
-            "Set it to your wallet private key (with USDC on Base mainnet).");
+        console.error("[netintel-mcp] No EVM_PRIVATE_KEY set — running wallet-less. Free-tier tools work " +
+            `(${FREE_TOOLS.join(", ")}); paid tools will explain how to fund an agent wallet.`);
+        return plain;
     }
-    const client = new x402Client();
     const signer = privateKeyToAccount(key);
+    walletAddress = signer.address;
+    const client = new x402Client();
     registerExactEvmScheme(client, { signer });
-    return wrapAxiosWithPayment(axios.create({ baseURL: BASE_URL }), client);
+    client.onBeforePaymentCreation(async (context) => {
+        const req = context?.selectedRequirements;
+        const atomic = Number(req?.amount);
+        const usd = atomic / 1_000_000;
+        if (!Number.isFinite(usd) || usd < 0) {
+            refusedPayments += 1;
+            return { abort: true, reason: `${SPEND_LIMIT}: the payment requirements carry no usable amount (got ${JSON.stringify(req?.amount)}); refusing to sign` };
+        }
+        if (usd > MAX_PER_CALL_USD) {
+            refusedPayments += 1;
+            return { abort: true, reason: `${SPEND_LIMIT}: this call costs ${usd} — above the per-call limit of ${MAX_PER_CALL_USD}. Ask the user; to allow it, raise NETINTEL_MAX_PER_CALL_USD (env or plugin config) and restart the server` };
+        }
+        if (sessionAuthorizedUsd + usd > MAX_SESSION_USD) {
+            refusedPayments += 1;
+            return { abort: true, reason: `${SPEND_LIMIT}: this call costs ${usd} and this session has already authorized ${sessionAuthorizedUsd.toFixed(3)} of its ${MAX_SESSION_USD} limit. Ask the user; to continue, raise NETINTEL_MAX_SESSION_USD (env or plugin config) and restart the server` };
+        }
+        sessionAuthorizedUsd += usd;
+        return undefined;
+    });
+    return wrapAxiosWithPayment(plain, client);
+}
+/** USDC balance of the configured wallet on Base (keyless public RPC). */
+export async function walletUsdcBalance() {
+    if (!walletAddress)
+        return null;
+    const pc = createPublicClient({ chain: base, transport: http() });
+    const raw = await pc.readContract({
+        address: USDC_BASE,
+        abi: [{ type: "function", name: "balanceOf", stateMutability: "view", inputs: [{ name: "a", type: "address" }], outputs: [{ type: "uint256" }] }],
+        functionName: "balanceOf",
+        args: [walletAddress],
+    });
+    return formatUnits(raw, 6);
 }

package/dist/index.js

@@ -2,7 +2,7 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { z } from "zod";
-import { createClient } from "./client.js";
+import { createClient, configuredWallet, walletUsdcBalance, spendStatus, FREE_TOOLS } from "./client.js";
 function ok(data) {
     return { content: [{ type: "text", text: JSON.stringify(data) }] };
 }
@@ -10,6 +10,22 @@ function err(e) {
     const ax = e;
     const status = ax.response?.status ?? "unknown";
     const msg = ax.message ?? String(e);
+    // A spending-limit refusal: the SDK aborted BEFORE signing, so no payment was
+    // made. Hand the agent the exact reason (which limit, how to raise it).
+    const limitAt = msg.indexOf("SPEND_LIMIT:");
+    if (limitAt >= 0) {
+        return { content: [{ type: "text", text: `Payment refused by your spending limit — nothing was paid. ${msg.slice(limitAt)}` }], isError: true };
+    }
+    if (status === 402) {
+        // The one error a user can act on: the call needs a payment that did not
+        // happen. Say what it costs and exactly what to do, instead of "402".
+        const price = ax.response?.data?.accepts?.[0]?.price;
+        const cost = price ? `This tool costs ${price} per call (USDC on Base). ` : "This tool is paid per call (USDC on Base). ";
+        const fix = configuredWallet()
+            ? `The agent wallet ${configuredWallet()} is configured but the payment did not settle — usually an empty wallet. Run netintel_wallet_status to check its USDC balance, then fund it on Base.`
+            : `No agent wallet is configured, so it cannot be paid. Set EVM_PRIVATE_KEY to a wallet holding USDC on Base (or enter it in the Claude Code plugin config), then retry. Without a wallet these tools still work free, up to a quota: ${FREE_TOOLS.join(", ")}.`;
+        return { content: [{ type: "text", text: `Payment required. ${cost}${fix}` }], isError: true };
+    }
     return {
         content: [{ type: "text", text: `Error (${status}): ${msg}` }],
         isError: true,
@@ -1262,6 +1278,27 @@ function registerTools(server, api) {
         }
     });
 }
+// Wallet status — free, local: lets an agent (or a human) tell "no wallet",
+// "empty wallet" and "funded" apart before spending a call on finding out.
+// Deliberately OUTSIDE registerTools(): scripts/sync-ecosystem.ts pairs each
+// server.tool() in there with the api.get/post path that follows it, and this
+// tool makes no API call.
+function registerWalletTool(server) {
+    server.tool("netintel_wallet_status", "Check the agent wallet this MCP server pays NetIntel with: whether a key is configured, its address, its USDC balance on Base, and the spending limits (per call and per session) with how much this session has authorized. Free and local (no NetIntel call). Use when a paid tool reports 'Payment required' or 'SPEND_LIMIT', before funding, or to confirm a top-up arrived. Also lists the tools that work with no wallet at all.", {}, async () => {
+        const address = configuredWallet();
+        const free = { free_without_wallet: [...FREE_TOOLS], note: "Free tools are rate-limited per client (about 30/hour); over the quota they cost their normal price." };
+        if (!address) {
+            return ok({ wallet_configured: false, how_to_fund: "Set EVM_PRIVATE_KEY (or the plugin's wallet config) to a dedicated agent wallet, then send it a few dollars of USDC on Base mainnet — no ETH needed, settlement is gasless.", ...free });
+        }
+        try {
+            const usdc = await walletUsdcBalance();
+            return ok({ wallet_configured: true, address, usdc_balance_base: usdc, funded: Number(usdc) > 0, top_up: Number(usdc) > 0 ? undefined : `Send USDC on Base to ${address}`, spending_limits: spendStatus(), ...free });
+        }
+        catch (e) {
+            return ok({ wallet_configured: true, address, usdc_balance_base: null, balance_error: String(e.message).slice(0, 160), spending_limits: spendStatus(), ...free });
+        }
+    });
+}
 async function main() {
     const api = await createClient();
     const server = new McpServer({
@@ -1269,6 +1306,7 @@ async function main() {
         version: "1.1.0",
     });
     registerTools(server, api);
+    registerWalletTool(server);
     const transport = new StdioServerTransport();
     await server.connect(transport);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "netintel-mcp",
-  "version": "1.1.53",
+  "version": "1.1.56",
   "mcpName": "io.github.kjgueye/netintel-mcp",
   "repository": {
     "type": "git",