chainhint-mcp 1.3.1 → 1.3.3

package/dist/evidence.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Address evidence wording — MIRROR of the main repo's
+ * backend/supabase/functions/_shared/evidence-labels.ts (migration 129).
+ * Change both or neither; test/evidence.test.mjs pins the strings.
+ *
+ * Rule (owner decision 2026-09-14): "Sanctioned" is printed only for a
+ * sanctions designation. A law-enforcement attribution, an issuer freeze, a
+ * national seizure order and an industry blocklist each say what they are and
+ * that they are not a sanctions designation.
+ */
+export declare const EVIDENCE_CLASSES: readonly ["sanctions_designation", "law_enforcement_attribution", "issuer_freeze", "national_seizure_order", "industry_blocklist", "analyst_verified"];
+export type EvidenceClass = typeof EVIDENCE_CLASSES[number];
+export interface EvidenceItem {
+    class: EvidenceClass | string;
+    authority: string;
+    subject?: string | null;
+    document_ref?: string | null;
+    document_url?: string | null;
+    document_date?: string | null;
+    legal_basis?: string | null;
+    token?: string | null;
+    chain?: string | null;
+    first_seen_at?: string | null;
+}
+export declare const NOT_A_SANCTIONS_DESIGNATION = "Not a sanctions designation.";
+/** "⛔ Sanctioned — US OFAC · … " / "🧊 Frozen by issuer — Tether (USDT, TRON) · … Not a sanctions designation." */
+export declare function evidenceText(e: EvidenceItem): string | null;
+/** Designations first, then by strength of proof; unknown classes dropped. */
+export declare function evidenceLines(items: ReadonlyArray<EvidenceItem> | null | undefined): string[];

package/dist/evidence.js

@@ -0,0 +1,88 @@
+/**
+ * Address evidence wording — MIRROR of the main repo's
+ * backend/supabase/functions/_shared/evidence-labels.ts (migration 129).
+ * Change both or neither; test/evidence.test.mjs pins the strings.
+ *
+ * Rule (owner decision 2026-09-14): "Sanctioned" is printed only for a
+ * sanctions designation. A law-enforcement attribution, an issuer freeze, a
+ * national seizure order and an industry blocklist each say what they are and
+ * that they are not a sanctions designation.
+ */
+export const EVIDENCE_CLASSES = [
+    "sanctions_designation",
+    "law_enforcement_attribution",
+    "issuer_freeze",
+    "national_seizure_order",
+    "industry_blocklist",
+    "analyst_verified",
+];
+export const NOT_A_SANCTIONS_DESIGNATION = "Not a sanctions designation.";
+const TITLES = {
+    sanctions_designation: { icon: "⛔", title: "Sanctioned" },
+    law_enforcement_attribution: { icon: "🚩", title: "Law-enforcement attribution" },
+    issuer_freeze: { icon: "🧊", title: "Frozen by issuer" },
+    national_seizure_order: { icon: "🏛️", title: "National seizure order" },
+    industry_blocklist: { icon: "⚠️", title: "Industry blocklist" },
+    analyst_verified: { icon: "🔎", title: "Analyst-verified" },
+};
+const CHAIN_NAMES = { bsc: "BSC", tron: "TRON", ton: "TON" };
+function isEvidenceClass(v) {
+    return typeof v === "string" && EVIDENCE_CLASSES.includes(v);
+}
+function chainName(chain) {
+    const c = (chain ?? "").trim().toLowerCase();
+    if (!c)
+        return "";
+    return CHAIN_NAMES[c] ?? c.charAt(0).toUpperCase() + c.slice(1);
+}
+function day(value) {
+    if (!value)
+        return null;
+    const m = /^(\d{4}-\d{2}-\d{2})/.exec(value.trim());
+    return m ? m[1] : null;
+}
+const join = (parts, sep) => parts.filter((p) => !!p && p.trim() !== "").join(sep);
+function attributionLine(e) {
+    const date = day(e.document_date);
+    let head = join([e.authority, e.document_ref], ", ");
+    if (date)
+        head = `${head} (${date})`;
+    return e.subject ? `${head}: ${e.subject}` : head;
+}
+/** "⛔ Sanctioned — US OFAC · … " / "🧊 Frozen by issuer — Tether (USDT, TRON) · … Not a sanctions designation." */
+export function evidenceText(e) {
+    if (!isEvidenceClass(e.class))
+        return null;
+    const { icon, title } = TITLES[e.class];
+    const date = day(e.document_date);
+    let line;
+    switch (e.class) {
+        case "sanctions_designation":
+            line = join([e.authority, e.document_ref ?? e.legal_basis, date, e.subject], " · ");
+            break;
+        case "issuer_freeze": {
+            const what = join([e.token, chainName(e.chain)], ", ");
+            const when = date ?? join(["first seen by ChainHint", day(e.first_seen_at)], " ");
+            line = join([what ? `${e.authority} (${what})` : e.authority, when], " · ");
+            break;
+        }
+        case "law_enforcement_attribution":
+        case "national_seizure_order":
+            line = attributionLine(e);
+            break;
+        default:
+            line = join([e.authority, e.subject, date ?? (e.first_seen_at ? `first seen by ChainHint ${day(e.first_seen_at)}` : null)], " · ");
+    }
+    const caveat = e.class === "sanctions_designation" ? null : NOT_A_SANCTIONS_DESIGNATION;
+    return `${icon} ${caveat ? `${title} — ${line}. ${caveat}` : `${title} — ${line}`}`;
+}
+/** Designations first, then by strength of proof; unknown classes dropped. */
+export function evidenceLines(items) {
+    if (!items?.length)
+        return [];
+    const rank = (c) => EVIDENCE_CLASSES.indexOf(c);
+    return [...items]
+        .filter((e) => isEvidenceClass(e.class))
+        .sort((a, b) => rank(a.class) - rank(b.class))
+        .map((e) => `- ${evidenceText(e)}`);
+}

package/dist/index.js

@@ -17,12 +17,14 @@
 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";
+import { evidenceLines } from "./evidence.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.3.1";
+const VERSION = "1.3.3";
 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 +51,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 +89,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;
 }
@@ -270,9 +257,14 @@ server.tool("check_wallet_risk", "Fast risk check for a crypto wallet address ag
         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**`);
+        // sanctions.hit comes only from a sanctions designation (API since migration 129);
+        // the evidence lines say which authority and that other classes are not sanctions.
+        const walletEvidence = evidenceLines(d.evidence);
+        if (d.sanctions?.hit && !walletEvidence.some((l) => l.startsWith("- ⛔"))) {
+            lines.push(`⛔ **SANCTIONED**`);
         }
+        if (walletEvidence.length)
+            lines.push(`**Evidence:**`, ...walletEvidence);
         if (d.entity?.name) {
             const sub = d.entity.subcategory ? ` / ${d.entity.subcategory}` : "";
             const ver = d.entity.verified ? ", verified" : "";
@@ -340,15 +332,11 @@ 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 lookupEvidence = evidenceLines(d.evidence);
+        if (lookupEvidence.length)
+            lines.push(`**Evidence:**`, ...lookupEvidence);
         const sanctionIds = d.sanctions?.identifications ?? [];
         if (sanctionIds.length) {
             const names = sanctionIds.map((s) => [s.name, s.program].filter(Boolean).join(" / ")).filter(Boolean);
@@ -497,15 +485,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.1",
-  "description": "ChainHint MCP server — crypto risk intelligence tools for Claude Desktop and Cursor",
+  "version": "1.3.3",
+  "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",