chainhint-mcp 1.3.1 → 1.3.2

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.3.1";
+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;
 }
@@ -340,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);
@@ -497,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.1",
-  "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",