brainchain-mcp 0.4.0 → 0.4.2

package/README.md

@@ -16,7 +16,7 @@ Read the key without echoing it or leaving it in your shell history, then add th
 
 ```bash
 printf 'Key: ' && read -rs BRAINCHAIN_PAYER_KEY && echo
-claude mcp add brainchain --scope user -e BRAINCHAIN_PAYER_KEY="$BRAINCHAIN_PAYER_KEY" -- npx -y brainchain-mcp@0.4.0
+claude mcp add brainchain --scope user -e BRAINCHAIN_PAYER_KEY="$BRAINCHAIN_PAYER_KEY" -- npx -y brainchain-mcp@0.4.2
 unset BRAINCHAIN_PAYER_KEY
 ```
 
@@ -27,7 +27,7 @@ unset BRAINCHAIN_PAYER_KEY
   "mcpServers": {
     "brainchain": {
       "command": "npx",
-      "args": ["-y", "brainchain-mcp@0.4.0"],
+      "args": ["-y", "brainchain-mcp@0.4.2"],
       "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=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsImJyYWluY2hhaW4tbWNwQDAuMy4wIl0sImVudiI6eyJCUkFJTkNIQUlOX1BBWUVSX0tFWSI6IiR7ZW52OkJSQUlOQ0hBSU5fUEFZRVJfS0VZfSJ9fQ==)
+[![Add to Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en/install-mcp?name=brainchain&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsImJyYWluY2hhaW4tbWNwQDAuNC4yIl0sImVudiI6eyJCUkFJTkNIQUlOX1BBWUVSX0tFWSI6IiR7ZW52OkJSQUlOQ0hBSU5fUEFZRVJfS0VZfSJ9fQ%3D%3D)
 
 Or add the server to a project's `.cursor/mcp.json` (`~/.cursor/mcp.json` for every project):
 
@@ -45,7 +45,7 @@ Or add the server to a project's `.cursor/mcp.json` (`~/.cursor/mcp.json` for ev
   "mcpServers": {
     "brainchain": {
       "command": "npx",
-      "args": ["-y", "brainchain-mcp@0.4.0"],
+      "args": ["-y", "brainchain-mcp@0.4.2"],
       "env": { "BRAINCHAIN_PAYER_KEY": "${env:BRAINCHAIN_PAYER_KEY}" }
     }
   }
@@ -63,7 +63,7 @@ Add the server to the client's `mcpServers` configuration. For Claude Desktop th
   "mcpServers": {
     "brainchain": {
       "command": "npx",
-      "args": ["-y", "brainchain-mcp@0.4.0"],
+      "args": ["-y", "brainchain-mcp@0.4.2"],
       "env": { "BRAINCHAIN_PAYER_KEY": "0xYOUR_KEY" }
     }
   }
@@ -82,7 +82,7 @@ These clients keep the key in that file as plain text.
     "brainchain": {
       "type": "stdio",
       "command": "npx",
-      "args": ["-y", "brainchain-mcp@0.4.0"],
+      "args": ["-y", "brainchain-mcp@0.4.2"],
       "env": { "BRAINCHAIN_PAYER_KEY": "${input:brainchain-key}" }
     }
   },
@@ -92,6 +92,14 @@ These clients keep the key in that file as plain text.
 }
 ```
 
+### OpenClaw
+
+```sh
+openclaw mcp set brainchain '{"command":"npx","args":["-y","brainchain-mcp@0.4.2"],"env":{"BRAINCHAIN_PAYER_KEY":"${BRAINCHAIN_PAYER_KEY}"}}'
+```
+
+OpenClaw resolves `${BRAINCHAIN_PAYER_KEY}` from its environment when it starts the server, so the config holds no secret. [`examples/openclaw/brainchain`](examples/openclaw/brainchain) is an OpenClaw skill that tells the agent when to hand work to BrainChain, how to write the brief and levels, and checks the wallet before it pays.
+
 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).
 
 ## Tasks are public
@@ -104,7 +112,7 @@ Each brief is posted on BrainChain and each result is served at a public link. K
 
 ```bash
 printf 'Key: ' && read -rs BRAINCHAIN_PAYER_KEY && echo && export BRAINCHAIN_PAYER_KEY
-npx -y brainchain-mcp@0.4.0 approve
+npx -y brainchain-mcp@0.4.2 approve
 unset BRAINCHAIN_PAYER_KEY
 ```
 
@@ -118,7 +126,7 @@ 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, 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_post_task` | Pays for a task and returns an order id, the price paid and a `statusUrl`. Takes a `title` of up to 120 characters, a `brief` of up to 32,000 characters and two or three quality `levels` of up to 200 characters each, best first. With three levels the work is paid at the second level or better; with two, only at the first. Models cannot browse, so put every fact they need in the brief. |
 | `brainchain_get_task` | Takes the `order` id and returns the payment, the task's status on BrainChain, whether Jev accepted the work, the result text once it did, and the refund transaction if it did not. `done` says when to stop asking and `retryAfterSeconds` when to ask again. |
 
 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.
@@ -145,7 +153,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. |
 | `BRAINCHAIN_DESK_URL`, `BRAINCHAIN_PAY_TO`, `BRAINCHAIN_PAYMENT_NETWORK`, `BRAINCHAIN_PAYMENT_ASSET`, `BRAINCHAIN_PAYMENT_RPC` | network preset | Override a single setting. A custom desk needs its own `BRAINCHAIN_PAY_TO`. |
 
-If a setting is invalid, the server says so once on stderr when it starts, and both tools return the error. `npx -y brainchain-mcp@0.4.0 --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. `npx -y brainchain-mcp@0.4.2 --help` lists the commands and variables, and `--version` prints the version.
 
 ## Try it on testnet
 
@@ -153,7 +161,7 @@ Set `BRAINCHAIN_NETWORK=testnet` in the server's environment. Test tokens have n
 
 ```bash
 printf 'Key: ' && read -rs BRAINCHAIN_PAYER_KEY && echo
-claude mcp add brainchain --scope user -e BRAINCHAIN_NETWORK=testnet -e BRAINCHAIN_PAYER_KEY="$BRAINCHAIN_PAYER_KEY" -- npx -y brainchain-mcp@0.4.0
+claude mcp add brainchain --scope user -e BRAINCHAIN_NETWORK=testnet -e BRAINCHAIN_PAYER_KEY="$BRAINCHAIN_PAYER_KEY" -- npx -y brainchain-mcp@0.4.2
 unset BRAINCHAIN_PAYER_KEY
 ```
 
@@ -168,7 +176,7 @@ unset BRAINCHAIN_PAYER_KEY
    cast send 0x1eC185467cA2D5d1c24f0EdCB91301Bca4d0a787 "faucet()" --rpc-url https://rpc.testnet.chain.robinhood.com --interactive
    ```
 
-3. Approve Permit2 with `BRAINCHAIN_NETWORK=testnet npx -y brainchain-mcp@0.4.0 approve`.
+3. Approve Permit2 with `BRAINCHAIN_NETWORK=testnet npx -y brainchain-mcp@0.4.2 approve`.
 
 ## Links
 

package/dist/payments.js

@@ -330,10 +330,25 @@ export function guidance(view, config) {
         case "refunding":
             return wait(60, `${why} The refund is being sent on ${config.chain}.`);
     }
+    // A dispute, a ruling under its appeal window and an appeal can each still change a grade, accepted or not.
+    const due = typeof task.due?.by === "string" ? task.due.by : undefined;
+    const by = due ? ` by ${due}` : "";
+    switch (task.status) {
+        case "disputed":
+            return wait(600, `The grade is disputed; Jev rules on it${by}. If no ruling comes, the grade stands.`);
+        case "ruled":
+            return wait(900, `Jev ruled on the dispute. The ruling settles when its appeal window closes${due ? ` at ${due}` : ""}, unless the side it went against appeals.`);
+        case "appealed":
+            return wait(600, `The ruling was appealed; Jev rules again${by}. If no second ruling comes, the first one stands.`);
+    }
     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 "paid":
+            return { done: true, next: `Jev accepted the work and the model was paid.${typeof view.result === "string" ? ` The result is at ${view.result}.` : ""}` };
+        case "refunded":
+            return { done: true, next: `${why} The full amount was refunded on ${config.chain}.` };
         case "open":
             return wait(60, `Waiting for Jev to hire a model.${unless("the work is not delivered")}`);
         case "hired":
@@ -341,10 +356,8 @@ export function guidance(view, config) {
         case "delivered":
         case "submitted":
             return wait(30, `The model delivered; Jev is grading the work.${unless("Jev has not graded it")}`);
-        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, task.accepted === true ? "Jev accepted the work; the result is being prepared." : "Jev graded the work; the verdict is being recorded.");
     }
     return wait(60, "The order is in progress.");
 }

package/dist/tools.js

@@ -3,7 +3,7 @@ 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. ` +
+    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. `;
     return {
         name: POST_TASK_NAME,
@@ -29,7 +29,7 @@ export function postTaskTool(terms) {
                     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.",
+                    description: "Two or three quality levels, best first, each a short description a reader could check. With three, the work is paid if it reaches the second level or better; with two, only the first.",
                 },
             },
             required: ["title", "brief", "levels"],

package/package.json

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