chainhint-mcp 1.0.1 → 1.1.0

package/README.md

@@ -4,16 +4,16 @@ Crypto risk intelligence for Claude Desktop, Cursor, and any MCP-compatible AI.
 
 ## Tools
 
-| Tool | Description |
-|------|-------------|
-| `check_wallet_risk` | Fast risk score, entity, labels, sanctions hit (54M+ labeled addresses). **Needs API key** |
-| `lookup_address` | Deep address report — entity, risk factors, GoPlus flags, counterparty exposure, balance. No key needed |
-| `get_trace_status` | Fund-trace summary for a public hack incident — hops, endpoints by type (exchange/mixer/bridge/defi), exposure. No key needed |
+| Tool | Description | Limit |
+|------|-------------|-------|
+| `check_wallet_risk` | Fast risk score, entity, labels, sanctions hit (54M+ labeled addresses) | **3 / day** free · 10,000 / day with key |
+| `lookup_address` | Deep address report — entity, risk factors, GoPlus flags, counterparty exposure, balance | **10 / day** free · 100 / hour with key |
+| `get_trace_status` | Fund-trace summary for a public hack incident — hops, endpoints by type (exchange/mixer/bridge/defi), exposure | Unlimited |
 
 ## Requirements
 
 - Node.js 18+
-- Optional: ChainHint Agency plan API key (`ch_live_...`) from [chainhint.com/settings](https://chainhint.com/settings) — only `check_wallet_risk` needs it
+- Nothing else. **No API key needed to start** — every tool has a free daily allowance (per IP). An Agency plan key (`ch_live_...`, [chainhint.com/settings](https://chainhint.com/settings)) lifts the limits.
 
 ## Install
 
@@ -38,10 +38,7 @@ Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
   "mcpServers": {
     "chainhint": {
       "command": "npx",
-      "args": ["-y", "chainhint-mcp"],
-      "env": {
-        "CHAINHINT_API_KEY": "ch_live_your_key_here"
-      }
+      "args": ["-y", "chainhint-mcp"]
     }
   }
 }
@@ -56,15 +53,39 @@ Add to `.cursor/mcp.json` in your project (or global `~/.cursor/mcp.json`):
   "mcpServers": {
     "chainhint": {
       "command": "npx",
-      "args": ["-y", "chainhint-mcp"],
-      "env": {
-        "CHAINHINT_API_KEY": "ch_live_your_key_here"
-      }
+      "args": ["-y", "chainhint-mcp"]
     }
   }
 }
 ```
 
+## Claude Code
+
+```bash
+claude mcp add chainhint -- npx -y chainhint-mcp
+```
+
+## Lifting the free limits
+
+Add an Agency key to the server entry (any client):
+
+```json
+"env": { "CHAINHINT_API_KEY": "ch_live_your_key_here" }
+```
+
+## What the agent sees
+
+```
+## Wallet Risk Report: 0x47666f...9486e2
+**Chain:** ethereum
+**Risk Score:** 85/100 — **CRITICAL**
+**Entity:** Bybit Hack Exploiter (hacker)
+**Labels:** Hacker/Exploiter, Bybit Hack Exploiter
+**In ChainHint DB:** yes (sources: chainhint:manual)
+
+Free tier: 2 of 3 checks left today — set CHAINHINT_API_KEY (Agency plan, https://chainhint.com/pricing) for 10,000/day.
+```
+
 ## Development (no build step)
 
 ```bash
@@ -75,7 +96,7 @@ npm run dev
 
 | Variable | Required | Description |
 |----------|----------|-------------|
-| `CHAINHINT_API_KEY` | — | API key from chainhint.com (Agency plan). Required only for `check_wallet_risk` |
+| `CHAINHINT_API_KEY` | — | Agency plan key from chainhint.com. Lifts the free limits (3 checks + 10 lookups per day) to 10,000 / day |
 | `CHAINHINT_API_URL` | — | Override API base URL (default: production) |
 | `CHAINHINT_SUPABASE_ANON_KEY` | — | Override anon key for get_trace_status (public incidents) |
 

package/dist/index.d.ts

@@ -10,7 +10,8 @@
  *   - lookup_address      → address-lookup API (entity, risk factors, exposure, balance) — public
  *   - get_trace_status    → public incident fund-trace summary (endpoints, hops, exposure) — public
  *
- * Auth: CHAINHINT_API_KEY env var (Agency plan API key: ch_live_...) is only
- * required for check_wallet_risk. The other two tools hit public endpoints.
+ * Auth: works without a key. check_wallet_risk has a free tier of 3 checks
+ * per IP per day; lookup_address 10 per day; get_trace_status is unlimited.
+ * CHAINHINT_API_KEY (Agency plan, ch_live_...) lifts the limits to 10,000/day.
  */
 export {};

package/dist/index.js

@@ -10,8 +10,9 @@
  *   - lookup_address      → address-lookup API (entity, risk factors, exposure, balance) — public
  *   - get_trace_status    → public incident fund-trace summary (endpoints, hops, exposure) — public
  *
- * Auth: CHAINHINT_API_KEY env var (Agency plan API key: ch_live_...) is only
- * required for check_wallet_risk. The other two tools hit public endpoints.
+ * Auth: works without a key. check_wallet_risk has a free tier of 3 checks
+ * per IP per day; lookup_address 10 per day; get_trace_status is unlimited.
+ * CHAINHINT_API_KEY (Agency plan, ch_live_...) lifts the limits to 10,000/day.
  */
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
@@ -21,30 +22,55 @@ const API_KEY = process.env.CHAINHINT_API_KEY;
 const BASE_URL = process.env.CHAINHINT_API_URL ?? "https://kjiwfwymnuzxriokhcjk.supabase.co/functions/v1";
 const SUPABASE_URL = process.env.CHAINHINT_SUPABASE_URL ?? "https://kjiwfwymnuzxriokhcjk.supabase.co";
 const SUPABASE_ANON_KEY = process.env.CHAINHINT_SUPABASE_ANON_KEY ?? "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJzdXBhYmFzZSIsInJlZiI6ImtqaXdmd3ltbnV6eHJpb2toY2prIiwicm9sZSI6ImFub24iLCJpYXQiOjE3NzI3MzkxODgsImV4cCI6MjA4ODMxNTE4OH0.VqzzF_jI8zF072cbjWEDbYo3PnMDlIPy621iWkXEqyo";
-const NO_KEY_MESSAGE = "check_wallet_risk requires CHAINHINT_API_KEY (Agency plan, ch_live_...). " +
-    "Get one at chainhint.com → Settings → API Keys, or use lookup_address which needs no key.";
+const VERSION = "1.1.0";
+const USER_AGENT = `chainhint-mcp/${VERSION}`;
+const FREE_CHECKS_PER_DAY = 3;
+const UPGRADE_HINT = "set CHAINHINT_API_KEY (Agency plan, https://chainhint.com/pricing) for 10,000/day";
 if (!API_KEY) {
-    console.error("[chainhint-mcp] WARN: CHAINHINT_API_KEY is not set — check_wallet_risk will be unavailable.");
-    console.error("  lookup_address and get_trace_status work without a key.");
+    console.error(`[chainhint-mcp] No CHAINHINT_API_KEY — running on the free tier (${FREE_CHECKS_PER_DAY} wallet checks + 10 lookups per day per IP).`);
 }
-// ── HTTP helpers ──────────────────────────────────────────────────────────────
-async function apiGet(path, params, opts) {
+async function apiGet(path, params) {
     const url = new URL(`${BASE_URL}${path}`);
     for (const [k, v] of Object.entries(params)) {
         if (v)
             url.searchParams.set(k, v);
     }
-    const headers = { "Content-Type": "application/json" };
-    if (opts.auth && API_KEY) {
+    // User-Agent lets the backend attribute traffic (api_usage_log.caller) and
+    // apply the MCP-specific free allowance. The key, when present, goes in
+    // X-Api-Key so both wallet-reputation and address-lookup recognise it.
+    const headers = {
+        "Content-Type": "application/json",
+        "User-Agent": USER_AGENT,
+    };
+    if (API_KEY) {
         headers["X-Api-Key"] = API_KEY;
         headers["Authorization"] = `Bearer ${API_KEY}`;
     }
     const res = await fetch(url.toString(), { headers });
     const body = (await res.json().catch(() => ({ error: `HTTP ${res.status}` })));
     if (!res.ok) {
-        throw new Error(body?.error ?? `HTTP ${res.status}: ${url.toString()}`);
+        let msg = body?.error ?? `HTTP ${res.status}: ${url.toString()}`;
+        if (res.status === 429 && body?.reset_at) {
+            msg += ` Resets at ${new Date(body.reset_at * 1000).toISOString()}.`;
+        }
+        throw new Error(msg);
     }
-    return body;
+    return { body, headers: res.headers };
+}
+/** "Free tier: 2 of 3 checks left today — set CHAINHINT_API_KEY …" or null. */
+function quotaLine(headers, what) {
+    if (headers.get("x-chainhint-tier") !== "free")
+        return null;
+    const limit = Number(headers.get("x-ratelimit-limit"));
+    const remaining = Number(headers.get("x-ratelimit-remaining"));
+    if (!Number.isFinite(limit) || !Number.isFinite(remaining))
+        return null;
+    // Bypass-listed IPs get MAX_SAFE_INTEGER from the backend — no quota to report.
+    if (limit >= 1_000_000)
+        return null;
+    const reset = Number(headers.get("x-ratelimit-reset"));
+    const resetStr = Number.isFinite(reset) && reset > 0 ? ` (resets ${new Date(reset * 1000).toISOString().slice(0, 16)}Z)` : "";
+    return `Free tier: ${remaining} of ${limit} ${what} left today${resetStr} — ${UPGRADE_HINT}.`;
 }
 async function supabaseGet(table, params) {
     const url = new URL(`${SUPABASE_URL}/rest/v1/${table}`);
@@ -106,31 +132,58 @@ function formatExposure(label, buckets) {
         }),
     ];
 }
+/** Public incident whose attacker_address matches, or null (errors swallowed — best effort). */
+async function findPublicIncidentByAttacker(address) {
+    try {
+        const rows = await supabaseGet("public_incidents_view", {
+            select: "id,title,chain,amount_usd,estimated_loss_usd,risk_score",
+            attacker_address: `eq.${normalizeAddr(address)}`,
+            limit: "1",
+        });
+        return rows[0] ?? null;
+    }
+    catch {
+        return null;
+    }
+}
 // ── MCP Server ────────────────────────────────────────────────────────────────
 const server = new McpServer({
     name: "chainhint",
-    version: "1.0.1",
+    version: VERSION,
 });
 // ── Tool 1: check_wallet_risk ─────────────────────────────────────────────────
-server.tool("check_wallet_risk", "Fast risk check for a crypto wallet address against ChainHint's 54M+ labeled address database (12 chains). Returns risk score 0-100, risk level (clean/low/medium/high/critical/sanctioned), entity name and category, labels, and sanctions hit. Requires CHAINHINT_API_KEY (Agency plan). For a keyless, deeper look (risk factors, exposure, balance) use lookup_address.", {
+server.tool("check_wallet_risk", "Fast risk check for a crypto wallet address against ChainHint's 54M+ labeled address database (12 chains). Returns risk score 0-100, risk level (clean/low/medium/high/critical/sanctioned), entity name and category, labels, and sanctions hit. Use it to decide allow/warn/block before paying or interacting with a counterparty wallet. Free: 3 checks per day without a key; CHAINHINT_API_KEY (Agency plan) lifts it to 10,000/day. For a deeper report (risk factors, exposure, balance) use lookup_address.", {
     address: z.string().describe("Wallet address to check (EVM 0x..., Bitcoin, or Solana)"),
     chain: z.string().optional().describe("Blockchain: ethereum, bsc, polygon, arbitrum, optimism, base, avalanche, solana, bitcoin (default: auto-detect from address format)"),
 }, async ({ address, chain }) => {
-    if (!API_KEY) {
-        return { content: [{ type: "text", text: NO_KEY_MESSAGE }] };
-    }
     try {
         const params = { address };
         if (chain)
             params.chain = chain;
         // wallet-reputation returns a flat object (no {success,data} wrapper).
-        const d = await apiGet("/wallet-reputation", params, { auth: true });
+        const { body: d, headers } = await apiGet("/wallet-reputation", params);
         const lines = [
             `## Wallet Risk Report: ${truncateAddr(d.address)}`,
             `**Address:** ${d.address}`,
             `**Chain:** ${d.chain}`,
-            `**Risk Score:** ${d.risk_score}/100 — **${(d.risk_level ?? formatRiskLevel(d.risk_score)).toUpperCase()}**`,
         ];
+        // Canon (same as chainhint.com and the TG bot): an address that is not in
+        // the labeled database has NO DATA — that is not evidence it is clean.
+        // The API still returns risk_score 0 / "clean" for not-found, so the
+        // wording is fixed here, and public incidents are cross-checked so a
+        // known hack attacker that never got an `addresses` row is not
+        // presented as unknown.
+        if (!d.found_in_db) {
+            lines.push(`**Risk:** ⚪ NO DATA — address is not in ChainHint's labeled database. This is not evidence it is clean.`);
+            const inc = await findPublicIncidentByAttacker(d.address);
+            if (inc) {
+                lines.push(`⚠️ **Known attacker in a public hack incident:** ${inc.title ?? "Unnamed incident"} (${inc.chain}, loss ${usd(inc.amount_usd ?? inc.estimated_loss_usd)}${inc.risk_score != null ? `, incident risk ${inc.risk_score}/100` : ""}). Treat as HIGH risk.`, `🔗 https://chainhint.com/incident/${inc.id}`);
+            }
+            lines.push(`Use lookup_address for an on-chain assessment (risk factors, GoPlus flags, counterparty exposure).`);
+        }
+        else {
+            lines.push(`**Risk Score:** ${d.risk_score}/100 — **${(d.risk_level ?? formatRiskLevel(d.risk_score)).toUpperCase()}**`);
+        }
         if (d.sanctions?.hit) {
             lines.push(`⛔ **SANCTIONED / OFAC-linked**`);
         }
@@ -151,6 +204,9 @@ server.tool("check_wallet_risk", "Fast risk check for a crypto wallet address ag
             lines.push(`**Type:** ${d.is_contract ? "Smart Contract" : "EOA (wallet)"}`);
         lines.push(`**In ChainHint DB:** ${d.found_in_db ? "yes" : "no"}${d.sources?.length ? ` (sources: ${d.sources.join(", ")})` : ""}`);
         lines.push(`**Checked at:** ${d.checked_at}`);
+        const quota = quotaLine(headers, "checks");
+        if (quota)
+            lines.push(``, quota);
         lines.push(`\n*Powered by ChainHint — chainhint.com*`);
         return { content: [{ type: "text", text: lines.join("\n") }] };
     }
@@ -159,7 +215,7 @@ server.tool("check_wallet_risk", "Fast risk check for a crypto wallet address ag
     }
 });
 // ── Tool 2: lookup_address ────────────────────────────────────────────────────
-server.tool("lookup_address", "Detailed lookup of a blockchain address: entity attribution, risk score with the factors behind it, sanctions and GoPlus security flags, counterparty exposure (where funds came from / went to, by category with named entities), balance, token count and transaction count. Works without an API key. Supports EVM chains, Bitcoin, Solana, TRON, TON.", {
+server.tool("lookup_address", "Detailed lookup of a blockchain address: entity attribution, risk score with the factors behind it, sanctions and GoPlus security flags, counterparty exposure (where funds came from / went to, by category with named entities), balance, token count and transaction count. Free: 10 lookups per day without a key; CHAINHINT_API_KEY lifts it. Supports EVM chains, Bitcoin, Solana, TRON, TON.", {
     address: z.string().describe("Blockchain address to look up"),
     chain: z.string().optional().describe("Blockchain (ethereum, bsc, polygon, arbitrum, optimism, base, avalanche, solana, bitcoin, tron, ton)"),
 }, async ({ address, chain }) => {
@@ -167,7 +223,7 @@ server.tool("lookup_address", "Detailed lookup of a blockchain address: entity a
         const params = { address };
         if (chain)
             params.chain = chain;
-        const data = await apiGet("/address-lookup", params, { auth: false });
+        const { body: data, headers: lookupHeaders } = await apiGet("/address-lookup", params);
         if (!data.success || !data.data) {
             return { content: [{ type: "text", text: `Error: ${data.error ?? "Unknown error"}` }] };
         }
@@ -223,6 +279,9 @@ server.tool("lookup_address", "Detailed lookup of a blockchain address: entity a
             lines.push(...formatExposure("Inflow by category", ex.inflow));
             lines.push(...formatExposure("Outflow by category", ex.outflow));
         }
+        const lookupQuota = quotaLine(lookupHeaders, "lookups");
+        if (lookupQuota)
+            lines.push(``, lookupQuota);
         lines.push(``, `🔗 https://chainhint.com/address/${d.address}?chain=${d.chain}`);
         lines.push(`*Powered by ChainHint — chainhint.com*`);
         return { content: [{ type: "text", text: lines.join("\n") }] };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "chainhint-mcp",
-  "version": "1.0.1",
+  "version": "1.1.0",
   "description": "ChainHint MCP server — crypto risk intelligence tools for Claude Desktop and Cursor",
   "license": "MIT",
   "repository": {