brainchain-mcp 0.2.0 → 0.2.1

package/README.md

@@ -12,7 +12,7 @@ Claude Code, reading the key without echoing it or leaving it in your shell hist
 
 ```bash
 read -rs BRAINCHAIN_PAYER_KEY
-claude mcp add brainchain -e BRAINCHAIN_PAYER_KEY="$BRAINCHAIN_PAYER_KEY" -- npx -y brainchain-mcp@0.2.0
+claude mcp add brainchain -e BRAINCHAIN_PAYER_KEY="$BRAINCHAIN_PAYER_KEY" -- npx -y brainchain-mcp@0.2.1
 unset BRAINCHAIN_PAYER_KEY
 ```
 
@@ -25,7 +25,7 @@ Cursor (`~/.cursor/mcp.json`), Claude Desktop, Windsurf and other clients that u
   "mcpServers": {
     "brainchain": {
       "command": "npx",
-      "args": ["-y", "brainchain-mcp@0.2.0"],
+      "args": ["-y", "brainchain-mcp@0.2.1"],
       "env": { "BRAINCHAIN_PAYER_KEY": "0xYOUR_KEY" }
     }
   }
@@ -40,7 +40,7 @@ VS Code (`.vscode/mcp.json`), which can prompt for the key instead of storing it
     "brainchain": {
       "type": "stdio",
       "command": "npx",
-      "args": ["-y", "brainchain-mcp@0.2.0"],
+      "args": ["-y", "brainchain-mcp@0.2.1"],
       "env": { "BRAINCHAIN_PAYER_KEY": "${input:brainchain-key}" }
     }
   },
@@ -60,7 +60,7 @@ These pay in USDG on Robinhood Chain. To pay in USDC on Base instead, add `BRAIN
 
 ```bash
 read -rs BRAINCHAIN_PAYER_KEY && export BRAINCHAIN_PAYER_KEY
-npx -y brainchain-mcp@0.2.0 approve
+npx -y brainchain-mcp@0.2.1 approve
 unset BRAINCHAIN_PAYER_KEY
 ```
 
@@ -73,16 +73,16 @@ Use a dedicated wallet that holds only what you plan to spend. The key stays on
 | Tool | What it does |
 | --- | --- |
 | `brainchain_post_task` | Pays for a task and returns an order id. Takes a `title`, a `brief` and two or three quality `levels`, best first. The work is paid if it reaches the second level or better. Models cannot browse, so the brief carries every fact they need. |
-| `brainchain_get_task` | Reads an order: the payment, the task's status on BrainChain, Jev's grade, the result text once Jev accepts the work, and the refund transaction if it does not. `done` says when to stop asking and `retryAfterSeconds` when to ask again. |
+| `brainchain_get_task` | Reads an order: the payment, the task's status on BrainChain, whether Jev accepted the work, the result text once it did, and the refund transaction if it did not. `done` says when to stop asking and `retryAfterSeconds` when to ask again. |
 
 Results usually arrive within minutes. If a post reply says `possiblyCharged`, the connection dropped after the payment was signed: read the order with `brainchain_get_task` rather than posting again.
 
 ## What a task costs
 
-- 1 USDC or 1 USDG, taken when the task is posted. The server never pays more per task than `BRAINCHAIN_MAX_PRICE_UNITS` (1 by default), never more in total than `BRAINCHAIN_BUDGET_UNITS` while it runs (10 by default), and only to the BrainChain payment desk.
+- 1 USDC or 1 USDG, taken when the task is posted. The server never pays more per task than `BRAINCHAIN_MAX_PRICE_UNITS` (1 USDC or USDG by default), never more in total than `BRAINCHAIN_BUDGET_UNITS` (10 USDC or USDG by default), and only to the BrainChain payment desk. The budget resets whenever the server restarts, including when your MCP client restarts it.
 - If Jev accepts the work, you get the result and the model receives the payment minus BrainChain's 3% protocol fee.
 - If Jev rejects the work, or no model delivers within 24 hours, you get no result and the full amount goes back to the paying wallet on the chain it paid on.
-- The payment or refund is final about six hours after grading, when the dispute window closes.
+- The payment or refund is final about six hours after grading (about an hour on testnet), when the dispute window closes.
 
 Every hire and grade is recorded on BrainChain and listed at [usebrainchain.com/decisions](https://usebrainchain.com/decisions).
 
@@ -112,7 +112,7 @@ Set `BRAINCHAIN_NETWORK=testnet` in the server's environment. Test tokens have n
    cast send 0x1eC185467cA2D5d1c24f0EdCB91301Bca4d0a787 "faucet()" --rpc-url https://rpc.testnet.chain.robinhood.com --interactive
    ```
 
-3. Approve Permit2 with `BRAINCHAIN_NETWORK=testnet npx -y brainchain-mcp@0.2.0 approve`.
+3. Approve Permit2 with `BRAINCHAIN_NETWORK=testnet npx -y brainchain-mcp@0.2.1 approve`.
 
 ## Links
 

package/dist/config.js

@@ -58,27 +58,32 @@ export function formatUnits(units) {
     const fraction = (units % 10n ** BigInt(DECIMALS)).toString().padStart(DECIMALS, "0").replace(/0+$/, "");
     return fraction ? `${whole}.${fraction}` : `${whole}`;
 }
+/** MCP clients often pass optional variables as empty strings; those count as unset. */
+function envString(env, name) {
+    const value = env[name]?.trim();
+    return value ? value : undefined;
+}
 function envUnits(env, name, fallback) {
-    const raw = env[name] ?? fallback.toString();
+    const raw = envString(env, name) ?? fallback.toString();
     if (!/^\d+$/.test(raw) || BigInt(raw) === 0n)
         throw new Error(`${name} must be a positive whole number of base units.`);
     return BigInt(raw);
 }
 function envAddress(env, name, fallback) {
-    const value = env[name] ?? fallback;
+    const value = envString(env, name) ?? fallback;
     if (!/^0x[0-9a-fA-F]{40}$/.test(value))
         throw new Error(`${name} must be an address.`);
     return value;
 }
 export function resolveConfig(env) {
-    const name = (env.BRAINCHAIN_NETWORK ?? "mainnet").toLowerCase();
+    const name = (envString(env, "BRAINCHAIN_NETWORK") ?? "mainnet").toLowerCase();
     if (name !== "mainnet" && name !== "testnet")
         throw new Error("BRAINCHAIN_NETWORK must be mainnet or testnet.");
-    const payOn = (env.BRAINCHAIN_PAY_ON ?? "robinhood").toLowerCase();
+    const payOn = (envString(env, "BRAINCHAIN_PAY_ON") ?? "robinhood").toLowerCase();
     if (payOn !== "robinhood" && payOn !== "base")
         throw new Error("BRAINCHAIN_PAY_ON must be robinhood or base.");
     const preset = PRESETS[name][payOn];
-    const network = env.BRAINCHAIN_PAYMENT_NETWORK ?? preset.network;
+    const network = envString(env, "BRAINCHAIN_PAYMENT_NETWORK") ?? preset.network;
     const match = /^eip155:(\d+)$/.exec(network);
     if (!match)
         throw new Error("BRAINCHAIN_PAYMENT_NETWORK must look like eip155:<chain id>.");
@@ -90,12 +95,12 @@ export function resolveConfig(env) {
         name,
         payOn,
         permit2: preset.permit2,
-        desk: (env.BRAINCHAIN_DESK_URL ?? preset.desk).replace(/\/$/, ""),
+        desk: (envString(env, "BRAINCHAIN_DESK_URL") ?? preset.desk).replace(/\/$/, ""),
         network: network,
         chainId: Number(match[1]),
         asset: envAddress(env, "BRAINCHAIN_PAYMENT_ASSET", preset.asset),
         payTo: envAddress(env, "BRAINCHAIN_PAY_TO", preset.payTo),
-        rpc: env.BRAINCHAIN_PAYMENT_RPC ?? preset.rpc,
+        rpc: envString(env, "BRAINCHAIN_PAYMENT_RPC") ?? preset.rpc,
         chain: preset.chain,
         token: preset.token,
         maxPrice,

package/dist/index.js

@@ -23,7 +23,7 @@ MCP server that pays for tasks on BrainChain and reads their graded results.
 Usage:
   brainchain-mcp                 Start the server on stdio (what MCP clients run).
   brainchain-mcp approve [USDG]  Let Permit2 spend the paying wallet's USDG, once.
-                                 Default 100 USDG; pass a number or "max".
+                                 Default 100 USDG; pass a number, "max", or 0 to revoke.
                                  Not needed when paying in USDC on Base.
 
 Environment:
@@ -45,7 +45,7 @@ if (command === "--help" || command === "-h" || command === "help") {
     console.log(USAGE);
     process.exit(0);
 }
-if (command === "--version" || command === "-v") {
+if (command === "--version" || command === "-v" || command === "version") {
     console.log(version);
     process.exit(0);
 }
@@ -93,7 +93,9 @@ if (command === "approve") {
         const receipt = await reader.waitForTransactionReceipt({ hash, timeout: 180_000 });
         if (receipt.status !== "success")
             fail("The approval reverted.");
-        console.log(`Permit2 can now spend ${arg === "max" ? "any amount of" : formatUnits(amount)} ${config.token} from ${account.address}.`);
+        console.log(amount === 0n
+            ? `Permit2 can no longer spend ${config.token} from ${account.address}. Run approve with an amount to pay for tasks again.`
+            : `Permit2 can now spend ${arg === "max" ? "any amount of" : formatUnits(amount)} ${config.token} from ${account.address}.`);
         process.exit(0);
     }
     catch (error) {

package/dist/payments.js

@@ -155,10 +155,12 @@ export function createDesk(options) {
         const reply = await json(response);
         if (response.ok)
             return { ...reply, order: typeof reply.order === "string" ? reply.order : signed ? orderIdOf(signed) : undefined };
-        if (signed && (response.status === 409 || response.status >= 500)) {
+        // The desk answers 400 (a brief it refuses) and 402 (a payment it refuses)
+        // before settling. Any other answer to a signed payment may have charged it.
+        if (signed && response.status !== 400 && response.status !== 402) {
             return possiblyCharged(typeof reply.order === "string" ? reply.order : orderIdOf(signed), `The desk answered ${response.status}.`);
         }
-        // The desk answered with a client error, so the signed payment was not settled.
+        // The desk refused the brief or the payment before settling it.
         spent -= amount;
         amount = 0n;
         if (response.status === 402)
@@ -166,8 +168,28 @@ export function createDesk(options) {
         throw new Error(typeof reply.error === "string" ? `${reply.error} Nothing was charged.` : `The desk answered ${response.status}. Nothing was charged.`);
     }
     async function get(order) {
-        const response = await fetchImpl(`${endpoint}/${order}`, { signal: AbortSignal.timeout(20_000) });
+        let response;
+        try {
+            response = await fetchImpl(`${endpoint}/${order}`, { signal: AbortSignal.timeout(20_000) });
+        }
+        catch (error) {
+            return { order, error: `Could not reach the desk (${firstLine(error)}).`, done: false, next: "The desk could not be reached. Read the order again shortly.", retryAfterSeconds: 30 };
+        }
         const view = await json(response);
+        // A payment authorization lasts at most MAX_TIMEOUT_SECONDS, so an order the
+        // desk still does not know after that was never charged.
+        if (response.status === 404) {
+            return {
+                order,
+                error: "The desk has no order with this id.",
+                done: false,
+                next: `If brainchain_post_task said possiblyCharged, the payment either never reached the desk or is still settling. Read the order again in a minute. If the desk still has no record ${MAX_TIMEOUT_SECONDS / 60} minutes after you posted, nothing was charged and you can post the task again.`,
+                retryAfterSeconds: 60,
+            };
+        }
+        if (response.status >= 500) {
+            return { order, error: `The desk answered ${response.status}.`, done: false, next: "The desk is briefly unavailable. Read the order again shortly.", retryAfterSeconds: 30 };
+        }
         if (!response.ok)
             throw new Error(typeof view.error === "string" ? view.error : `The desk answered ${response.status}.`);
         // Results are served by the desk itself; anything else is left as a link.

package/dist/tools.js

@@ -69,9 +69,10 @@ export async function callTool(desk, name, args) {
             return reply(await desk.post(brief));
         }
         if (name === GET_TASK_NAME) {
-            if (typeof input.order !== "string" || !/^0x[0-9a-f]{64}$/.test(input.order))
-                return reply({ error: "order must be a 0x-prefixed 32-byte hex id." }, true);
-            return reply(await desk.get(input.order));
+            const order = typeof input.order === "string" ? input.order.trim().toLowerCase() : "";
+            if (!/^0x[0-9a-f]{64}$/.test(order))
+                return reply({ error: "order must be the 0x-prefixed, 64-character hex id that brainchain_post_task returned." }, true);
+            return reply(await desk.get(order));
         }
         return reply({ error: `Unknown tool ${name}.` }, true);
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "brainchain-mcp",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "MCP server for BrainChain: hire frontier models through Jev and pay in USDC on Base or USDG on Robinhood Chain, only for work that passes its grade.",
   "mcpName": "com.usebrainchain/brainchain",
   "license": "MIT",
@@ -26,7 +26,7 @@
     "dist"
   ],
   "engines": {
-    "node": ">=20"
+    "node": ">=22"
   },
   "scripts": {
     "build": "rm -rf dist && tsc -p tsconfig.json",
@@ -43,5 +43,12 @@
     "@types/node": "^22.10.2",
     "typescript": "^5.7.2",
     "vitest": "^2.1.5"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/usebrainchain/brainchain-mcp.git"
+  },
+  "bugs": {
+    "url": "https://github.com/usebrainchain/brainchain-mcp/issues"
   }
 }