cabal-hunter-mcp 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Cabal-Hunter
+
+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,95 @@
+# cabal-hunter-mcp
+
+**On-chain Solana cabal & rug detection as an MCP server.** One tool — `check_cabal_risk` — scans any Solana token mint *before your agent buys* and returns an **Exit-Liquidity Risk** verdict (`SAFE | REVIEW | AVOID`), a 0–100 cabal score, funding-cluster detection, same-block Jito-bundle detection, coordinated-dump detection, serial-rug **deployer history** ("launched 14, 13 dead"), and a Solana-native **honeypot** check (freeze authority + Token-2022 traps). Every flag links to its on-chain evidence transaction.
+
+[![npm](https://img.shields.io/npm/v/cabal-hunter-mcp?color=cb3837&logo=npm)](https://www.npmjs.com/package/cabal-hunter-mcp)
+[![MCP server](https://img.shields.io/badge/MCP-server-7c3aed)](https://api.cabal-hunter.com/mcp)
+[![Solana](https://img.shields.io/badge/Solana-on--chain-14F195)](https://api.cabal-hunter.com)
+[![Free tier](https://img.shields.io/badge/250%2Fmo%20free-no%20API%20key-10b981)](https://api.cabal-hunter.com/api/info)
+[![License: MIT](https://img.shields.io/badge/license-MIT-94a3b8)](LICENSE)
+
+Contract-clean is **not** cabal-clean. RugCheck-style scanners tell you the mint/freeze/LP are fine — they don't tell you that 15 wallets funded from one source are holding 30% of supply, waiting to dump on you. That's what this catches.
+
+## Quick start
+
+```bash
+npx cabal-hunter-mcp
+```
+
+No install, no signup, no API key — **250 free scans/month per IP**. That's the whole setup; the command below is what you drop into any MCP client.
+
+### Claude Desktop / Claude Code / Cursor / VS Code / ElizaOS
+
+```json
+{
+  "mcpServers": {
+    "cabal-hunter": {
+      "command": "npx",
+      "args": ["-y", "cabal-hunter-mcp"]
+    }
+  }
+}
+```
+
+Prefer a remote HTTP server (no local process)? Point straight at the hosted endpoint instead:
+
+```json
+{ "mcpServers": { "cabal-hunter": { "url": "https://api.cabal-hunter.com/mcp" } } }
+```
+
+## The tool
+
+**`check_cabal_risk({ mint })`** — pass a Solana token mint (contract) address. Returns the full forensic JSON:
+
+```jsonc
+{
+  "recommendation": "AVOID",        // SAFE | REVIEW | AVOID  ← the headline
+  "risk": "HIGH",                   // exit-liquidity risk
+  "cabal_score": 100,               // 0-100
+  "honeypot_risk": "LOW",           // freeze authority + Token-2022 traps
+  "mint_authority_revoked": true,
+  "freeze_authority_revoked": true,
+  "deployer": { "verdict": "SERIAL_RUGGER", "tokens_launched": 14, "dead": 13 },
+  "coordinated_clusters": [
+    { "wallets": 5, "combined_pct": 23.1, "evidence_tx": "https://solscan.io/tx/…" }
+  ],
+  "time_sync": true,                // same-block (Jito-bundled) buys
+  "coordinated_exit": false,        // ≥2 holders dumped together
+  "top_reasons": ["..."],
+  "wallets_checked": 15,
+  "scan_complete": true
+}
+```
+
+`scan_complete` / `wallets_checked` are included on purpose so your agent can apply **its own** risk tolerance instead of inheriting ours — the score is a starting point you can verify (every cluster carries an `evidence_tx`), not a verdict you take on faith.
+
+### Gate a buy in your agent
+
+> "Before buying any token, call `check_cabal_risk` with the mint. If `recommendation` is `AVOID` or `cabal_score >= 65` or `honeypot_risk` is `HIGH`, skip the trade and say why."
+
+## Pricing
+
+- **250 scans/month per IP — free, no key.**
+- After that: **$9/month for Unlimited** (fair use), or pay-as-you-go at **$0.001 USDC per scan** (priced at cost). No signup, no card.
+- Prepaid key: send USDC, `POST /api/buy-key`, then set `CABAL_HUNTER_API_KEY` (sent as the `X-API-Key` header). Full details: [api.cabal-hunter.com/pricing](https://api.cabal-hunter.com/pricing).
+
+## Configuration
+
+| Env var | Default | Purpose |
+|---|---|---|
+| `CABAL_HUNTER_API_KEY` | *(none)* | Prepaid key for unlimited / metered use (`X-API-Key`). |
+| `CABAL_HUNTER_API` | `https://api.cabal-hunter.com` | Override the API base URL. |
+
+## Other ways to use Cabal-Hunter
+
+- **REST:** `curl "https://api.cabal-hunter.com/api/scan-cabal?mintAddress=<MINT>"` — [OpenAPI spec](https://api.cabal-hunter.com/openapi.json)
+- **ElizaOS plugin:** [`elizaos-plugin-cabal-hunter`](https://github.com/paulf280-ui/plugin-cabal-hunter) (`npm install elizaos-plugin-cabal-hunter`)
+- **Human?** Free interactive bubble map — wallets, Solscan receipts, live chart + trade links on one screen: [api.cabal-hunter.com/map](https://api.cabal-hunter.com/map)
+
+## What it detects (why "contract-clean" misses it)
+
+A cabal is 15 fresh wallets — all funded from the same master wallet, all buying in the first seconds of launch — quietly accumulating 25–40% of supply before your bot sees the first candle. Contract clean. LP burned. Everything green. Then they dump, simultaneously, into your liquidity. Cabal-Hunter traces the funding graph on-chain and answers the only question that matters before you sign a swap: **are you the exit liquidity?**
+
+---
+
+MIT licensed. Powered by [Cabal-Hunter](https://api.cabal-hunter.com). This package is a thin MCP wrapper over the hosted API — the detection runs server-side against live Solana on-chain data (Helius RPC).

package/index.js

@@ -0,0 +1,95 @@
+#!/usr/bin/env node
+/**
+ * cabal-hunter-mcp — local MCP server for on-chain Solana cabal/rug detection.
+ *
+ * Exposes one tool, `check_cabal_risk`, that scans any Solana token mint and
+ * returns an exit-liquidity risk verdict (SAFE / REVIEW / AVOID), a 0-100 cabal
+ * score, funding-cluster + same-block-bundle + coordinated-dump detection,
+ * serial-rug deployer history, and a honeypot (freeze / Token-2022) check.
+ *
+ * It is a thin stdio wrapper over the hosted Cabal-Hunter API
+ * (https://api.cabal-hunter.com) so any MCP client — Claude Desktop, Claude
+ * Code, Cursor, VS Code, ElizaOS — can run it with `npx cabal-hunter-mcp`.
+ *
+ * Free tier: 250 scans/month per IP, no signup, no key. To use a prepaid key
+ * (e.g. $9/mo unlimited), set CABAL_HUNTER_API_KEY.
+ */
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import {
+  ListToolsRequestSchema,
+  CallToolRequestSchema,
+} from "@modelcontextprotocol/sdk/types.js";
+
+const API = (process.env.CABAL_HUNTER_API || "https://api.cabal-hunter.com").replace(/\/+$/, "");
+const API_KEY = process.env.CABAL_HUNTER_API_KEY || "";
+
+const TOOL = {
+  name: "check_cabal_risk",
+  description:
+    "Real-time on-chain coordinated-wallet (cabal) and rug detection for any " +
+    "Solana token mint. One call returns an Exit-Liquidity Risk verdict " +
+    "(SAFE | REVIEW | AVOID), a 0-100 cabal score, funding-cluster detection " +
+    "(top holders funded by the same source), same-block Jito-bundle detection, " +
+    "coordinated-dump detection, serial-rug deployer history (e.g. 'launched 14, " +
+    "13 dead'), a honeypot check (freeze authority + Token-2022 traps), and " +
+    "on-chain evidence transactions for every flag. Use it before an agent buys a " +
+    "pump.fun / PumpSwap / Raydium token to answer: are you the exit liquidity? " +
+    "Free: 250 scans/month, no API key required.",
+  inputSchema: {
+    type: "object",
+    properties: {
+      mint: {
+        type: "string",
+        description:
+          "The Solana token mint (contract) address to scan, e.g. " +
+          "DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263",
+      },
+    },
+    required: ["mint"],
+  },
+};
+
+const server = new Server(
+  { name: "cabal-hunter", version: "0.1.0" },
+  { capabilities: { tools: {} } }
+);
+
+server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: [TOOL] }));
+
+server.setRequestHandler(CallToolRequestSchema, async (req) => {
+  const { name, arguments: args } = req.params;
+  if (name !== TOOL.name) {
+    return { content: [{ type: "text", text: `Unknown tool: ${name}` }], isError: true };
+  }
+  const mint = String(args?.mint || "").trim();
+  if (!mint) {
+    return {
+      content: [{ type: "text", text: "Error: 'mint' (a Solana token mint address) is required." }],
+      isError: true,
+    };
+  }
+  const url = `${API}/api/scan-cabal?mintAddress=${encodeURIComponent(mint)}`;
+  const headers = { Accept: "application/json" };
+  if (API_KEY) headers["X-API-Key"] = API_KEY;
+  try {
+    const res = await fetch(url, { headers });
+    const text = await res.text();
+    if (!res.ok) {
+      return {
+        content: [{ type: "text", text: `Cabal-Hunter API error ${res.status}: ${text.slice(0, 800)}` }],
+        isError: true,
+      };
+    }
+    return { content: [{ type: "text", text }] };
+  } catch (e) {
+    return {
+      content: [{ type: "text", text: `Request to Cabal-Hunter failed: ${e?.message || String(e)}` }],
+      isError: true,
+    };
+  }
+});
+
+const transport = new StdioServerTransport();
+await server.connect(transport);
+console.error(`cabal-hunter MCP server running on stdio → ${API}`);

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "cabal-hunter-mcp",
+  "version": "0.1.0",
+  "description": "MCP server for on-chain Solana cabal & rug detection — exit-liquidity risk verdict, funding-cluster + same-block-bundle + coordinated-dump detection, serial-rug deployer history, and honeypot check for any token mint. Run with npx, no API key. 250 free scans/month.",
+  "type": "module",
+  "bin": {
+    "cabal-hunter-mcp": "index.js"
+  },
+  "main": "index.js",
+  "files": [
+    "index.js",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "start": "node index.js"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "mcp-server",
+    "solana",
+    "rug-check",
+    "rug-detection",
+    "rugcheck",
+    "cabal-detection",
+    "memecoin",
+    "pump-fun",
+    "pumpfun",
+    "token-safety",
+    "honeypot-detection",
+    "exit-liquidity",
+    "trading-bot",
+    "ai-agent",
+    "ai-agents",
+    "web3",
+    "defi",
+    "claude",
+    "cursor",
+    "elizaos"
+  ],
+  "license": "MIT",
+  "author": "Cabal-Hunter (https://api.cabal-hunter.com)",
+  "homepage": "https://api.cabal-hunter.com",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/paulf280-ui/cabal-hunter-mcp.git"
+  },
+  "bugs": {
+    "url": "https://github.com/paulf280-ui/cabal-hunter-mcp/issues"
+  }
+}