brainchain-mcp 0.5.1 → 0.6.1

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.5.1
+claude mcp add brainchain --scope user -e BRAINCHAIN_PAYER_KEY="$BRAINCHAIN_PAYER_KEY" -- npx -y brainchain-mcp@0.6.1
 unset BRAINCHAIN_PAYER_KEY
 ```
 
@@ -27,7 +27,7 @@ unset BRAINCHAIN_PAYER_KEY
   "mcpServers": {
     "brainchain": {
       "command": "npx",
-      "args": ["-y", "brainchain-mcp@0.5.1"],
+      "args": ["-y", "brainchain-mcp@0.6.1"],
       "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=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsImJyYWluY2hhaW4tbWNwQDAuNS4xIl0sImVudiI6eyJCUkFJTkNIQUlOX1BBWUVSX0tFWSI6IiR7ZW52OkJSQUlOQ0hBSU5fUEFZRVJfS0VZfSJ9fQ%3D%3D)
+[![Add to Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en/install-mcp?name=brainchain&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsImJyYWluY2hhaW4tbWNwQDAuNi4xIl0sImVudiI6eyJCUkFJTkNIQUlOX1BBWUVSX0tFWSI6IiR7ZW52OkJSQUlOQ0hBSU5fUEFZRVJfS0VZfSJ9fQ%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.5.1"],
+      "args": ["-y", "brainchain-mcp@0.6.1"],
       "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.5.1"],
+      "args": ["-y", "brainchain-mcp@0.6.1"],
       "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.5.1"],
+      "args": ["-y", "brainchain-mcp@0.6.1"],
       "env": { "BRAINCHAIN_PAYER_KEY": "${input:brainchain-key}" }
     }
   },
@@ -100,10 +100,10 @@ Save the key in a file only your account can read, then point the server at it:
 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.1"],"env":{"BRAINCHAIN_PAYER_KEY_FILE":"~/.brainchain/payer.key"}}'
+openclaw mcp set brainchain '{"command":"npx","args":["-y","brainchain-mcp@0.6.1"],"env":{"BRAINCHAIN_PAYER_KEY_FILE":"~/.brainchain/payer.key"}}'
 ```
 
-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.1 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.
+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.6.1 wallet` checks the file and prints the wallet it holds and its balance. [`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).
 
@@ -117,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.5.1 approve
+npx -y brainchain-mcp@0.6.1 approve
 unset BRAINCHAIN_PAYER_KEY
 ```
 
@@ -133,8 +133,9 @@ An agent with a shell on the same account can read whatever that account can, in
 
 | 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_post_task` | Pays for a task and returns an order id, the price paid and a `statusUrl`. Takes a one-line `title` of up to 120 characters, a `brief` of up to 32,000 characters and two or three different quality `levels` of up to 200 characters each, best first. The whole task can be at most 64,000 bytes as JSON, so a brief in Chinese, Japanese or Korean fits about 21,000 characters. An emoji counts as two characters. 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 (`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. |
+| `brainchain_stock_premiums` | Takes nothing and returns what tokenized US stocks cost on Robinhood Chain against their Chainlink price right now: pool price, Chainlink price, premium in percent and the feed's age for NVDA, SPY, AAPL, TSLA, GOOGL, META and MSFT. Free, no key, read from the chain. The same board is at [usebrainchain.com/premium](https://usebrainchain.com/premium). |
 
 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.
 
@@ -162,7 +163,7 @@ Every hire and grade is recorded on BrainChain and listed at [usebrainchain.com/
 | `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`, and an https URL unless it is on localhost or 127.0.0.1. |
 
-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.1 wallet` checks the settings and the key, and prints the wallet that pays. `--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, and so is a `BRAINCHAIN_STATE_DIR` that cannot hold the daily limit's record when `BRAINCHAIN_DAILY_UNITS` is set. `npx -y brainchain-mcp@0.6.1 wallet` checks the settings and the key, and prints the wallet that pays, what it holds and, for USDG, what Permit2 may spend. `--help` lists the commands and variables, and `--version` prints the version.
 
 ## Try it on testnet
 
@@ -170,7 +171,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.5.1
+claude mcp add brainchain --scope user -e BRAINCHAIN_NETWORK=testnet -e BRAINCHAIN_PAYER_KEY="$BRAINCHAIN_PAYER_KEY" -- npx -y brainchain-mcp@0.6.1
 unset BRAINCHAIN_PAYER_KEY
 ```
 
@@ -189,7 +190,7 @@ unset BRAINCHAIN_PAYER_KEY
 
    ```bash
    printf 'Key: ' && read -rs BRAINCHAIN_PAYER_KEY && echo && export BRAINCHAIN_PAYER_KEY
-   BRAINCHAIN_NETWORK=testnet npx -y brainchain-mcp@0.5.1 approve
+   BRAINCHAIN_NETWORK=testnet npx -y brainchain-mcp@0.6.1 approve
    unset BRAINCHAIN_PAYER_KEY
    ```
 

package/dist/daily.js

@@ -1,5 +1,6 @@
 // The daily limit is kept on disk, so restarting the server, or a second server
 // paying from the same wallet, does not reset what the wallet may spend today.
+import { accessSync, constants, mkdirSync } from "node:fs";
 import { mkdir, open, readFile, rename, rm, stat, writeFile } from "node:fs/promises";
 import { dirname } from "node:path";
 const LOCK_STALE_MS = 10_000;
@@ -10,6 +11,28 @@ const TAKEOVER_STALE_MS = 5_000;
 export function utcDay(now) {
     return new Date(now).toISOString().slice(0, 10);
 }
+function stateDirMessage(dir, error) {
+    const { code } = error;
+    const which = code === "EEXIST" || code === "ENOTDIR"
+        ? "is not a folder"
+        : code === "EACCES" || code === "EPERM"
+            ? "this account cannot write to"
+            : code === "EROFS"
+                ? "is on a read-only disk"
+                : `cannot be used (${code ?? String(error)})`;
+    return `BRAINCHAIN_STATE_DIR is ${dir}, which ${which}, so the daily limit's record cannot be kept there. Set it to a folder this account can write, then restart the server.`;
+}
+/** Why the daily limit's record cannot be kept in `dir`, creating the folder if it is missing; undefined when it can. */
+export function stateDirProblem(dir) {
+    try {
+        mkdirSync(dir, { recursive: true });
+        accessSync(dir, constants.W_OK);
+        return undefined;
+    }
+    catch (error) {
+        return stateDirMessage(dir, error);
+    }
+}
 /** How long ago a file was last written, or 0 when it is gone. */
 const ageOf = (file) => stat(file).then((s) => Date.now() - s.mtimeMs, () => 0);
 /**
@@ -42,7 +65,9 @@ async function clearStale(lockPath) {
 export function dailyLedger(path, limit, now = Date.now) {
     const lockPath = `${path}.lock`;
     async function locked(work) {
-        await mkdir(dirname(path), { recursive: true });
+        await mkdir(dirname(path), { recursive: true }).catch((error) => {
+            throw new Error(stateDirMessage(dirname(path), error));
+        });
         const deadline = Date.now() + LOCK_WAIT_MS;
         for (;;) {
             try {
@@ -51,7 +76,7 @@ export function dailyLedger(path, limit, now = Date.now) {
             }
             catch (error) {
                 if (error.code !== "EEXIST")
-                    throw error;
+                    throw new Error(stateDirMessage(dirname(path), error));
             }
             if ((await ageOf(lockPath)) > LOCK_STALE_MS && (await clearStale(lockPath)))
                 continue;

package/dist/index.js

@@ -3,18 +3,20 @@ 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 { approvalFailure, chainClients, createServer, erc20, payerAccount, PERMIT2 } from "./server.js";
+import { stateDirProblem } from "./daily.js";
+import { approvalFailure, approveCommand, chainClients, createServer, erc20, payerAccount, PERMIT2, walletFunds, walletReport } from "./server.js";
 const { version } = createRequire(import.meta.url)("../package.json");
 const USAGE = `brainchain-mcp ${version}
 
-MCP server that pays for tasks on BrainChain and reads their graded results.
+MCP server that pays for tasks on BrainChain, reads their graded results, and reads what stock tokens cost on Robinhood Chain.
 
 Usage:
   brainchain-mcp                 Start the server on stdio (what MCP clients run).
   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.
+  brainchain-mcp wallet          Check the key and settings, and print the wallet that pays, what it
+                                 holds and, for USDG, what Permit2 may spend.
 
 Environment:
   BRAINCHAIN_PAYER_KEY        Private key of the paying wallet, 64 hex characters with or without 0x.
@@ -46,23 +48,34 @@ if (command === "--version" || command === "-v" || command === "version") {
 }
 if (command !== undefined && command !== "approve" && command !== "wallet")
     fail(`Unknown command ${command}.\n\n${USAGE}`);
+const extra = process.argv[command === "approve" ? 4 : 3];
+if (command !== undefined && extra !== undefined)
+    fail(`Unexpected argument ${extra}: ${command === "approve" ? "approve takes one amount" : "wallet takes none"}.\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}.`);
+    const funds = await walletFunds(config, account.address).catch((error) => (error instanceof Error ? error : new Error(String(error))));
+    console.log(walletReport(config, account.address, funds, approveCommand(config, version)));
 }
 else {
     await approve(process.argv[3] ?? "100");
 }
 function settings() {
+    let config;
+    let account;
     try {
-        return { config: resolveConfig(process.env), account: payerAccount(process.env) };
+        config = resolveConfig(process.env);
+        account = payerAccount(process.env);
     }
     catch (error) {
         fail(error instanceof Error ? error.message : String(error));
     }
+    const problem = config.daily === undefined ? undefined : stateDirProblem(config.stateDir);
+    if (problem)
+        fail(problem);
+    return { config, account };
 }
 async function approve(arg) {
     const { config, account } = settings();

package/dist/payments.js

@@ -26,6 +26,8 @@ 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] ?? "";
+/** Text from the desk or a library, ended as a sentence so what this server adds after it reads apart. */
+const sentence = (text) => (/[.!?]$/.test(text.trim()) ? text.trim() : `${text.trim()}.`);
 /** 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. */
@@ -112,11 +114,12 @@ export function createDesk(options) {
         if (/fetch failed|ECONNREFUSED|ENOTFOUND|EAI_AGAIN/i.test(message)) {
             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.`;
+        // The x402 client puts its own words before an error raised while it prepared the payment.
+        return `The payment could not be prepared: ${sentence(message.replace(/^Failed to create payment payload: /, ""))} Nothing was charged.`;
     }
     /** Explains a payment the desk refused, from the wallet's balance and Permit2 allowance where possible. */
     async function explainRefusal(reason) {
-        const fallback = typeof reason === "string" ? `The desk refused the payment: ${reason}. Nothing was charged.` : "The desk refused the payment. Nothing was charged.";
+        const fallback = typeof reason === "string" && reason.trim() ? `The desk refused the payment: ${sentence(reason)} Nothing was charged.` : "The desk refused the payment. Nothing was charged.";
         if (!options.funds)
             return fallback;
         try {
@@ -222,14 +225,19 @@ export function createDesk(options) {
             if (!signed)
                 await unreserve();
         });
+        // Short enough that a possiblyCharged reply reaches a client that gives up after 60 seconds.
+        // The x402 client sends clones of the request, and a clone follows the request's signal
+        // through weak references only, so once garbage is collected a deadline set on the request
+        // never fires. Each request it sends carries the deadline itself, which the timer keeps alive.
+        const deadline = new AbortController();
+        const timer = setTimeout(() => deadline.abort(new DOMException("The operation was aborted due to timeout", "TimeoutError")), options.postTimeoutMs ?? 45_000);
+        const timed = (input, init) => fetchImpl(input, { ...init, signal: deadline.signal });
         let response;
         try {
-            response = await wrapFetchWithPayment(fetchImpl, client)(endpoint, {
+            response = await wrapFetchWithPayment(timed, client)(endpoint, {
                 method: "POST",
                 headers: { "content-type": "application/json" },
                 body: JSON.stringify(task),
-                // Short enough that a possiblyCharged reply reaches a client that gives up after 60 seconds.
-                signal: AbortSignal.timeout(options.postTimeoutMs ?? 45_000),
             });
         }
         catch (error) {
@@ -237,6 +245,9 @@ export function createDesk(options) {
                 return possiblyCharged(receipt(orderIdOf(signed)), `The desk did not confirm the order (${firstLine(error)}).`);
             throw new Error(await explainUnsigned(error));
         }
+        finally {
+            clearTimeout(timer);
+        }
         const reply = (await jsonObject(response)) ?? {};
         if (response.ok) {
             if (!signed) {
@@ -253,7 +264,7 @@ export function createDesk(options) {
         await unreserve();
         if (response.status === 402)
             throw new Error(await explainRefusal(reply.error));
-        throw new Error(typeof reply.error === "string" ? `${reply.error} Nothing was charged.` : `The desk answered ${response.status}. Nothing was charged.`);
+        throw new Error(typeof reply.error === "string" && reply.error.trim() ? `${sentence(reply.error)} Nothing was charged.` : `The desk answered ${response.status}. Nothing was charged.`);
     }
     async function get(order) {
         let response;

package/dist/premiums.js

@@ -0,0 +1,94 @@
+import { createPublicClient, http, parseAbi } from "viem";
+export const PREMIUMS_NAME = "brainchain_stock_premiums";
+/** The desks' mandate on Robinhood Chain: it lists each stock token's deepest USDG pool and Chainlink feed. */
+export const MANDATE = "0xA76916D1b75a82776779fb9d7EB156A4E4a55099";
+export const ROBINHOOD_RPC = "https://rpc.mainnet.chain.robinhood.com";
+const MULTICALL3 = "0xcA11bde05977b3631167028862bE2a173976CA11";
+const USDG = "0x5fc5360d0400a0fd4f2af552add042d716f1d168";
+const mandateAbi = parseAbi([
+    "function tokenCount() view returns (uint256)",
+    "function tokens(uint256) view returns (address)",
+    "function venues(address) view returns (address pool, address feed, bool live)",
+]);
+const tokenAbi = parseAbi(["function symbol() view returns (string)", "function uiMultiplier() view returns (uint256)"]);
+const poolAbi = parseAbi([
+    "function token0() view returns (address)",
+    "function slot0() view returns (uint160 sqrtPriceX96, int24 tick, uint16, uint16, uint16, uint8, bool)",
+]);
+const feedAbi = parseAbi(["function latestRoundData() view returns (uint80, int256 answer, uint256, uint256 updatedAt, uint80)"]);
+export const PREMIUMS_TOOL = {
+    name: PREMIUMS_NAME,
+    title: "Stock premiums on Robinhood Chain",
+    description: "What tokenized US stocks cost on Robinhood Chain against their Chainlink price right now: pool price, Chainlink price, " +
+        "the premium in percent and the feed's age, for NVDA, SPY, AAPL, TSLA, GOOGL, META and MSFT. Read from the chain, free, no key " +
+        "and no payment. Outside US market hours no new tokens are minted, so the premium shows where the market clears on its own. " +
+        "Prices are in USDG per token with each token's split multiplier applied. Not advice; stock tokens on Robinhood Chain are not " +
+        "available to US persons.",
+    inputSchema: { type: "object", properties: {}, additionalProperties: false },
+};
+export function chainReader(rpc = ROBINHOOD_RPC) {
+    return createPublicClient({ transport: http(rpc) });
+}
+/** Monday to Friday, 14:30 to 21:00 UTC, the regular NYSE session in winter time. */
+export function usMarketOpen(now) {
+    const day = now.getUTCDay();
+    if (day === 0 || day === 6)
+        return false;
+    const minutes = now.getUTCHours() * 60 + now.getUTCMinutes();
+    return minutes >= 14 * 60 + 30 && minutes < 21 * 60;
+}
+const usd = (units) => `${units / 1000000n}.${((units % 1000000n) / 10000n).toString().padStart(2, "0")}`;
+/** USDG (6 decimals) for one whole stock token at the pool's current price. */
+function spotFromSlot0(sqrtPriceX96, token0) {
+    const squared = sqrtPriceX96 * sqrtPriceX96;
+    return token0.toLowerCase() === USDG ? (10n ** 18n << 192n) / squared : (10n ** 18n * squared) >> 192n;
+}
+export async function stockPremiums(reader, now = new Date()) {
+    const count = Number(await reader.readContract({ address: MANDATE, abi: mandateAbi, functionName: "tokenCount" }));
+    const tokens = (await reader.multicall({
+        multicallAddress: MULTICALL3,
+        allowFailure: false,
+        contracts: Array.from({ length: count }, (_, i) => ({ address: MANDATE, abi: mandateAbi, functionName: "tokens", args: [BigInt(i)] })),
+    }));
+    const venues = (await reader.multicall({
+        multicallAddress: MULTICALL3,
+        allowFailure: false,
+        contracts: tokens.map((token) => ({ address: MANDATE, abi: mandateAbi, functionName: "venues", args: [token] })),
+    }));
+    const live = tokens.map((token, i) => ({ token, pool: venues[i][0], feed: venues[i][1], live: venues[i][2] })).filter((v) => v.live);
+    const reads = await reader.multicall({
+        multicallAddress: MULTICALL3,
+        allowFailure: false,
+        contracts: live.flatMap((v) => [
+            { address: v.token, abi: tokenAbi, functionName: "symbol" },
+            { address: v.token, abi: tokenAbi, functionName: "uiMultiplier" },
+            { address: v.pool, abi: poolAbi, functionName: "token0" },
+            { address: v.pool, abi: poolAbi, functionName: "slot0" },
+            { address: v.feed, abi: feedAbi, functionName: "latestRoundData" },
+        ]),
+    });
+    const at = Math.floor(now.getTime() / 1000);
+    const stocks = live.map((v, i) => {
+        const [symbol, multiplier, token0, slot0, round] = reads.slice(i * 5, i * 5 + 5);
+        const spot = spotFromSlot0(slot0[0], token0);
+        const feed = (round[1] * multiplier) / 10n ** 20n;
+        const bps = feed === 0n ? 0 : Number(((spot - feed) * 1000000n) / feed) / 100;
+        const updatedAt = Number(round[3]);
+        return {
+            symbol,
+            token: v.token,
+            pool: v.pool,
+            poolPrice: usd(spot),
+            chainlinkPrice: usd(feed),
+            premiumPct: `${bps >= 0 ? "+" : ""}${(bps / 100).toFixed(2)}`,
+            feedUpdatedAt: new Date(updatedAt * 1000).toISOString(),
+            feedAgeSeconds: Math.max(0, at - updatedAt),
+        };
+    });
+    return { chain: "Robinhood Chain", readAt: now.toISOString(), usMarketOpen: usMarketOpen(now), stocks };
+}
+let reader;
+export function readPremiums() {
+    reader ??= chainReader();
+    return stockPremiums(reader);
+}

package/dist/server.js

@@ -2,10 +2,12 @@ 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 { createPublicClient, defineChain, formatEther, http, maxUint256, parseAbi } from "viem";
 import { privateKeyToAccount } from "viem/accounts";
-import { expandHome, resolveConfig } from "./config.js";
+import { expandHome, formatUnits, resolveConfig } from "./config.js";
+import { stateDirProblem } from "./daily.js";
 import { createDesk } from "./payments.js";
+import { PREMIUMS_NAME, PREMIUMS_TOOL } from "./premiums.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";
@@ -19,7 +21,7 @@ export const INSTRUCTIONS = `Post a task with ${POST_TASK_NAME}, then read it wi
     `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.`;
+    `${GET_TASK_NAME} and ${PREMIUMS_NAME} work 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) {
@@ -79,6 +81,38 @@ export function chainClients(config) {
     });
     return { chain, reader: createPublicClient({ chain, transport: http(config.rpc, { retryCount: 2, timeout: 15_000 }) }) };
 }
+/** Reads what `wallet` reports, on the payment chain only. */
+export async function walletFunds(config, address) {
+    const { reader } = chainClients(config);
+    const [balance, allowance, eth] = 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,
+        reader.getBalance({ address }),
+    ]);
+    return { balance, ...(allowance === undefined ? {} : { allowance }), eth };
+}
+/** What `wallet` says: the wallet that pays, what it holds, and what it still needs before a post can be paid. */
+export function walletReport(config, address, funds, approve) {
+    const lines = [`${address} pays for tasks in ${config.token} on ${config.chain}.`];
+    if (funds instanceof Error) {
+        lines.push(`Its balance could not be read from ${config.chain} (${messageOf(funds).split("\n")[0]}). The key and settings are fine.`);
+        return lines.join("\n");
+    }
+    const { balance, allowance, eth } = funds;
+    const short = balance < config.maxPrice ? ` A task costs ${config.terms.cost}, so send at least ${formatUnits(config.maxPrice - balance)} ${config.token} to it on ${config.chain} before posting.` : "";
+    lines.push(`It holds ${formatUnits(balance)} ${config.token}.${short}`);
+    if (allowance !== undefined) {
+        if (allowance >= maxUint256 / 2n)
+            lines.push(`Permit2 may spend any amount of its ${config.token}.`);
+        else if (allowance >= config.maxPrice)
+            lines.push(`Permit2 may spend up to ${formatUnits(allowance)} of its ${config.token}.`);
+        else {
+            const only = allowance > 0n ? ` (only ${formatUnits(allowance)})` : "";
+            lines.push(`Permit2 is not approved to spend enough of its ${config.token} for a task${only}. Run \`${approve}\` once; it needs a little ETH on ${config.chain}, and the wallet holds ${formatEther(eth)} ETH there.`);
+        }
+    }
+    return lines.join("\n");
+}
 export function approveCommand(config, version) {
     return `${config.name === "testnet" ? "BRAINCHAIN_NETWORK=testnet " : ""}npx -y brainchain-mcp@${version} approve`;
 }
@@ -105,6 +139,8 @@ function deskFor(env, version, fetchImpl) {
         if (env.BRAINCHAIN_PAYER_KEY?.trim() || env.BRAINCHAIN_PAYER_KEY_FILE?.trim())
             keyProblem = messageOf(error);
     }
+    // Said at start, not at the first post: with a daily limit set, no payment can be signed without its record.
+    const problem = [keyProblem, config.daily === undefined ? undefined : stateDirProblem(config.stateDir)].filter(Boolean).join(" ");
     const payer = () => {
         try {
             return (account ??= payerAccount(env));
@@ -128,14 +164,14 @@ function deskFor(env, version, fetchImpl) {
             return { balance, allowance };
         },
     });
-    return { desk, terms: { ...config.terms, ...(account ? { wallet: account.address } : {}), ...(keyProblem ? { keyProblem } : {}) } };
+    return { desk, terms: { ...config.terms, ...(account ? { wallet: account.address } : {}), ...(problem ? { problem } : {}) } };
 }
 export function createServer(env, version, options = {}) {
     const { desk, terms } = deskFor(env, version, options.fetch);
-    const problem = typeof terms === "string" ? terms : terms.keyProblem;
+    const problem = typeof terms === "string" ? terms : terms.problem;
     if (problem)
         (options.log ?? console.error)(`brainchain-mcp has an invalid setting: ${problem}`);
-    const tools = [postTaskTool(terms), GET_TASK_TOOL];
+    const tools = [postTaskTool(terms), GET_TASK_TOOL, PREMIUMS_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));

package/dist/tools.js

@@ -1,5 +1,9 @@
 import { REPOST_AFTER_MINUTES } from "./config.js";
+import { canonicalStringify } from "./payments.js";
+import { PREMIUMS_NAME, readPremiums } from "./premiums.js";
 export const POST_TASK_NAME = "brainchain_post_task";
+/** The desk's cap on a task as it goes on chain: title, brief, levels and pass level as JSON. */
+export const MAX_TASK_BYTES = 64_000;
 export const GET_TASK_NAME = "brainchain_get_task";
 const POST_TASK_INPUT = {
     type: "object",
@@ -9,14 +13,16 @@ const POST_TASK_INPUT = {
             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.",
+            description: "What to produce, in what format, and anything the model must not do. Models cannot browse, so include every fact they need. " +
+                "Up to 32,000 characters, an emoji counting as two, and the whole task as JSON at most 64,000 bytes: about 21,000 characters of Chinese, Japanese or Korean.",
         },
         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.",
+            uniqueItems: true,
+            description: "Two or three different 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"],
@@ -25,13 +31,14 @@ const POST_TASK_INPUT = {
 /** 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. ` +
-        `Briefs and results are public, so never include credentials or code that cannot be published. `;
+        `Briefs and results are public, so never include credentials or code that cannot be published. ` +
+        `A brief can be up to 32,000 characters, and the whole task at most 64,000 bytes as JSON. `;
     return {
         name: POST_TASK_NAME,
         title: "Post a paid task to BrainChain",
         description: typeof terms === "string"
             ? `Invalid setting: ${terms} Until then this tool only returns that error. ${about}`
-            : (terms.keyProblem ? `Invalid setting: ${terms.keyProblem} Until the operator fixes it, this tool only returns that error. ` : "") +
+            : (terms.problem ? `Invalid setting: ${terms.problem} 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}. ` +
@@ -55,14 +62,20 @@ export const GET_TASK_TOOL = {
 };
 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. */
+/**
+ * Text that shows nothing: whitespace, control and format characters, line and
+ * paragraph separators, and the default-ignorable and blank letters that have
+ * no Unicode property of their own.
+ */
+const BLANK = /^[\s\p{Cc}\p{Cf}\p{Zl}\p{Zp}\u034f\u115f\u1160\u17b4\u17b5\u180b-\u180f\u2800\u3164\ufe00-\ufe0f\uffa0\u{e0000}-\u{e0fff}]*$/u;
+/** A string field as it is sent, trimmed; throws what is wrong with it. Lengths count UTF-16 units, as the desk does. */
 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)
+    if (BLANK.test(sent))
         throw new Error(`${name} is empty.`);
     if (sent.length > max)
         throw new Error(`${name} is ${count(sent.length)} characters; the limit is ${count(max)}.`);
@@ -74,9 +87,15 @@ function refuseUnknownFields(input, schema) {
     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. */
+/**
+ * The desk's own limits, applied to what is sent, before anything is signed,
+ * plus what this tool's description promises: a title of one line and levels
+ * that differ. Returns the trimmed brief; throws what is wrong with it.
+ */
 export function checkBrief(input) {
     const title = text("title", input.title, 120);
+    if (/[\n\r\u2028\u2029]/.test(title))
+        throw new Error("title must be one line.");
     const brief = text("brief", input.brief, 32_000);
     const { levels } = input;
     if (levels === undefined)
@@ -85,7 +104,18 @@ export function checkBrief(input) {
         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)) };
+    const sent = levels.map((level, i) => text(`levels[${i}]`, level, 200));
+    sent.forEach((level, i) => {
+        const first = sent.indexOf(level);
+        if (first < i)
+            throw new Error(`levels[${i}] repeats levels[${first}]; each level must describe a different quality.`);
+    });
+    // Measured as the desk measures it: the trimmed task with its pass level, as canonical JSON.
+    const bytes = Buffer.byteLength(canonicalStringify({ title, brief, levels: sent, passIndex: Math.min(1, sent.length - 2) }));
+    if (bytes > MAX_TASK_BYTES) {
+        throw new Error(`The task is ${count(bytes)} bytes as JSON; the limit is ${count(MAX_TASK_BYTES)}. Shorten the brief.`);
+    }
+    return { title, brief, levels: sent };
 }
 function reply(value, isError = false) {
     return { content: [{ type: "text", text: JSON.stringify(value, null, 2) }], isError };
@@ -98,7 +128,7 @@ function orderReply(view) {
         result.content.push({ type: "text", text: resultText });
     return result;
 }
-export async function callTool(desk, name, args) {
+export async function callTool(desk, name, args, premiums = readPremiums) {
     const input = (args ?? {});
     try {
         if (name === POST_TASK_NAME) {
@@ -112,6 +142,8 @@ export async function callTool(desk, name, args) {
                 throw new Error("order must be the 0x-prefixed, 64-character hex id that brainchain_post_task returned.");
             return orderReply(await desk.get(order));
         }
+        if (name === PREMIUMS_NAME)
+            return reply(await premiums());
         return reply({ error: `Unknown tool ${name}.` }, true);
     }
     catch (error) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "brainchain-mcp",
-  "version": "0.5.1",
+  "version": "0.6.1",
   "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",