netintel-mcp 1.1.53 → 1.1.54

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.
 
 ## Tools
 

package/dist/client.js

@@ -1,18 +1,58 @@
 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;
+/** 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);
+    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, FREE_TOOLS } from "./client.js";
 function ok(data) {
     return { content: [{ type: "text", text: JSON.stringify(data) }] };
 }
@@ -10,6 +10,16 @@ function err(e) {
     const ax = e;
     const status = ax.response?.status ?? "unknown";
     const msg = ax.message ?? String(e);
+    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 +1272,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, and its USDC balance on Base. Free and local (no NetIntel call). Use when a paid tool reports 'Payment required', 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}`, ...free });
+        }
+        catch (e) {
+            return ok({ wallet_configured: true, address, usdc_balance_base: null, balance_error: String(e.message).slice(0, 160), ...free });
+        }
+    });
+}
 async function main() {
     const api = await createClient();
     const server = new McpServer({
@@ -1269,6 +1300,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.54",
   "mcpName": "io.github.kjgueye/netintel-mcp",
   "repository": {
     "type": "git",