@blockula/mcp 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jack Dishman
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,28 @@
-# Temporary Holding Version
+# @blockula/mcp
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+🧛 MCP server that lets any coding agent use **Blockula**, a post-quantum blockchain. Agents can hold a wallet, send FANG, claim `.boo` names, look things up in plain English, and start or summon chains.
+
+```bash
+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`.
+
+**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 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` | 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 (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.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,208 @@
+#!/usr/bin/env node
+// 🧛 Blockula MCP server. Add to Claude Code with:
+//   claude mcp add blockula -- npx -y @blockula/mcp
+//
+// Env:
+//   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, 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 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";
+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;
+}
+function loadWallet() {
+    const f = readWalletFile();
+    if (!f)
+        return null;
+    const w = Wallet.fromSeed(f.seed, client);
+    if (f.account)
+        w.account = f.account;
+    return w;
+}
+function requireWallet() {
+    const w = loadWallet();
+    if (!w)
+        throw new Error("No agent wallet yet — call create_wallet first.");
+    return w;
+}
+function tool(name, description, shape, run) {
+    server.registerTool(name, { description, inputSchema: shape }, (async (args) => {
+        try {
+            return text(await run(args));
+        }
+        catch (e) {
+            const msg = e.message;
+            const hint = /fetch failed|ECONNREFUSED/.test(msg) ? ` (no node at ${RPC} — call start_dev_node)` : "";
+            return { ...text(`Error: ${msg}${hint}`), isError: true };
+        }
+    }));
+}
+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", (e) => {
+        missing = e.code === "ENOENT";
+    });
+    child.unref();
+    for (let i = 0; i < 40 && !missing; i++) {
+        await new Promise((r) => setTimeout(r, 250));
+        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. 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" });
+    return out.trim();
+});
+tool("create_wallet", "Create this agent's post-quantum (ML-DSA-65) wallet, stored locally. Returns the existing one if it already exists.", {}, async () => {
+    let w = loadWallet();
+    const existed = !!w;
+    if (!w) {
+        w = Wallet.generate(client);
+        mkdirSync(HOME, { recursive: true });
+        writeFileSync(WALLET_FILE, JSON.stringify({ address: w.address, key_id: w.keyId, seed: w.seedHex }, null, 2), { mode: 0o600 });
+    }
+    return {
+        key_id: w.keyId,
+        own_address: w.address,
+        acting_for: w.account,
+        existed,
+        stored_at: WALLET_FILE,
+        next_steps: "To spend from the user's account: ask them to open the Blockula web wallet → Devices & agents → 'Give an agent a budget' and paste this key_id. Then call use_account with their .boo name. (Or use faucet to fund this key's own address for testing.)",
+    };
+});
+tool("use_account", "Act for a user's account (name or address) that has authorized this agent's key — usually as a session key with a spending limit. Pass 'self' to go back to the key's own address.", { account: z.string() }, async ({ account }) => {
+    const f = readWalletFile();
+    if (!f)
+        throw new Error("No agent wallet yet — call create_wallet first.");
+    const w = loadWallet();
+    if (account === "self") {
+        delete f.account;
+    }
+    else {
+        const addr = await client.resolve(account);
+        const { accounts } = await client.keyAccounts(w.keyId);
+        const grant = accounts.find((a) => a.account.address === addr);
+        if (!grant)
+            throw new Error(`${account} hasn't authorized this key yet. Ask the user to add key_id ${w.keyId} in their wallet (Devices & agents).`);
+        f.account = addr;
+        writeFileSync(WALLET_FILE, JSON.stringify(f, null, 2), { mode: 0o600 });
+        return { acting_for: grant.account.name ?? addr, role: grant.role, label: grant.label };
+    }
+    writeFileSync(WALLET_FILE, JSON.stringify(f, null, 2), { mode: 0o600 });
+    return { acting_for: w.address };
+});
+tool("wallet_info", "This agent's address, balance, .boo names and recent activity.", {}, async () => {
+    const w = requireWallet();
+    const a = await client.account(w.account).catch(() => null);
+    const mine = a?.keys?.find((k) => k.key_id === w.keyId);
+    return { key_id: w.keyId, acting_for: a?.account?.name ?? w.account, my_permissions: mine ?? "not authorized on this account", address: w.account, balance: a?.balance_display ?? "0 FANG", names: a?.names ?? [], recent: (a?.recent_txs ?? []).slice(0, 10).map((t) => `${t.summary} (${t.id.slice(0, 12)}…)`) };
+});
+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 { 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 }) => {
+    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));
+tool("register_name", "Claim a .boo name for this agent's wallet (3–32 chars, a-z 0-9 -). Shorter names cost more.", { name: z.string() }, async ({ name }) => {
+    const tx = await requireWallet().registerName(name);
+    return { summary: tx.summary, tx_id: tx.id, explorer: `${RPC}/#/tx/${tx.id}` };
+});
+tool("lookup", "Look up anything — a .boo name, boo1… address, block number/hash or tx id — and get a plain-English explanation.", { query: z.string() }, async ({ query }) => {
+    const hit = await client.search(query);
+    const data = hit.type === "block" ? await client.block(hit.id) : hit.type === "tx" ? await client.tx(hit.id) : hit.type === "account" ? await client.account(hit.id) : await client.name(hit.id);
+    return { type: hit.type, explorer: `${RPC}/#/${hit.type}/${hit.id}`, ...data };
+});
+tool("latest_blocks", "The most recent blocks, summarized.", { limit: z.number().int().min(1).max(50).default(10) }, async ({ limit }) => {
+    const blocks = await client.blocks(limit);
+    return blocks.map((b) => `${b.summary} · ${b.hash.slice(0, 12)}…`);
+});
+await server.connect(new StdioServerTransport());

package/package.json

@@ -1,6 +1,43 @@
 {
   "name": "@blockula/mcp",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "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": {
+    "blockula-mcp": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/index.js"
+  },
+  "license": "MIT",
+  "dependencies": {
+    "@blockula/sdk": "^0.2.0",
+    "@modelcontextprotocol/sdk": "^1.32.1",
+    "zod": "^4.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "*",
+    "typescript": "*"
+  },
+  "author": "Jack Dishman",
+  "keywords": [
+    "blockula",
+    "mcp",
+    "model-context-protocol",
+    "post-quantum",
+    "blockchain",
+    "agents"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}