chainhint-mcp 1.3.0 → 1.3.2

package/README.md

@@ -86,6 +86,8 @@ Add an Agency key to the server entry (any client):
 Free tier: 2 of 3 checks left today — set CHAINHINT_API_KEY (Agency plan, https://chainhint.com/pricing) for 10,000/day.
 ```
 
+When the address is in ChainHint's agent-infrastructure registry (agent-token launchpads, deployer factories, routers, payment facilitators, known agent wallets), the report adds an `🤖` line, e.g. *Known agent infrastructure: Virtuals launchpad* — a registry fact you can verify at its source, not a behavioural classification and not part of the risk score.
+
 ## Development (no build step)
 
 ```bash

package/dist/index.js

@@ -17,12 +17,13 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { z } from "zod";
+import { apiErrorMessage, formatRiskLevel, lookupRiskLines, traceStatusLine } from "./verdicts.js";
 // ── Config ────────────────────────────────────────────────────────────────────
 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 VERSION = "1.1.0";
+const VERSION = "1.3.2";
 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";
@@ -49,11 +50,7 @@ async function apiGet(path, params) {
     const res = await fetch(url.toString(), { headers });
     const body = (await res.json().catch(() => ({ error: `HTTP ${res.status}` })));
     if (!res.ok) {
-        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);
+        throw new Error(apiErrorMessage(res.status, body?.error, url.toString(), body?.reset_at));
     }
     return { body, headers: res.headers };
 }
@@ -91,17 +88,6 @@ async function supabaseGet(table, params) {
     return res.json();
 }
 // ── Format helpers ────────────────────────────────────────────────────────────
-function formatRiskLevel(score) {
-    if (score >= 90)
-        return "CRITICAL";
-    if (score >= 70)
-        return "HIGH";
-    if (score >= 40)
-        return "MEDIUM";
-    if (score >= 10)
-        return "LOW";
-    return "CLEAN";
-}
 function truncateAddr(addr) {
     return addr.length > 12 ? `${addr.slice(0, 8)}...${addr.slice(-6)}` : addr;
 }
@@ -196,11 +182,29 @@ function formatExposure(label, buckets) {
         }),
     ];
 }
+/**
+ * Same rule as chainhint.com (src/lib/attackerAttribution.ts): an address is
+ * "the attacker" only when the attribution was checked against the exploit
+ * transaction (attacker_address_source = analyst_verified). Everything else is
+ * a report — shown as one, and never as a HIGH-risk verdict.
+ */
+function attackerAttribution(inc) {
+    if (!inc.attacker_address)
+        return { verified: false, label: "Attacker not identified" };
+    if (inc.attacker_address_source === "analyst_verified")
+        return { verified: true, label: "Attacker" };
+    return {
+        verified: false,
+        label: inc.source === "defillama"
+            ? "Reported attacker (DeFiLlama), unverified"
+            : "Reported attacker (user-provided), unverified",
+    };
+}
 /** 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",
+            select: "id,title,chain,amount_usd,estimated_loss_usd,risk_score,source,attacker_address_source",
             attacker_address: `eq.${normalizeAddr(address)}`,
             limit: "1",
         });
@@ -241,7 +245,11 @@ server.tool("check_wallet_risk", "Fast risk check for a crypto wallet address ag
             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}`);
+                const attribution = attackerAttribution({ attacker_address: d.address, ...inc });
+                const where = `${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` : ""})`;
+                lines.push(attribution.verified
+                    ? `⚠️ **Verified attacker in a public hack incident:** ${where}. The attribution was checked against the exploit transaction. Treat as HIGH risk.`
+                    : `ℹ️ **${attribution.label}, in a public hack incident:** ${where}. This attribution has not been verified against the exploit transaction — treat it as a lead to check, not as a risk verdict.`, `🔗 https://chainhint.com/incident/${inc.id}`);
             }
             lines.push(`Use lookup_address for an on-chain assessment (risk factors, GoPlus flags, counterparty exposure).`);
         }
@@ -318,15 +326,8 @@ server.tool("lookup_address", "Detailed lookup of a blockchain address: entity a
         }
         if (d.labels?.length)
             lines.push(`**Labels:** ${[...new Set(d.labels)].join(", ")}`);
-        if (d.risk) {
-            const level = (d.risk.level ?? formatRiskLevel(d.risk.score)).toUpperCase();
-            lines.push(`**Risk Score:** ${d.risk.score}/100 — **${level}**`);
-            const factors = Object.entries(d.risk.factors ?? {}).filter(([, v]) => v).map(([k]) => k);
-            if (factors.length)
-                lines.push(`**Risk Factors:** ${factors.join(", ")}`);
-            if (d.risk.details?.length)
-                lines.push(`**Risk Details:** ${d.risk.details.join("; ")}`);
-        }
+        // Never a score or "CLEAN" when there was nothing to score (verdicts.ts).
+        lines.push(...lookupRiskLines(d));
         const sanctionIds = d.sanctions?.identifications ?? [];
         if (sanctionIds.length) {
             const names = sanctionIds.map((s) => [s.name, s.program].filter(Boolean).join(" / ")).filter(Boolean);
@@ -375,7 +376,7 @@ server.tool("get_trace_status", "Fund-trace summary for a publicly tracked crypt
         // public_incidents_view is the canonical anonymous read path (SECURITY DEFINER,
         // exposes only is_public rows and only public-safe columns).
         const queryParams = {
-            select: "id,title,status,chain,attacker_address,amount_usd,estimated_loss_usd,risk_score,incident_type,hack_date,display_date,created_at,updated_at,source,endpoints,flow_graph,counterparty_exposure",
+            select: "id,title,status,chain,attacker_address,attacker_address_source,amount_usd,estimated_loss_usd,risk_score,incident_type,hack_date,display_date,created_at,updated_at,source,endpoints,flow_graph,counterparty_exposure",
             limit: "1",
             order: "created_at.desc",
         };
@@ -406,7 +407,7 @@ server.tool("get_trace_status", "Fund-trace summary for a publicly tracked crypt
             `**Incident ID:** ${inc.id}`,
             `**Chain:** ${inc.chain}`,
             `**Status:** ${status.toUpperCase()}`,
-            `**Attacker:** ${inc.attacker_address}`,
+            `**${attackerAttribution(inc).label}:** ${inc.attacker_address ?? "—"}`,
             `**Loss:** ${usd(lossUsd)}`,
             `**Date:** ${date.slice(0, 10)}`,
         ];
@@ -475,15 +476,8 @@ server.tool("get_trace_status", "Fund-trace summary for a publicly tracked crypt
             lines.push(...formatExposure("Inflow by category", cx.inflow));
         }
         lines.push(``);
-        if (status === "traced") {
-            lines.push(`✅ Trace complete — full flow graph and counterparty exposure on ChainHint.`);
-        }
-        else if (status === "analyzing") {
-            lines.push(`⏳ Trace in progress...`);
-        }
-        else {
-            lines.push(`⚠️ Status: ${status}`);
-        }
+        // "✅ Trace complete" only for a trace that holds transfers (verdicts.ts).
+        lines.push(traceStatusLine({ status, chain: inc.chain, attacker_address: inc.attacker_address, edgeCount: edges.length }));
         lines.push(`🔗 View full trace: https://chainhint.com/incident/${inc.id}`);
         lines.push(`*Powered by ChainHint — chainhint.com*`);
         return { content: [{ type: "text", text: lines.join("\n") }] };

package/dist/verdicts.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Verdict wording — pure functions, tested in test/verdicts.test.mjs.
+ *
+ * One rule, the same as chainhint.com (KIR-83): when ChainHint could not read
+ * the data, the tool says so. A missing input is never printed as "CLEAN",
+ * "0/100" or "Trace complete".
+ *
+ * 1.3.1 and earlier printed "Risk Score: 0/100 — CLEAN" for a Solana address
+ * whose transfer history could not be read (the API already returned
+ * risk_status "unavailable") and "✅ Trace complete" for an incident whose
+ * stored trace had no transfers.
+ */
+/**
+ * The 12 chains ChainHint traces. Mirror of CHAINS in the backend
+ * (backend/supabase/functions/_shared/address-validation.ts in the main repo).
+ */
+export declare const TRACEABLE_CHAINS: readonly ["ethereum", "bsc", "polygon", "arbitrum", "optimism", "base", "avalanche", "gnosis", "bitcoin", "solana", "tron", "ton"];
+export declare function isTraceableChain(chain: string | null | undefined): boolean;
+/** Same sentence as the backend's tracingUnavailableMessage. */
+export declare function tracingUnavailableMessage(chain: string | null | undefined): string;
+export declare function formatRiskLevel(score: number): string;
+export type DataUnavailable = {
+    provider?: string;
+    reason?: string;
+};
+export interface LookupRiskInput {
+    risk?: {
+        score: number;
+        level?: string;
+        factors?: Record<string, boolean>;
+        details?: string[];
+    };
+    /** address-lookup: "scored" | "insufficient_data" | "unavailable". Absent on old API versions. */
+    risk_status?: string;
+    data_availability?: {
+        transfers?: string;
+        provider?: string;
+        reason?: string;
+        detail?: string;
+    };
+    exposure?: {
+        data_unavailable?: DataUnavailable | null;
+    } | null;
+}
+/** The risk lines of lookup_address. Never a score when there was nothing to score. */
+export declare function lookupRiskLines(d: LookupRiskInput): string[];
+export interface TraceStatusInput {
+    status: string | null | undefined;
+    chain: string | null | undefined;
+    attacker_address: string | null | undefined;
+    edgeCount: number;
+}
+/** The closing status line of get_trace_status. "✅" only for a trace that holds transfers. */
+export declare function traceStatusLine(inc: TraceStatusInput): string;
+/**
+ * HTTP errors. A 422 is ChainHint's final answer ("Tracing not available for
+ * Sui") — say so, so an agent does not retry it as a transient failure.
+ */
+export declare function apiErrorMessage(status: number, bodyError: string | undefined, url: string, resetAt?: number): string;

package/dist/verdicts.js

@@ -0,0 +1,110 @@
+/**
+ * Verdict wording — pure functions, tested in test/verdicts.test.mjs.
+ *
+ * One rule, the same as chainhint.com (KIR-83): when ChainHint could not read
+ * the data, the tool says so. A missing input is never printed as "CLEAN",
+ * "0/100" or "Trace complete".
+ *
+ * 1.3.1 and earlier printed "Risk Score: 0/100 — CLEAN" for a Solana address
+ * whose transfer history could not be read (the API already returned
+ * risk_status "unavailable") and "✅ Trace complete" for an incident whose
+ * stored trace had no transfers.
+ */
+/**
+ * The 12 chains ChainHint traces. Mirror of CHAINS in the backend
+ * (backend/supabase/functions/_shared/address-validation.ts in the main repo).
+ */
+export const TRACEABLE_CHAINS = [
+    "ethereum", "bsc", "polygon", "arbitrum", "optimism", "base",
+    "avalanche", "gnosis", "bitcoin", "solana", "tron", "ton",
+];
+export function isTraceableChain(chain) {
+    return typeof chain === "string" && TRACEABLE_CHAINS.includes(chain.trim().toLowerCase());
+}
+/** Same sentence as the backend's tracingUnavailableMessage. */
+export function tracingUnavailableMessage(chain) {
+    const c = (chain ?? "").trim();
+    if (!c || c.toLowerCase() === "unknown")
+        return "Tracing not available — the chain is unknown";
+    return `Tracing not available for ${c.charAt(0).toUpperCase()}${c.slice(1)}`;
+}
+export function formatRiskLevel(score) {
+    if (score >= 90)
+        return "CRITICAL";
+    if (score >= 70)
+        return "HIGH";
+    if (score >= 40)
+        return "MEDIUM";
+    if (score >= 10)
+        return "LOW";
+    return "CLEAN";
+}
+function unavailableDetail(d) {
+    const provider = d.data_availability?.provider ?? d.exposure?.data_unavailable?.provider;
+    return d.data_availability?.detail
+        ?? `transfer data${provider ? ` (${provider})` : ""} could not be read`;
+}
+/** The API's detail may already say "not a clean result" — don't say it twice. */
+function notClean(detail) {
+    return /not a clean result/i.test(detail) ? "" : " This is not a clean result.";
+}
+/** The risk lines of lookup_address. Never a score when there was nothing to score. */
+export function lookupRiskLines(d) {
+    if (d.risk_status === "unavailable") {
+        const why = unavailableDetail(d);
+        return [`**Risk:** ⚪ DATA UNAVAILABLE — ${why}.${notClean(why)} No risk score was computed.`];
+    }
+    if (d.risk_status === "insufficient_data") {
+        return [
+            `**Risk:** ⚪ NOT SCORED — insufficient data. This is not evidence the address is clean.`,
+        ];
+    }
+    if (!d.risk)
+        return [];
+    const level = (d.risk.level ?? formatRiskLevel(d.risk.score)).toUpperCase();
+    const lines = [`**Risk Score:** ${d.risk.score}/100 — **${level}**`];
+    const factors = Object.entries(d.risk.factors ?? {}).filter(([, v]) => v).map(([k]) => k);
+    if (factors.length)
+        lines.push(`**Risk Factors:** ${factors.join(", ")}`);
+    if (d.risk.details?.length)
+        lines.push(`**Risk Details:** ${d.risk.details.join("; ")}`);
+    // Scored from other inputs (DB entity, sanctions), but the transfer side was missing.
+    if (d.exposure?.data_unavailable || d.data_availability?.transfers === "unavailable") {
+        const why = unavailableDetail(d);
+        lines.push(`**Counterparty Exposure:** not scored — ${why}.${notClean(why)} The score above does not include transfer exposure.`);
+    }
+    return lines;
+}
+/** The closing status line of get_trace_status. "✅" only for a trace that holds transfers. */
+export function traceStatusLine(inc) {
+    const status = (inc.status ?? "unknown").toLowerCase();
+    if (!isTraceableChain(inc.chain)) {
+        return `⚪ ${tracingUnavailableMessage(inc.chain)}. ChainHint traces 12 networks; this incident and its loss figure come from the hack feed, and no fund flow was fetched. That is final, and it is not evidence that the funds did not move.`;
+    }
+    if (inc.edgeCount > 0 && (status === "traced" || status === "monitoring")) {
+        return `✅ Trace complete — full flow graph and counterparty exposure on ChainHint.`;
+    }
+    if (status === "analyzing")
+        return `⏳ Trace in progress...`;
+    if (!inc.attacker_address) {
+        return `⚪ Not traced — this incident has no attacker address to trace from.`;
+    }
+    if (status === "traced" || status === "monitoring") {
+        return `⚠️ No transfers in the stored trace. This is not evidence that the funds are dormant: the chain's transfer provider may have been unavailable, or the address may not belong to this chain.`;
+    }
+    return `⚠️ Status: ${status}`;
+}
+/**
+ * HTTP errors. A 422 is ChainHint's final answer ("Tracing not available for
+ * Sui") — say so, so an agent does not retry it as a transient failure.
+ */
+export function apiErrorMessage(status, bodyError, url, resetAt) {
+    let msg = bodyError ?? `HTTP ${status}: ${url}`;
+    if (status === 422)
+        msg += " (final answer — not a temporary error; do not retry)";
+    if (status === 429 && resetAt)
+        msg += ` Resets at ${new Date(resetAt * 1000).toISOString()}.`;
+    if (status === 503)
+        msg += " (the data provider is unavailable — this is not a clean result)";
+    return msg;
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "chainhint-mcp",
-  "version": "1.3.0",
-  "description": "ChainHint MCP server — crypto risk intelligence tools for Claude Desktop and Cursor",
+  "version": "1.3.2",
+  "description": "ChainHint MCP server \u2014 crypto risk intelligence tools for Claude Desktop and Cursor",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -35,7 +35,8 @@
     "build": "tsc",
     "dev": "tsx src/index.ts",
     "start": "node dist/index.js",
-    "prepublishOnly": "npm run build"
+    "prepublishOnly": "npm run build",
+    "test": "npm run build && node --test test/*.test.mjs"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.0.0",