keryx-mcp 0.1.0 → 0.1.1

package/README.md

@@ -1,74 +1,74 @@
-# Keryx MCP server — add Keryx to any agent
-
-Give any MCP-capable agent (Claude Code, Claude Desktop, Cursor, …) a tool that asks **Keryx** a
-question. Keryx autonomously buys paid sources under a budget, answers with inline citations, and
-**pays every creator it cites** in USDC on Arc. The toll for each call is paid from *your own*
-Arc-testnet wallet — so every call is a real on-chain payment, visible live on
-[keryx.cc/dashboard](https://keryx.cc/dashboard).
-
-## Tools
-
-| Tool | What it does |
-|------|--------------|
-| `ask_keryx` | Ask a research question (+ optional USDC `budget`). Returns a cited answer and the creators Keryx paid downstream. Costs **0.02 USDC** per call, paid from your wallet. |
-| `keryx_wallet_status` | Show the wallet this server pays from — address, balances, whether it's ready, and how to fund it. **Run this first.** |
-
-## Setup (≈3 minutes)
-
-Published to npm as [`keryx-mcp`](https://www.npmjs.com/package/keryx-mcp) — no clone, no build.
-
-### Add it to Claude Code (one line)
-
-```bash
-claude mcp add keryx -- npx -y keryx-mcp@latest
-```
-
-### Or add it to any MCP client (Claude Desktop, Cursor, Windsurf, …)
-
-```json
-{
-  "mcpServers": {
-    "keryx": {
-      "command": "npx",
-      "args": ["-y", "keryx-mcp@latest"]
-    }
-  }
-}
-```
-
-### Fund the wallet, then ask
-
-1. Call **`keryx_wallet_status`** — it prints the wallet address it pays from.
-2. Open the [Circle faucet](https://faucet.circle.com), pick **Arc Testnet**, paste that address.
-   (20 USDC / 2h — also covers gas.)
-3. Call **`ask_keryx`** with your question. The server deposits to Circle Gateway on the first call
-   and pays the toll; Keryx researches, answers with citations, and pays the creators it cited.
-
-That's it — the answer comes back with the on-chain payment proof and a link to the live dashboard
-where your call now appears as external traction.
-
-## Configuration (env)
-
-All optional — sane Arc-testnet defaults are built in.
-
-| Var | Default | Purpose |
-|-----|---------|---------|
-| `KERYX_BASE_URL` | `https://keryx.cc` | Keryx deployment to call. |
-| `KERYX_BUYER_PRIVATE_KEY` | *(generated)* | Bring your own funded Arc wallet instead of the generated one. |
-| `KERYX_WALLET_FILE` | `~/.keryx/buyer-wallet.json` | Where the generated wallet is persisted. |
-| `KERYX_GATEWAY_DEPOSIT` | `0.5` | USDC moved into Gateway per top-up. |
-| `KERYX_RPC_URL` | `https://rpc.testnet.arc.network` | Arc testnet RPC. |
-
-> **Real money, testnet.** Calls settle real USDC on Arc testnet. The generated wallet holds only
-> what you faucet into it; Keryx never touches your keys. To go mainnet, point `KERYX_BASE_URL` at a
-> mainnet deployment and fund with real USDC — only with eyes open.
-
-## From source (development)
-
-```bash
-git clone https://github.com/tang-vu/keryx && cd keryx && npm install
-claude mcp add keryx -- node --import tsx --no-warnings "$(pwd)/mcp/keryx-mcp-server.mts"
-```
-
-`npm run build` (in `mcp/`) bundles `keryx-mcp-server.mts` → `dist/keryx-mcp.mjs` with esbuild; that
-single file is what ships to npm and runs under plain `node`.
+# Keryx MCP server — add Keryx to any agent
+
+Give any MCP-capable agent (Claude Code, Claude Desktop, Cursor, …) a tool that asks **Keryx** a
+question. Keryx autonomously buys paid sources under a budget, answers with inline citations, and
+**pays every creator it cites** in USDC on Arc. The toll for each call is paid from *your own*
+Arc-testnet wallet — so every call is a real on-chain payment, visible live on
+[keryx.cc/dashboard](https://keryx.cc/dashboard).
+
+## Tools
+
+| Tool | What it does |
+|------|--------------|
+| `ask_keryx` | Ask a research question (+ optional USDC `budget`). Returns a cited answer and the creators Keryx paid downstream. Costs **0.02 USDC** per call, paid from your wallet. |
+| `keryx_wallet_status` | Show the wallet this server pays from — address, balances, whether it's ready, and how to fund it. **Run this first.** |
+
+## Setup (≈3 minutes)
+
+Published to npm as [`keryx-mcp`](https://www.npmjs.com/package/keryx-mcp) — no clone, no build.
+
+### Add it to Claude Code (one line)
+
+```bash
+claude mcp add keryx -- npx -y keryx-mcp@latest
+```
+
+### Or add it to any MCP client (Claude Desktop, Cursor, Windsurf, …)
+
+```json
+{
+  "mcpServers": {
+    "keryx": {
+      "command": "npx",
+      "args": ["-y", "keryx-mcp@latest"]
+    }
+  }
+}
+```
+
+### Fund the wallet, then ask
+
+1. Call **`keryx_wallet_status`** — it prints the wallet address it pays from.
+2. Open the [Circle faucet](https://faucet.circle.com), pick **Arc Testnet**, paste that address.
+   (20 USDC / 2h — also covers gas.)
+3. Call **`ask_keryx`** with your question. The server deposits to Circle Gateway on the first call
+   and pays the toll; Keryx researches, answers with citations, and pays the creators it cited.
+
+That's it — the answer comes back with the on-chain payment proof and a link to the live dashboard
+where your call now appears as external traction.
+
+## Configuration (env)
+
+All optional — sane Arc-testnet defaults are built in.
+
+| Var | Default | Purpose |
+|-----|---------|---------|
+| `KERYX_BASE_URL` | `https://keryx.cc` | Keryx deployment to call. |
+| `KERYX_BUYER_PRIVATE_KEY` | *(generated)* | Bring your own funded Arc wallet instead of the generated one. |
+| `KERYX_WALLET_FILE` | `~/.keryx/buyer-wallet.json` | Where the generated wallet is persisted. |
+| `KERYX_GATEWAY_DEPOSIT` | `0.5` | USDC moved into Gateway per top-up. |
+| `KERYX_RPC_URL` | `https://rpc.testnet.arc.network` | Arc testnet RPC. |
+
+> **Real money, testnet.** Calls settle real USDC on Arc testnet. The generated wallet holds only
+> what you faucet into it; Keryx never touches your keys. To go mainnet, point `KERYX_BASE_URL` at a
+> mainnet deployment and fund with real USDC — only with eyes open.
+
+## From source (development)
+
+```bash
+git clone https://github.com/tang-vu/keryx && cd keryx && npm install
+claude mcp add keryx -- node --import tsx --no-warnings "$(pwd)/mcp/keryx-mcp-server.mts"
+```
+
+`npm run build` (in `mcp/`) bundles `keryx-mcp-server.mts` → `dist/keryx-mcp.mjs` with esbuild; that
+single file is what ships to npm and runs under plain `node`.

package/dist/keryx-mcp.mjs

@@ -51,6 +51,31 @@ var meta = {
 };
 var fee = parseUnits(String(FEE_USDC), 6);
 var deposit = parseUnits(DEPOSIT_USDC, 6);
+var ONRAMP_URL = `${BASE_URL}/api/faucet/onramp`;
+async function tryOnramp() {
+  try {
+    await fetch(ONRAMP_URL, {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({ address: account.address })
+    });
+  } catch {
+  }
+}
+async function waitForErc20(min) {
+  let bal = 0n;
+  for (let i = 0; i < 10; i++) {
+    bal = await pub.readContract({
+      address: USDC,
+      abi: erc20Abi,
+      functionName: "balanceOf",
+      args: [account.address]
+    });
+    if (bal >= min) return bal;
+    await new Promise((r) => setTimeout(r, 3e3));
+  }
+  return bal;
+}
 async function readBalances() {
   const [gas, erc20, bal] = await Promise.all([
     pub.getBalance({ address: account.address }),
@@ -76,10 +101,7 @@ async function getStatus() {
   } else if (erc20 >= deposit) {
     instructions = `You hold ${formatUnits(erc20, 6)} USDC but no gas to deposit it. Fund ${account.address} with a little Arc-testnet gas at ${FAUCET} (Arc Testnet), then retry.`;
   } else {
-    instructions = `Fund this address with Arc-testnet USDC, then call again:
-  1. Open ${FAUCET} \u2192 select Arc Testnet \u2192 paste ${account.address}
-  2. The faucet sends test USDC (also covers gas).
-Each Keryx call costs ${FEE_USDC} USDC, paid from YOUR wallet \u2014 visible live on ${BASE_URL}/dashboard.`;
+    instructions = `No testnet USDC yet \u2014 just call ask_keryx: it AUTO-FUNDS this wallet once from the Keryx onramp (no Circle faucet needed), then pays the toll from YOUR wallet. If the onramp is tapped out (daily cap), fund ${account.address} at ${FAUCET} (Arc Testnet). Each call costs ${FEE_USDC} USDC, paid from YOUR wallet \u2014 visible live on ${BASE_URL}/dashboard.`;
   }
   return {
     address: account.address,
@@ -93,16 +115,20 @@ Each Keryx call costs ${FEE_USDC} USDC, paid from YOUR wallet \u2014 visible liv
 async function ensureFunded() {
   const first = await gateway.getBalances();
   if (first.gateway.available >= fee) return;
-  const erc20 = await pub.readContract({
+  let erc20 = await pub.readContract({
     address: USDC,
     abi: erc20Abi,
     functionName: "balanceOf",
     args: [account.address]
   });
   if (erc20 < deposit) {
-    throw new Error(
-      `Insufficient testnet USDC. Fund ${account.address} at ${FAUCET} (Arc Testnet), then retry. Need \u2265 ${DEPOSIT_USDC} USDC (have ${formatUnits(erc20, 6)}).`
-    );
+    await tryOnramp();
+    erc20 = await waitForErc20(deposit);
+    if (erc20 < deposit) {
+      throw new Error(
+        `Insufficient testnet USDC and the Keryx onramp didn't land (already used or daily cap). Fund ${account.address} at ${FAUCET} (Arc Testnet), then retry. Need \u2265 ${DEPOSIT_USDC} USDC (have ${formatUnits(erc20, 6)}).`
+      );
+    }
   }
   await gateway.deposit(DEPOSIT_USDC);
   for (let i = 0; i < 30; i++) {

package/package.json

@@ -1,6 +1,7 @@
 {
   "name": "keryx-mcp",
-  "version": "0.1.0",
+  "version": "0.1.1",
+  "mcpName": "io.github.tang-vu/keryx",
   "description": "Add Keryx to any MCP agent — ask a research question, pay the x402 toll from your own Arc wallet, and Keryx answers with citations and pays every creator it cites in USDC on Arc.",
   "type": "module",
   "bin": {