chainhint-mcp 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ChainHint
+
+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

@@ -0,0 +1,88 @@
+# ChainHint MCP Server
+
+Crypto risk intelligence for Claude Desktop, Cursor, and any MCP-compatible AI.
+
+## Tools
+
+| Tool | Description |
+|------|-------------|
+| `check_wallet_risk` | Risk score, entity label, sanctions check for any wallet |
+| `lookup_address` | Full address details — entity, category, tx history |
+| `get_trace_status` | Fund trace status for hack incidents — where did the money go? |
+
+## Requirements
+
+- Node.js 18+
+- ChainHint Agency plan API key (`ch_live_...`) from [chainhint.com/settings](https://chainhint.com/settings)
+
+## Install
+
+No install needed — run straight from npm with `npx` (see configs below).
+
+From source instead:
+
+```bash
+git clone https://github.com/seomarlboro/chainhint-mcp
+cd chainhint-mcp
+npm install
+npm run build
+# then use "command": "node", "args": ["/absolute/path/to/chainhint-mcp/dist/index.js"]
+```
+
+## Claude Desktop
+
+Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "chainhint": {
+      "command": "npx",
+      "args": ["-y", "chainhint-mcp"],
+      "env": {
+        "CHAINHINT_API_KEY": "ch_live_your_key_here"
+      }
+    }
+  }
+}
+```
+
+## Cursor
+
+Add to `.cursor/mcp.json` in your project (or global `~/.cursor/mcp.json`):
+
+```json
+{
+  "mcpServers": {
+    "chainhint": {
+      "command": "npx",
+      "args": ["-y", "chainhint-mcp"],
+      "env": {
+        "CHAINHINT_API_KEY": "ch_live_your_key_here"
+      }
+    }
+  }
+}
+```
+
+## Development (no build step)
+
+```bash
+npm run dev
+```
+
+## Environment Variables
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `CHAINHINT_API_KEY` | ✅ | API key from chainhint.com (Agency plan) |
+| `CHAINHINT_API_URL` | — | Override API base URL (default: production) |
+| `CHAINHINT_SUPABASE_ANON_KEY` | — | For get_trace_status (public incidents) |
+
+## Example prompts
+
+> "Check if 0x47666fab8bd0ac7003bce3f5c3585383f09486e2 is a known hacker"
+
+> "Look up the Bybit attacker address on Ethereum"
+
+> "What's the trace status for attacker 0x47666fab..."

package/dist/index.d.ts

@@ -0,0 +1,15 @@
+#!/usr/bin/env node
+/**
+ * ChainHint MCP Server
+ *
+ * Provides crypto risk intelligence tools to Claude Desktop, Cursor,
+ * and any MCP-compatible AI client.
+ *
+ * Tools:
+ *   - check_wallet_risk   → wallet-reputation API (risk score, labels, sanctions)
+ *   - lookup_address      → address-lookup API (entity, category, transaction history)
+ *   - get_trace_status    → incident fund trace status (flow graph summary)
+ *
+ * Auth: set CHAINHINT_API_KEY env var (Agency plan API key: ch_live_...)
+ */
+export {};

package/dist/index.js

@@ -0,0 +1,253 @@
+#!/usr/bin/env node
+/**
+ * ChainHint MCP Server
+ *
+ * Provides crypto risk intelligence tools to Claude Desktop, Cursor,
+ * and any MCP-compatible AI client.
+ *
+ * Tools:
+ *   - check_wallet_risk   → wallet-reputation API (risk score, labels, sanctions)
+ *   - lookup_address      → address-lookup API (entity, category, transaction history)
+ *   - get_trace_status    → incident fund trace status (flow graph summary)
+ *
+ * Auth: set CHAINHINT_API_KEY env var (Agency plan API key: ch_live_...)
+ */
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+// ── 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";
+if (!API_KEY) {
+    console.error("[chainhint-mcp] ERROR: CHAINHINT_API_KEY is not set.");
+    console.error("  Get your API key from chainhint.com → Settings → API Keys (Agency plan required)");
+    process.exit(1);
+}
+// ── HTTP helpers ──────────────────────────────────────────────────────────────
+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 res = await fetch(url.toString(), {
+        headers: {
+            "X-Api-Key": API_KEY,
+            "Authorization": `Bearer ${API_KEY}`,
+            "Content-Type": "application/json",
+        },
+    });
+    const body = await res.json().catch(() => ({ error: `HTTP ${res.status}` }));
+    if (!res.ok) {
+        throw new Error(body?.error ?? `HTTP ${res.status}: ${url.toString()}`);
+    }
+    return body;
+}
+async function supabaseGet(table, params) {
+    const url = new URL(`${SUPABASE_URL}/rest/v1/${table}`);
+    for (const [k, v] of Object.entries(params)) {
+        url.searchParams.set(k, v);
+    }
+    const res = await fetch(url.toString(), {
+        headers: {
+            "apikey": SUPABASE_ANON_KEY,
+            "Authorization": `Bearer ${SUPABASE_ANON_KEY}`,
+            "X-Api-Key": API_KEY,
+            "Accept": "application/json",
+        },
+    });
+    if (!res.ok) {
+        const err = await res.text();
+        throw new Error(`Supabase ${res.status}: ${err}`);
+    }
+    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;
+}
+// ── MCP Server ────────────────────────────────────────────────────────────────
+const server = new McpServer({
+    name: "chainhint",
+    version: "1.0.0",
+});
+// ── Tool 1: check_wallet_risk ─────────────────────────────────────────────────
+server.tool("check_wallet_risk", "Check the risk score and labels for a crypto wallet address. Returns risk level (CLEAN/LOW/MEDIUM/HIGH/CRITICAL), entity label, category, sanctions status, and transaction statistics. Use this to assess whether a wallet is associated with hacks, scams, mixers, or sanctioned entities.", {
+    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 }) => {
+    try {
+        const params = { address };
+        if (chain)
+            params.chain = chain;
+        const data = await apiGet("/wallet-reputation", params);
+        if (!data.success || !data.data) {
+            return { content: [{ type: "text", text: `Error: ${data.error ?? "Unknown error"}` }] };
+        }
+        const d = data.data;
+        const risk = d.risk;
+        const entity = d.entity;
+        const sanctions = d.sanctions;
+        const stats = d.stats;
+        const lines = [
+            `## Wallet Risk Report: ${truncateAddr(d.address)}`,
+            `**Chain:** ${d.chain}`,
+            `**Risk Score:** ${risk?.score ?? "N/A"}/100 — **${risk?.level ?? formatRiskLevel(risk?.score ?? 0)}**`,
+        ];
+        if (entity?.name) {
+            lines.push(`**Entity:** ${entity.name} (${entity.category})`);
+            if (entity.label)
+                lines.push(`**Label:** ${entity.label}`);
+        }
+        else {
+            lines.push(`**Entity:** Unknown / unlabeled`);
+        }
+        if (sanctions?.is_sanctioned) {
+            lines.push(`⛔ **SANCTIONED** — Programs: ${sanctions.programs.join(", ")}`);
+        }
+        if (risk?.flags?.length) {
+            lines.push(`**Risk Flags:** ${risk.flags.join(", ")}`);
+        }
+        if (stats) {
+            lines.push(`**Transactions:** ${stats.tx_count?.toLocaleString() ?? "N/A"}`);
+            if (stats.first_seen)
+                lines.push(`**First seen:** ${stats.first_seen.slice(0, 10)}`);
+            if (stats.last_seen)
+                lines.push(`**Last seen:** ${stats.last_seen.slice(0, 10)}`);
+        }
+        lines.push(`\n*Powered by ChainHint — chainhint.com*`);
+        return { content: [{ type: "text", text: lines.join("\n") }] };
+    }
+    catch (err) {
+        return { content: [{ type: "text", text: `Error checking wallet: ${err.message}` }] };
+    }
+});
+// ── Tool 2: lookup_address ────────────────────────────────────────────────────
+server.tool("lookup_address", "Look up detailed information about a blockchain address including entity label, risk assessment, transaction history, and known associations. More detailed than check_wallet_risk — includes transaction counts, token holdings summary, and entity metadata.", {
+    address: z.string().describe("Blockchain address to look up"),
+    chain: z.string().optional().describe("Blockchain (ethereum, bsc, polygon, arbitrum, optimism, base, avalanche, solana, bitcoin)"),
+}, async ({ address, chain }) => {
+    try {
+        const params = { address };
+        if (chain)
+            params.chain = chain;
+        const data = await apiGet("/address-lookup", params);
+        if (!data.success || !data.data) {
+            return { content: [{ type: "text", text: `Error: ${data.error ?? "Unknown error"}` }] };
+        }
+        const d = data.data;
+        const lines = [
+            `## Address Lookup: ${truncateAddr(d.address)}`,
+            `**Chain:** ${d.chain}`,
+            `**Type:** ${d.is_contract ? "Smart Contract" : "EOA (wallet)"}`,
+        ];
+        if (d.entity)
+            lines.push(`**Entity:** ${d.entity}`);
+        if (d.label)
+            lines.push(`**Label:** ${d.label}`);
+        if (d.category)
+            lines.push(`**Category:** ${d.category}`);
+        if (d.balance)
+            lines.push(`**Balance:** ${d.balance}`);
+        const score = d.risk?.score;
+        if (score !== undefined) {
+            lines.push(`**Risk Score:** ${score}/100 — ${formatRiskLevel(score)}`);
+        }
+        if (d.risk?.flags?.length) {
+            lines.push(`**Flags:** ${d.risk.flags.join(", ")}`);
+        }
+        if (d.sanctions?.is_sanctioned) {
+            lines.push(`⛔ **SANCTIONED**`);
+        }
+        if (d.tx_count)
+            lines.push(`**Transactions:** ${d.tx_count.toLocaleString()}`);
+        if (d.first_seen)
+            lines.push(`**First seen:** ${d.first_seen.slice(0, 10)}`);
+        if (d.last_seen)
+            lines.push(`**Last seen:** ${d.last_seen.slice(0, 10)}`);
+        lines.push(`\n*Powered by ChainHint — chainhint.com*`);
+        return { content: [{ type: "text", text: lines.join("\n") }] };
+    }
+    catch (err) {
+        return { content: [{ type: "text", text: `Error looking up address: ${err.message}` }] };
+    }
+});
+// ── Tool 3: get_trace_status ──────────────────────────────────────────────────
+server.tool("get_trace_status", "Get the fund trace status for a crypto hack incident. Returns how stolen funds moved — number of hops, total amount traced, known endpoints (exchanges, mixers, bridges), and current movement status (in_transit, mixing, reached_exchange, dormant). Useful for incident response and understanding where stolen funds went.", {
+    attacker_address: z.string().optional().describe("Attacker wallet address to look up incident by"),
+    incident_id: z.string().optional().describe("Incident UUID (from chainhint.com) — alternative to attacker_address"),
+}, async ({ attacker_address, incident_id }) => {
+    try {
+        if (!attacker_address && !incident_id) {
+            return { content: [{ type: "text", text: "Error: provide either attacker_address or incident_id" }] };
+        }
+        // Query public incidents via Supabase REST
+        let queryParams = {
+            select: "id,title,status,chain,attacker_address,amount_usd,estimated_loss_usd,created_at,source",
+            is_public: "eq.true",
+            limit: "1",
+            order: "created_at.desc",
+        };
+        if (incident_id) {
+            queryParams["id"] = `eq.${incident_id}`;
+            delete queryParams["is_public"];
+        }
+        else if (attacker_address) {
+            queryParams["attacker_address"] = `eq.${attacker_address.toLowerCase()}`;
+        }
+        const rows = await supabaseGet("incidents", queryParams);
+        if (!rows?.length) {
+            return {
+                content: [{
+                        type: "text",
+                        text: attacker_address
+                            ? `No public incident found for attacker address ${attacker_address}.\nCheck https://chainhint.com/velocity for tracked incidents.`
+                            : `Incident ${incident_id} not found or not public.`,
+                    }],
+            };
+        }
+        const inc = rows[0];
+        const lossUsd = inc.amount_usd ?? inc.estimated_loss_usd;
+        const lines = [
+            `## Fund Trace: ${inc.title ?? "Unnamed Incident"}`,
+            `**Incident ID:** ${inc.id}`,
+            `**Chain:** ${inc.chain}`,
+            `**Status:** ${inc.status.toUpperCase()}`,
+            `**Attacker:** ${truncateAddr(inc.attacker_address)}`,
+            `**Loss:** ${lossUsd ? `$${(lossUsd / 1_000_000).toFixed(2)}M` : "Unknown"}`,
+            `**Date:** ${inc.created_at.slice(0, 10)}`,
+        ];
+        if (inc.status.toLowerCase() === "traced") {
+            lines.push(`\n✅ Trace complete — view full flow graph and counterparty exposure on ChainHint.`);
+        }
+        else if (inc.status.toLowerCase() === "analyzing") {
+            lines.push(`\n⏳ Trace in progress...`);
+        }
+        else {
+            lines.push(`\n⚠️ Status: ${inc.status}`);
+        }
+        lines.push(`\n🔗 View full trace: https://chainhint.com/incident/${inc.id}`);
+        lines.push(`*Powered by ChainHint — chainhint.com*`);
+        return { content: [{ type: "text", text: lines.join("\n") }] };
+    }
+    catch (err) {
+        return { content: [{ type: "text", text: `Error fetching trace: ${err.message}` }] };
+    }
+});
+// ── Start ─────────────────────────────────────────────────────────────────────
+const transport = new StdioServerTransport();
+await server.connect(transport);
+console.error("[chainhint-mcp] Server running on stdio");

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "chainhint-mcp",
+  "version": "1.0.0",
+  "description": "ChainHint MCP server — crypto risk intelligence tools for Claude Desktop and Cursor",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/seomarlboro/chainhint-mcp.git"
+  },
+  "homepage": "https://chainhint.com/docs/api",
+  "main": "dist/index.js",
+  "type": "module",
+  "bin": {
+    "chainhint-mcp": "dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "crypto",
+    "blockchain",
+    "wallet",
+    "risk",
+    "aml",
+    "sanctions",
+    "forensics",
+    "claude"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsx src/index.ts",
+    "start": "node dist/index.js",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "tsx": "^4.0.0",
+    "typescript": "^5.0.0"
+  }
+}