@blockula/mcp 0.2.0 → 0.3.0

package/README.md

@@ -8,7 +8,7 @@ claude mcp add blockula -- npx -y @blockula/mcp
 
 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`, `start_dev_node`, `summon_chain`, `create_wallet`, `use_account`, `wallet_info`, `faucet`, `send`, `check_name`, `register_name`, `lookup`, `latest_blocks`.
+**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.

package/dist/index.js

@@ -7,14 +7,15 @@
 //   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: found on PATH)
+//   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, 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 LOCAL_RPC = "http://localhost:7070";
@@ -25,7 +26,19 @@ const MAX_SEND = parseFang(process.env.BLOCKULA_MAX_SEND ?? "100");
 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 BIN = process.env.BLOCKULA_BIN ?? "blockula";
+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();
@@ -121,10 +134,36 @@ tool("start_dev_node", "Start a local Blockula dev chain (faucet + built-in expl
         }
     }
     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. To run your own chain, build the node from the Blockula repo (cargo build --release) and set BLOCKULA_BIN.`);
+        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 });
+    }
+    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" });
     return out.trim();
@@ -205,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.2.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.2.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"
   }
 }