@walletbrake/mcp 0.1.0 → 0.1.1

package/README.md

@@ -5,8 +5,6 @@ An [MCP](https://modelcontextprotocol.io) server that lets any AI agent pay from
 The server holds the agent's key. The model only sees tools. Every payment is checked against the vault's limits and trusted addresses, and anything else goes to the owner to approve. The vault contract enforces the result on chain, so a prompt injection can't empty it.
 
 > Test networks only for now (Base Sepolia, BNB testnet, Ethereum Sepolia). Mainnet comes after the security audit.
->
-> **Coming soon to npm.** Want early access? Email support@walletbrake.com.
 
 ## Set up
 
@@ -19,7 +17,7 @@ The server holds the agent's key. The model only sees tools. Every payment is ch
    chmod 600 ~/.walletbrake/agent.key
    ```
 
-3. **Add the server to your AI app**, with your vault's address from the app.
+3. **Add the server to your AI app**, with your vault's address from the app. Your app runs it with `npx -y @walletbrake/mcp` (Node 20 or newer), which fetches it from npm.
 
 ### Claude Desktop
 

package/dist/cli.js

@@ -35,7 +35,10 @@ async function main() {
     if (!url)
         throw new Error("set WALLETBRAKE_URL to your vault's address in the WalletBrake app");
     const privateKey = readKey(env.WALLETBRAKE_AGENT_KEY, env.WALLETBRAKE_AGENT_KEY_FILE);
-    const rpcUrl = env.WALLETBRAKE_RPC_URL?.trim() || (await publicNode(url));
+    // looked up on first use, so the server starts even while WalletBrake is loading the network
+    const rpcUrl = env.WALLETBRAKE_RPC_URL?.trim() || (() => publicNode(url));
+    if (typeof rpcUrl !== "string" && !/^https?:\/\/[^/]+\/c\/\d+\/v\//.test(url))
+        throw new Error("set WALLETBRAKE_RPC_URL: a node for the vault's network");
     const waitSecs = Number(env.WALLETBRAKE_WAIT_FOR_OWNER_SECONDS ?? "0");
     if (!Number.isFinite(waitSecs) || waitSecs < 0 || waitSecs > 900)
         throw new Error("WALLETBRAKE_WAIT_FOR_OWNER_SECONDS: between 0 and 900");
@@ -79,6 +82,12 @@ async function publicNode(url) {
     if (!res.ok)
         throw new Error(`couldn't read ${m[1]}/api/config (${res.status}); set WALLETBRAKE_RPC_URL instead`);
     const cfg = (await res.json());
+    const down = cfg.down?.find((d) => d.chainId === Number(m[2]));
+    if (down) {
+        throw new Error(down.starting
+            ? `WalletBrake is loading ${down.name} after an update. Try again in a few minutes.`
+            : `WalletBrake can't reach ${down.name} right now. Try again in a few minutes.`);
+    }
     const rpc = cfg.chains?.find((c) => c.chainId === Number(m[2]))?.rpc?.[0];
     if (!rpc)
         throw new Error(`WalletBrake lists no public node for chain ${m[2]}; set WALLETBRAKE_RPC_URL`);

package/dist/tools.d.ts

@@ -17,8 +17,12 @@ export interface WalletBrakeToolsOptions {
     url: string;
     /** The vault's spending-wallet key. */
     privateKey: Hex;
-    /** A node for the vault's network. */
-    rpcUrl: string;
+    /**
+     * A node for the vault's network, or how to find one. A function is
+     * called on first use (and again after a failure), so the server can
+     * start while WalletBrake is still loading the network.
+     */
+    rpcUrl: string | (() => Promise<string>);
     /**
      * How long walletbrake_pay waits for the owner when a payment needs their
      * approval. Default 0: it answers at once, and the agent asks again later.

package/dist/tools.js

@@ -25,19 +25,28 @@ export function walletBrakeTools(o) {
     const x402Max = o.x402Max === undefined ? undefined : parseUnits(o.x402Max, 6);
     if (x402Max !== undefined && x402Max <= 0n)
         throw new RangeError("x402Max must be more than 0");
-    const wb = new WalletBrake({ url: o.url, privateKey: o.privateKey, rpcUrl: o.rpcUrl, fetch: o.fetch, requestTimeoutMs: o.requestTimeoutMs });
-    let checked;
-    /** The vault, once: and a clear message if the key isn't its spending wallet. */
-    const vault = () => (checked ??= wb.info().then((info) => {
-        if (getAddress(wb.account.address) !== info.operator) {
-            throw new WalletBrakeError(`this key (${getAddress(wb.account.address)}) isn't the vault's spending wallet (${info.operator}). ` +
-                "Give the MCP server the spending wallet's key, or set this wallet as the spending wallet in the vault's Safety tab.");
-        }
-        return info;
-    })).catch((err) => {
-        checked = undefined;
+    const rpc = typeof o.rpcUrl === "string" ? ((u) => async () => u)(o.rpcUrl) : o.rpcUrl;
+    let made;
+    const client = () => (made ??= rpc().then((rpcUrl) => new WalletBrake({ url: o.url, privateKey: o.privateKey, rpcUrl, fetch: o.fetch, requestTimeoutMs: o.requestTimeoutMs }))).catch((err) => {
+        made = undefined;
         throw err;
     });
+    let checked;
+    /** The client, once the vault is known: and a clear message if the key isn't its spending wallet. */
+    const vault = async () => {
+        const wb = await client();
+        await (checked ??= wb.info().then((info) => {
+            if (getAddress(wb.account.address) !== info.operator) {
+                throw new WalletBrakeError(`this key (${getAddress(wb.account.address)}) isn't the vault's spending wallet (${info.operator}). ` +
+                    "Give the MCP server the spending wallet's key, or set this wallet as the spending wallet in the vault's Safety tab.");
+            }
+            return info;
+        })).catch((err) => {
+            checked = undefined;
+            throw err;
+        });
+        return wb;
+    };
     // One payment at a time: each sends a transaction from the same key.
     let queue = Promise.resolve();
     const oneAtATime = (f) => {
@@ -45,7 +54,7 @@ export function walletBrakeTools(o) {
         queue = p.catch(() => { });
         return p;
     };
-    const coin = async (token) => {
+    const coin = async (wb, token) => {
         const t = (await wb.info()).tokens.find((x) => x.address === getAddress(token));
         return t ? { symbol: t.symbol, decimals: t.decimals } : { symbol: `of token ${token} (base units)`, decimals: 0 };
     };
@@ -56,7 +65,7 @@ export function walletBrakeTools(o) {
             description: "Shows the WalletBrake vault you pay from: the coins it holds, how much you can still spend this hour and today, the largest payment, and whether it is frozen.",
             inputSchema: { type: "object", properties: {}, additionalProperties: false },
             annotations: { readOnlyHint: true, openWorldHint: true },
-            call: () => run(async () => describeVault(await vault().then(() => wb.info()))),
+            call: () => run(async () => describeVault(await (await vault()).info())),
         },
         {
             name: "walletbrake_pay",
@@ -84,7 +93,7 @@ export function walletBrakeTools(o) {
                 const to = str(a, "to", true), amount = str(a, "amount", true);
                 if (!/^\d+(\.\d+)?$/.test(amount))
                     return fail(`Not paid: "${amount}" isn't an amount. Give coin units, like "10" or "0.5".`);
-                await vault();
+                const wb = await vault();
                 const p = { to, amount, token: str(a, "token"), note: str(a, "note"), task: str(a, "task") };
                 const until = Date.now() + wait;
                 let approval;
@@ -106,7 +115,7 @@ export function walletBrakeTools(o) {
                     }
                 }
                 const res = await wb.send(approval);
-                const c = await coin(approval.token);
+                const c = await coin(wb, approval.token);
                 const what = `${formatUnits(approval.amount, c.decimals)} ${c.symbol} to ${approval.to}`;
                 if (res.queued) {
                     return {
@@ -131,7 +140,7 @@ export function walletBrakeTools(o) {
                 const id = str(a, "queueId", true).trim();
                 if (!/^\d+$/.test(id))
                     return fail(`Not sent: ${id} isn't a queue id.`);
-                await vault();
+                const wb = await vault();
                 const hash = await wb.executeQueued(BigInt(id));
                 return { text: `Sent the held payment ${id}. Transaction: ${hash}` };
             })),
@@ -159,7 +168,7 @@ export function walletBrakeTools(o) {
             },
             annotations: { destructiveHint: false, idempotentHint: false, openWorldHint: true },
             call: (a) => run(async () => {
-                await vault();
+                const wb = await vault();
                 const payOnly = a.payOnly;
                 if (payOnly !== undefined && (!Array.isArray(payOnly) || payOnly.some((x) => typeof x !== "string"))) {
                     return fail("Not opened: payOnly must be a list of addresses.");
@@ -174,7 +183,7 @@ export function walletBrakeTools(o) {
                     payOnly: payOnly,
                     minutes: minutes,
                 });
-                const c = await coin(t.token);
+                const c = await coin(wb, t.token);
                 return {
                     text: `Task ${t.id} is open until ${t.expires.toISOString()}: "${t.description}", up to ${formatUnits(t.budget, c.decimals)} ${c.symbol}. Pass task "${t.id}" when paying for it.`,
                 };
@@ -210,7 +219,7 @@ export function walletBrakeTools(o) {
                 const method = (str(a, "method") ?? "GET").toUpperCase();
                 if (method !== "GET" && method !== "POST")
                     return fail("Not fetched: method must be GET or POST.");
-                await vault();
+                const wb = await vault();
                 let paid;
                 const pay = wb.x402Fetch({ max: x402Max, task: str(a, "task"), onPayment: (p) => (paid = p) });
                 const init = { method, redirect: "error" };
@@ -225,7 +234,7 @@ export function walletBrakeTools(o) {
                     : `(${type || "no content type"}, ${(await res.arrayBuffer()).byteLength} bytes, not shown)`;
                 const head = [`HTTP ${res.status}${type ? ` (${type.split(";")[0]})` : ""}.`];
                 if (paid) {
-                    const c = await coin(paid.token);
+                    const c = await coin(wb, paid.token);
                     head.push(`Paid ${formatUnits(paid.amount, c.decimals)} ${c.symbol} to ${paid.to} (transaction ${paid.txHash}).`);
                 }
                 const body = text.length > BODY_LIMIT ? text.slice(0, BODY_LIMIT) + `\n… (${text.length - BODY_LIMIT} more characters not shown)` : text;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@walletbrake/mcp",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "An MCP server that lets any AI agent pay from a WalletBrake vault without ever seeing a key: spending limits, trusted addresses and owner approval, enforced on chain.",
   "license": "MIT",
   "author": "WalletBrake <support@walletbrake.com>",