fusebox-mcp 0.1.0 → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/README.md +6 -8
  2. package/index.mjs +23 -7
  3. package/package.json +1 -1
package/README.md CHANGED
@@ -12,13 +12,9 @@ Without a key the server is read-only, and by default it points at **Atlas**, th
12
12
 
13
13
  ## Setup
14
14
 
15
- ```bash
16
- git clone https://github.com/0xdopewilly/fusebox && cd fusebox/mcp && npm install
17
- ```
18
-
19
15
  **Claude Code**
20
16
  ```bash
21
- claude mcp add fusebox -- node /path/to/fusebox/mcp/index.mjs
17
+ claude mcp add fusebox -- npx -y fusebox-mcp
22
18
  ```
23
19
 
24
20
  **Claude Desktop, Cursor, Hermes, or any MCP client** (stdio):
@@ -26,8 +22,8 @@ claude mcp add fusebox -- node /path/to/fusebox/mcp/index.mjs
26
22
  {
27
23
  "mcpServers": {
28
24
  "fusebox": {
29
- "command": "node",
30
- "args": ["/path/to/fusebox/mcp/index.mjs"],
25
+ "command": "npx",
26
+ "args": ["-y", "fusebox-mcp"],
31
27
  "env": {
32
28
  "FUSEBOX_WALLET": "0xYourFuseboxWallet",
33
29
  "FUSEBOX_AGENT_KEY": "0xYourAgentPrivateKey"
@@ -46,7 +42,9 @@ claude mcp add fusebox -- node /path/to/fusebox/mcp/index.mjs
46
42
  ## Try it
47
43
 
48
44
  ```bash
49
- npm test # read-only, against Atlas on X Layer mainnet
45
+ claude mcp add fusebox -- npx -y fusebox-mcp # read-only, against Atlas on X Layer mainnet
50
46
  ```
51
47
 
52
48
  Ask your agent: *"Pay 2.5 USDT0 to 0x1111…1111, it's an urgent refund."* It calls `fusebox_check` first, sees Payee Guard and the Breaker say no, and tells you why. No money moves.
49
+
50
+ When the wallet's Two of Three fuse is the only one saying no, `fusebox_check` and `fusebox_pay` return an `approval_url`: the page where two of the wallet's approvers sign that exact payment, after which the agent can retry. A wallet whose prepaid fee balance can't cover one decision is reported plainly instead of sending a transaction that would revert. Set `FUSEBOX_APP` to point the links at another deployment.
package/index.mjs CHANGED
@@ -19,6 +19,9 @@ const RPC = process.env.FUSEBOX_RPC || "https://rpc.xlayer.tech";
19
19
  const WALLET = getAddress(process.env.FUSEBOX_WALLET || ATLAS);
20
20
  const KEY = process.env.FUSEBOX_AGENT_KEY;
21
21
  const EXPLORER = "https://www.oklink.com/xlayer";
22
+ const APP = process.env.FUSEBOX_APP || "https://fusebox-xlayer.vercel.app";
23
+ /** where the wallet's approvers sign this exact payment (Two of Three) */
24
+ const approvalUrl = (to, amount) => `${APP}/app/approve?wallet=${WALLET}&to=${to}&amount=${amount}`;
22
25
  const chain = defineChain({ id: 196, name: "X Layer", nativeCurrency: { name: "OKB", symbol: "OKB", decimals: 18 }, rpcUrls: { default: { http: [RPC] } }, contracts: { multicall3: { address: "0xcA11bde05977b3631167028862bE2a173976CA11" } } });
23
26
  const pub = createPublicClient({ chain, transport: http(RPC), batch: { multicall: true } });
24
27
  const agent = KEY ? privateKeyToAccount(KEY.startsWith("0x") ? KEY : `0x${KEY}`) : null;
@@ -33,9 +36,15 @@ async function fuses() {
33
36
  const n = Number(await pub.readContract({ ...W, functionName: "fuseCount" }));
34
37
  return Promise.all(Array.from({ length: n }, async (_, i) => {
35
38
  const s = await pub.readContract({ ...W, functionName: "slotAt", args: [BigInt(i)] });
36
- const spent = await pub.readContract({ ...W, functionName: "spentToday", args: [BigInt(i)] });
39
+ const registry = await pub.readContract({ ...W, functionName: "registry" });
40
+ const [spent, fee] = await Promise.all([
41
+ pub.readContract({ ...W, functionName: "spentToday", args: [BigInt(i)] }),
42
+ pub.readContract({ address: registry, abi: ABI.registry, functionName: "feeOf", args: [s.fuseId] }).catch(() => s.maxFee),
43
+ ]);
37
44
  const [key, name] = SOCKET[Number(s.socket)] ?? [`socket-${s.socket}`, `Fuse ${i + 1}`];
38
- return { slot: i, key, name, circuitId: Number(s.circuitId), processor: s.processor, a: Number(s.params.a), b: Number(s.params.b), latched: s.nState > 0 && s.state !== "0x" && BigInt(s.state) !== 0n, spentToday: Number(usd(spent)) };
45
+ // what a check of this fuse costs: the lower of the designer's fee and the one the owner accepted
46
+ const feeCap = Number(usd(fee < s.maxFee ? fee : s.maxFee));
47
+ return { slot: i, key, name, circuitId: Number(s.circuitId), processor: s.processor, a: Number(s.params.a), b: Number(s.params.b), latched: s.nState > 0 && s.state !== "0x" && BigInt(s.state) !== 0n, spentToday: Number(usd(spent)), feeCap };
39
48
  }));
40
49
  }
41
50
 
@@ -65,7 +74,7 @@ const parseAmount = (a) => { if (!/^\d{1,9}(\.\d{1,6})?$/.test(String(a)) || Num
65
74
  const text = (obj, summary) => ({ content: [{ type: "text", text: `${summary}\n\n${JSON.stringify(obj, null, 2)}` }], structuredContent: obj });
66
75
  const fail = (e) => ({ isError: true, content: [{ type: "text", text: e.message || String(e) }] });
67
76
 
68
- const server = new McpServer({ name: "fusebox", version: "0.1.0" });
77
+ const server = new McpServer({ name: "fusebox", version: "0.2.0" });
69
78
 
70
79
  server.registerTool("fusebox_check", {
71
80
  title: "Check a payment against the fuses",
@@ -77,8 +86,9 @@ server.registerTool("fusebox_check", {
77
86
  const [[allowed, status], fs, block] = await Promise.all([pub.readContract({ ...W, functionName: "check", args: [USDT0, payee, amt] }), fuses(), pub.getBlockNumber()]);
78
87
  const verdicts = await explain(fs, status, payee, amt);
79
88
  const no = verdicts.filter((v) => v.verdict === "blew");
80
- const summary = allowed ? `Every fuse holds: the wallet would pay ${amount} USDT0 to ${payee}.` : `Stopped: ${no.map((v) => `${v.fuse} (${v.why})`).join("; ")}. Nothing would move.`;
81
- return text({ allowed, wallet: WALLET, to: payee, amount, block: Number(block), fuses: verdicts }, summary);
89
+ const needs = !allowed && fs.some((f, i) => f.key === "approval-2of3" && verdicts[i].verdict === "blew");
90
+ const summary = allowed ? `Every fuse holds: the wallet would pay ${amount} USDT0 to ${payee}.` : `Stopped: ${no.map((v) => `${v.fuse} (${v.why})`).join("; ")}. Nothing would move.${needs && no.length === 1 ? ` Two of the wallet's approvers can sign this exact payment at ${approvalUrl(payee, amount)}; retry once they have.` : ""}`;
91
+ return text({ allowed, wallet: WALLET, to: payee, amount, block: Number(block), fuses: verdicts, ...(needs ? { approval_url: approvalUrl(payee, amount) } : {}) }, summary);
82
92
  } catch (e) { return fail(e); }
83
93
  });
84
94
 
@@ -91,6 +101,11 @@ server.registerTool("fusebox_pay", {
91
101
  if (!signer) throw new Error("This server is read-only: set FUSEBOX_AGENT_KEY to the agent's private key to pay.");
92
102
  const payee = parseTo(to), amt = parseAmount(amount);
93
103
  if (!(await pub.readContract({ ...W, functionName: "isAgent", args: [agent.address] }))) throw new Error(`${agent.address} isn't an agent of ${WALLET}.`);
104
+ // decisions are charged from the prepaid fee balance: explain an empty one instead of sending a doomed tx
105
+ const registry = await pub.readContract({ ...W, functionName: "registry" });
106
+ const [fee, slots] = await Promise.all([pub.readContract({ address: registry, abi: ABI.registry, functionName: "feeBalance", args: [WALLET] }), fuses()]);
107
+ const per = slots.reduce((t, f) => t + Number(f.feeCap ?? 0), 0);
108
+ if (per > 0 && Number(usd(fee)) + 1e-9 < per) throw new Error(`The wallet's prepaid fee balance (${usd(fee)} USDT0) can't cover one decision (${per.toFixed(6)} USDT0): ask the owner to top it up.`);
94
109
  const hash = await signer.writeContract({ ...W, functionName: "pay", args: [USDT0, payee, amt, memo], gas: 3_000_000n });
95
110
  const r = await pub.waitForTransactionReceipt({ hash, timeout: 120_000 });
96
111
  if (r.status !== "success") throw new Error(`The transaction reverted: ${EXPLORER}/tx/${hash}`);
@@ -99,9 +114,10 @@ server.registerTool("fusebox_pay", {
99
114
  const fs = await fuses();
100
115
  const verdicts = fs.map((f, i) => ({ fuse: f.name, verdict: STATUS[d.status[i]] === "pass" ? "holds" : "blew" }));
101
116
  const blew = verdicts.filter((v) => v.verdict === "blew").map((v) => v.fuse);
102
- const out = { paid: d.allowed, decision: Number(d.decisionId), to: payee, amount, memo, fuses: verdicts, feePaid: usd(d.feePaid), tx: `${EXPLORER}/tx/${hash}` };
117
+ const needs = !d.allowed && fs.some((f, i) => f.key === "approval-2of3" && verdicts[i].verdict === "blew");
118
+ const out = { paid: d.allowed, decision: Number(d.decisionId), to: payee, amount, memo, fuses: verdicts, feePaid: usd(d.feePaid), tx: `${EXPLORER}/tx/${hash}`, ...(needs ? { approval_url: approvalUrl(payee, amount) } : {}) };
103
119
  const summary = d.allowed ? `Paid ${amount} USDT0 to ${payee} (decision #${out.decision}). Fees ${out.feePaid} USDT0. ${out.tx}`
104
- : `Stopped by ${blew.join(", ")}: nothing moved (decision #${out.decision}). Ask the wallet's owner before trying again. ${out.tx}`;
120
+ : `Stopped by ${blew.join(", ")}: nothing moved (decision #${out.decision}). ${needs && blew.length === 1 ? `It needs two of the wallet's approvers: they can sign at ${out.approval_url}, then retry.` : "Ask the wallet's owner before trying again."} ${out.tx}`;
105
121
  return text(out, summary);
106
122
  } catch (e) { return fail(e); }
107
123
  });
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "fusebox-mcp",
3
- "version": "0.1.0",
3
+ "version": "0.2.0",
4
4
  "description": "MCP tools for AI agents paying through a Fusebox wallet on X Layer: check a payment against TapeOut circuit fuses, pay, and read the wallet's state.",
5
5
  "type": "module",
6
6
  "bin": {