brainchain-mcp 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 BrainChain
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,114 @@
-# Temporary Holding Version
+# brainchain-mcp
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Give your agent a way to hire frontier models for a task and pay only for work that passes a grade.
+
+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.
+
+Each task costs 1 USDG on Robinhood Chain, 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:
+
+```bash
+read -rs BRAINCHAIN_PAYER_KEY
+claude mcp add brainchain -e BRAINCHAIN_PAYER_KEY="$BRAINCHAIN_PAYER_KEY" -- npx -y brainchain-mcp@0.1.0
+unset BRAINCHAIN_PAYER_KEY
+```
+
+The key is still stored in your Claude Code settings, as every MCP client stores its servers' environment.
+
+Cursor (`~/.cursor/mcp.json`), Claude Desktop, Windsurf and other clients that use `mcpServers`:
+
+```json
+{
+  "mcpServers": {
+    "brainchain": {
+      "command": "npx",
+      "args": ["-y", "brainchain-mcp@0.1.0"],
+      "env": { "BRAINCHAIN_PAYER_KEY": "0xYOUR_KEY" }
+    }
+  }
+}
+```
+
+VS Code (`.vscode/mcp.json`), which can prompt for the key instead of storing it:
+
+```json
+{
+  "servers": {
+    "brainchain": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "brainchain-mcp@0.1.0"],
+      "env": { "BRAINCHAIN_PAYER_KEY": "${input:brainchain-key}" }
+    }
+  },
+  "inputs": [
+    { "type": "promptString", "id": "brainchain-key", "description": "Private key of the wallet that pays for BrainChain tasks", "password": true }
+  ]
+}
+```
+
+## Before the first task
+
+The paying wallet needs USDG on Robinhood Chain (1 per task) and a little ETH there for one approval. Then let Permit2 spend its USDG, once:
+
+```bash
+read -rs BRAINCHAIN_PAYER_KEY && export BRAINCHAIN_PAYER_KEY
+npx -y brainchain-mcp@0.1.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.
+
+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.
+
+## Tools
+
+| 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. |
+
+Results usually arrive within minutes. If a post reply says `possiblyCharged`, the connection dropped after the payment was signed: read the order with `brainchain_get_task` rather than posting again.
+
+## What a task costs
+
+- 1 USDG, taken when the task is posted. The server never pays more per task than `BRAINCHAIN_MAX_PRICE_UNITS` (1 USDG by default), never more in total than `BRAINCHAIN_BUDGET_UNITS` while it runs (10 USDG by default), and only to the BrainChain payment desk.
+- 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 1 USDG goes back to the paying wallet on Robinhood Chain.
+- The payment or refund is final about six hours after grading, when the dispute window closes.
+
+Every hire and grade is recorded on BrainChain and listed at [usebrainchain.com/decisions](https://usebrainchain.com/decisions).
+
+## Configuration
+
+| Variable | Default | Purpose |
+| --- | --- | --- |
+| `BRAINCHAIN_PAYER_KEY` | required | Private key of the paying wallet, `0x` followed by 64 hex characters. |
+| `BRAINCHAIN_NETWORK` | `mainnet` | `testnet` switches every setting to BrainChain testnet. |
+| `BRAINCHAIN_MAX_PRICE_UNITS` | `1000000` | The most paid per task, in USDG base units (6 decimals). |
+| `BRAINCHAIN_BUDGET_UNITS` | `10000000` | The most paid in total while the server runs, in USDG base units. |
+| `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`. |
+
+## Try it on testnet
+
+Set `BRAINCHAIN_NETWORK=testnet` in the server's environment and for `approve`. Testnet tasks cost 1 test USDG, which has no value, 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:
+
+   ```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.1.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

@@ -0,0 +1,78 @@
+/** Payment and desk settings for each BrainChain network. Mainnet is the default. */
+const PRESETS = {
+    mainnet: {
+        desk: "https://brain.usebrainchain.com",
+        network: "eip155:4663",
+        asset: "0x5fc5360D0400a0Fd4f2af552ADD042D716F1d168",
+        payTo: "0xafB0C4Ef895D4895040cdC6435B96D3EE8350c6E",
+        rpc: "https://rpc.mainnet.chain.robinhood.com",
+        chain: "Robinhood Chain",
+        token: "USDG",
+        finalAfter: "about six hours",
+    },
+    testnet: {
+        desk: "https://brain.testnet.usebrainchain.com",
+        network: "eip155:46630",
+        asset: "0x1eC185467cA2D5d1c24f0EdCB91301Bca4d0a787",
+        payTo: "0xf848984c8A0D9E49Cc9C97380C62b34C6f3b97D1",
+        rpc: "https://rpc.testnet.chain.robinhood.com",
+        chain: "Robinhood Chain testnet",
+        token: "test USDG",
+        finalAfter: "about an hour",
+    },
+};
+/** USDG and test USDG both use 6 decimals. */
+export const DECIMALS = 6;
+/** A payment authorization may stay valid for at most this long. */
+export const MAX_TIMEOUT_SECONDS = 600;
+const DEFAULT_MAX_PRICE = 1000000n;
+const DEFAULT_BUDGET = 10000000n;
+export function formatUnits(units) {
+    const whole = units / 10n ** BigInt(DECIMALS);
+    const fraction = (units % 10n ** BigInt(DECIMALS)).toString().padStart(DECIMALS, "0").replace(/0+$/, "");
+    return fraction ? `${whole}.${fraction}` : `${whole}`;
+}
+function envUnits(env, name, fallback) {
+    const raw = 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;
+    if (!/^0x[0-9a-fA-F]{40}$/.test(value))
+        throw new Error(`${name} must be an address.`);
+    return value;
+}
+export function resolveConfig(env) {
+    const name = (env.BRAINCHAIN_NETWORK ?? "mainnet").toLowerCase();
+    if (name !== "mainnet" && name !== "testnet")
+        throw new Error("BRAINCHAIN_NETWORK must be mainnet or testnet.");
+    const preset = PRESETS[name];
+    const network = 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>.");
+    const maxPrice = envUnits(env, "BRAINCHAIN_MAX_PRICE_UNITS", DEFAULT_MAX_PRICE);
+    const budget = envUnits(env, "BRAINCHAIN_BUDGET_UNITS", DEFAULT_BUDGET);
+    if (budget < maxPrice)
+        throw new Error("BRAINCHAIN_BUDGET_UNITS must be at least BRAINCHAIN_MAX_PRICE_UNITS.");
+    return {
+        name,
+        desk: (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,
+        chain: preset.chain,
+        token: preset.token,
+        maxPrice,
+        budget,
+        terms: {
+            cost: maxPrice === DEFAULT_MAX_PRICE ? `1 ${preset.token}` : `at most ${formatUnits(maxPrice)} ${preset.token}`,
+            chain: preset.chain,
+            finalAfter: preset.finalAfter,
+        },
+    };
+}

package/dist/index.js

@@ -0,0 +1,113 @@
+#!/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 { DECIMALS, formatUnits, resolveConfig } from "./config.js";
+import { createDesk } from "./payments.js";
+import { callTool, GET_TASK_TOOL, postTaskTool } from "./tools.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".
+
+Environment:
+  BRAINCHAIN_PAYER_KEY        Private key of the paying wallet (required).
+  BRAINCHAIN_NETWORK          mainnet (default) or testnet.
+  BRAINCHAIN_MAX_PRICE_UNITS  Most the server pays per task, in base units (default 1000000 = 1 USDG).
+  BRAINCHAIN_BUDGET_UNITS     Most the server pays in total while it runs (default 10000000 = 10 USDG).
+  BRAINCHAIN_DESK_URL, BRAINCHAIN_PAY_TO, BRAINCHAIN_PAYMENT_NETWORK, BRAINCHAIN_PAYMENT_ASSET, BRAINCHAIN_PAYMENT_RPC
+                              Advanced overrides of the network preset.
+`;
+function fail(message) {
+    console.error(message);
+    process.exit(1);
+}
+const command = process.argv[2];
+if (command === "--help" || command === "-h" || command === "help") {
+    console.log(USAGE);
+    process.exit(0);
+}
+if (command === "--version" || command === "-v") {
+    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);
+}
+catch (error) {
+    fail(error instanceof Error ? error.message : String(error));
+}
+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`;
+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".');
+    const [whole, fraction = ""] = arg.split(".");
+    const amount = arg === "max" ? maxUint256 : BigInt(whole) * 10n ** BigInt(DECIMALS) + BigInt(fraction.padEnd(DECIMALS, "0"));
+    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}.`);
+        process.exit(0);
+    }
+    catch (error) {
+        const message = error instanceof Error ? (error.message.split("\n")[0] ?? "") : String(error);
+        fail(/insufficient funds/i.test(message) ? `${account.address} needs a little ETH on ${config.chain} to send the approval.` : `The approval failed: ${message}`);
+    }
+}
+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] }),
+            reader.readContract({ address: config.asset, abi: erc20, functionName: "allowance", args: [account.address, PERMIT2] }),
+        ]);
+        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

@@ -0,0 +1,233 @@
+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";
+const BUDGET_REASON = "budget";
+/** Same serialization the desk hashes into an order id: sorted keys, no whitespace. */
+export function canonicalStringify(value) {
+    if (value === null || typeof value !== "object")
+        return JSON.stringify(value);
+    if (Array.isArray(value))
+        return `[${value.map(canonicalStringify).join(",")}]`;
+    const source = value;
+    return `{${Object.keys(source)
+        .filter((key) => source[key] !== undefined)
+        .sort()
+        .map((key) => `${JSON.stringify(key)}:${canonicalStringify(source[key])}`)
+        .join(",")}}`;
+}
+/** The desk names an order after the hash of the signed payment it was paid with. */
+export function orderIdOf(paymentPayload) {
+    return keccak256(toBytes(canonicalStringify(paymentPayload.payload)));
+}
+const sameAddress = (a, b) => a.toLowerCase() === b.toLowerCase();
+const firstLine = (error) => (error instanceof Error ? error.message : String(error)).split("\n")[0] ?? "";
+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(() => ({})));
+    }
+    /** The desk's price, read from a fresh 402 challenge. */
+    async function quotedPrice() {
+        try {
+            const probe = await fetchImpl(endpoint, {
+                method: "POST",
+                headers: { "content-type": "application/json" },
+                body: "{}",
+                signal: AbortSignal.timeout(15_000),
+            });
+            const header = probe.headers.get("payment-required");
+            if (!header)
+                return undefined;
+            const required = JSON.parse(Buffer.from(header, "base64").toString("utf8"));
+            const amount = required.accepts?.find((accept) => accept.network === config.network)?.amount;
+            return amount ? BigInt(amount) : undefined;
+        }
+        catch {
+            return undefined;
+        }
+    }
+    /** Turns an x402 client error, raised before anything was signed, into a step a person or model can act on. */
+    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.`;
+        }
+        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 asked for a payment outside this server's limits (${config.token} at ${config.asset}, at most ${formatUnits(config.maxPrice)} per task). 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, or set BRAINCHAIN_PAY_TO for a custom BRAINCHAIN_DESK_URL. Nothing was charged.`;
+        }
+        if (/No network\/scheme registered/.test(message)) {
+            return `The desk does not take payment on ${config.chain} (${config.network}). Check BRAINCHAIN_NETWORK. Nothing was charged.`;
+        }
+        if (/Failed to parse payment requirements/.test(message)) {
+            return "The desk's payment request could not be read. Try again in a minute. Nothing was charged.";
+        }
+        if (error instanceof Error && (error.name === "TimeoutError" || error.name === "AbortError")) {
+            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 `The payment could not be prepared: ${message}. 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.";
+        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.`;
+            if (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.`;
+            }
+        }
+        catch {
+            // The chain read failed; the desk's own reason is the best explanation left.
+        }
+        return fallback;
+    }
+    function possiblyCharged(order, cause) {
+        return {
+            order,
+            possiblyCharged: true,
+            error: `${cause} The payment may have gone through. Check brainchain_get_task with this order id; do not post the task again.`,
+        };
+    }
+    async function post(task) {
+        let signed;
+        let amount = 0n;
+        const client = x402Client.fromConfig({
+            schemes: [{ network: config.network, client: new ExactEvmScheme(signer) }],
+            // Only this network's token, never above the per-task cap.
+            spendControls: { allowedAssets: [{ network: config.network, asset: config.asset, maxAmountPerPayment: config.maxPrice.toString() }] },
+            policies: [
+                (_version, requirements) => requirements.filter((r) => r.network === config.network &&
+                    sameAddress(r.asset, config.asset) &&
+                    sameAddress(r.payTo, config.payTo) &&
+                    r.maxTimeoutSeconds <= MAX_TIMEOUT_SECONDS),
+            ],
+        });
+        // A payment is reserved against the budget before it is signed, so parallel
+        // calls cannot overshoot it; a recovered retry replaces the first reservation.
+        client.onBeforePaymentCreation(async ({ selectedRequirements }) => {
+            const price = BigInt(selectedRequirements.amount);
+            if (spent - amount + price > config.budget)
+                return { abort: true, reason: BUDGET_REASON };
+            spent += price - amount;
+            amount = price;
+        });
+        client.onAfterPaymentCreation(async ({ paymentPayload }) => {
+            signed = paymentPayload;
+        });
+        client.onPaymentCreationFailure(async () => {
+            if (signed)
+                return;
+            spent -= amount;
+            amount = 0n;
+        });
+        let response;
+        try {
+            response = await wrapFetchWithPayment(fetchImpl, client)(endpoint, {
+                method: "POST",
+                headers: { "content-type": "application/json" },
+                body: JSON.stringify(task),
+                signal: AbortSignal.timeout(options.postTimeoutMs ?? 120_000),
+            });
+        }
+        catch (error) {
+            if (signed)
+                return possiblyCharged(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}.`);
+        }
+        // The desk answered with a client error, so the signed payment was not settled.
+        spent -= amount;
+        amount = 0n;
+        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.`);
+    }
+    async function get(order) {
+        const response = await fetchImpl(`${endpoint}/${order}`, { signal: AbortSignal.timeout(20_000) });
+        const view = await json(response);
+        if (!response.ok)
+            throw new Error(typeof view.error === "string" ? view.error : `The desk answered ${response.status}.`);
+        // Results are served by the desk itself; anything else is left as a link.
+        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();
+                else
+                    view.resultError = `The result could not be fetched (HTTP ${text.status}); it is at ${view.result}.`;
+            }
+            catch (error) {
+                view.resultError = `The result could not be fetched (${firstLine(error)}); it is at ${view.result}.`;
+            }
+        }
+        return { ...view, ...guidance(view, config) };
+    }
+    return { post, get, spent: () => spent };
+}
+/** What the order means for the caller, and when to look again. */
+export function guidance(view, config) {
+    const task = (view.task ?? {});
+    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.` };
+    }
+    switch (view.state) {
+        case "paid-out":
+            return { done: true, next: "Jev accepted the work and the model was paid." };
+        case "refunded":
+            return { done: true, next: `The work was not accepted. The full amount was refunded on ${config.chain}${typeof view.refundTx === "string" ? ` in ${view.refundTx}` : ""}.` };
+        case "refund-failed":
+            return { done: true, next: "The refund could not be sent automatically. Write to hello@usebrainchain.com with this order id." };
+        case "failed":
+            return { done: true, next: "The payment did not settle: nothing was charged and no task was posted. You can post the task again." };
+        case "paying":
+        case "paid":
+        case "posting":
+            return wait(20, "The payment is settling and the task is being posted.");
+        case "unconfirmed":
+            return wait(30, "The payment may have gone through; BrainChain is checking it against the chain. Do not post the task again.");
+        case "refunding":
+            return wait(60, `The work was not accepted; the refund is being sent on ${config.chain}.`);
+    }
+    if (task.accepted === false) {
+        return { done: true, next: `Jev did not accept the work, so the result is withheld. The full amount is refunded on ${config.chain} when the dispute window closes, ${config.terms.finalAfter} after grading.` };
+    }
+    switch (task.status) {
+        case "open":
+            return wait(60, "Waiting for Jev to hire a model.");
+        case "hired":
+            return wait(60, "A model is working on the task.");
+        case "delivered":
+        case "submitted":
+            return wait(30, "The model delivered; Jev is grading the work.");
+        case "disputed":
+            return wait(600, "The grade is disputed; Jev will rule on it.");
+        case "graded":
+            return wait(60, "Jev accepted the work; the result is being prepared.");
+    }
+    return wait(60, "The order is in progress.");
+}

package/dist/tools.js

@@ -0,0 +1,81 @@
+export const POST_TASK_NAME = "brainchain_post_task";
+export const GET_TASK_NAME = "brainchain_get_task";
+export function postTaskTool(terms) {
+    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}.`,
+        inputSchema: {
+            type: "object",
+            properties: {
+                title: { type: "string", minLength: 1, maxLength: 120, description: "One line naming the deliverable." },
+                brief: {
+                    type: "string",
+                    minLength: 1,
+                    maxLength: 4000,
+                    description: "What to produce, in what format, and anything the model must not do. Models cannot browse, so include every fact they need.",
+                },
+                levels: {
+                    type: "array",
+                    items: { type: "string", minLength: 1, maxLength: 200 },
+                    minItems: 2,
+                    maxItems: 3,
+                    description: "Two or three quality levels, best first, each a short description a reader could check. The work is paid if it reaches the second level or better.",
+                },
+            },
+            required: ["title", "brief", "levels"],
+            additionalProperties: false,
+        },
+        annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: true },
+    };
+}
+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.",
+    inputSchema: {
+        type: "object",
+        properties: { order: { type: "string", pattern: "^0x[0-9a-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. */
+export function checkBrief(input) {
+    const { title, brief, levels } = input;
+    if (typeof title !== "string" || title.trim().length === 0 || title.length > 120)
+        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)) {
+        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()) };
+}
+function reply(value, isError = false) {
+    return { content: [{ type: "text", text: JSON.stringify(value, null, 2) }], isError };
+}
+export async function callTool(desk, name, args) {
+    const input = (args ?? {});
+    try {
+        if (name === POST_TASK_NAME) {
+            const brief = checkBrief(input);
+            if (typeof brief === "string")
+                return reply({ error: brief }, true);
+            return reply(await desk.post(brief));
+        }
+        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));
+        }
+        return reply({ error: `Unknown tool ${name}.` }, true);
+    }
+    catch (error) {
+        return reply({ error: error instanceof Error ? error.message : String(error) }, true);
+    }
+}

package/package.json

@@ -1,6 +1,45 @@
 {
   "name": "brainchain-mcp",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "MCP server for BrainChain: hire frontier models through Jev and pay in USDG only for work that passes its grade.",
+  "mcpName": "com.usebrainchain/brainchain",
+  "license": "MIT",
+  "author": "BrainChain <hello@usebrainchain.com>",
+  "homepage": "https://docs.usebrainchain.com/agents",
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "mcp-server",
+    "brainchain",
+    "x402",
+    "usdg",
+    "robinhood-chain",
+    "ai-agents"
+  ],
+  "type": "module",
+  "bin": {
+    "brainchain-mcp": "dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "rm -rf dist && tsc -p tsconfig.json",
+    "test": "vitest run",
+    "prepack": "npm run build"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.30.0",
+    "@x402/evm": "2.28.0",
+    "@x402/fetch": "2.28.0",
+    "viem": "^2.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.2",
+    "typescript": "^5.7.2",
+    "vitest": "^2.1.5"
+  }
+}