@blockula/mcp 0.1.0 → 0.3.0

package/README.md

@@ -6,20 +6,23 @@
 claude mcp add blockula -- npx -y @blockula/mcp
 ```
 
-**Tools:** `status`, `start_dev_node`, `summon_chain`, `create_wallet`, `use_account`, `wallet_info`, `faucet`, `send`, `check_name`, `register_name`, `lookup`, `latest_blocks`.
+It works with zero setup: if no local node is running, it connects to the public testnet at `https://blockula-testnet.fly.dev`. Call `status` to see which node you're on.
+
+**Tools:** `status`, `tx_status`, `install_node`, `list_hunts`, `link_github`, `fund_hunt`, `start_dev_node`, `summon_chain`, `create_wallet`, `use_account`, `wallet_info`, `faucet`, `send`, `check_name`, `register_name`, `lookup`, `latest_blocks`.
 
 **Spending a user's money safely:**
 1. `create_wallet` gives you a `key_id`. Hand it to the user.
-2. The user grants it a budget in the Blockula web wallet (Devices & agents → Give an agent a budget). The chain enforces the limit and expiry.
+2. The user grants it a budget in the Blockula web wallet at https://blockula-wallet.vercel.app (Devices & agents → Give an agent a budget). The chain enforces the limit and expiry.
 3. `use_account("theirname.boo")`, then `send`.
 
 | Env | Default | |
 |---|---|---|
-| `BLOCKULA_RPC` | `http://localhost:7070` | node URL |
+| `BLOCKULA_RPC` | local node if running, else the public testnet | node URL |
 | `BLOCKULA_HOME` | `~/.blockula` | where the agent key is stored (mode 600) |
 | `BLOCKULA_MAX_SEND` | `100` | max FANG per `send` call |
+| `BLOCKULA_MAX_DAILY` | `100` | max FANG sent per UTC day across all calls (persisted in `BLOCKULA_HOME`) |
 | `BLOCKULA_BIN` | `blockula` | node binary used by `start_dev_node` / `summon_chain` |
 
-`start_dev_node` and `summon_chain` need the `blockula` node binary on your PATH. All other tools work against any reachable node.
+`start_dev_node` and `summon_chain` need the `blockula` node binary (build it from the Blockula repo with `cargo build --release`). Every other tool works against the public testnet without it.
 
 ⚠️ Early and unaudited: test chains only.

package/dist/index.js

@@ -3,25 +3,72 @@
 //   claude mcp add blockula -- npx -y @blockula/mcp
 //
 // Env:
-//   BLOCKULA_RPC       node URL (default http://localhost:7070)
-//   BLOCKULA_HOME      where the agent wallet lives (default ~/.blockula)
-//   BLOCKULA_MAX_SEND  max FANG per send() call (default 100) — a guardrail until on-chain session keys land
-//   BLOCKULA_BIN       path to the `blockula` binary (default: found on PATH)
+//   BLOCKULA_RPC        node URL (default: a local node on :7070 if one is running, else the public testnet)
+//   BLOCKULA_HOME       where the agent wallet lives (default ~/.blockula)
+//   BLOCKULA_MAX_SEND   max FANG per send() call (default 100)
+//   BLOCKULA_MAX_DAILY  max FANG this MCP sends per UTC day, across calls (default 100)
+//   BLOCKULA_BIN        path to the `blockula` binary (default: ~/.blockula/bin/blockula from install_node, else PATH)
+// When acting for a user's account via a session key, the chain also enforces that key's limit.
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
-import { Client, Wallet, parseFang } from "@blockula/sdk";
+import { Client, Wallet, formatFang, parseFang } from "@blockula/sdk";
 import { spawn, execFileSync } from "node:child_process";
-import { existsSync, mkdirSync, openSync, readFileSync, writeFileSync } from "node:fs";
-import { homedir } from "node:os";
+import { createHash } from "node:crypto";
+import { chmodSync, copyFileSync, existsSync, mkdirSync, mkdtempSync, openSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { homedir, tmpdir } from "node:os";
 import { join } from "node:path";
 import { z } from "zod";
-const RPC = process.env.BLOCKULA_RPC ?? "http://localhost:7070";
+const LOCAL_RPC = "http://localhost:7070";
+const TESTNET_RPC = "https://blockula-testnet.fly.dev";
 const HOME = process.env.BLOCKULA_HOME ?? join(homedir(), ".blockula");
 const WALLET_FILE = join(HOME, "agent-wallet.json");
 const MAX_SEND = parseFang(process.env.BLOCKULA_MAX_SEND ?? "100");
-const BIN = process.env.BLOCKULA_BIN ?? "blockula";
-const client = new Client(RPC);
-const server = new McpServer({ name: "blockula", version: "0.1.0" });
+const MAX_DAILY = parseFang(process.env.BLOCKULA_MAX_DAILY ?? "100");
+const SPEND_FILE = join(HOME, "agent-spend.json");
+const VERSION = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")).version;
+const REPO = "jackdishman/blockula";
+const INSTALLED_BIN = join(HOME, "bin", "blockula");
+let BIN = process.env.BLOCKULA_BIN ?? (existsSync(INSTALLED_BIN) ? INSTALLED_BIN : "blockula");
+function releaseTarget() {
+    const key = `${process.platform}-${process.arch}`;
+    return { "darwin-arm64": "aarch64-apple-darwin", "darwin-x64": "x86_64-apple-darwin", "linux-x64": "x86_64-unknown-linux-gnu", "linux-arm64": "aarch64-unknown-linux-gnu" }[key] ?? null;
+}
+async function download(url) {
+    const res = await fetch(url, { redirect: "follow" });
+    if (!res.ok)
+        throw new Error(`download failed (${res.status}): ${url}`);
+    return Buffer.from(await res.arrayBuffer());
+}
+async function reachable(url) {
+    try {
+        await new Client(url).status();
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+// No configuration needed: use a local node if one is running, otherwise the public testnet.
+let RPC = process.env.BLOCKULA_RPC ?? ((await reachable(LOCAL_RPC)) ? LOCAL_RPC : TESTNET_RPC);
+let client = new Client(RPC);
+function useRpc(url) {
+    RPC = url;
+    client = new Client(url);
+}
+/** Running total of FANG sent today (UTC), persisted so the cap holds across calls and restarts. */
+function spentToday() {
+    const day = new Date().toISOString().slice(0, 10);
+    try {
+        const f = JSON.parse(readFileSync(SPEND_FILE, "utf8"));
+        if (f.day === day)
+            return { day, spent: BigInt(f.spent) };
+    }
+    catch {
+        /* no spend yet */
+    }
+    return { day, spent: 0n };
+}
+const server = new McpServer({ name: "blockula", version: VERSION });
 const text = (v) => ({ content: [{ type: "text", text: typeof v === "string" ? v : JSON.stringify(v, null, 2) }] });
 function readWalletFile() {
     return existsSync(WALLET_FILE) ? JSON.parse(readFileSync(WALLET_FILE, "utf8")) : null;
@@ -41,15 +88,6 @@ function requireWallet() {
         throw new Error("No agent wallet yet — call create_wallet first.");
     return w;
 }
-async function nodeUp() {
-    try {
-        await client.status();
-        return true;
-    }
-    catch {
-        return false;
-    }
-}
 function tool(name, description, shape, run) {
     server.registerTool(name, { description, inputSchema: shape }, (async (args) => {
         try {
@@ -62,22 +100,69 @@ function tool(name, description, shape, run) {
         }
     }));
 }
-tool("status", "Blockula network status: chain id, height, supply, fees burned, and the crypto in use.", {}, () => client.status());
-tool("start_dev_node", "Start a local Blockula dev chain (with faucet + built-in explorer) if one isn't already running. Requires the `blockula` binary.", { reset: z.boolean().optional().describe("wipe the dev chain first") }, async ({ reset }) => {
-    if (!reset && (await nodeUp()))
-        return `Already running at ${RPC} (explorer: ${RPC})`;
-    const port = new URL(RPC).port || "7070";
+tool("status", "Blockula network status: which node you're connected to, chain id, height, supply, fees burned, and the crypto in use.", {}, async () => ({
+    rpc: RPC,
+    network: RPC === TESTNET_RPC ? "public testnet" : RPC === LOCAL_RPC ? "local node" : "custom node",
+    explorer: RPC,
+    mcp_version: VERSION,
+    ...(await client.status()),
+}));
+tool("tx_status", "Check a transaction by id: pending, finalized (with block), and its plain-English summary.", { tx_id: z.string().regex(/^[0-9a-f]{64}$/) }, async ({ tx_id }) => {
+    const tx = await client.tx(tx_id);
+    return { status: tx.status, summary: tx.summary, block: tx.height, fee: tx.fee_display, explorer: `${RPC}/#/tx/${tx_id}` };
+});
+tool("start_dev_node", "Start a local Blockula dev chain (faucet + built-in explorer) and switch to it. Needs the `blockula` binary; without it, keep using the public testnet, which supports everything except running your own chain.", { reset: z.boolean().optional().describe("wipe the dev chain first") }, async ({ reset }) => {
+    const target = process.env.BLOCKULA_RPC ?? LOCAL_RPC;
+    if (!reset && (await reachable(target))) {
+        useRpc(target);
+        return `Already running at ${target} (explorer: ${target})`;
+    }
+    const port = new URL(target).port || "7070";
     mkdirSync(HOME, { recursive: true });
     const log = openSync(join(HOME, "dev-node.log"), "a");
+    let missing = false;
     const child = spawn(BIN, ["dev", "--port", port, ...(reset ? ["--reset"] : [])], { detached: true, stdio: ["ignore", log, log] });
-    child.on("error", () => { });
+    child.on("error", (e) => {
+        missing = e.code === "ENOENT";
+    });
     child.unref();
-    for (let i = 0; i < 40; i++) {
+    for (let i = 0; i < 40 && !missing; i++) {
         await new Promise((r) => setTimeout(r, 250));
-        if (await nodeUp())
-            return `🧛 Dev chain is up. Explorer: ${RPC} · logs: ${join(HOME, "dev-node.log")}`;
+        if (await reachable(target)) {
+            useRpc(target);
+            return `🧛 Dev chain is up. Explorer: ${target} · logs: ${join(HOME, "dev-node.log")}`;
+        }
+    }
+    if (missing) {
+        throw new Error(`The \`${BIN}\` node binary isn't installed, so a local chain can't start. You're connected to ${RPC}${RPC === TESTNET_RPC ? " (the public testnet)" : ""}, which works for wallets, the faucet, names and sends. Call install_node to download the prebuilt node (checksum-verified), then start_dev_node again.`);
+    }
+    throw new Error(`node didn't start. See ${join(HOME, "dev-node.log")}`);
+});
+tool("install_node", "Download the prebuilt `blockula` node + CLI for this machine from the official GitHub release, verify its SHA-256 checksum, and install it to ~/.blockula/bin. Needed for start_dev_node and summon_chain; nothing else needs it.", { version: z.string().regex(/^(latest|v\d+\.\d+\.\d+)$/).default("latest") }, async ({ version }) => {
+    const target = releaseTarget();
+    if (!target)
+        throw new Error(`No prebuilt node for ${process.platform}/${process.arch}. Build from source: https://github.com/${REPO}`);
+    const base = version === "latest" ? `https://github.com/${REPO}/releases/latest/download` : `https://github.com/${REPO}/releases/download/${version}`;
+    const asset = `blockula-${target}.tar.gz`;
+    const [tarball, sums] = await Promise.all([download(`${base}/${asset}`), download(`${base}/checksums.txt`)]);
+    const expected = sums.toString("utf8").split("\n").map((l) => l.trim().split(/\s+/)).find(([, f]) => f === asset)?.[0];
+    const actual = createHash("sha256").update(tarball).digest("hex");
+    if (!expected || expected !== actual)
+        throw new Error(`checksum mismatch for ${asset}; not installing`);
+    const tmp = mkdtempSync(join(tmpdir(), "blockula-"));
+    try {
+        writeFileSync(join(tmp, asset), tarball);
+        execFileSync("tar", ["-xzf", join(tmp, asset), "-C", tmp]);
+        mkdirSync(join(HOME, "bin"), { recursive: true });
+        copyFileSync(join(tmp, `blockula-${target}`, "blockula"), INSTALLED_BIN);
+        chmodSync(INSTALLED_BIN, 0o755);
+    }
+    finally {
+        rmSync(tmp, { recursive: true, force: true });
     }
-    throw new Error(`node didn't start — is \`${BIN}\` installed? See ${join(HOME, "dev-node.log")}`);
+    BIN = INSTALLED_BIN;
+    const installed = execFileSync(INSTALLED_BIN, ["--version"], { encoding: "utf8" }).trim();
+    return { installed, path: INSTALLED_BIN, sha256: actual, next: "start_dev_node runs a local chain; summon_chain creates your own network" };
 });
 tool("summon_chain", "Create a brand-new Blockula chain (fresh genesis + validator key) that you can run as your own network.", { chain_id: z.string().regex(/^[a-z0-9-]{3,40}$/), faucet: z.boolean().default(true) }, async ({ chain_id, faucet }) => {
     const out = execFileSync(BIN, ["summon", chain_id, ...(faucet ? [] : ["--no-faucet"])], { encoding: "utf8" });
@@ -130,12 +215,19 @@ tool("wallet_info", "This agent's address, balance, .boo names and recent activi
 tool("faucet", "Get 100 test FANG on a dev/test chain (to this agent's wallet, or any name/address).", { to: z.string().optional() }, async ({ to }) => {
     const target = to ?? requireWallet().account;
     const tx = await client.faucet(target);
-    return tx.summary;
+    return { summary: tx.summary, tx_id: tx.id, explorer: `${RPC}/#/tx/${tx.id}` };
 });
 tool("send", "Send FANG to a .boo name or boo1… address. Amounts are in FANG, e.g. \"1.5\".", { to: z.string(), amount: z.string(), memo: z.string().max(256).optional() }, async ({ to, amount, memo }) => {
-    if (parseFang(amount) > MAX_SEND)
+    const drops = parseFang(amount);
+    if (drops > MAX_SEND)
         throw new Error(`amount exceeds this agent's per-send limit (BLOCKULA_MAX_SEND=${process.env.BLOCKULA_MAX_SEND ?? "100"} FANG)`);
+    const today = spentToday();
+    if (today.spent + drops > MAX_DAILY) {
+        throw new Error(`this would exceed the agent's daily limit (BLOCKULA_MAX_DAILY=${process.env.BLOCKULA_MAX_DAILY ?? "100"} FANG; ${formatFang(today.spent)} already sent today)`);
+    }
     const tx = await requireWallet().send(to, amount, { memo });
+    mkdirSync(HOME, { recursive: true });
+    writeFileSync(SPEND_FILE, JSON.stringify({ day: today.day, spent: (today.spent + drops + BigInt(tx.fee)).toString() }), { mode: 0o600 });
     return { summary: tx.summary, fee: tx.fee_display, tx_id: tx.id, block: tx.height, explorer: `${RPC}/#/tx/${tx.id}` };
 });
 tool("check_name", "Check whether a .boo name is available and what it costs.", { name: z.string() }, ({ name }) => client.name(name));
@@ -152,4 +244,25 @@ tool("latest_blocks", "The most recent blocks, summarized.", { limit: z.number()
     const blocks = await client.blocks(limit);
     return blocks.map((b) => `${b.summary} · ${b.hash.slice(0, 12)}…`);
 });
+tool("list_hunts", "Open bounties (Hunts) on GitHub issues, with FANG escrowed on-chain. Each links to an issue with acceptance criteria: implement it, open a PR, and the bounty is awarded on-chain when it merges.", { status: z.enum(["open", "awarded", "cancelled", "expired"]).default("open") }, async ({ status }) => {
+    const res = await client.hunts(status);
+    const hunts = (Array.isArray(res) ? res : res.hunts ?? []);
+    return hunts.map((h) => ({ hunt_id: h.id, bounty: h.amount_display, title: h.title, issue: h.issue_url, funders: h.funders?.length ?? 0, explorer: `${RPC}/#/hunt/${h.id}` }));
+});
+tool("link_github", "Link a GitHub handle to the account this agent acts for, so Hunt awards show up on its profile. First create a PUBLIC gist (as that GitHub user) containing the account's boo1 address, then pass the gist id here.", { handle: z.string().regex(/^[A-Za-z0-9-]{1,39}$/), gist_id: z.string().regex(/^[0-9a-f]{20,40}$/) }, async ({ handle, gist_id }) => {
+    const tx = await requireWallet().linkGithub(handle, gist_id);
+    const check = await client.github(handle).catch(() => null);
+    return { summary: tx.summary, verified: check?.verified ?? false, explorer: `${RPC}/#/tx/${tx.id}` };
+});
+tool("fund_hunt", "Add FANG to an open Hunt's bounty (crowdfunding). Refunded to you if the hunt is cancelled.", { hunt_id: z.number().int().min(0), amount: z.string() }, async ({ hunt_id, amount }) => {
+    const drops = parseFang(amount);
+    if (drops > MAX_SEND)
+        throw new Error(`amount exceeds this agent's per-send limit (BLOCKULA_MAX_SEND=${process.env.BLOCKULA_MAX_SEND ?? "100"} FANG)`);
+    const today = spentToday();
+    if (today.spent + drops > MAX_DAILY)
+        throw new Error(`this would exceed the agent's daily limit (BLOCKULA_MAX_DAILY=${process.env.BLOCKULA_MAX_DAILY ?? "100"} FANG)`);
+    const tx = await requireWallet().fundHunt(hunt_id, amount);
+    writeFileSync(SPEND_FILE, JSON.stringify({ day: today.day, spent: (today.spent + drops + BigInt(tx.fee)).toString() }), { mode: 0o600 });
+    return { summary: tx.summary, explorer: `${RPC}/#/hunt/${hunt_id}` };
+});
 await server.connect(new StdioServerTransport());

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blockula/mcp",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "\ud83e\udddb MCP server for Blockula \u2014 lets any coding agent run a node, hold a post-quantum wallet, send FANG and claim .boo names",
   "type": "module",
   "bin": {
@@ -17,7 +17,7 @@
   },
   "license": "MIT",
   "dependencies": {
-    "@blockula/sdk": "^0.1.0",
+    "@blockula/sdk": "^0.3.0",
     "@modelcontextprotocol/sdk": "^1.32.1",
     "zod": "^4.0.0"
   },
@@ -39,5 +39,14 @@
   },
   "publishConfig": {
     "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jackdishman/blockula.git",
+    "directory": "mcp"
+  },
+  "homepage": "https://github.com/jackdishman/blockula#readme",
+  "bugs": {
+    "url": "https://github.com/jackdishman/blockula/issues"
   }
 }