keryx-mcp 0.1.0

package/README.md

@@ -0,0 +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`.

package/dist/keryx-mcp.mjs

@@ -0,0 +1,184 @@
+#!/usr/bin/env node
+
+// keryx-mcp-server.mts
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+
+// keryx-buyer.mts
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { GatewayClient } from "@circle-fin/x402-batching/client";
+import { createPublicClient, erc20Abi, formatUnits, http, parseUnits } from "viem";
+import { arcTestnet } from "viem/chains";
+import { generatePrivateKey, privateKeyToAccount } from "viem/accounts";
+var USDC = process.env.KERYX_USDC_ADDRESS ?? "0x3600000000000000000000000000000000000000";
+var RPC = process.env.KERYX_RPC_URL ?? "https://rpc.testnet.arc.network";
+var CHAIN = process.env.KERYX_NETWORK ?? "arcTestnet";
+var BASE_URL = (process.env.KERYX_BASE_URL ?? "https://keryx.cc").replace(/\/$/, "");
+var FEE_USDC = Number(process.env.KERYX_A2A_FEE ?? "0.02");
+var DEPOSIT_USDC = process.env.KERYX_GATEWAY_DEPOSIT ?? "0.5";
+var FAUCET = "https://faucet.circle.com";
+var EXPLORER = "https://testnet.arcscan.app";
+var WALLET_FILE = process.env.KERYX_WALLET_FILE ?? path.join(os.homedir(), ".keryx", "buyer-wallet.json");
+function loadOrCreateKey() {
+  const envKey = process.env.KERYX_BUYER_PRIVATE_KEY;
+  if (envKey && envKey.startsWith("0x")) return envKey;
+  try {
+    return JSON.parse(fs.readFileSync(WALLET_FILE, "utf8")).privateKey;
+  } catch {
+    const key2 = generatePrivateKey();
+    fs.mkdirSync(path.dirname(WALLET_FILE), { recursive: true });
+    fs.writeFileSync(
+      WALLET_FILE,
+      JSON.stringify({ privateKey: key2, address: privateKeyToAccount(key2).address }, null, 2)
+    );
+    return key2;
+  }
+}
+var key = loadOrCreateKey();
+var account = privateKeyToAccount(key);
+var gateway = new GatewayClient({ chain: CHAIN, privateKey: key, rpcUrl: RPC });
+var pub = createPublicClient({ chain: arcTestnet, transport: http(RPC) });
+var meta = {
+  address: account.address,
+  baseUrl: BASE_URL,
+  feeUsdc: FEE_USDC,
+  faucet: FAUCET,
+  explorer: EXPLORER,
+  walletFile: WALLET_FILE
+};
+var fee = parseUnits(String(FEE_USDC), 6);
+var deposit = parseUnits(DEPOSIT_USDC, 6);
+async function readBalances() {
+  const [gas, erc20, bal] = await Promise.all([
+    pub.getBalance({ address: account.address }),
+    pub.readContract({
+      address: USDC,
+      abi: erc20Abi,
+      functionName: "balanceOf",
+      args: [account.address]
+    }),
+    gateway.getBalances()
+  ]);
+  return { gas, erc20, available: bal.gateway.available };
+}
+async function getStatus() {
+  const { gas, erc20, available } = await readBalances();
+  const ready = available >= fee;
+  let instructions;
+  if (ready) {
+    const calls = Math.floor(Number(formatUnits(available, 6)) / FEE_USDC);
+    instructions = `Ready \u2014 ${formatUnits(available, 6)} USDC in Gateway, ~${calls} Keryx calls.`;
+  } else if (erc20 >= deposit && gas > 0n) {
+    instructions = `You hold ${formatUnits(erc20, 6)} USDC but it isn't in the Gateway yet. ask_keryx will auto-deposit ${DEPOSIT_USDC} USDC on the next call.`;
+  } 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.`;
+  }
+  return {
+    address: account.address,
+    gasBalance: formatUnits(gas, 18),
+    usdcBalance: formatUnits(erc20, 6),
+    gatewayAvailable: formatUnits(available, 6),
+    ready,
+    instructions
+  };
+}
+async function ensureFunded() {
+  const first = await gateway.getBalances();
+  if (first.gateway.available >= fee) return;
+  const 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 gateway.deposit(DEPOSIT_USDC);
+  for (let i = 0; i < 30; i++) {
+    const b = await gateway.getBalances();
+    if (b.gateway.available >= fee) return;
+    await new Promise((r) => setTimeout(r, 3e3));
+  }
+  throw new Error("Gateway deposit didn't confirm in time \u2014 check balance and retry.");
+}
+async function askKeryx(question, budget) {
+  await ensureFunded();
+  const r = await gateway.pay(`${BASE_URL}/api/agent/ask`, {
+    method: "POST",
+    body: { question, ...budget ? { budget } : {} }
+  });
+  return { ...r.data, settlementId: String(r.transaction), amountPaid: r.formattedAmount };
+}
+
+// keryx-mcp-server.mts
+var server = new McpServer({ name: "keryx", version: "0.1.0" });
+server.registerTool(
+  "ask_keryx",
+  {
+    title: "Ask Keryx",
+    description: `Ask Keryx \u2014 an autonomous research agent that buys paid sources under a budget, answers with inline citations, and pays each cited creator in USDC on Arc. Costs ${meta.feeUsdc} USDC per call, paid from your own funded Arc-testnet wallet (run keryx_wallet_status first to fund it). Use when you want a grounded, source-cited answer AND the creators paid for their work.`,
+    inputSchema: {
+      question: z.string().min(3).describe("The research question to ask Keryx."),
+      budget: z.number().positive().optional().describe("Optional USDC budget Keryx may spend buying sources (default ~0.05).")
+    }
+  },
+  async ({ question, budget }) => {
+    try {
+      const r = await askKeryx(question, budget);
+      const cites = r.citations?.length ? r.citations.map((c) => `  \u2022 ${c.source} \u2014 $${c.reward}`).join("\n") : "  (none)";
+      const proof = r.settlementId ? ` (Circle Gateway settlement ${r.settlementId.slice(0, 12)}\u2026, batched on Arc)` : "";
+      const text = `${r.answer}
+
+\u2014 Paid Keryx ${r.amountPaid ?? meta.feeUsdc} USDC${proof}
+Keryx paid ${r.creatorsPaid} creator(s) $${r.totalToCreators} downstream:
+${cites}
+On-chain proof + live feed: ${meta.baseUrl}/dashboard`;
+      return { content: [{ type: "text", text }] };
+    } catch (e) {
+      const msg = e instanceof Error ? e.message : String(e);
+      return { isError: true, content: [{ type: "text", text: `Keryx call failed: ${msg}` }] };
+    }
+  }
+);
+server.registerTool(
+  "keryx_wallet_status",
+  {
+    title: "Keryx wallet status",
+    description: "Show the Arc-testnet wallet the Keryx MCP server pays from: address, balances, whether it's ready, and exactly how to fund it via the Circle faucet. Run this before ask_keryx.",
+    inputSchema: {}
+  },
+  async () => {
+    try {
+      const s = await getStatus();
+      const text = `Keryx buyer wallet
+  address:  ${s.address}
+  USDC:     ${s.usdcBalance}
+  gas:      ${s.gasBalance}
+  Gateway:  ${s.gatewayAvailable} USDC available
+  ready:    ${s.ready ? "yes" : "no"}
+
+${s.instructions}`;
+      return { content: [{ type: "text", text }] };
+    } catch (e) {
+      const msg = e instanceof Error ? e.message : String(e);
+      return {
+        isError: true,
+        content: [{ type: "text", text: `Status check failed: ${msg}` }]
+      };
+    }
+  }
+);
+var transport = new StdioServerTransport();
+await server.connect(transport);
+console.error(`Keryx MCP server ready \xB7 paying from ${meta.address} \u2192 ${meta.baseUrl}`);

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "keryx-mcp",
+  "version": "0.1.0",
+  "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": {
+    "keryx-mcp": "dist/keryx-mcp.mjs"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "esbuild keryx-mcp-server.mts --bundle --platform=node --format=esm --target=node20 --packages=external --outfile=dist/keryx-mcp.mjs",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "x402",
+    "circle",
+    "arc",
+    "usdc",
+    "ai-agent",
+    "citations",
+    "micropayments",
+    "keryx"
+  ],
+  "license": "MIT",
+  "homepage": "https://keryx.cc",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/tang-vu/keryx.git",
+    "directory": "mcp"
+  },
+  "dependencies": {
+    "@circle-fin/x402-batching": "^2.1.0",
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "viem": "^2.52.2",
+    "zod": "^3.25.76"
+  }
+}