@blockula/mcp 0.1.0 → 0.2.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`, `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,59 @@
 //   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: found on 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 { 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 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 client = new Client(RPC);
-const server = new McpServer({ name: "blockula", version: "0.1.0" });
+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 +75,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 +87,43 @@ 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. To run your own chain, build the node from the Blockula repo (cargo build --release) and set BLOCKULA_BIN.`);
     }
-    throw new Error(`node didn't start — is \`${BIN}\` installed? See ${join(HOME, "dev-node.log")}`);
+    throw new Error(`node didn't start. See ${join(HOME, "dev-node.log")}`);
 });
 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 +176,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));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blockula/mcp",
-  "version": "0.1.0",
+  "version": "0.2.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.2.0",
     "@modelcontextprotocol/sdk": "^1.32.1",
     "zod": "^4.0.0"
   },