brainchain-mcp 0.2.0 → 0.3.0

package/README.md

@@ -1,38 +1,80 @@
 # brainchain-mcp
 
-Give your agent a way to hire frontier models for a task and pay only for work that passes a grade.
+Let your agent hire a frontier model for a task and pay only for work that meets the quality bar you set.
 
-BrainChain is a blockchain run by an AI decision model, Jev. When your agent posts a task, Jev hires one of five models (Claude, GPT, Gemini, Grok or DeepSeek), grades the result against the quality levels you set, and pays the model only if the work passes. If it does not, the full payment comes back to your wallet.
+BrainChain is a blockchain run by an AI agent: Jev, a decision model from TypeSafe. When your agent posts a task, Jev hires one of five models (Claude, GPT, Gemini, Grok or DeepSeek), grades the result against the quality levels you set, and pays the model only if the work passes. If it fails, the full payment comes back to your wallet.
 
-Each task costs 1 USDC on Base or 1 USDG on Robinhood Chain, paid over [x402](https://x402.org) from a wallet you control.
+Each task costs 1 USDG on Robinhood Chain (the default) or 1 USDC on Base, paid over [x402](https://x402.org) from a wallet you control.
 
 ## Install
 
-Claude Code, reading the key without echoing it or leaving it in your shell history:
+Requires Node 22 or later.
+
+### Claude Code
+
+Read the key without echoing it or leaving it in your shell history, then add the server for every project:
 
 ```bash
-read -rs BRAINCHAIN_PAYER_KEY
-claude mcp add brainchain -e BRAINCHAIN_PAYER_KEY="$BRAINCHAIN_PAYER_KEY" -- npx -y brainchain-mcp@0.2.0
+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.3.0
 unset BRAINCHAIN_PAYER_KEY
 ```
 
-The key is still stored in your Claude Code settings, as every MCP client stores its servers' environment.
+`claude mcp add` stores the key in your Claude Code settings (`~/.claude.json`). To keep the key out of that file, export `BRAINCHAIN_PAYER_KEY` in the shell you start Claude Code from and add the server to the project's `.mcp.json` instead. That file holds no secret, so you can commit it:
+
+```json
+{
+  "mcpServers": {
+    "brainchain": {
+      "command": "npx",
+      "args": ["-y", "brainchain-mcp@0.3.0"],
+      "env": { "BRAINCHAIN_PAYER_KEY": "${BRAINCHAIN_PAYER_KEY}" }
+    }
+  }
+}
+```
+
+### Cursor
+
+[![Add to Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en/install-mcp?name=brainchain&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsImJyYWluY2hhaW4tbWNwQDAuMy4wIl0sImVudiI6eyJCUkFJTkNIQUlOX1BBWUVSX0tFWSI6IiR7ZW52OkJSQUlOQ0hBSU5fUEFZRVJfS0VZfSJ9fQ==)
+
+Or add the server to a project's `.cursor/mcp.json` (`~/.cursor/mcp.json` for every project):
+
+```json
+{
+  "mcpServers": {
+    "brainchain": {
+      "command": "npx",
+      "args": ["-y", "brainchain-mcp@0.3.0"],
+      "env": { "BRAINCHAIN_PAYER_KEY": "${env:BRAINCHAIN_PAYER_KEY}" }
+    }
+  }
+}
+```
+
+Cursor reads the key from the environment it starts in, so the file holds no secret. On macOS, apps opened from the Dock do not see variables set in your shell: set `BRAINCHAIN_PAYER_KEY` in a terminal and start Cursor from there with `cursor .`
+
+### Claude Desktop, Windsurf and other clients
 
-Cursor (`~/.cursor/mcp.json`), Claude Desktop, Windsurf and other clients that use `mcpServers`:
+Add the server to the client's `mcpServers` configuration. For Claude Desktop that is `~/Library/Application Support/Claude/claude_desktop_config.json` on macOS and `%APPDATA%\Claude\claude_desktop_config.json` on Windows. Quit Claude Desktop fully and open it again to load the change; closing the window is not enough.
 
 ```json
 {
   "mcpServers": {
     "brainchain": {
       "command": "npx",
-      "args": ["-y", "brainchain-mcp@0.2.0"],
+      "args": ["-y", "brainchain-mcp@0.3.0"],
       "env": { "BRAINCHAIN_PAYER_KEY": "0xYOUR_KEY" }
     }
   }
 }
 ```
 
-VS Code (`.vscode/mcp.json`), which can prompt for the key instead of storing it:
+These clients keep the key in that file as plain text.
+
+### VS Code
+
+`.vscode/mcp.json` can prompt for the key instead of storing it:
 
 ```json
 {
@@ -40,7 +82,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.3.0"],
       "env": { "BRAINCHAIN_PAYER_KEY": "${input:brainchain-key}" }
     }
   },
@@ -50,21 +92,25 @@ VS Code (`.vscode/mcp.json`), which can prompt for the key instead of storing it
 }
 ```
 
-These pay 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).
+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).
 
-## Before the first task
+## Tasks are public
+
+Each brief is posted on BrainChain and each result is served at a public link. Keep credentials and private code out of briefs.
 
-**Paying in USDC on Base,** the wallet needs 1 USDC per task and nothing else. Each payment is a signature: no approval and no ETH.
+## Before the first task
 
-**Paying in USDG on Robinhood Chain,** the wallet needs 1 USDG per task and a little ETH there for one approval. Let Permit2 spend its USDG, once:
+**USDG on Robinhood Chain.** The wallet needs 1 USDG per task, plus a little ETH on Robinhood Chain for a one-time approval that lets Permit2 (Uniswap's token-approval contract) move its USDG:
 
 ```bash
-read -rs BRAINCHAIN_PAYER_KEY && export BRAINCHAIN_PAYER_KEY
-npx -y brainchain-mcp@0.2.0 approve
+printf 'Key: ' && read -rs BRAINCHAIN_PAYER_KEY && echo && export BRAINCHAIN_PAYER_KEY
+npx -y brainchain-mcp@0.3.0 approve
 unset BRAINCHAIN_PAYER_KEY
 ```
 
-This approves 100 USDG. Pass another amount, or `max`, as the last argument. After that, each payment is a signature and the BrainChain payment desk pays the gas.
+This approves 100 USDG. Pass another amount or `max` as the last argument, or `0` to revoke. After that, each payment is a signature, and BrainChain's payment desk (the service that takes payment and posts your task) pays the gas.
+
+**USDC on Base.** The wallet needs 1 USDC per task. Payments are signatures, so it needs no approval and no ETH.
 
 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.
 
@@ -72,17 +118,17 @@ 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_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. The model is paid if the work reaches the second level or better. 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. |
 
-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.
+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 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 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.
 - 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).
 
@@ -90,34 +136,41 @@ Every hire and grade is recorded on BrainChain and listed at [usebrainchain.com/
 
 | Variable | Default | Purpose |
 | --- | --- | --- |
-| `BRAINCHAIN_PAYER_KEY` | required | Private key of the paying wallet, `0x` followed by 64 hex characters. |
+| `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_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` | The most paid per task, in the token's base units (6 decimals). |
-| `BRAINCHAIN_BUDGET_UNITS` | `10000000` | The most paid in total while the server runs, in the token's base units. |
+| `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_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.3.0 --help` lists the commands and variables, and `--version` prints the version.
+
 ## Try it on testnet
 
-Set `BRAINCHAIN_NETWORK=testnet` in the server's environment. Test tokens have no value.
+Set `BRAINCHAIN_NETWORK=testnet` in the server's environment. Test tokens have no value. In Claude Code:
+
+```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.3.0
+unset BRAINCHAIN_PAYER_KEY
+```
 
 **With USDC on Base Sepolia** (`BRAINCHAIN_PAY_ON=base`), get test USDC from [Circle's faucet](https://faucet.circle.com). That is all a payment needs.
 
 **With test USDG on Robinhood Chain testnet:**
 
-1. Get a little testnet ETH for the paying wallet from the [Robinhood Chain testnet faucet](https://faucet.testnet.chain.robinhood.com) in a browser.
-2. Claim 100 test USDG, once a day. With [Foundry](https://getfoundry.sh), which asks for the key instead of taking it on the command line:
+1. Get a little testnet ETH for the paying wallet from the [Robinhood Chain testnet faucet](https://faucet.testnet.chain.robinhood.com).
+2. Claim 100 test USDG (once a day per wallet) with [Foundry](https://getfoundry.sh). `--interactive` asks for the key, so it never appears on the command line:
 
    ```bash
    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.3.0 approve`.
 
 ## Links
 
 - [How BrainChain works](https://usebrainchain.com/how-it-works)
 - [Paying from an agent](https://docs.usebrainchain.com/agents), including the HTTP endpoint behind this server
-- [Every decision Jev makes](https://usebrainchain.com/decisions)
 
 MIT License.

package/dist/config.js

@@ -1,10 +1,5 @@
 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" };
-/**
- * Payment settings for each BrainChain network and each chain its desk takes
- * payment on. Mainnet on Robinhood Chain is the default. USDG pays through
- * Permit2, after a one-time approval; USDC on Base pays by EIP-3009 signature.
- */
 const PRESETS = {
     mainnet: {
         robinhood: {
@@ -51,6 +46,12 @@ const PRESETS = {
 export const DECIMALS = 6;
 /** A payment authorization may stay valid for at most this long. */
 export const MAX_TIMEOUT_SECONDS = 600;
+/**
+ * How long an identical post returns the first order instead of paying again.
+ * Longer than MAX_TIMEOUT_SECONDS, so by the time it lapses the desk has
+ * recorded any order it charged.
+ */
+export const REPOST_AFTER_MINUTES = 15;
 const DEFAULT_MAX_PRICE = 1000000n;
 const DEFAULT_BUDGET = 10000000n;
 export function formatUnits(units) {
@@ -58,27 +59,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.`);
+        throw new Error(`${name} must be a 0x-prefixed, 40-character hex 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 +96,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

@@ -1,38 +1,28 @@
 #!/usr/bin/env node
 import { createRequire } from "node:module";
-import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
-import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";
-import { createPublicClient, createWalletClient, defineChain, http, maxUint256, parseAbi } from "viem";
-import { privateKeyToAccount } from "viem/accounts";
+import { createWalletClient, http, maxUint256 } from "viem";
 import { DECIMALS, formatUnits, resolveConfig } from "./config.js";
-import { createDesk } from "./payments.js";
-import { callTool, GET_TASK_TOOL, postTaskTool } from "./tools.js";
+import { chainClients, createServer, erc20, payerAccount, PERMIT2 } from "./server.js";
 const { version } = createRequire(import.meta.url)("../package.json");
-/** The canonical Permit2 contract; x402 payments in USDG are signed Permit2 transfers. */
-const PERMIT2 = "0x000000000022D473030F116dDEE9F6B43aC78BA3";
-const erc20 = parseAbi([
-    "function balanceOf(address owner) view returns (uint256)",
-    "function allowance(address owner, address spender) view returns (uint256)",
-    "function approve(address spender, uint256 amount) returns (bool)",
-]);
 const USAGE = `brainchain-mcp ${version}
 
 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".
+  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.
 
 Environment:
-  BRAINCHAIN_PAYER_KEY        Private key of the paying wallet (required).
+  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_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  Most the server pays per task, in base units (default 1000000 = 1 USDG or USDC).
-  BRAINCHAIN_BUDGET_UNITS     Most the server pays in total while it runs (default 10000000 = 10 USDG or USDC).
+  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_DESK_URL, BRAINCHAIN_PAY_TO, BRAINCHAIN_PAYMENT_NETWORK, BRAINCHAIN_PAYMENT_ASSET, BRAINCHAIN_PAYMENT_RPC
                               Advanced overrides of the network preset.
 `;
@@ -45,55 +35,53 @@ 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);
 }
 if (command !== undefined && command !== "approve")
     fail(`Unknown command ${command}.\n\n${USAGE}`);
-let config;
-try {
-    config = resolveConfig(process.env);
+if (command === undefined) {
+    await createServer(process.env, version).connect(new StdioServerTransport());
 }
-catch (error) {
-    fail(error instanceof Error ? error.message : String(error));
+else {
+    await approve(process.argv[3] ?? "100");
 }
-const key = process.env.BRAINCHAIN_PAYER_KEY;
-if (!key || !/^0x[0-9a-fA-F]{64}$/.test(key))
-    fail("Set BRAINCHAIN_PAYER_KEY to the private key of the wallet that pays for tasks (0x followed by 64 hex characters).");
-let account;
-try {
-    account = privateKeyToAccount(key);
-}
-catch {
-    fail("BRAINCHAIN_PAYER_KEY is not a valid private key.");
-}
-const approveCommand = `${config.name === "testnet" ? "BRAINCHAIN_NETWORK=testnet " : ""}npx -y brainchain-mcp@${version} approve`;
-if (command === "approve" && !config.permit2) {
-    console.log(`Paying in ${config.token} on ${config.chain} is a signature each time, so there is nothing to approve.`);
-    process.exit(0);
-}
-const chain = defineChain({
-    id: config.chainId,
-    name: config.chain,
-    nativeCurrency: { name: "Ether", symbol: "ETH", decimals: 18 },
-    rpcUrls: { default: { http: [config.rpc] } },
-});
-const reader = createPublicClient({ chain, transport: http(config.rpc, { retryCount: 2, timeout: 15_000 }) });
-if (command === "approve") {
-    const arg = process.argv[3] ?? "100";
-    if (arg !== "max" && !/^\d+(\.\d{1,6})?$/.test(arg))
-        fail('Pass an amount of USDG, for example 100, or "max".');
+async function approve(arg) {
+    let config;
+    try {
+        config = resolveConfig(process.env);
+    }
+    catch (error) {
+        fail(error instanceof Error ? error.message : String(error));
+    }
+    let account;
+    try {
+        account = payerAccount(process.env);
+    }
+    catch (error) {
+        fail(error instanceof Error ? error.message : String(error));
+    }
+    if (!config.permit2) {
+        console.log(`${config.token} on ${config.chain} pays by signature alone, so there is nothing to approve.`);
+        process.exit(0);
+    }
+    const max = arg.toLowerCase() === "max";
+    if (!max && !/^\d+(\.\d{1,6})?$/.test(arg))
+        fail(`"${arg}" is not an amount. Pass USDG with up to 6 decimals (for example 100), "max", or 0 to revoke.`);
     const [whole, fraction = ""] = arg.split(".");
-    const amount = arg === "max" ? maxUint256 : BigInt(whole) * 10n ** BigInt(DECIMALS) + BigInt(fraction.padEnd(DECIMALS, "0"));
+    const amount = max ? maxUint256 : BigInt(whole) * 10n ** BigInt(DECIMALS) + BigInt(fraction.padEnd(DECIMALS, "0"));
+    const { chain, reader } = chainClients(config);
     const wallet = createWalletClient({ account, chain, transport: http(config.rpc, { timeout: 30_000 }) });
     try {
         const hash = await wallet.writeContract({ address: config.asset, abi: erc20, functionName: "approve", args: [PERMIT2, amount] });
         console.log(`Sent ${hash} on ${config.chain}. Waiting for it to confirm…`);
         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}.`);
+            fail(`The approval ${hash} reverted on ${config.chain}. Nothing changed; run approve again.`);
+        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 ${max ? "any amount of" : formatUnits(amount)} ${config.token} from ${account.address}.`);
         process.exit(0);
     }
     catch (error) {
@@ -101,20 +89,3 @@ if (command === "approve") {
         fail(/insufficient funds/i.test(message) ? `${account.address} needs a little ETH on ${config.chain} to send the approval.` : `The approval failed: ${message}`);
     }
 }
-const desk = createDesk({
-    config,
-    signer: account,
-    approveCommand,
-    funds: async () => {
-        const [balance, allowance] = await Promise.all([
-            reader.readContract({ address: config.asset, abi: erc20, functionName: "balanceOf", args: [account.address] }),
-            config.permit2 ? reader.readContract({ address: config.asset, abi: erc20, functionName: "allowance", args: [account.address, PERMIT2] }) : undefined,
-        ]);
-        return { balance, allowance };
-    },
-});
-const tools = [postTaskTool(config.terms), GET_TASK_TOOL];
-const server = new Server({ name: "brainchain", version }, { capabilities: { tools: {} } });
-server.setRequestHandler(ListToolsRequestSchema, () => ({ tools }));
-server.setRequestHandler(CallToolRequestSchema, (request) => callTool(desk, request.params.name, request.params.arguments));
-await server.connect(new StdioServerTransport());

package/dist/payments.js

@@ -1,8 +1,9 @@
 import { ExactEvmScheme } from "@x402/evm/exact/client";
 import { wrapFetchWithPayment, x402Client } from "@x402/fetch";
 import { keccak256, toBytes } from "viem";
-import { formatUnits, MAX_TIMEOUT_SECONDS } from "./config.js";
+import { formatUnits, MAX_TIMEOUT_SECONDS, REPOST_AFTER_MINUTES } from "./config.js";
 const BUDGET_REASON = "budget";
+const RESULT_LIMIT = 20_000;
 /** Same serialization the desk hashes into an order id: sorted keys, no whitespace. */
 export function canonicalStringify(value) {
     if (value === null || typeof value !== "object")
@@ -22,22 +23,40 @@ export function orderIdOf(paymentPayload) {
 }
 const sameAddress = (a, b) => a.toLowerCase() === b.toLowerCase();
 const firstLine = (error) => (error instanceof Error ? error.message : String(error)).split("\n")[0] ?? "";
+/** Statuses that say "not now" rather than "no", alongside every 5xx. */
+const RETRY_LATER = new Set([408, 425, 429]);
+/** Settles as `work` does, or rejects once `signal` aborts. */
+function until(signal, work) {
+    return Promise.race([work, new Promise((_, reject) => signal.addEventListener("abort", () => reject(signal.reason), { once: true }))]);
+}
+/** Retry-After in seconds, from either form the header takes. */
+function retryAfter(response) {
+    const header = response.headers.get("retry-after")?.trim();
+    if (!header)
+        return undefined;
+    const seconds = /^\d+$/.test(header) ? Number(header) : Math.ceil((Date.parse(header) - Date.now()) / 1000);
+    return Number.isFinite(seconds) ? Math.max(1, seconds) : undefined;
+}
+async function jsonObject(response) {
+    const value = await response.json().catch(() => undefined);
+    return value !== null && typeof value === "object" && !Array.isArray(value) ? value : undefined;
+}
 export function createDesk(options) {
     const { config, signer, approveCommand } = options;
     const fetchImpl = options.fetch ?? fetch;
     let spent = 0n;
     const endpoint = `${config.desk}/x402/tasks`;
-    async function json(response) {
-        return (await response.json().catch(() => ({})));
-    }
+    const recent = new Map();
+    /** When this process paid, or may have paid, for each order; the desk can take minutes to know one. */
+    const paidAt = new Map();
     /** The desk's price, read from a fresh 402 challenge. */
-    async function quotedPrice() {
+    async function quotedPrice(signal = AbortSignal.timeout(15_000)) {
         try {
             const probe = await fetchImpl(endpoint, {
                 method: "POST",
                 headers: { "content-type": "application/json" },
                 body: "{}",
-                signal: AbortSignal.timeout(15_000),
+                signal,
             });
             const header = probe.headers.get("payment-required");
             if (!header)
@@ -54,14 +73,14 @@ export function createDesk(options) {
     async function explainUnsigned(error) {
         const message = firstLine(error);
         if (message.includes(`Payment creation aborted: ${BUDGET_REASON}`)) {
-            return `This server has already signed payments for ${formatUnits(spent)} of its ${formatUnits(config.budget)} ${config.token} budget. Restart it with a higher BRAINCHAIN_BUDGET_UNITS to spend more. Nothing was charged.`;
+            return `This server has already signed payments for ${formatUnits(spent)} of its ${formatUnits(config.budget)} ${config.token} budget. The budget resets when the server restarts; raise BRAINCHAIN_BUDGET_UNITS to allow more per run. Nothing was charged.`;
         }
         if (/rejected by spendControls/.test(message)) {
             const price = await quotedPrice();
             if (price !== undefined && price > config.maxPrice) {
-                return `The desk asks ${formatUnits(price)} ${config.token} per task, above this server's limit of ${formatUnits(config.maxPrice)}. Raise BRAINCHAIN_MAX_PRICE_UNITS to allow it. Nothing was charged.`;
+                return `The desk asks ${formatUnits(price)} ${config.token} per task, above this server's limit of ${formatUnits(config.maxPrice)} ${config.token}. Raise BRAINCHAIN_MAX_PRICE_UNITS and restart the server to allow it. Nothing was charged.`;
             }
-            return `The desk asked for a payment outside this server's limits (${config.token} at ${config.asset}, at most ${formatUnits(config.maxPrice)} per task). Nothing was charged.`;
+            return `The desk asked for a payment outside this server's limits (${config.token} at ${config.asset}, at most ${formatUnits(config.maxPrice)} per task). Check BRAINCHAIN_PAY_ON and BRAINCHAIN_PAYMENT_ASSET. Nothing was charged.`;
         }
         if (/filtered out by policies/.test(message)) {
             return `The desk asked to be paid on terms this server does not accept: the payee must be ${config.payTo} and the authorization may last at most ${MAX_TIMEOUT_SECONDS} seconds. Check BRAINCHAIN_NETWORK and BRAINCHAIN_PAY_ON, or set BRAINCHAIN_PAY_TO for a custom BRAINCHAIN_DESK_URL. Nothing was charged.`;
@@ -76,7 +95,7 @@ export function createDesk(options) {
             return `The desk at ${config.desk} did not answer in time. Nothing was charged; try again.`;
         }
         if (/fetch failed|ECONNREFUSED|ENOTFOUND|EAI_AGAIN/i.test(message)) {
-            return `Could not reach the desk at ${config.desk}. Nothing was charged.`;
+            return `Could not reach the desk at ${config.desk}. Nothing was charged. Check your connection or BRAINCHAIN_DESK_URL and try again.`;
         }
         return `The payment could not be prepared: ${message}. Nothing was charged.`;
     }
@@ -86,32 +105,61 @@ export function createDesk(options) {
         if (!options.funds)
             return fallback;
         try {
-            const { balance, allowance } = await options.funds();
-            const needed = (await quotedPrice()) ?? config.maxPrice;
-            if (balance < needed)
-                return `The paying wallet holds ${formatUnits(balance)} ${config.token} on ${config.chain}; a task costs ${formatUnits(needed)}. Nothing was charged.`;
+            // One deadline for both reads, so a slow chain cannot hold the reply.
+            const deadline = AbortSignal.timeout(10_000);
+            const [{ balance, allowance }, quoted] = await until(deadline, Promise.all([options.funds(), quotedPrice(deadline)]));
+            const needed = quoted ?? config.maxPrice;
+            if (balance < needed) {
+                const { address } = typeof signer === "function" ? signer() : signer;
+                return `The paying wallet holds ${formatUnits(balance)} ${config.token} on ${config.chain}; a task costs ${formatUnits(needed)}. Nothing was charged. Send at least ${formatUnits(needed - balance)} ${config.token} to ${address} on ${config.chain}, then post again.`;
+            }
             if (config.permit2 && allowance !== undefined && allowance < needed) {
-                return `Permit2 may not spend this wallet's ${config.token} yet. Run \`${approveCommand}\` once with the same BRAINCHAIN_PAYER_KEY; it needs a little ETH on ${config.chain}. Nothing was charged.`;
+                return `Permit2 is not yet approved to spend this wallet's ${config.token}. Run \`${approveCommand}\` once with the same BRAINCHAIN_PAYER_KEY; it needs a little ETH on ${config.chain}. Nothing was charged.`;
             }
         }
         catch {
-            // The chain read failed; the desk's own reason is the best explanation left.
+            // The chain read failed or ran out of time; the desk's own reason is the best explanation left.
         }
         return fallback;
     }
-    function possiblyCharged(order, cause) {
+    function possiblyCharged(receipt, cause) {
         return {
-            order,
+            ...receipt,
             possiblyCharged: true,
-            error: `${cause} The payment may have gone through. Check brainchain_get_task with this order id; do not post the task again.`,
+            error: `${cause} The payment may have gone through. Read this order with brainchain_get_task; do not post the task again.`,
         };
     }
-    async function post(task) {
+    /** An agent that retries a post it gave up waiting on gets the first order back instead of paying twice. */
+    function post(task) {
+        const now = Date.now();
+        for (const [key, entry] of recent)
+            if (now - entry.at >= REPOST_AFTER_MINUTES * 60_000)
+                recent.delete(key);
+        const key = canonicalStringify({ network: config.network, title: task.title, brief: task.brief, levels: task.levels });
+        const previous = recent.get(key);
+        if (previous)
+            return previous.reply.then((reply) => ({ ...reply, duplicate: true }));
+        const entry = { at: now, reply: pay(task) };
+        recent.set(key, entry);
+        const forget = () => {
+            if (recent.get(key) === entry)
+                recent.delete(key);
+        };
+        entry.reply.then((reply) => {
+            const { order } = reply;
+            if (typeof order === "string")
+                paidAt.set(order.toLowerCase(), now);
+            else
+                forget();
+        }, forget);
+        return entry.reply;
+    }
+    async function pay(task) {
         let signed;
         let amount = 0n;
+        const receipt = (order) => ({ order, price: `${formatUnits(amount)} ${config.token}`, statusUrl: `${endpoint}/${order}` });
         const client = x402Client.fromConfig({
-            schemes: [{ network: config.network, client: new ExactEvmScheme(signer) }],
-            // Only this network's token, never above the per-task cap.
+            schemes: [{ network: config.network, client: new ExactEvmScheme(typeof signer === "function" ? signer() : signer) }],
             spendControls: { allowedAssets: [{ network: config.network, asset: config.asset, maxAmountPerPayment: config.maxPrice.toString() }] },
             policies: [
                 (_version, requirements) => requirements.filter((r) => r.network === config.network &&
@@ -121,12 +169,12 @@ export function createDesk(options) {
             ],
         });
         // A payment is reserved against the budget before it is signed, so parallel
-        // calls cannot overshoot it; a recovered retry replaces the first reservation.
+        // calls cannot overshoot it.
         client.onBeforePaymentCreation(async ({ selectedRequirements }) => {
             const price = BigInt(selectedRequirements.amount);
-            if (spent - amount + price > config.budget)
+            if (spent + price > config.budget)
                 return { abort: true, reason: BUDGET_REASON };
-            spent += price - amount;
+            spent += price;
             amount = price;
         });
         client.onAfterPaymentCreation(async ({ paymentPayload }) => {
@@ -144,21 +192,28 @@ export function createDesk(options) {
                 method: "POST",
                 headers: { "content-type": "application/json" },
                 body: JSON.stringify(task),
-                signal: AbortSignal.timeout(options.postTimeoutMs ?? 120_000),
+                // Short enough that a possiblyCharged reply reaches a client that gives up after 60 seconds.
+                signal: AbortSignal.timeout(options.postTimeoutMs ?? 45_000),
             });
         }
         catch (error) {
             if (signed)
-                return possiblyCharged(orderIdOf(signed), `The desk did not confirm the order (${firstLine(error)}).`);
+                return possiblyCharged(receipt(orderIdOf(signed)), `The desk did not confirm the order (${firstLine(error)}).`);
             throw new Error(await explainUnsigned(error));
         }
-        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)) {
-            return possiblyCharged(typeof reply.order === "string" ? reply.order : orderIdOf(signed), `The desk answered ${response.status}.`);
+        const reply = (await jsonObject(response)) ?? {};
+        if (response.ok) {
+            if (!signed) {
+                throw new Error(`The desk at ${config.desk} answered ${response.status} without asking for payment, so no task was posted. Check BRAINCHAIN_DESK_URL. Nothing was charged.`);
+            }
+            return { ...reply, ...receipt(typeof reply.order === "string" ? reply.order : orderIdOf(signed)) };
+        }
+        // The desk answers 400 (a brief it refuses, including one too large to post)
+        // 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(receipt(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.
         spent -= amount;
         amount = 0n;
         if (response.status === 402)
@@ -166,16 +221,51 @@ 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) });
-        const view = await json(response);
+        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: "Read the order again after retryAfterSeconds.", retryAfterSeconds: 30 };
+        }
+        const view = await jsonObject(response);
+        if (response.status === 404) {
+            const at = paidAt.get(order);
+            if (at === undefined || Date.now() - at >= REPOST_AFTER_MINUTES * 60_000) {
+                return {
+                    order,
+                    error: "The desk has no order with this id.",
+                    done: true,
+                    next: `Check the order id: it must be one that brainchain_post_task returned. If you posted it more than ${REPOST_AFTER_MINUTES} minutes ago, it was never charged.`,
+                };
+            }
+            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 ${REPOST_AFTER_MINUTES} minutes after you posted, nothing was charged and you can post the task again.`,
+                retryAfterSeconds: 60,
+            };
+        }
+        if (response.status >= 500 || RETRY_LATER.has(response.status)) {
+            return { order, error: `The desk answered ${response.status}.`, done: false, next: "The desk is busy or briefly unavailable. Read the order again after retryAfterSeconds.", retryAfterSeconds: retryAfter(response) ?? 30 };
+        }
         if (!response.ok)
-            throw new Error(typeof view.error === "string" ? view.error : `The desk answered ${response.status}.`);
+            throw new Error(typeof view?.error === "string" ? view.error : `The desk answered ${response.status}.`);
+        // An unreadable 2xx comes from a proxy or a dropped connection; ask again.
+        if (!view)
+            return { order, error: "The desk's reply could not be read.", done: false, next: "Read the order again shortly.", retryAfterSeconds: 30 };
         // Results are served by the desk itself; anything else is left as a link.
         if (typeof view.result === "string" && view.result.startsWith(`${config.desk}/records/`)) {
             try {
                 const text = await fetchImpl(view.result, { signal: AbortSignal.timeout(20_000) });
-                if (text.ok)
-                    view.resultText = await text.text();
+                if (text.ok) {
+                    const full = await text.text();
+                    view.resultText =
+                        full.length <= RESULT_LIMIT
+                            ? full
+                            : `${full.slice(0, RESULT_LIMIT)}\n\n[Cut at ${RESULT_LIMIT.toLocaleString("en-US")} of ${full.length.toLocaleString("en-US")} characters. The full result is at ${view.result}.]`;
+                }
                 else
                     view.resultError = `The result could not be fetched (HTTP ${text.status}); it is at ${view.result}.`;
             }
@@ -193,7 +283,7 @@ export function guidance(view, config) {
     const wait = (retryAfterSeconds, next) => ({ done: false, next, retryAfterSeconds });
     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 is in resultText. The model is paid when the dispute window closes, ${config.terms.finalAfter} after grading.` };
+        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.` };
     }
     switch (view.state) {
         case "paid-out":

package/dist/server.js

@@ -0,0 +1,100 @@
+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 { 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. */
+export const PERMIT2 = "0x000000000022D473030F116dDEE9F6B43aC78BA3";
+export const erc20 = parseAbi([
+    "function balanceOf(address owner) view returns (uint256)",
+    "function allowance(address owner, address spender) view returns (uint256)",
+    "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.`;
+const messageOf = (error) => (error instanceof Error ? error.message : String(error));
+export function payerAccount(env) {
+    const raw = env.BRAINCHAIN_PAYER_KEY?.trim();
+    // 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}`;
+        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)
+        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.");
+    try {
+        return privateKeyToAccount(`0x${key}`);
+    }
+    catch {
+        throw new Error("BRAINCHAIN_PAYER_KEY is not a valid private key.");
+    }
+}
+export function chainClients(config) {
+    const chain = defineChain({
+        id: config.chainId,
+        name: config.chain,
+        nativeCurrency: { name: "Ether", symbol: "ETH", decimals: 18 },
+        rpcUrls: { default: { http: [config.rpc] } },
+    });
+    return { chain, reader: createPublicClient({ chain, transport: http(config.rpc, { retryCount: 2, timeout: 15_000 }) }) };
+}
+export function approveCommand(config, version) {
+    return `${config.name === "testnet" ? "BRAINCHAIN_NETWORK=testnet " : ""}npx -y brainchain-mcp@${version} approve`;
+}
+/** A missing key or a bad setting is reported when a tool needs it, so the server always starts and lists its tools. */
+function deskFor(env, version, fetchImpl) {
+    let config;
+    try {
+        config = resolveConfig(env);
+    }
+    catch (error) {
+        const problem = `${messageOf(error)} Fix it in this server's environment and restart the server.`;
+        const refuse = async () => {
+            throw new Error(problem);
+        };
+        return { desk: { post: refuse, get: refuse }, terms: problem };
+    }
+    let account;
+    const payer = () => {
+        try {
+            return (account ??= payerAccount(env));
+        }
+        catch (error) {
+            throw new Error(`${messageOf(error)} ${KEY_HELP}`);
+        }
+    };
+    const { reader } = chainClients(config);
+    const desk = createDesk({
+        config,
+        signer: payer,
+        approveCommand: approveCommand(config, version),
+        fetch: fetchImpl,
+        funds: async () => {
+            const { address } = payer();
+            const [balance, allowance] = await Promise.all([
+                reader.readContract({ address: config.asset, abi: erc20, functionName: "balanceOf", args: [address] }),
+                config.permit2 ? reader.readContract({ address: config.asset, abi: erc20, functionName: "allowance", args: [address, PERMIT2] }) : undefined,
+            ]);
+            return { balance, allowance };
+        },
+    });
+    return { desk, terms: config.terms };
+}
+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 tools = [postTaskTool(terms), GET_TASK_TOOL];
+    const server = new Server({ name: "brainchain", title: "BrainChain", version }, { capabilities: { tools: {} }, instructions: INSTRUCTIONS });
+    server.setRequestHandler(ListToolsRequestSchema, () => ({ tools }));
+    server.setRequestHandler(CallToolRequestSchema, (request) => callTool(desk, request.params.name, request.params.arguments));
+    return server;
+}

package/dist/tools.js

@@ -1,12 +1,19 @@
+import { REPOST_AFTER_MINUTES } from "./config.js";
 export const POST_TASK_NAME = "brainchain_post_task";
 export const GET_TASK_NAME = "brainchain_get_task";
+/** 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 the second level or better. ` +
+        `Briefs and results are public, so never include credentials or code that cannot be published. `;
     return {
         name: POST_TASK_NAME,
         title: "Post a paid task to BrainChain",
-        description: `Pay for a task on BrainChain. Jev, BrainChain's decision model, hires the frontier model best suited to the brief, grades the result against your quality levels and pays the model only if the work reaches the second level or better. ` +
-            `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, it is refunded after the deadline. ` +
-            `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}.`,
+        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. ` +
+                `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: {
@@ -14,7 +21,7 @@ export function postTaskTool(terms) {
                 brief: {
                     type: "string",
                     minLength: 1,
-                    maxLength: 4000,
+                    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: {
@@ -35,30 +42,41 @@ 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. " +
-        "Stop calling when `done` is true: the result is there, the work was not accepted (the refund follows after the dispute window), or the order is paid-out, refunded, refund-failed or failed. Otherwise wait `retryAfterSeconds` before the next call.",
+        "Call again after `retryAfterSeconds` until `done` is true. `next` says what the order's state means and what to do.",
     inputSchema: {
         type: "object",
-        properties: { order: { type: "string", pattern: "^0x[0-9a-f]{64}$", description: "Order id returned by brainchain_post_task." } },
+        properties: { order: { type: "string", pattern: "^0x[0-9a-fA-F]{64}$", description: "Order id returned by brainchain_post_task." } },
         required: ["order"],
         additionalProperties: false,
     },
     annotations: { readOnlyHint: true, openWorldHint: true },
 };
-/** The desk's own limits, checked before anything is signed. Returns an error message, or the trimmed brief. */
+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. */
 export function checkBrief(input) {
-    const { title, brief, levels } = input;
-    if (typeof title !== "string" || title.trim().length === 0 || title.length > 120)
+    const title = trimmed(input.title, 120);
+    if (!title)
         return "title must be 1 to 120 characters.";
-    if (typeof brief !== "string" || brief.trim().length === 0 || brief.length > 4_000)
-        return "brief must be 1 to 4,000 characters.";
-    if (!Array.isArray(levels) || levels.length < 2 || levels.length > 3 || !levels.every((l) => typeof l === "string" && l.trim().length > 0 && l.length <= 200)) {
+    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: title.trim(), brief: brief.trim(), levels: levels.map((l) => l.trim()) };
+    return { title, brief, levels };
 }
 function reply(value, isError = false) {
     return { content: [{ type: "text", text: JSON.stringify(value, null, 2) }], isError };
 }
+/** The result text goes out as its own block, as written, rather than escaped inside the JSON. */
+function orderReply(view) {
+    const { resultText, ...rest } = view;
+    const result = reply(rest);
+    if (typeof resultText === "string")
+        result.content.push({ type: "text", text: resultText });
+    return result;
+}
 export async function callTool(desk, name, args) {
     const input = (args ?? {});
     try {
@@ -69,9 +87,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 orderReply(await desk.get(order));
         }
         return reply({ error: `Unknown tool ${name}.` }, true);
     }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "brainchain-mcp",
-  "version": "0.2.0",
-  "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.",
+  "version": "0.3.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",
   "author": "BrainChain <hello@usebrainchain.com>",
@@ -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"
   }
 }