chaink9-mcp 0.0.0-stage → 0.1.0

package/LICENSE

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

@@ -1,3 +1,80 @@
-# Temporary Holding Version
+# ChainK9 MCP server
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Token risk checks for AI agents on **BNB Smart Chain, Ethereum and Base**.
+
+Most token scanners read flags from someone else's API. ChainK9 does what a buyer would: it
+forks the chain and really buys and sells the token through its market (PancakeSwap or
+Uniswap V2, V3 or V4, hooks included), then runs 60+ checks. A honeypot is caught by what it
+does, not by what its code looks like.
+
+Each successful call is paid automatically in **USDC on Base** with the
+[x402](https://x402.org) protocol, from a wallet you choose. There is no account and no API
+key, and failed calls (bad input, not a token, no liquidity, engine busy) are free.
+
+## Tools
+
+The tool list is read live from [api.chaink9.com](https://api.chaink9.com), so new products
+appear without updating this package.
+
+| Tool | Price | What it does |
+|---|---|---|
+| `scan` | $0.02 | Full check of a token: honeypot, buy/sell taxes and how they change, owner pause, blacklist, mint and confiscation powers, limits, liquidity, upgrade authority. Verdict: danger, caution or ok. |
+| `report` | $0.002 | The latest stored scan of a token, without a new one. |
+| `feed` | $0.002 | Tokens that just got a market, with a verdict where scanned. |
+| `simulate-trade` | $0.02 | Buy or sell for a given wallet on a fork, with its real balances. |
+| `exit-check` | $0.04 | Test up to four sell sizes from a wallet's real balance. |
+| `transaction-preview` | $0.02 | Run any transaction on a fork and see balance changes. |
+| `liquidity-report` | $0.003 | The token's pool: reserves and LP tokens (V2), or liquidity and price (V3/V4). |
+| `launch-feed` | $0.003 | New markets that are actually funded, optionally by verdict. |
+| `risk-changes` | $0.002 | What changed between a token's last two scans. |
+| `deployer-report` | $0.005 | A token's verified creator and their other known tokens. |
+| `portfolio-screen` | $0.005 | A wallet's balances of given tokens, riskiest first. |
+
+Every tool takes `chain`: `bsc` (default), `eth` or `base`.
+
+## Setup
+
+1. Make a **new wallet just for this** and put a few dollars of **USDC on Base** in it. It
+   needs no ETH: x402 payments are signatures, and the payment service pays the gas.
+2. Add the server to your MCP client with that wallet's private key.
+
+Claude Code:
+
+```bash
+claude mcp add chaink9 -e CHAINK9_PRIVATE_KEY=0x... -- npx -y chaink9-mcp
+```
+
+Cursor, Claude Desktop or any client with a JSON config:
+
+```json
+{
+  "mcpServers": {
+    "chaink9": {
+      "command": "npx",
+      "args": ["-y", "chaink9-mcp"],
+      "env": { "CHAINK9_PRIVATE_KEY": "0x..." }
+    }
+  }
+}
+```
+
+Claude Desktop can also install the `.mcpb` bundle from the
+[releases](https://github.com/ChainK9/chaink9-mcp/releases) with a click.
+
+## Limits
+
+| Variable | Default | Meaning |
+|---|---|---|
+| `CHAINK9_PRIVATE_KEY` | (required) | Private key of the dedicated Base wallet that pays. |
+| `CHAINK9_MAX_USD_PER_CALL` | `0.05` | Any single payment above this is refused. |
+| `CHAINK9_MAX_USD_PER_DAY` | `1` | Stops paying once this much was spent today (UTC). |
+
+The daily total is kept in `~/.chaink9-mcp/spend.json`. The wallet only ever signs payments
+on Base, and the key never leaves your machine.
+
+## Disclaimer
+
+ChainK9 reports what happened when it traded the token on a private copy of its blockchain at
+the block shown. That is evidence, not a guarantee: a token's owner can change its rules after
+the scan, and traps no check tests can be missed. Nothing here is financial advice; you trade
+at your own risk.

package/index.js

@@ -0,0 +1,119 @@
+#!/usr/bin/env node
+// chaink9-mcp: ChainK9's token risk checks as MCP tools, paid per call with x402 (USDC on Base).
+// Tools come from the live catalog (https://api.chaink9.com/openapi.json), so new products
+// appear without updating this package.
+
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";
+import { decodePaymentResponseHeader, wrapFetchWithPaymentFromConfig } from "@x402/fetch";
+import { ExactEvmScheme } from "@x402/evm";
+import { privateKeyToAccount } from "viem/accounts";
+
+const VERSION = JSON.parse(readFileSync(new URL("./package.json", import.meta.url), "utf8")).version;
+const API = "https://api.chaink9.com";
+const BASE_MAINNET = "eip155:8453"; // ChainK9 is paid in USDC on Base only
+const MAX_PER_CALL = Number(process.env.CHAINK9_MAX_USD_PER_CALL || 0.05);
+const MAX_PER_DAY = Number(process.env.CHAINK9_MAX_USD_PER_DAY || 1);
+const DIR = join(homedir(), ".chaink9-mcp");
+const LEDGER = join(DIR, "spend.json");
+const log = (...a) => console.error("[chaink9]", ...a); // stdout carries the MCP protocol
+
+// ---------------------------------------------------------------- catalog
+let catalog; // name -> { path, price, tool }
+async function loadCatalog() {
+  if (catalog) return catalog;
+  const res = await fetch(`${API}/openapi.json`, { headers: { accept: "application/json" }, signal: AbortSignal.timeout(20_000) });
+  if (!res.ok) throw new Error(`could not load the ChainK9 catalog (HTTP ${res.status})`);
+  const spec = await res.json();
+  catalog = new Map();
+  for (const [path, ops] of Object.entries(spec.paths ?? {})) {
+    const op = ops.post;
+    if (!op) continue;
+    const price = Number(op["x-payment-info"]?.price?.amount ?? NaN);
+    const name = path.slice(1).replace(/[^a-zA-Z0-9_-]/g, "_");
+    catalog.set(name, {
+      path,
+      price,
+      tool: {
+        name,
+        description: `${op.description || op.summary || name} Costs $${price} per successful call, paid automatically in USDC on Base; failed calls are free.`,
+        inputSchema: op.requestBody?.content?.["application/json"]?.schema ?? { type: "object", properties: {} },
+      },
+    });
+  }
+  log(`${catalog.size} tools from ${API}`);
+  return catalog;
+}
+
+// ---------------------------------------------------------------- wallet and limits
+let payFetch;
+function payer() {
+  if (payFetch) return payFetch;
+  const key = process.env.CHAINK9_PRIVATE_KEY;
+  if (!key) return null;
+  // The x402 client signs only Base payments and refuses any single one above the cap,
+  // whatever a server asks for.
+  payFetch = wrapFetchWithPaymentFromConfig(fetch, {
+    schemes: [{ network: BASE_MAINNET, client: new ExactEvmScheme(privateKeyToAccount(key)) }],
+    spendControls: { maxAmountPerPayment: `$${MAX_PER_CALL}` },
+  });
+  return payFetch;
+}
+
+const today = () => new Date().toISOString().slice(0, 10);
+function spentToday() {
+  try {
+    const l = JSON.parse(readFileSync(LEDGER, "utf8"));
+    return l.day === today() ? l.usd : 0;
+  } catch {
+    return 0;
+  }
+}
+function addSpend(usd) {
+  mkdirSync(DIR, { recursive: true });
+  writeFileSync(LEDGER, JSON.stringify({ day: today(), usd: Math.round((spentToday() + usd) * 1e6) / 1e6 }));
+}
+
+// ---------------------------------------------------------------- MCP
+const fail = (text) => ({ isError: true, content: [{ type: "text", text }] });
+const server = new Server({ name: "chaink9", version: VERSION }, { capabilities: { tools: {} } });
+
+server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: [...(await loadCatalog()).values()].map((t) => t.tool) }));
+
+server.setRequestHandler(CallToolRequestSchema, async (req) => {
+  const entry = (await loadCatalog()).get(req.params.name);
+  if (!entry) return fail(`Unknown tool ${req.params.name}.`);
+  const pay = payer();
+  if (!pay) return fail("No wallet configured. Set CHAINK9_PRIVATE_KEY to the private key of a dedicated Base wallet holding a little USDC (no ETH needed); see https://api.chaink9.com.");
+  if (!(entry.price <= MAX_PER_CALL)) return fail(`${req.params.name} costs $${entry.price}, above CHAINK9_MAX_USD_PER_CALL ($${MAX_PER_CALL}).`);
+  if (spentToday() + entry.price > MAX_PER_DAY) return fail(`Daily limit reached: $${spentToday()} of CHAINK9_MAX_USD_PER_DAY ($${MAX_PER_DAY}) spent today.`);
+
+  let res;
+  try {
+    res = await pay(`${API}${entry.path}`, {
+      method: "POST",
+      headers: { "content-type": "application/json", accept: "application/json", "user-agent": `chaink9-mcp/${VERSION}` },
+      body: JSON.stringify(req.params.arguments ?? {}),
+      signal: AbortSignal.timeout(120_000), // a full scan takes 10-40 s
+    });
+  } catch (e) {
+    return fail(`Payment or request failed: ${e?.message ?? e}`);
+  }
+  const receipt = res.headers.get("payment-response");
+  if (receipt) {
+    try {
+      if (decodePaymentResponseHeader(receipt).success) addSpend(entry.price);
+    } catch {}
+  }
+  const text = await res.text();
+  // ChainK9 charges only for 2xx answers; say so, so the agent can fix its input or retry.
+  if (!res.ok) return fail(`${req.params.name} answered ${res.status} (not charged): ${text.slice(0, 2000)}`);
+  return { content: [{ type: "text", text }] };
+});
+
+await server.connect(new StdioServerTransport());
+log(`chaink9-mcp ${VERSION} ready (limits: $${MAX_PER_CALL}/call, $${MAX_PER_DAY}/day)`);

package/manifest.json

@@ -0,0 +1,56 @@
+{
+  "manifest_version": "0.3",
+  "name": "chaink9",
+  "display_name": "ChainK9 token risk checks",
+  "version": "0.1.0",
+  "description": "Check a token on BNB Smart Chain, Ethereum or Base for honeypots, hidden taxes and owner traps before buying it. Paid per call in USDC on Base.",
+  "long_description": "ChainK9 checks a token by doing what a buyer would: it forks the chain and really buys and sells the token through its market (Uniswap or PancakeSwap V2, V3 or V4, hooks included), then runs 60+ checks: honeypot, buy and sell taxes and how they change, owner pause, blacklist, mint and confiscation powers, transfer and sell limits, liquidity, upgrade authority and more. Tools also simulate a trade for a given wallet, test exits, preview a transaction, read liquidity and follow new launches. There is no account and no API key: each successful call is paid automatically in USDC on Base with the x402 protocol, from a wallet you choose; failed calls are free. Use a dedicated wallet holding a few dollars of USDC; the per-call and per-day limits below are a second safety net. Results are evidence from a private copy of the chain at one block, not a guarantee and not financial advice.",
+  "author": { "name": "ChainK9", "email": "hello@chaink9.com", "url": "https://chaink9.com" },
+  "repository": { "type": "git", "url": "https://github.com/ChainK9/chaink9-mcp" },
+  "homepage": "https://chaink9.com",
+  "support": "https://github.com/ChainK9/chaink9-mcp/issues",
+  "server": {
+    "type": "node",
+    "entry_point": "index.js",
+    "mcp_config": {
+      "command": "node",
+      "args": ["${__dirname}/index.js"],
+      "env": {
+        "CHAINK9_PRIVATE_KEY": "${user_config.private_key}",
+        "CHAINK9_MAX_USD_PER_CALL": "${user_config.max_usd_per_call}",
+        "CHAINK9_MAX_USD_PER_DAY": "${user_config.max_usd_per_day}"
+      }
+    }
+  },
+  "tools_generated": true,
+  "keywords": ["token security", "honeypot", "rug pull", "bsc", "ethereum", "base", "x402", "usdc"],
+  "license": "MIT",
+  "compatibility": { "platforms": ["darwin", "win32", "linux"], "runtimes": { "node": ">=20.0.0" } },
+  "user_config": {
+    "private_key": {
+      "type": "string",
+      "title": "Base wallet private key",
+      "description": "0x + 64 hex. A NEW, dedicated wallet holding a few dollars of USDC on Base (no ETH needed). Never your main wallet.",
+      "sensitive": true,
+      "required": true
+    },
+    "max_usd_per_call": {
+      "type": "number",
+      "title": "Max USD per call",
+      "description": "Any single payment above this is refused. The most expensive tool costs $0.04.",
+      "default": 0.05,
+      "min": 0.001,
+      "max": 1,
+      "required": false
+    },
+    "max_usd_per_day": {
+      "type": "number",
+      "title": "Max USD per day",
+      "description": "Stops paying once this much was spent today (UTC).",
+      "default": 1,
+      "min": 0.01,
+      "max": 100,
+      "required": false
+    }
+  }
+}

package/package.json

@@ -1,6 +1,48 @@
 {
   "name": "chaink9-mcp",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "MCP server for ChainK9: token risk checks on BNB Smart Chain, Ethereum and Base. It buys and sells the token on a private fork of the chain to catch honeypots, hidden taxes and owner traps. Paid per call in USDC on Base with x402.",
+  "mcpName": "com.chaink9/chaink9",
+  "type": "module",
+  "bin": {
+    "chaink9-mcp": "index.js"
+  },
+  "files": [
+    "index.js",
+    "README.md",
+    "LICENSE",
+    "manifest.json"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "x402",
+    "honeypot",
+    "token-security",
+    "rug-pull",
+    "bsc",
+    "ethereum",
+    "base",
+    "uniswap",
+    "pancakeswap",
+    "ai-agents"
+  ],
+  "homepage": "https://chaink9.com",
+  "license": "MIT",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "1.32.0",
+    "@x402/evm": "2.28.0",
+    "@x402/fetch": "2.28.0",
+    "viem": "2.57.7"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ChainK9/chaink9-mcp.git"
+  },
+  "scripts": {
+    "test": "node test/smoke.mjs"
+  }
+}