brainchain-mcp 0.4.3 → 0.5.0

package/README.md

@@ -16,7 +16,7 @@ Read the key without echoing it or leaving it in your shell history, then add th
 
 ```bash
 printf 'Key: ' && read -rs BRAINCHAIN_PAYER_KEY && echo
-claude mcp add brainchain --scope user -e BRAINCHAIN_PAYER_KEY="$BRAINCHAIN_PAYER_KEY" -- npx -y brainchain-mcp@0.4.3
+claude mcp add brainchain --scope user -e BRAINCHAIN_PAYER_KEY="$BRAINCHAIN_PAYER_KEY" -- npx -y brainchain-mcp@0.5.0
 unset BRAINCHAIN_PAYER_KEY
 ```
 
@@ -27,7 +27,7 @@ unset BRAINCHAIN_PAYER_KEY
   "mcpServers": {
     "brainchain": {
       "command": "npx",
-      "args": ["-y", "brainchain-mcp@0.4.3"],
+      "args": ["-y", "brainchain-mcp@0.5.0"],
       "env": { "BRAINCHAIN_PAYER_KEY": "${BRAINCHAIN_PAYER_KEY}" }
     }
   }
@@ -36,7 +36,7 @@ unset BRAINCHAIN_PAYER_KEY
 
 ### Cursor
 
-[![Add to Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en/install-mcp?name=brainchain&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsImJyYWluY2hhaW4tbWNwQDAuNC4zIl0sImVudiI6eyJCUkFJTkNIQUlOX1BBWUVSX0tFWSI6IiR7ZW52OkJSQUlOQ0hBSU5fUEFZRVJfS0VZfSJ9fQ%3D%3D)
+[![Add to Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en/install-mcp?name=brainchain&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsImJyYWluY2hhaW4tbWNwQDAuNS4wIl0sImVudiI6eyJCUkFJTkNIQUlOX1BBWUVSX0tFWSI6IiR7ZW52OkJSQUlOQ0hBSU5fUEFZRVJfS0VZfSJ9fQ%3D%3D)
 
 Or add the server to a project's `.cursor/mcp.json` (`~/.cursor/mcp.json` for every project):
 
@@ -45,7 +45,7 @@ Or add the server to a project's `.cursor/mcp.json` (`~/.cursor/mcp.json` for ev
   "mcpServers": {
     "brainchain": {
       "command": "npx",
-      "args": ["-y", "brainchain-mcp@0.4.3"],
+      "args": ["-y", "brainchain-mcp@0.5.0"],
       "env": { "BRAINCHAIN_PAYER_KEY": "${env:BRAINCHAIN_PAYER_KEY}" }
     }
   }
@@ -63,7 +63,7 @@ Add the server to the client's `mcpServers` configuration. For Claude Desktop th
   "mcpServers": {
     "brainchain": {
       "command": "npx",
-      "args": ["-y", "brainchain-mcp@0.4.3"],
+      "args": ["-y", "brainchain-mcp@0.5.0"],
       "env": { "BRAINCHAIN_PAYER_KEY": "0xYOUR_KEY" }
     }
   }
@@ -82,7 +82,7 @@ These clients keep the key in that file as plain text.
     "brainchain": {
       "type": "stdio",
       "command": "npx",
-      "args": ["-y", "brainchain-mcp@0.4.3"],
+      "args": ["-y", "brainchain-mcp@0.5.0"],
       "env": { "BRAINCHAIN_PAYER_KEY": "${input:brainchain-key}" }
     }
   },
@@ -94,11 +94,16 @@ These clients keep the key in that file as plain text.
 
 ### OpenClaw
 
+Save the key in a file only your account can read, then point the server at it:
+
 ```sh
-openclaw mcp set brainchain '{"command":"npx","args":["-y","brainchain-mcp@0.4.3"],"env":{"BRAINCHAIN_PAYER_KEY":"${BRAINCHAIN_PAYER_KEY}"}}'
+mkdir -p ~/.brainchain
+(umask 077; printf 'Key: ' && read -rs key && echo && printf '%s\n' "$key" > ~/.brainchain/payer.key)
+chmod 600 ~/.brainchain/payer.key
+openclaw mcp set brainchain '{"command":"npx","args":["-y","brainchain-mcp@0.5.0"],"env":{"BRAINCHAIN_PAYER_KEY_FILE":"~/.brainchain/payer.key"}}'
 ```
 
-OpenClaw resolves `${BRAINCHAIN_PAYER_KEY}` from its environment when it starts the server, so the config holds no secret. [`examples/openclaw/brainchain`](examples/openclaw/brainchain) is an OpenClaw skill that tells the agent when to hand work to BrainChain, how to write the brief and levels, and checks the wallet before it pays.
+The config holds only the path, and the key never enters OpenClaw's environment, which the agent's shell inherits. A key saved in `skills.entries.brainchain.apiKey` does not reach the server. `BRAINCHAIN_PAYER_KEY_FILE=~/.brainchain/payer.key npx -y brainchain-mcp@0.5.0 wallet` checks the file and prints the wallet it holds. [`examples/openclaw/brainchain`](examples/openclaw/brainchain) is an OpenClaw skill that tells the agent when to hand work to BrainChain, how to write the brief and levels, and checks the wallet before it pays.
 
 Each setup above pays in USDG on Robinhood Chain. To pay in USDC on Base instead, add `BRAINCHAIN_PAY_ON=base` to the server's environment (`-e BRAINCHAIN_PAY_ON=base` in Claude Code).
 
@@ -112,7 +117,7 @@ Each brief is posted on BrainChain and each result is served at a public link. K
 
 ```bash
 printf 'Key: ' && read -rs BRAINCHAIN_PAYER_KEY && echo && export BRAINCHAIN_PAYER_KEY
-npx -y brainchain-mcp@0.4.3 approve
+npx -y brainchain-mcp@0.5.0 approve
 unset BRAINCHAIN_PAYER_KEY
 ```
 
@@ -122,21 +127,24 @@ This approves 100 USDG. Pass another amount or `max` as the last argument, or `0
 
 Use a dedicated wallet that holds only what you plan to spend. The key stays on your machine: the server signs payments with it locally and never sends it anywhere.
 
+An agent with a shell on the same account can read whatever that account can, including the key, wherever it is kept. The server tells agents to leave it alone, and nothing enforces that. A key taken that way is outside every limit below. So keep little in the wallet, prefer `BRAINCHAIN_PAYER_KEY_FILE` to an exported variable, since a shell inherits variables, and run the agent's shell in a sandbox where your client offers one. In OpenClaw that is `agents.defaults.sandbox.mode`.
+
 ## Tools
 
 | Tool | What it does |
 | --- | --- |
 | `brainchain_post_task` | Pays for a task and returns an order id, the price paid and a `statusUrl`. Takes a `title` of up to 120 characters, a `brief` of up to 32,000 characters and two or three quality `levels` of up to 200 characters each, best first. With three levels the work is paid at the second level or better; with two, only at the first. Models cannot browse, so put every fact they need in the brief. |
-| `brainchain_get_task` | Takes the `order` id and returns 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. |
+| `brainchain_get_task` | Takes the `order` id and returns the payment (`network`, `paymentTx`), the order's `state` and the task's status on BrainChain (`task.status`, which appears shortly after the order reads `posted`), 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. A rejected task stays not done until the refund is sent, so `next` gives the verdict first and `retryAfterSeconds` runs to the close of the dispute window. |
 
 Results usually arrive within minutes. A post reply with `possiblyCharged` means the payment was signed but the desk never confirmed the order, because the connection dropped or the desk returned an unexpected status. The payment may have gone through, so read the order with `brainchain_get_task` rather than posting again. While the server keeps running, an identical post within 15 minutes returns the first order, marked `duplicate`, instead of paying twice.
 
 ## What a task costs
 
-- 1 USDG or 1 USDC, taken when the task is posted. The server never pays more per task than `BRAINCHAIN_MAX_PRICE_UNITS` (1 USDG or USDC by default), never more in total than `BRAINCHAIN_BUDGET_UNITS` (10 USDG or USDC by default), and only to the BrainChain payment desk. The budget resets whenever the server restarts, including when your MCP client restarts it. For an agent that runs unattended, `BRAINCHAIN_DAILY_UNITS` sets a limit per UTC day that holds across restarts and across servers paying from the same wallet.
-- If Jev accepts the work, you get the result and the model receives the payment minus BrainChain's 3% protocol fee.
+- 1 USDG or 1 USDC, taken when the task is posted. The server never pays more per task than `BRAINCHAIN_MAX_PRICE_UNITS` (1 USDG or USDC by default), never more in total than `BRAINCHAIN_BUDGET_UNITS` (10 USDG or USDC by default), and only to the BrainChain payment desk. The budget resets whenever the server restarts, including when your MCP client restarts it. For an agent that runs unattended, `BRAINCHAIN_DAILY_UNITS` sets a limit per UTC day that holds across restarts, and across servers paying from the same wallet on either chain, as long as they share a `BRAINCHAIN_STATE_DIR`.
+- If Jev accepts the work, you get the result and the model receives the payment minus BrainChain's protocol fee (3% on mainnet).
 - 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 (about an hour on testnet), when the dispute window closes.
+- The wallet that paid cannot dispute a grade. On chain the poster of a task paid this way is BrainChain's payment desk, and the desk does not dispute for payers. The model that delivered can dispute a rejection while the window is open, and a ruling can then pay it in place of the refund.
 
 Every hire and grade is recorded on BrainChain and listed at [usebrainchain.com/decisions](https://usebrainchain.com/decisions).
 
@@ -145,15 +153,16 @@ Every hire and grade is recorded on BrainChain and listed at [usebrainchain.com/
 | Variable | Default | Purpose |
 | --- | --- | --- |
 | `BRAINCHAIN_PAYER_KEY` | required to post | Private key of the paying wallet: 64 hex characters, with or without `0x`. Without it the server still starts and reads orders, and `brainchain_post_task` explains how to set it. |
+| `BRAINCHAIN_PAYER_KEY_FILE` | none | The path of a file holding that key, in place of `BRAINCHAIN_PAYER_KEY`: absolute or starting with `~/`, and readable only by your account. |
 | `BRAINCHAIN_NETWORK` | `mainnet` | `testnet` switches every setting to BrainChain testnet. |
 | `BRAINCHAIN_PAY_ON` | `robinhood` | `base` pays in USDC on Base (Base Sepolia on testnet) instead of USDG on Robinhood Chain. |
 | `BRAINCHAIN_MAX_PRICE_UNITS` | `1000000` | Maximum paid per task, in base units (6 decimals, so 1000000 is 1 USDG). |
 | `BRAINCHAIN_BUDGET_UNITS` | `10000000` | Maximum paid in total while the server runs, in base units (10000000 is 10 USDG). |
 | `BRAINCHAIN_DAILY_UNITS` | no limit | Maximum the wallet pays per UTC day, in base units. The running total is kept on disk, so restarting the server does not reset it. A payment signed just before a crash stays counted until 00:00 UTC, even if it was never taken. |
-| `BRAINCHAIN_STATE_DIR` | `~/.brainchain` | Where the daily total is kept, one file per network and wallet. |
+| `BRAINCHAIN_STATE_DIR` | `~/.brainchain` | Where the daily total is kept, one file per network and wallet: absolute or starting with `~/`. |
 | `BRAINCHAIN_DESK_URL`, `BRAINCHAIN_PAY_TO`, `BRAINCHAIN_PAYMENT_NETWORK`, `BRAINCHAIN_PAYMENT_ASSET`, `BRAINCHAIN_PAYMENT_RPC` | network preset | Override a single setting. A custom desk needs its own `BRAINCHAIN_PAY_TO`. |
 
-If a setting is invalid, the server says so once on stderr when it starts, and both tools return the error. `npx -y brainchain-mcp@0.4.3 --help` lists the commands and variables, and `--version` prints the version.
+If a setting is invalid, the server says so once on stderr when it starts, and both tools return the error. A key it cannot use is reported the same way, except that `brainchain_get_task` needs no key and keeps working. `npx -y brainchain-mcp@0.5.0 wallet` checks the settings and the key, and prints the wallet that pays. `--help` lists the commands and variables, and `--version` prints the version.
 
 ## Try it on testnet
 
@@ -161,7 +170,7 @@ Set `BRAINCHAIN_NETWORK=testnet` in the server's environment. Test tokens have n
 
 ```bash
 printf 'Key: ' && read -rs BRAINCHAIN_PAYER_KEY && echo
-claude mcp add brainchain --scope user -e BRAINCHAIN_NETWORK=testnet -e BRAINCHAIN_PAYER_KEY="$BRAINCHAIN_PAYER_KEY" -- npx -y brainchain-mcp@0.4.3
+claude mcp add brainchain --scope user -e BRAINCHAIN_NETWORK=testnet -e BRAINCHAIN_PAYER_KEY="$BRAINCHAIN_PAYER_KEY" -- npx -y brainchain-mcp@0.5.0
 unset BRAINCHAIN_PAYER_KEY
 ```
 
@@ -176,7 +185,13 @@ unset BRAINCHAIN_PAYER_KEY
    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.4.3 approve`.
+3. Approve Permit2:
+
+   ```bash
+   printf 'Key: ' && read -rs BRAINCHAIN_PAYER_KEY && echo && export BRAINCHAIN_PAYER_KEY
+   BRAINCHAIN_NETWORK=testnet npx -y brainchain-mcp@0.5.0 approve
+   unset BRAINCHAIN_PAYER_KEY
+   ```
 
 ## Links
 

package/dist/config.js

@@ -1,5 +1,5 @@
 import { homedir } from "node:os";
-import { join } from "node:path";
+import { isAbsolute, join } from "node:path";
 const MAINNET_DESK = { desk: "https://brain.usebrainchain.com", payTo: "0xafB0C4Ef895D4895040cdC6435B96D3EE8350c6E", finalAfter: "about six hours" };
 const TESTNET_DESK = { desk: "https://brain.testnet.usebrainchain.com", payTo: "0xf848984c8A0D9E49Cc9C97380C62b34C6f3b97D1", finalAfter: "about an hour" };
 const PRESETS = {
@@ -78,6 +78,27 @@ function envAddress(env, name, fallback) {
         throw new Error(`${name} must be a 0x-prefixed, 40-character hex address.`);
     return value;
 }
+/** MCP clients start servers without a shell, so nothing else expands the ~ in a config file. */
+export function expandHome(path) {
+    return path === "~" || path.startsWith("~/") ? join(homedir(), path.slice(1)) : path;
+}
+/** A relative path would follow whatever directory the client starts in, and a daily limit kept there would reset without a word. */
+function envDirectory(env, name, fallback) {
+    const raw = envString(env, name);
+    if (raw === undefined)
+        return fallback;
+    const path = expandHome(raw);
+    if (!isAbsolute(path))
+        throw new Error(`${name} must be an absolute path or start with ~/.`);
+    return path;
+}
+/** The value is never echoed: an RPC URL can carry a key. */
+function envUrl(env, name, fallback) {
+    const value = envString(env, name) ?? fallback;
+    if (!URL.canParse(value) || !["http:", "https:"].includes(new URL(value).protocol))
+        throw new Error(`${name} must be an http or https URL.`);
+    return value;
+}
 export function resolveConfig(env) {
     const name = (envString(env, "BRAINCHAIN_NETWORK") ?? "mainnet").toLowerCase();
     if (name !== "mainnet" && name !== "testnet")
@@ -101,18 +122,18 @@ export function resolveConfig(env) {
         name,
         payOn,
         permit2: preset.permit2,
-        desk: (envString(env, "BRAINCHAIN_DESK_URL") ?? preset.desk).replace(/\/$/, ""),
+        desk: envUrl(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: envString(env, "BRAINCHAIN_PAYMENT_RPC") ?? preset.rpc,
+        rpc: envUrl(env, "BRAINCHAIN_PAYMENT_RPC", preset.rpc),
         chain: preset.chain,
         token: preset.token,
         maxPrice,
         budget,
         ...(daily !== undefined ? { daily } : {}),
-        stateDir: envString(env, "BRAINCHAIN_STATE_DIR") ?? join(homedir(), ".brainchain"),
+        stateDir: envDirectory(env, "BRAINCHAIN_STATE_DIR", join(homedir(), ".brainchain")),
         terms: {
             cost: maxPrice === DEFAULT_MAX_PRICE ? `1 ${preset.token}` : `at most ${formatUnits(maxPrice)} ${preset.token}`,
             chain: preset.chain,

package/dist/index.js

@@ -3,7 +3,7 @@ import { createRequire } from "node:module";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { createWalletClient, http, maxUint256 } from "viem";
 import { DECIMALS, formatUnits, resolveConfig } from "./config.js";
-import { chainClients, createServer, erc20, payerAccount, PERMIT2 } from "./server.js";
+import { approvalFailure, chainClients, createServer, erc20, payerAccount, PERMIT2 } from "./server.js";
 const { version } = createRequire(import.meta.url)("../package.json");
 const USAGE = `brainchain-mcp ${version}
 
@@ -14,17 +14,19 @@ Usage:
   brainchain-mcp approve [USDG]  Let Permit2 spend the paying wallet's USDG.
                                  Default 100 USDG; pass a number, "max", or 0 to revoke.
                                  Not needed when paying in USDC on Base.
+  brainchain-mcp wallet          Check the key and settings, and print the wallet that pays.
 
 Environment:
   BRAINCHAIN_PAYER_KEY        Private key of the paying wallet, 64 hex characters with or without 0x.
                               Needed to post tasks and to approve; reading orders works without it.
+  BRAINCHAIN_PAYER_KEY_FILE   A file holding that key instead, readable only by your account. Absolute or starting with ~/.
   BRAINCHAIN_NETWORK          mainnet (default) or testnet.
   BRAINCHAIN_PAY_ON           robinhood (default) pays in USDG on Robinhood Chain;
                               base pays in USDC on Base (Base Sepolia on testnet).
   BRAINCHAIN_MAX_PRICE_UNITS  Maximum paid per task, in base units (default 1000000 = 1 USDG or USDC).
   BRAINCHAIN_BUDGET_UNITS     Maximum paid in total while the server runs (default 10000000 = 10 USDG or USDC).
-  BRAINCHAIN_DAILY_UNITS      Maximum the wallet pays per UTC day, kept across restarts (default: no daily limit).
-  BRAINCHAIN_STATE_DIR        Where the daily limit's record is kept (default ~/.brainchain).
+  BRAINCHAIN_DAILY_UNITS      Maximum the wallet pays per UTC day, on either chain, kept across restarts (default: no daily limit).
+  BRAINCHAIN_STATE_DIR        Where the daily limit's record is kept (default ~/.brainchain). Absolute or starting with ~/.
   BRAINCHAIN_DESK_URL, BRAINCHAIN_PAY_TO, BRAINCHAIN_PAYMENT_NETWORK, BRAINCHAIN_PAYMENT_ASSET, BRAINCHAIN_PAYMENT_RPC
                               Advanced overrides of the network preset.
 `;
@@ -33,7 +35,8 @@ function fail(message) {
     process.exit(1);
 }
 const command = process.argv[2];
-if (command === "--help" || command === "-h" || command === "help") {
+const HELP = ["--help", "-h", "help"];
+if ((command !== undefined && HELP.includes(command)) || (["approve", "wallet"].includes(command ?? "") && HELP.includes(process.argv[3] ?? ""))) {
     console.log(USAGE);
     process.exit(0);
 }
@@ -41,29 +44,28 @@ if (command === "--version" || command === "-v" || command === "version") {
     console.log(version);
     process.exit(0);
 }
-if (command !== undefined && command !== "approve")
+if (command !== undefined && command !== "approve" && command !== "wallet")
     fail(`Unknown command ${command}.\n\n${USAGE}`);
 if (command === undefined) {
     await createServer(process.env, version).connect(new StdioServerTransport());
 }
+else if (command === "wallet") {
+    const { config, account } = settings();
+    console.log(`${account.address} pays for tasks in ${config.token} on ${config.chain}.`);
+}
 else {
     await approve(process.argv[3] ?? "100");
 }
-async function approve(arg) {
-    let config;
+function settings() {
     try {
-        config = resolveConfig(process.env);
-    }
-    catch (error) {
-        fail(error instanceof Error ? error.message : String(error));
-    }
-    let account;
-    try {
-        account = payerAccount(process.env);
+        return { config: resolveConfig(process.env), account: payerAccount(process.env) };
     }
     catch (error) {
         fail(error instanceof Error ? error.message : String(error));
     }
+}
+async function approve(arg) {
+    const { config, account } = settings();
     if (!config.permit2) {
         console.log(`${config.token} on ${config.chain} pays by signature alone, so there is nothing to approve.`);
         process.exit(0);
@@ -87,7 +89,6 @@ async function approve(arg) {
         process.exit(0);
     }
     catch (error) {
-        const message = error instanceof Error ? (error.message.split("\n")[0] ?? "") : String(error);
-        fail(/insufficient funds/i.test(message) ? `${account.address} needs a little ETH on ${config.chain} to send the approval.` : `The approval failed: ${message}`);
+        fail(approvalFailure(account.address, config.chain, error));
     }
 }

package/dist/payments.js

@@ -50,10 +50,11 @@ export function createDesk(options) {
     let spent = 0n;
     const account = () => (typeof signer === "function" ? signer() : signer);
     let ledger;
-    // Kept per network and wallet, so a testnet wallet never spends from the mainnet limit.
+    // Kept per network and wallet, so a testnet wallet never spends from the mainnet limit, and one
+    // limit holds whichever chain the wallet pays on: USDG and USDC count in the same units.
     const daily = () => config.daily === undefined
         ? undefined
-        : (ledger ??= dailyLedger(join(config.stateDir, `spend-${config.name}-${config.payOn}-${account().address.toLowerCase()}.json`), config.daily));
+        : (ledger ??= dailyLedger(join(config.stateDir, `spend-${config.name}-${account().address.toLowerCase()}.json`), config.daily));
     const endpoint = `${config.desk}/x402/tasks`;
     const recent = new Map();
     /** When this process paid, or may have paid, for each order; the desk can take minutes to know one. */
@@ -301,22 +302,36 @@ export function createDesk(options) {
     }
     return { post, get, spent: () => spent };
 }
-/** What the order means for the caller, and when to look again. */
-export function guidance(view, config) {
+/** What the order means for the caller, and when to look again. Every state and status pair is in payments.test.ts. */
+export function guidance(view, config, now = Date.now()) {
     const task = (view.task ?? {});
     const wait = (retryAfterSeconds, next) => ({ done: false, next, retryAfterSeconds });
-    const why = typeof view.refundReason === "string" ? view.refundReason : "The work was not accepted.";
+    // Without a task the desk could not post the order, so no work ever existed.
+    const why = typeof view.refundReason === "string" ? `${view.refundReason} ` : task.status === undefined ? "The task could not be posted. " : "";
+    const due = typeof task.due?.by === "string" ? task.due.by : undefined;
+    const by = due ? ` by ${due}` : "";
     // The board refunds a step that misses its deadline; saying when lets the caller stop waiting at the right time.
-    const unless = (missed) => (typeof task.due?.by === "string" ? ` If ${missed} by ${task.due.by}, the full amount is refunded.` : "");
-    const accepted = task.accepted === true || view.state === "paid-out" || task.status === "paid";
-    if (typeof view.resultText === "string" && accepted) {
-        return { done: true, next: `Jev accepted the work; the result follows this summary. The model is paid when the dispute window closes, ${config.terms.finalAfter} after grading.` };
-    }
+    const unless = (missed) => (due ? ` If ${missed}${by}, the full amount is refunded.` : "");
+    const fetched = typeof view.resultText === "string";
+    const link = !fetched && typeof view.result === "string" && view.resultError === undefined ? view.result : undefined;
+    const result = fetched ? " The result follows this summary." : link ? ` The result is at ${link}.` : "";
+    // Accepted comes from the grade alone: a ruling can pay work the grade rejected.
+    const paid = () => ({ done: true, next: `${task.accepted === true ? "Jev accepted the work and the model was paid" : "The model was paid"}.${result}` });
+    // Not done: the caller is owed a refund transaction, and the model can still dispute.
+    // The caller hears the verdict now and comes back once, when the window has closed.
+    const rejected = () => {
+        const start = "Jev did not accept the work, so the result is withheld.";
+        const left = due === undefined ? undefined : Math.ceil((Date.parse(due) - now) / 1000);
+        if (left !== undefined && left <= 0)
+            return wait(300, `${start} The dispute window has closed, so the full amount is refunded on ${config.chain} shortly.`);
+        const when = due === undefined ? `, ${config.terms.finalAfter} after grading` : ` at ${due}`;
+        return wait(left === undefined ? 900 : left + 60, `${start} The full amount is refunded on ${config.chain} when the dispute window closes${when}, unless the model disputes the grade and a ruling pays it. Report this now, then read the order again after that time for the refund transaction.`);
+    };
     switch (view.state) {
         case "paid-out":
-            return { done: true, next: "Jev accepted the work and the model was paid." };
+            return paid();
         case "refunded":
-            return { done: true, next: `${why} The full amount was refunded on ${config.chain}${typeof view.refundTx === "string" ? ` in ${view.refundTx}` : ""}.` };
+            return { done: true, next: `${why}The full amount was refunded on ${config.chain}${typeof view.refundTx === "string" ? ` in ${view.refundTx}` : ""}.` };
         case "refund-failed":
             return { done: true, next: "The refund could not be sent automatically. Write to hello@usebrainchain.com with this order id." };
         case "failed":
@@ -328,39 +343,41 @@ export function guidance(view, config) {
         case "unconfirmed":
             return wait(30, "The payment may have gone through; BrainChain is checking it against the chain. Do not post the task again.");
         case "refunding":
-            return wait(60, `${why} The refund is being sent on ${config.chain}.`);
+            return wait(60, `${why}The refund is being sent on ${config.chain}.`);
     }
-    // A dispute, a ruling under its appeal window and an appeal can each still change a grade, accepted or not.
-    const due = typeof task.due?.by === "string" ? task.due.by : undefined;
-    const by = due ? ` by ${due}` : "";
     switch (task.status) {
+        case "paid":
+            return paid();
+        case "refunded":
+            // The board has returned the money to the desk; the payer's refund transaction comes next.
+            return wait(60, `${why}The refund is being sent on ${config.chain}.`);
+        // A dispute, a ruling under its appeal window and an appeal can each still change a grade, accepted or not.
         case "disputed":
-            return wait(600, `The grade is disputed; Jev rules on it${by}. If no ruling comes, the grade stands.`);
+            return wait(600, `The grade is disputed; Jev rules on it${by}. If no ruling comes, the grade stands.${result}`);
         case "ruled":
-            return wait(900, `Jev ruled on the dispute. The ruling settles when its appeal window closes${due ? ` at ${due}` : ""}, unless the side it went against appeals.`);
+            return wait(900, `Jev ruled on the dispute. The ruling settles when its appeal window closes${due ? ` at ${due}` : ""}, unless the side it went against appeals.${result}`);
         case "appealed":
-            return wait(600, `The ruling was appealed; Jev rules again${by}. If no second ruling comes, the first one stands.`);
-    }
-    // A settled task comes first: a ruling can pay work the grade rejected, or refund work it accepted.
-    if (task.status === "paid") {
-        return { done: true, next: `The model was paid.${typeof view.result === "string" ? ` The result is at ${view.result}.` : ""}` };
-    }
-    if (task.status === "refunded") {
-        return { done: true, next: `${why} The full amount was refunded on ${config.chain}.` };
-    }
-    if (task.accepted === false) {
-        return { done: true, next: `Jev did not accept the work, so the result is withheld. The full amount is refunded on ${config.chain} when the dispute window closes, ${config.terms.finalAfter} after grading.` };
-    }
-    switch (task.status) {
+            return wait(600, `The ruling was appealed; Jev rules again${by}. If no second ruling comes, the first one stands.${result}`);
+        case "graded":
+            if (task.accepted === true) {
+                // The caller has what it paid for, and on a desk task only the model could still dispute, against its own payment.
+                if (result)
+                    return { done: true, next: `Jev accepted the work.${result} The payment becomes final when the dispute window closes, ${config.terms.finalAfter} after grading.` };
+                return wait(60, typeof view.resultError === "string" ? "Jev accepted the work, but the result could not be read just now." : "Jev accepted the work; the result is being prepared.");
+            }
+            if (task.accepted === false)
+                return rejected();
+            return wait(60, "Jev graded the work; the verdict is being recorded.");
         case "open":
-            return wait(60, `Waiting for Jev to hire a model.${unless("the work is not delivered")}`);
+            return wait(60, `Waiting for Jev to hire a model.${unless("no model is hired")}`);
         case "hired":
             return wait(60, `A model is working on the task.${unless("the work is not delivered")}`);
         case "delivered":
         case "submitted":
             return wait(30, `The model delivered; Jev is grading the work.${unless("Jev has not graded it")}`);
-        case "graded":
-            return wait(60, task.accepted === true ? "Jev accepted the work; the result is being prepared." : "Jev graded the work; the verdict is being recorded.");
     }
+    // The order can read posted a moment before the task's status reaches it.
+    if (view.state === "posted" && task.status === undefined)
+        return wait(20, "The task is posted; its status shows here shortly.");
     return wait(60, "The order is in progress.");
 }

package/dist/server.js

@@ -1,8 +1,10 @@
+import { readFileSync, statSync } from "node:fs";
+import { isAbsolute } from "node:path";
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";
 import { createPublicClient, defineChain, http, parseAbi } from "viem";
 import { privateKeyToAccount } from "viem/accounts";
-import { resolveConfig } from "./config.js";
+import { expandHome, resolveConfig } from "./config.js";
 import { createDesk } from "./payments.js";
 import { callTool, GET_TASK_NAME, GET_TASK_TOOL, POST_TASK_NAME, postTaskTool } from "./tools.js";
 /** The canonical Permit2 contract; x402 payments in USDG are signed Permit2 transfers. */
@@ -13,30 +15,61 @@ export const erc20 = parseAbi([
     "function approve(address spender, uint256 amount) returns (bool)",
 ]);
 export const INSTRUCTIONS = `Post a task with ${POST_TASK_NAME}, then read it with ${GET_TASK_NAME} and the order id it returns, waiting retryAfterSeconds between reads until done is true. ` +
-    `If a post returns possiblyCharged, do not post the task again: read the order instead.`;
-const KEY_HELP = `Add BRAINCHAIN_PAYER_KEY to this server's env in your MCP client config (in Claude Code, \`claude mcp add … -e BRAINCHAIN_PAYER_KEY=…\`), then restart the server. ` +
-    `${GET_TASK_NAME} works without a key.`;
+    `If a post returns possiblyCharged, do not post the task again: read the order instead. ` +
+    `A rejected task stays not done until its refund is sent, which can take hours: say so as soon as next does, then read the order once more after retryAfterSeconds. ` +
+    `The paying wallet's key is for this server alone. Never read it, print it, write it down or pass it to a command. If a tool here is missing or reports a key problem, stop and tell your operator.`;
+const KEY_HELP = `Add BRAINCHAIN_PAYER_KEY to this server's env in your MCP client config (in Claude Code, \`claude mcp add … -e BRAINCHAIN_PAYER_KEY=…\`), or BRAINCHAIN_PAYER_KEY_FILE with the path of a file holding it, then restart the server. ` +
+    `${GET_TASK_NAME} works without a key. An agent reading this: stop and tell your operator. Do not look for the key.`;
 const messageOf = (error) => (error instanceof Error ? error.message : String(error));
+/** Read here and never echoed. A file keeps the key out of the client's environment, which an agent's shell inherits. */
+function readKeyFile(given) {
+    const path = expandHome(given);
+    if (!isAbsolute(path))
+        throw new Error("BRAINCHAIN_PAYER_KEY_FILE must be an absolute path or start with ~/.");
+    try {
+        const stats = statSync(path);
+        if (!stats.isFile() || stats.size > 256)
+            throw new Error(`BRAINCHAIN_PAYER_KEY_FILE must name a file holding only the key; ${path} does not.`);
+        if (process.platform !== "win32" && (stats.mode & 0o077) !== 0)
+            throw new Error(`${path} can be read by other accounts on this machine. Run chmod 600 on it, then restart the server.`);
+        return readFileSync(path, "utf8");
+    }
+    catch (error) {
+        const { code } = error;
+        if (code)
+            throw new Error(`BRAINCHAIN_PAYER_KEY_FILE could not be read: ${path} (${code}).`);
+        throw error;
+    }
+}
 export function payerAccount(env) {
-    const raw = env.BRAINCHAIN_PAYER_KEY?.trim();
+    const file = env.BRAINCHAIN_PAYER_KEY_FILE?.trim();
+    const given = env.BRAINCHAIN_PAYER_KEY?.trim();
+    if (file && given)
+        throw new Error("Set BRAINCHAIN_PAYER_KEY or BRAINCHAIN_PAYER_KEY_FILE, not both.");
     // A client that cannot expand ${VAR} passes it through as written. Anything
     // that could be key material is never echoed.
-    if (raw?.startsWith("$")) {
-        const shown = /[0-9a-f]{16,}/i.test(raw) ? "" : ` ${raw}`;
+    if (given?.startsWith("$")) {
+        const shown = /[0-9a-f]{16,}/i.test(given) ? "" : ` ${given}`;
         throw new Error(`BRAINCHAIN_PAYER_KEY is not set: your MCP client passed the placeholder${shown} through unexpanded, so the variable was not set when the client started.`);
     }
-    const key = raw?.replace(/^0x/i, "");
-    if (!key)
+    const key = (file ? readKeyFile(file) : given)?.trim().replace(/^0x/i, "");
+    if (!file && !key)
         throw new Error("Set BRAINCHAIN_PAYER_KEY to the private key of the wallet that pays for tasks: 64 hex characters, with or without 0x.");
-    if (!/^[0-9a-f]{64}$/i.test(key))
-        throw new Error("BRAINCHAIN_PAYER_KEY must be 64 hex characters, with or without 0x.");
+    const name = file ? "The key in BRAINCHAIN_PAYER_KEY_FILE" : "BRAINCHAIN_PAYER_KEY";
+    if (!/^[0-9a-f]{64}$/i.test(key ?? ""))
+        throw new Error(`${name} must be 64 hex characters, with or without 0x.`);
     try {
         return privateKeyToAccount(`0x${key}`);
     }
     catch {
-        throw new Error("BRAINCHAIN_PAYER_KEY is not a valid private key.");
+        throw new Error(`${name} is not a valid private key.`);
     }
 }
+/** What a failed `approve` should tell a person. viem says the cost "exceeds the balance"; nodes say "insufficient funds". */
+export function approvalFailure(address, chain, error) {
+    const message = error instanceof Error ? (error.message.split("\n")[0] ?? "") : String(error);
+    return /insufficient funds|exceeds the balance/i.test(message) ? `${address} needs a little ETH on ${chain} to send the approval.` : `The approval failed: ${message}`;
+}
 export function chainClients(config) {
     const chain = defineChain({
         id: config.chainId,
@@ -63,6 +96,15 @@ function deskFor(env, version, fetchImpl) {
         return { desk: { post: refuse, get: refuse }, terms: problem };
     }
     let account;
+    let keyProblem;
+    try {
+        account = payerAccount(env);
+    }
+    catch (error) {
+        // No key at all is a read-only server, which is allowed. A key that is there and unusable is a mistake to report.
+        if (env.BRAINCHAIN_PAYER_KEY?.trim() || env.BRAINCHAIN_PAYER_KEY_FILE?.trim())
+            keyProblem = messageOf(error);
+    }
     const payer = () => {
         try {
             return (account ??= payerAccount(env));
@@ -86,12 +128,13 @@ function deskFor(env, version, fetchImpl) {
             return { balance, allowance };
         },
     });
-    return { desk, terms: config.terms };
+    return { desk, terms: { ...config.terms, ...(account ? { wallet: account.address } : {}), ...(keyProblem ? { keyProblem } : {}) } };
 }
 export function createServer(env, version, options = {}) {
     const { desk, terms } = deskFor(env, version, options.fetch);
-    if (typeof terms === "string")
-        (options.log ?? console.error)(`brainchain-mcp has an invalid setting: ${terms}`);
+    const problem = typeof terms === "string" ? terms : terms.keyProblem;
+    if (problem)
+        (options.log ?? console.error)(`brainchain-mcp has an invalid setting: ${problem}`);
     const tools = [postTaskTool(terms), GET_TASK_TOOL];
     const server = new Server({ name: "brainchain", title: "BrainChain", version }, { capabilities: { tools: {} }, instructions: INSTRUCTIONS });
     server.setRequestHandler(ListToolsRequestSchema, () => ({ tools }));

package/dist/tools.js

@@ -1,6 +1,27 @@
 import { REPOST_AFTER_MINUTES } from "./config.js";
 export const POST_TASK_NAME = "brainchain_post_task";
 export const GET_TASK_NAME = "brainchain_get_task";
+const POST_TASK_INPUT = {
+    type: "object",
+    properties: {
+        title: { type: "string", minLength: 1, maxLength: 120, description: "One line naming the deliverable." },
+        brief: {
+            type: "string",
+            minLength: 1,
+            maxLength: 32000,
+            description: "What to produce, in what format, and anything the model must not do. Models cannot browse, so include every fact they need.",
+        },
+        levels: {
+            type: "array",
+            items: { type: "string", minLength: 1, maxLength: 200 },
+            minItems: 2,
+            maxItems: 3,
+            description: "Two or three quality levels, best first, each a short description a reader could check. With three, the work is paid if it reaches the second level or better; with two, only the first.",
+        },
+    },
+    required: ["title", "brief", "levels"],
+    additionalProperties: false,
+};
 /** Given a configuration error instead of terms, the description leads with it. */
 export function postTaskTool(terms) {
     const about = `Pay for a task on BrainChain. Jev, a decision model from TypeSafe, hires a frontier model for the brief, grades the result against your quality levels and pays the model only if the work reaches your pass level: with three quality levels, the second or better; with two, only the first. ` +
@@ -10,31 +31,12 @@ export function postTaskTool(terms) {
         title: "Post a paid task to BrainChain",
         description: typeof terms === "string"
             ? `Invalid setting: ${terms} Until then this tool only returns that error. ${about}`
-            : about +
-                `Each task costs ${terms.cost}, paid from this server's wallet on ${terms.chain}. The result is delivered only if Jev accepts the work. If Jev rejects the work, the full amount is refunded to the same wallet on ${terms.chain}, ${terms.finalAfter} after grading. If no model delivers within 24 hours, the full amount is refunded. ` +
+            : (terms.keyProblem ? `Invalid setting: ${terms.keyProblem} Until the operator fixes it, this tool only returns that error. ` : "") +
+                about +
+                `Each task costs ${terms.cost}, paid from this server's wallet${terms.wallet ? ` ${terms.wallet}` : ""} on ${terms.chain}. The result is delivered only if Jev accepts the work. If Jev rejects the work, the full amount is refunded to the same wallet on ${terms.chain}, ${terms.finalAfter} after grading, unless the model disputes the grade and a ruling pays it. If no model delivers within 24 hours, the full amount is refunded. ` +
                 `Returns an order id for ${GET_TASK_NAME}; results usually arrive within minutes. If the reply says possiblyCharged, do not post the task again: read the order with ${GET_TASK_NAME}. ` +
                 `While this server keeps running, an identical post within ${REPOST_AFTER_MINUTES} minutes returns the first post's order, marked duplicate, instead of paying again.`,
-        inputSchema: {
-            type: "object",
-            properties: {
-                title: { type: "string", minLength: 1, maxLength: 120, description: "One line naming the deliverable." },
-                brief: {
-                    type: "string",
-                    minLength: 1,
-                    maxLength: 32000,
-                    description: "What to produce, in what format, and anything the model must not do. Models cannot browse, so include every fact they need.",
-                },
-                levels: {
-                    type: "array",
-                    items: { type: "string", minLength: 1, maxLength: 200 },
-                    minItems: 2,
-                    maxItems: 3,
-                    description: "Two or three quality levels, best first, each a short description a reader could check. With three, the work is paid if it reaches the second level or better; with two, only the first.",
-                },
-            },
-            required: ["title", "brief", "levels"],
-            additionalProperties: false,
-        },
+        inputSchema: POST_TASK_INPUT,
         annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: true },
     };
 }
@@ -42,7 +44,7 @@ export const GET_TASK_TOOL = {
     name: GET_TASK_NAME,
     title: "Read a BrainChain order",
     description: "Read an order from brainchain_post_task: the payment, the task's status on BrainChain, Jev's grade, the result text once the work is accepted, and the refund transaction if it is not. " +
-        "Call again after `retryAfterSeconds` until `done` is true. `next` says what the order's state means and what to do.",
+        "Call again after `retryAfterSeconds` until `done` is true. `next` says what the order's state means and what to do. A rejected task stays not done until the refund is sent, when the dispute window closes.",
     inputSchema: {
         type: "object",
         properties: { order: { type: "string", pattern: "^0x[0-9a-fA-F]{64}$", description: "Order id returned by brainchain_post_task." } },
@@ -51,20 +53,39 @@ export const GET_TASK_TOOL = {
     },
     annotations: { readOnlyHint: true, openWorldHint: true },
 };
-const trimmed = (value, max) => (typeof value === "string" && value.trim().length > 0 && value.trim().length <= max ? value.trim() : undefined);
-/** The desk's own limits, applied to what is sent, before anything is signed. Returns an error message, or the trimmed brief. */
+const typeName = (value) => (value === null ? "null" : Array.isArray(value) ? "an array" : typeof value === "object" ? "an object" : `a ${typeof value}`);
+const count = (n) => n.toLocaleString("en-US");
+/** A string field as it is sent, trimmed; throws what is wrong with it. */
+function text(name, value, max = Infinity) {
+    if (value === undefined)
+        throw new Error(`${name} is required.`);
+    if (typeof value !== "string")
+        throw new Error(`${name} must be a string, not ${typeName(value)}.`);
+    const sent = value.trim();
+    if (sent.length === 0)
+        throw new Error(`${name} is empty.`);
+    if (sent.length > max)
+        throw new Error(`${name} is ${count(sent.length)} characters; the limit is ${count(max)}.`);
+    return sent;
+}
+function refuseUnknownFields(input, schema) {
+    const known = Object.keys(schema.properties ?? {});
+    const unknown = Object.keys(input).filter((key) => !known.includes(key));
+    if (unknown.length > 0)
+        throw new Error(`Unknown field${unknown.length === 1 ? "" : "s"}: ${unknown.join(", ")}. This tool takes only ${known.join(", ")}.`);
+}
+/** The desk's own limits, applied to what is sent, before anything is signed. Returns the trimmed brief; throws what is wrong with it. */
 export function checkBrief(input) {
-    const title = trimmed(input.title, 120);
-    if (!title)
-        return "title must be 1 to 120 characters.";
-    const brief = trimmed(input.brief, 32_000);
-    if (!brief)
-        return "brief must be 1 to 32,000 characters.";
-    const levels = Array.isArray(input.levels) ? input.levels.map((l) => trimmed(l, 200)) : [];
-    if (levels.length < 2 || levels.length > 3 || !levels.every((l) => l !== undefined)) {
-        return "levels must list 2 or 3 quality levels, best first, each 1 to 200 characters.";
-    }
-    return { title, brief, levels };
+    const title = text("title", input.title, 120);
+    const brief = text("brief", input.brief, 32_000);
+    const { levels } = input;
+    if (levels === undefined)
+        throw new Error("levels is required.");
+    if (!Array.isArray(levels))
+        throw new Error(`levels must be an array of strings, not ${typeName(levels)}.`);
+    if (levels.length < 2 || levels.length > 3)
+        throw new Error(`levels must list 2 or 3 quality levels, best first; this lists ${levels.length}.`);
+    return { title, brief, levels: levels.map((level, i) => text(`levels[${i}]`, level, 200)) };
 }
 function reply(value, isError = false) {
     return { content: [{ type: "text", text: JSON.stringify(value, null, 2) }], isError };
@@ -81,15 +102,14 @@ export async function callTool(desk, name, args) {
     const input = (args ?? {});
     try {
         if (name === POST_TASK_NAME) {
-            const brief = checkBrief(input);
-            if (typeof brief === "string")
-                return reply({ error: brief }, true);
-            return reply(await desk.post(brief));
+            refuseUnknownFields(input, POST_TASK_INPUT);
+            return reply(await desk.post(checkBrief(input)));
         }
         if (name === GET_TASK_NAME) {
-            const order = typeof input.order === "string" ? input.order.trim().toLowerCase() : "";
+            refuseUnknownFields(input, GET_TASK_TOOL.inputSchema);
+            const order = text("order", input.order).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);
+                throw new Error("order must be the 0x-prefixed, 64-character hex id that brainchain_post_task returned.");
             return orderReply(await desk.get(order));
         }
         return reply({ error: `Unknown tool ${name}.` }, true);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "brainchain-mcp",
-  "version": "0.4.3",
+  "version": "0.5.0",
   "description": "MCP server for BrainChain: let your agent hire a frontier model for a task and pay in USDG on Robinhood Chain or USDC on Base, only for work that meets the quality bar you set.",
   "mcpName": "com.usebrainchain/brainchain",
   "license": "MIT",